Legacy Document

Inside Macintosh: Networking /

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

Routines / Sending an ATP Request

PSendRequest

The PSendRequest function sends a request to another socket whose client application is to respond to the request. PSendRequest then waits for a response before completing execution.

FUNCTION PSendRequest (thePBPtr: ATPPBPt; 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 sendRequest for this function.
<--	currBitMap	Byte	A bitmap.
<->	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 request data.
-->	bdsPointer	Ptr	A pointer to response data.
-->	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.
-->	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. If you want to use the PRelTCB function to cancel the transaction, you must pass it this number.

currBitMap

A bitmap showing which packets of the transaction were received.

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, and use the TRelTime field to indicate the amount of time. Bit 2 (atpXcallvalue) indicates that the parameter block is extended to include the release timer field.

ATP sets the atpTIDValidvalue 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 send checksum (atpSendChkvalue) bit (bit 0) of this flag.

addrBlock

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

reqLength

The size of the request to be sent.

reqPointer

A pointer to the request data to be sent.

bdsPointer

A pointer to a buffer data structure (BDS) that is to be used to hold the responses.

numOfBuffs

On input, the number of response packets that you expect from the responder application. If this field contains a nonzero number on return, you can examine the currBitMap field to determine which packets of the transaction were actually received.

timeOutVal

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

numOfResps

The number of responses actually received.

retryCount

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

TRelTime

The release timer setting. Set the 3 lower bits of this field value to indicate the time to which the release timer should be set for the other end of the connection:

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

DESCRIPTION

The PSendRequest function sends your request data to the destination ATP socket that you specify, and then it waits for that socket's client to return a response message. ATP dynamically assigns and opens the socket to be used to send the request, and it closes
the socket when the function completes execution. Before you call the PSendRequest function, you must build a buffer data structure to hold the response data. You can use the BuildBDS function to do this. See "The Buffer Data Structure" on page 6-8 and "BuildBDS" on page 6-44 for a discussion of this function.

If you want to include additional information along with the request message, you can use the user bytes to include it; for example, you can use these bytes for command information.

The PSendRequest function completes execution when it receives an entire response or when the retry count is exceeded. The timeout value (timeOutVal) determines how many seconds PSendRequest waits before resending the original request packet. The retry count (retryCount) value determines the maximum number of times that ATP is to resend the request. Together the timeout value and the retry count determine the total retry time in seconds (timeOutVal x retryCount = total retry time). ATP modifies the retry count field value during execution of the PSendRequest function if it resends the request; ATP decrements the field by 1 for each retry. See "Writing a Requester ATP Application" beginning on page 6-9 for information on how to select these values.

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. You can set the responding socket's release timer to a value other than 30 seconds. To do this, set
the extended call bit (bit 2) of the atpFlags field in the parameter block for the PSendRequest function and specify the release timer parameter as the value of the TRelTime field. 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 (bit 5) if you want the request to be part of an exactly-once transaction.

You can use the PKillSendReq function or the PRelTCB function to cancel a PSendRequest call. For the PRelTCB function, you need the request transaction ID that ATP returns in the request transaction ID (reqTID) field of the PSendRequest call's parameter block. You can examine the request transaction ID field before the completion of the call, but its contents are valid only after the tidValid bit (bit 1) of the atpFlags field has been set. You should determine if this bit is set before you check the request transaction ID.

ASSEMBLY-LANGUAGE INFORMATION

To execute the PSendRequest function from assembly language, call the _Control trap macro with a value of sendRequest 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
noDataArea	-1104	Too many outstanding ATP calls
reqAborted	-1105	Request canceled