Legacy Document

Inside Macintosh: Networking /

Chapter 6 - AppleTalk Transaction Protocol (ATP) / ATP Reference

Routines / Sending an ATP Request

PNSendRequest

The PNSendRequest function sends a request to another socket's client. It uses the socket that you specify to send the request.

FUNCTION PNSendRequest (thePBPtr: ATPPBPtr; async: Boolean): OSErr;

thePBPtr

A pointer to an ATP parameter block.

async

A Boolean that indicates 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.
-->	userData	LongInt	Four bytes of user data.
<--	reqTID	Integer	The transaction ID for this request.
-->	csCode	Integer	Always nSendRequest for this function.
-->	atpSocket	Byte	The socket number to send the request.
<->	atpFlags	Byte	The control information.
-->	addrBlock	AddrBlock	The destination socket address.
-->	reqLength	Integer	The size in bytes of the request.
-->	reqPointer	Ptr	A pointer to the request data.
-->	bdsPointer	Pointer	A pointer to the BDS.
-->	numOfBuffs	Byte	The number of responses expected.
-->	timeOutVal	Byte	The timeout interval.
<--	numOfResps	Byte	The number of responses received.
<->	retryCount	Byte	The number of retries.
<--	intBuff	Integer	A buffer that ATP uses internally.
-->	TRelTime	Byte	The release timer setting.

Field Description

userData

Four bytes of user data that are sent in the header of the message. You can use these bytes for any purpose that you wish.

reqTID

A number that identifies this transaction request.

atpSocket

The socket to be used to send the request. You must have previously opened this socket by calling the POpenATPSkt function.

atpFlags

A control information field whose bits, numbered 0-7, are used
as flags.

You set bit 5 (atpXOvalue) to specify an exactly-once transaction. To specify an at-least-once transaction, you clear the bit.

To set the other connection end's release timer, set bit 2 of this flag (atpXcallvalue) to signal that this is an extended call and that the parameter block includes an additional field. Then you use the TRelTime field to indicate the amount of time.

ATP sets the atpTIDidValidvalue bit (bit 1) of this field to indicate that the transaction ID field (reqTID) now contains
valid data; you should determine if this bit is set before you
check the request transaction ID.

To direct ATP to use DDP's checksum feature, set the atpSendChkvalue bit (bit 0) of this flag.

addrBlock

The AppleTalk internet socket address of the application to which the request is being sent.

reqLength

The size in bytes of the request data to be sent.

reqPointer

A pointer to the request data to be sent.

bdsPointer

A pointer to the buffer data structure (BDS) that is to hold the data returned in response to the request.

numOfBuffs

The number of response packets requested and expected from the responder application.

timeOutVal

The number of seconds that ATP should wait for a response before resending the request.

numOfResps

The number of response packets actually received.

retryCount

The maximum number of times ATP should retry to send the request. This field value is used to monitor the number of retries; for each retry, ATP decrements the value by 1.

intBuff

Two bytes that are used internally by ATP.

TRelTime

The release timer setting. The 3 lower bits of this field value indicate the time to which the release timer is to be set, as follows:

	TRelTime	Setting of release timer
	000	30 seconds
	001	1 minute
	010	4 minutes
	100	8 minutes

DESCRIPTION

The PNSendRequest function is similar to the PSendRequest function except that rather than relying on ATP to dynamically allocate a socket to use for the transaction, PNSendRequest lets you specify the socket to be used to send the request. You set the atpSocket field of the parameter block to the number of the socket to be used for the request; you must have previously opened the socket by calling the POpenATPSkt function. POpenATPSkt lets you send more than one asynchronous request using the same socket. The number of concurrent requests that you send using PNSendRequest
is machine dependent. If you exceed this limit, ATP returns an error message (tooManyReqs) indicating this. Note that if you call the PNSendRequest function without having previously opened the socket that you specify for the send request, ATP returns a bad ATP socket (badATPSkt) error.

The .ATP driver maintains a timer, called the release timer, for each call to the PSendResponse function that is part of an exactly-once (XO) transaction. If the timer expires before the transaction is complete (that is, before the socket receives the transaction release packet), the driver completes the PSendResponse function. Before AppleTalk Phase 2, the release timer was always set to 30 seconds. To set the other connection end's release timer to another value, set bit 2 of the atpFlags field in the parameter block for the PNSendRequest function to indicate that this is an extended call, then set the TRelTime field to the new value. The nodes at both ends of the ATP connection must be running AppleTalk Phase 2 drivers for this feature to work. For a discussion of exactly-once transactions and use of the release timer, see "At-Least-Once and Exactly-Once Transactions" on page 6-7. You should set the exactly-once flag if
you want the request to be part of an exactly-once transaction.

You can use the PKillSendReq function to cancel a pending PNSendRequest call. Unlike PSendRequest, you cannot use the PRelTCB function to kill this request call.

SPECIAL CONSIDERATIONS

The parameter block for the PNSendRequest function requires 2 additional bytes, intBuff, for ATP's internal use. You must not modify these bytes.

ASSEMBLY-LANGUAGE INFORMATION

To execute the PNSendRequest function from assembly language, call the _Control trap macro with a value of nSendRequest in the csCode field of the parameter block. To execute this function from assembly language, you must also specify the .ATP driver reference number.

RESULT CODES

noErr	0	No error
reqFailed	-1096	Retry count exceeded
tooManyReqs	-1097	Too many concurrent requests
badATPSkt	-1099	Specified socket is not opened
noDataArea	-1104	Too many outstanding ATP calls
reqAborted	-1105	Request canceled