Legacy Document

Inside Macintosh: Networking /

Chapter 12 - Multinode Architecture / Using Multinode Architecture

Acquiring and Removing Multinodes

You can add an AppleTalk multinode once the physical node that runs your application has connected to the AppleTalk network and AppleTalk has assigned to it a user node ID. After you are finished using the multinode, your application must remove it. This section describes how to do these tasks.

To acquire a multinode address, perform the following steps:

1. Use the Device Manager's OpenDriver function to open the .MPP driver.
   • The .MPP driver must be opened before you call the multinode routines. The OpenDriver function call returns the .MPP driver's reference number.
   • Save the returned value because you must supply this reference number as an input parameter in the ioRefNum field of the multinode parameter block when you call the multinode routines.

2. Create a receive routine to receive broadcast messages and packets addressed to your multinode. See "Receiving Packets Addressed to Your Multinode" beginning on page 12-10 for details.
   • You pass the address of the receive routine to the .MPP driver when you call the AddNode routine to acquire a multinode.
   • When the .MPP driver receives a packet addressed to your multinode or a broadcast message, it calls your receive routine for that multinode to handle
     the packet reception.

3. Allocate storage and set parameter block fields as needed.
   • Define a multinode parameter block of type MNParamBlock. Allocate storage for
     a multinode parameter block that includes the fields required for the AddNode routine. See "The Multinode Parameter Block" on page 12-18.
   • You must set the csCode parameter block field to the numeric value of 262 for the AddNode routine. For the other required parameter block fields, see "AddNode" beginning on page 12-20.

4. Call the AddNode routine once for each multinode that you need.
   • You can acquire only one multinode through each request. You can request a specific multinode address, and if that multinode is available, the .MPP driver will assign it to you. Otherwise, the .MPP driver will return a multinode address that
     it selects randomly.
   • Because the AddNode routine is not defined in the MPW interface files, you must call the Device Manager directly and execute the AddNode routine as an immediate synchronous control call.

From assembly language, you can directly make an immed _Control trap macro call. To issue the AddNode routine as an immediate synchronous control call from a high-level language such as Pascal or C, you must define a function as part of your application. Listing 12-1 shows how to do this in the Pascal language.

Listing 12-1 Defining a Pascal function that makes an immediate AddNode call

FUNCTION PBControlImmedSync(paramBlock: ParmBlkPtr): OSErr;
   INLINE $205F,$A204,$3E80;

FUNCTION AddNode(thePBptr: MNParmBlkPtr): OSErr; 
CONST
   tryAddNodeAgainErr   =  -1021;
VAR
   err: OSErr;

BEGIN
   thePBptr^.csCode  := 262; {addNode}
   thePBptr^.ioRefNum := mppUnitNum;
{If the call returns tryAddNodeAgainErr, make the call repeatedly 
until it no longer returns this error.}
   REPEAT
      err   := PBControlImmedSync(ParmBlkPtr(thePBptr));
      UNTIL (err <> tryAddNodeAgainErr);
      AddNode := err; 
END;

You must issue the AddNode call synchronously because you need to call AddNode repeatedly if the call returns an error of -1021, which indicates that the .MPP driver could not satisfy the AddNode request and that you should try the request again immediately.

The .MPP driver internally associates the address of your receive routine with the multinode address that it returns to you. See "AddNode" beginning on page 12-20
for a complete description of this routine and the parameters that you must pass it.

When you are finished using the multinode, you call the RemoveNode routine to remove the multinode.

1. Allocate nonrelocatable memory for a multinode parameter block that includes the fields required for the RemoveNode routine. See "The Multinode Parameter Block" beginning on page 12-18. The multinode parameter block belongs to the .MPP driver for the life of the RemoveNode call.
2. You issue the RemoveNode routine as a Device Manager's PBControl call. See "RemoveNode" beginning on page 12-23 for details on this routine and the parameters it requires. You must specify the csCode numeric value 263 for the RemoveNode routine.