Legacy Document

Inside Macintosh: Networking /

Chapter 12 - Multinode Architecture / Multinode Architecture Reference

Routines / Adding and Removing Multinode Addresses

AddNode

You use the AddNode routine to acquire a multinode ID that is separate from and in addition to the standard user node ID assigned to the system. You call the AddNode routine once for each additional multinode that you require. You use the PBControl function to call the AddNode routine. See "Routines" on page 12-19 for a description of the PBControl function. You use a synchronous immediate control call to issue the AddNode routine.

<--	ioResult	OSErr	The result code.
-->	ioRefNum	Integer	The .MPP driver reference number. You must fill in this value.
-->	csCode	Integer	The routine selector. Always equal to 262 for this routine. You must fill in this value.
-->	reqNodeAddr	AddrBlock	The requested multinode address.
<--	actNodeAddr	AddrBlock	The actual multinode address assigned and returned by the .MPP driver.
-->	recvRoutine	LongInt	The address of the application's receive routine.
-->	reqCableLo	Integer	The start of requested network number range for the multinode.
-->	reqCableHi	Integer	The end of the requested network number range for the multinode.
-->	reserved	char	70 reserved bytes required by the .MPP driver.

Field Description

reqNodeAddr

The desired network address of the multinode to be acquired. You specify a value for this field in AddrBlock format. (See "The Address Block Record" on page 12-17.) The value of the aSocket field of the AddrBlock record must always be 0. Set the aNet and aNode fields to the desired network number and multinode ID. If the address that you specify is in use or is invalid, the .MPP driver will assign a different multinode address. To allow the .MPP driver to randomly generate the multinode address to be assigned, specify 0 for all three fields of the AddrBlock record. The .MPP driver returns in the actNodeAddr field of the parameter block either the multinode address that you request or the one that it selects.

actNodeAddr

The actual network address of the multinode that the .MPP driver assigned and returned to you.

recvRoutine

The address of the routine that you provide as part of your application to receive packets addressed to this multinode. The .MPP driver calls this routine when it receives either a packet addressed to the multinode or a broadcast packet.

reqCableLo

The network number that defines the low end of the range of network numbers from which you would like the .MPP driver to select a multinode ID for your use. The reqCableHi field contains the network number that defines the high end of this range. The .MPP driver uses the values that you specify for the cable range if all of the following conditions are true: the .MPP driver could not assign the multinode number that you specified in the reqNodeAddr field (if you specified one), there is no router on the network, and all the multinode addresses belonging to the network whose number is specified in the NetHint field are being used. The NetHint field contains the last used network number stored in RAM.

The network range for the system on which your application is running is defined by the seed router on a network.

If your application does not require that the multinode ID that the .MPP driver assigns to it belong to a specific network cable range, you can set the reqCableLo and reqCableHi fields to 0.

reqCableHi

The network number that defines the high end of the range of network numbers from which you would like the .MPP driver to select a multinode ID for your use. The reqCableLo field value delimits the low end of the range.

reserved

70 bytes that are reserved for internal use by the .MPP driver.

DESCRIPTION

The AddNode routine acquires the multinode address that you specify as the value of the reqNodeAddr parameter if that multinode ID is available and the .MPP driver is able to service the call.

If the requested node is already in use or is invalid, or if you do not request a specific multinode ID, the .MPP driver will randomly select a multinode ID and return it as the value of the actNodeAddr parameter.

If the .MPP driver is unable to service the call, it will return a result code of -1021, which indicates that you should try the AddNode routine again. If you receive this result code, you can retry the AddNode routine call repeatedly until either the .MPP driver assigns and returns a multinode ID to you or you receive a different error message. Because of this need to be able to retry this call repeatedly, you cannot issue the AddNode call asynchronously.

Your application must provide the address of a receive routine that it uses to receive both packets addressed to the multinode and broadcast packets. You pass the address of this routine to the .MPP driver in the recvRoutine parameter. For more information about the receive routine, see "Receiving Packets Addressed to Your Multinode" beginning on page 12-10.

SPECIAL CONSIDERATIONS

You must issue the AddNode routine as a synchronous immediate control call at system task time.

ASSEMBLY-LANGUAGE INFORMATION

To execute the AddNode routine from assembly language, call the _Control trap macro with a value of 262 in the csCode field of the parameter block. You must issue the routine request as an immediate call.

RESULT CODES

noErr	0	No error
tryAddNodeAgainErr	-1021	The .MPP driver was not able to add the multinode; try again
mnNotSupported	-1022	Multinode is not supported by the current AppleTalk connection file of type 'adev'
noMoreMultiNodes	-1023	No multinode addresses are available on the network

SEE ALSO

For an example of how to issue the AddNode routine as a synchronous immediate control call from the Pascal language, see Listing 12-1 on page 12-8.