Legacy Document

Inside Macintosh: Networking /

Chapter 3 - Name-Binding Protocol (NBP) / NBP Reference

Routines / Handling Name and Address Requests

PLookupName

The PLookupName function returns the names and addresses of all the network-visible entities that match a name that you supply, which can include wildcard characters.

FUNCTION PLookupName (thePBptr: MPPPBPtr; async: Boolean): OSErr;

thePBptr

A pointer to an MPP parameter block.

async

A Boolean that specifies whether the function should be executed asynchronously or synchronously. Specify TRUE for asynchronous execution.

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
<--	ioResult	OSErr	The function result.
-->	ioRefNum	Integer	The .MPP driver reference number.
-->	csCode	Integer	Always lookupName.
-->	interval	Byte	The retry interval.
<->	count	Byte	The retry count.
-->	entityPtr	Ptr	A pointer to an entity name.
-->	retBuffPtr	Ptr	A pointer to the return data buffer.
-->	retBuffSize	Integer	The return buffer size in bytes.
-->	maxToGet	Integer	The maximum number of matches to get.
<--	numGotten	Integer	The number of addresses found and returned.

Field Description

ioCompletion

A pointer to a completion routine that you can provide. When you execute a function asynchronously, the .MPP driver calls your completion routine when it completes execution of the function if you specify a pointer to the routine as the value of this field. Specify NIL for this field if you do not wish to provide a completion routine. If you execute a function synchronously, the .MPP driver ignores the ioCompletion field. For information about completion routines, see the chapter "Introduction to AppleTalk" in this book.

ioResult

The result of the function. When you execute the function asynchro-
nously, the function sets this field to 1 and returns a function result of noErr as soon as the function begins execution. When the function completes execution, it sets the ioResult field to the actual result code.

ioRefNum

The .MPP driver reference number. The MPW interface fills in
this field.

csCode

The command code of the .MPP command to be executed. The MPW interface fills in this field.

interval

The retry interval to be used by NBP when it looks on the internet for matching names. The retry interval value specifies how long the function is to wait between retries in 8-tick units. The retry interval equals the interval field value 8 ticks. A value of 7 for the interval field is usually sufficient (7 8 = 56 ticks equals approxi-
mately 1 second). However, on a large network, you should base the interval value on the speed of the network and how many devices of this type you expect to be on the network.

count

The retry count to be used by NBP when it looks on the internet
for matching names. Its value specifies the number of times PLookupName is to retry the operation. A retry count of 3 or 4 is usually sufficient. However, on a large network, you should base the value on how likely it is for the type of device to miss the NBP request. For example, the AppleTalk ImageWriter has a dedicated processor on the LocalTalk option card to handle AppleTalk processing, so the retry count for a device of this type can be low, whereas most Macintosh systems and LaserWriter printers depend on their shared processor to handle all system processing, so
a retry count for a device of these types should be higher. The PLookupName function decrements this field each time it looks
for names.

entityPtr

A pointer to an entity name in the format shown in Figure 3-5 on page 3-11. You can use the NBPSetEntity procedure to prepare the entity name record.

retBuffPtr

A pointer to a buffer you provide into which the PLookupName function puts the names and addresses that it finds. Each matching tuple takes a maximum of 104 bytes, and you use the maxToGet field to specify the maximum number of tuples to be returned.

retBuffSize

The size of the buffer you are providing.

maxToGet

The maximum number of matches to be returned.

numGotten

The actual number of matches that PLookupName returned. The PLookupName function updates this field each time it receives an NBP returned packet and adds names to the return buffer. If there is space remaining in the buffer, NBP may return more matches than the number specified by maxToGet. If numGotten is greater than or equal to maxToGet, there may be additional matches. In this case, you should increase the size of the buffer pointed to by retBuffPtr and call the PLookupName function again.

DESCRIPTION

Before you can send data to another entity, you must have the network address of
that entity. The PLookupName function returns the names and addresses of any network-visible entities whose names match the entity name you specify. The entity name can include any of the wildcard characters given in Table 3-1 on page 3-12.

The PLookupName function completes execution when the number of matches
returned is equal to or greater than the number in the maxToGet field, the function exceeds the retry count, the buffer overflows, or the request is canceled through the
PKillNBP function.

The number of matches returned can be greater than the number specified in the maxToGet field under the following circumstances: A single lookup request or retry can return more than one match in a reply packet. If there is space remaining in the buffer and NBP receives a packet containing multiple matches, PLookupName will return
as many of the matches as fit in the buffer. If this occurs, you should increase the size
of the buffer and call the PLookupName function again to ensure that you obtain all of
the matches.

If all of the tuples returned in a reply packet do not fit in the buffer, then the function completes with as many tuples as can fit. Whether NBP returns more or fewer matches than you specify as the value of maxToGet, the value of numGotten reflects the actual number of tuples that PLookupName writes to the return buffer.

Because the function updates the numGotten field each time it receives a returned packet containing one or more matches and writes those name and address pairs to
the return buffer, you can start reading the names in the buffer and displaying them
for the user before the function completes execution.

The tuples in the buffer are in the format used in the NBP names table, as shown in Figure 3-6 on page 3-12. Because the object, type, and zone names in this format are
of arbitrary length, you cannot use Pascal to read these tuples. Use the NBPExtract function to read tuples from the buffer.

SPECIAL CONSIDERATIONS

Memory used for the entity name record and the return buffer belongs to PLookupName until the function completes execution and must be nonrelocatable.

ASSEMBLY-LANGUAGE INFORMATION

To execute the PLookupName function from assembly language, call the _Control trap macro with a value of lookupName in the csCode field of the parameter block. To execute the _Control trap asynchronously, include the value ,ASYNC in the operand field. To execute this function from assembly language, you must also specify the driver reference number.

RESULT CODES

noErr	0	No error
tooManyReqs	-1097	Too many concurrent requests; wait a few minutes, then try the request again
reqAborted	-1105	Request canceled

SEE ALSO

To read tuples from the buffer, use the NBPExtract function, described next.

To create the entity name record, use the NBPSetEntity procedure, described on page 3-27.

To check that a network-visible entity whose name and address you already know is still available on the network, use the PConfirmName function, described on page 3-32.

To cancel a name lookup request, use the PKillNBP function, described on page 3-36.