Legacy Document

Inside Macintosh: Networking /

Chapter 12 - Multinode Architecture / Multinode Architecture Reference

Routines / Sending Datagrams Through Multinodes

NetWrite

You use the NetWrite routine to send a packet from a multinode to another multinode or socket-client application. You use the PBControl function to call the NetWrite routine. See "Routines" on page 12-19 for a description of the PBControl call.

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
<--	ioResult	OSErr	The result code.
-->	ioRefNum	Integer	The .MPP driver reference number. You must fill in this value.
-->	csCode	Integer	A routine selector. Always equal to 261 for this routine. You must fill in this value.
-->	checkSumFlag	Byte	A flag indicating whether the checksum should be calculated or the existing checksum left unmodified.
-->	wdsPointer	Ptr	A pointer to the write-data structure for the function.

Field Description

ioCompletion

A pointer to a completion routine that you can provide. When you execute a function asynchronously, AppleTalk 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, AppleTalk ignores the ioCompletion field. For information about completion routines, see the chapter "Introduction to AppleTalk" in this book.

checkSumFlag

A flag whose value you set to a nonzero number if you want the checksum for the datagram to be calculated and placed in the DDP header of the packet. If you do not want the current value in the packet header's checksum field to be altered, you set this field to 0.

wdsPointer

A pointer to the write-data structure that contains a series of length words and pointers that indicate the length and location of a portion of the data, including the header information, that constitutes the packet to be sent over the network.

DESCRIPTION

To send a packet over an AppleTalk network from a multinode, you must first prepare
a write-data structure, and then call the NetWrite routine, passing it a pointer to the write-data structure.

The write-data structure that you create for multinodes differs slightly from the standard write-data structure that you create to send a DDP packet using the PWriteDDP function. For a multinode, you must specify both the source multinode address and the destination address in the packet header information data areas that you point to from the write-data structure. You can also set the checksum field of the write-data structure to 0 to direct AppleTalk to not calculate a checksum for this packet.

You specify the source network number and the source multinode ID of the multinode; the .MPP driver does not set these values for you in the header area of a packet sent from a multinode as it does for a standard DDP packet, although both packets are transmitted as DDP datagrams.

If you are sending the contents of an existing DDP packet through the NetWrite call, you can leave the value of the source socket field unchanged. The value in the source socket field should adhere to the conventions that the AppleTalk DDP protocol speci-
fication describes for the use of sockets. The socket number value must fall within the defined user range as stated in the DDP protocol specification. (See Inside AppleTalk, second edition, for this information.)

The checkSumFlag parameter block field of the NetWrite routine relates to the standard DDP header checksum field. However, the multinode architecture uses this
flag differently than the DDP interface uses it.

• If you want the checksum for the datagram to be calculated and placed in the
  DDP header before the .MPP driver transmits the packet, you set this field to a nonzero number.
• If you want the checksum field of the DDP packet header not to be modified, you
  set this field to 0, and the existing checksum value in the DDP header will not
  be changed.

Note that if you want to send a packet that does not include a checksum, you must hardcode the value by setting to 0 the checksum field of the data structure that contains the packet header that you point to from the write-data structure.

All packets that you send using the NetWrite routine are built with the long DDP packet header to allow for inclusion of the source multinode address. The DDP packet header includes the source multinode address even when the destination and source nodes are on the same LocalTalk network.

Because the source multinode ID is associated with the application that sent the packet and the source user node ID is associated with the machine that transmitted the packet, the source user node ID in the frame header and the source multinode ID in the DDP packet header are always different values.

IMPORTANT

Do not set the socket number to 0 ($00) for the source socket number that you specify in the data area pointed to by the write-data structure. You do this in the address block record socket field for the AddNode routine because the socket number does not apply when you are acquiring a multinode, but you must not do it for the NetWrite
call because NetWrite causes the .MPP driver to build a DDP packet, and socket number 0 has special meaning to DDP that is outside the valid user socket range.

SPECIAL CONSIDERATIONS

Memory used for the write-data structure belongs to the multinode implementation in the .MPP driver for the life of the NetWrite call and must be nonrelocatable. After the NetWrite call completes execution, you must release the memory that you used for
the write-data structure.

ASSEMBLY-LANGUAGE INFORMATION

To execute the NetWrite routine from assembly language, call the _Control trap macro with a value of 261 in the csCode field of the parameter block.

RESULT CODES

noErr	0	No error
ddpLenErr	-92	Datagram is too long
noBridgeErr	-93	No router found
excessCollsns	-95	Excessive collisions on write

SEE ALSO

See the section "Preparing a Write-Data Structure" on page 12-13 for information on how to create the write-data structure.