Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Networking With Open Transport / Part 1 - Open Transport Essentials: Chapter 17 - AppleTalk Transaction Protocol (ATP)

Using ATP
In order for two applications to use ATP, each application must have opened and bound an ATP endpoint. The requester initiates a transaction by making a request. When the responder receives the request, it accepts the request, formulates a response that includes any data required by the requester, and sends that response to the requester. When the requester receives the response, the transaction is complete. You can define how often ATP is to retry each request and how long it is to wait between each retry attempt by using the retry count and interval options, described in "Specifying ATP Options".

At-Least-Once and Exactly-Once Transactions
In the course of a transmission, a request might be lost, a response might be lost or delayed, or the responder might fail to acknowledge or accept a request. In any of these situations, the transaction cannot complete. To complete the transaction and assure reliable delivery of data, ATP is responsible for waiting a predetermined amount of time and then retrying the request until it is able to conclude the transaction. If it cannot conclude the transaction, ATP must let the requester know that the attempt has failed. In order to perform these services, ATP supports two types of transactions: at-least-once transactions and exactly-once transactions.

An at-least-once transaction ensures that the responder receives every request directed to it at least once, but this does not prevent the responder from receiving a request more than once. These are also referred to as ALO transactions.
An exactly-once transaction ensures that the responder receives a specific request only once. These are also referred to as XO transactions. PAP uses this type of ATP transaction.

Open Transport ATP provides XO transaction support for a request transaction when you set the T_ACKNOWLEDGED bit in the option flags for the OTSndURequest function. This kind of support is appropriate in those cases where harm could be done if a request is satisfied multiple times; for example, if you are appending data to the end of a file.
In those cases where no harm is done if a request is satisfied multiple times (for example, when the requester asks the responding node to identify itself) you can select ALO transactions by clearing the T_ACKNOWLEDGED bit in the option flags for the OTSndURequest function.

Sending and Receiving ATP Data
Typically, a requester sends a small amount of data requesting the remote endpoint to take some action or to send back data in reply. The amount of data that the responder can reply with can be quite large. A requester can send only a single ATP packet of 578 bytes, but a responder can return up to eight packets of 578 bytes each, totalling a maximum of 4624 bytes. ATP does not support zero-length packets.
To accomodate the restrictions that a particular network may place on sending that much data at a time, ATP uses the T_MORE flag to communicate to the awaiting requester endpoint when all of the reply data has been accumulated. A single reply may have up to eight packets, and each packet in the reply except for the very last has the T_MORE flag set. The reply data is held at the receiving requester endpoint until a packet arrives that does not have the T_MORE flag set. When this happens, ATP knows that all the reply data has arrived, and it releases the entire reply to the awaiting requester endpoint.

Specifying ATP Options
There are several ATP-specific options and you can use the generic Open Transport options, OPT_INTERVAL and OPT_RETRYCNT. Table 17-1 summarizes their definitions and default values. All of these options, except ATP_OPT_TRANID, can be set both globally (for the endpoint setting the option) with the OptionManagement function and locally by setting option flags for an individual transaction. The ATP_OPT_TRANID option can only be set globally.
Table 17-1 ATP option definitions and default values

Option Default Description
OPT_RETRYCNT 8 retries Sets the number of times ATP retries a request before returning an error to the client.
OPT_INTERVAL 2 seconds Sets the interval for ATP to wait between retries.
ATP_OPT_RELTIMER 30 seconds Sets the amount of time the responder must wait for a transaction release packet before it purges a request entry from its transactions list. Acceptable values are 0 (30 seconds), 1 (1 minute), 2 (2 minutes), 3 (4 minutes), 4 (8 minutes).
ATP_OPT_REPLYCNT 8 replies Specifies the number of replies (1-8) to expect in reply to a request.
ATP_OPT_DATALEN 578 bytes Sets maximum individual packet size.
ATP_OPT_TRANID true Requests a transaction ID.

The Retry Count and Interval Options
After transmitting a transaction request, ATP waits for the interval of time specified by the requester's defined OPT_INTERVAL option (default is 2 seconds). If the requester still hasn't received a response from the responder, it retransmits the request. It repeats this process for the number of times defined by the requester's OPT_RETRYCNT option (default is 8 retries). Once these maximums have been reached without any response, ATP informs the requester that the responder is unavailable.

The Release Timer Option
With ALO transactions, a responder can receive duplicate requests; with XO transactions, ATP uses additional processing to ensure that a responder receives a request only once. To handle XO transactions safely, the responder maintains a transactions list of all recently received requests. When it receives a request, the responder searches through this list to determine whether it is a new request or a duplicate request. If the request is new, the responder inserts it in the transactions list, time stamping the entry with its time of insertion. If it is a duplicate request and a reply has gone out, ATP automatically retransmits the reply without the intervention of the responder application. If it is a duplicate request and a reply has not yet been sent out, ATP discards the request.
When a requester receives a reply from the responder, it sends a transaction release packet to the responder to signal that the transaction has successfully completed, and the responder can now release the transaction from its transactions list. If this transaction release packet is lost, however, the responder would never be able to release the transaction from its list. Because the responder time stamped each new request when it inserted the request into its transactions list, the responder can check the list periodically and eliminate all requests that are older than the time defined by the ATP_OPT_RELTIMER option (default is 30 seconds), assuming that these requests remain in the list because the transaction release packet has been lost.

Other ATP-Specific Options
When a reply starts to arrive, the requester needs to know how many packets are in a given reply so that it knows when to stop waiting for more packets. The ATP_OPT_REPLYCNT option allows you to define a number between 0 and 8 (the default is 8 packets). You can set this globally for the endpoint, with the OptionManagement function, or locally for an individual request.
The ATP_OPT_DATALEN option allows you to set the maximum length of an individual packet up to a length of 578 bytes (the default). In most cases, you can leave this at the default. PAP servers, which use a maximum packet size of 512 bytes, can use this option to restrict the ATP packet size. You can set this globally for the endpoint, with the OptionManagement function, or locally for an individual request.
The ATP_OPT_TRANID option is a Boolean value that, when set to true, requests Open Transport to add an option to every request that contains the ATP transaction ID. You can only set this option globally, with the OptionManagement function; you cannot set it locally.

Using the ATP Packet Header User Bytes
The first 4 bytes of the ATP packet header contain information that allows Open Transport to identify whether an ATP packet is a request or a response, to specify the sequential position of a response packet, and to identify the transaction. The second 4 bytes of the header are called user bytes, and are available for your use. Your application could use the user bytes, for example, to create a simple header for a higher-level protocol.
ATP takes the first 4 bytes of data that the requester specifies and places them in the user bytes portion of the outgoing request. If you do not specify at least 4 bytes of data in the request, ATP pads the user bytes with zeros.
On the responder side, ATP takes the data in the first reply packet's user bytes and puts them into the first 4 bytes of the reply packet's data. ATP ignores the user bytes in all reply packets except for the first packet.
For more information on ATP packets and their header field definitions, refer to Inside AppleTalk, second edition.

Using General Open Transport Functions With ATP
This section describes any special considerations you must take into account for Open Transport functions when you use them with the Open Transport ATP implementation. You must be familiar with the descriptions of these functions in the chapter "Endpoints" in this book before reading this section.

OTSndURequest
A client of a connectionless transaction-based protocol such as ATP can use the OTSndURequest function to send an ATP request packet to an ATP responder endpoint.
To indicate XO transactions, set the T_ACKNOWLEDGED bit in the OTSndURequest function's reqFlags parameter. To indicate ALO transactions, clear this bit. ATP request packets can have up to 578 bytes, and zero-length TSDUs are not supported.

OTRcvURequest
A client of a connectionless transaction-based protocol such as ATP can use the OTRcvURequest function to receive an incoming ATP request packet from an ATP requester endpoint.
On XO transaction packets, the T_ACKNOWLEDGED bit in the OTRcvURequest function's reqFlags parameter is set. On ALO transactions, this bit is clear. ATP request packets can have up to 578 bytes, and zero-length TSDUs are not supported.

OTSndUReply
A client of a connectionless transaction-based protocol such as ATP can use the OTSndUReply function to send an ATP reply packet to an ATP requester endpoint. ATP reply packets can have up to eight packets (4624 bytes), and zero-length TSDUs are not supported.

OTRcvUReply
A client of a connectionless transaction-based protocol such as ATP can use the OTRcvUReply function to receive an incoming ATP reply packet from an ATP requester endpoint. ATP reply packets can have up to eight packets (4624 bytes), and zero-length TSDUs are not supported.

Subtopics
At-Least-Once and Exactly-Once Transactions

Sending and Receiving ATP Data

Specifying ATP Options

The Retry Count and Interval Options

The Release Timer Option

Other ATP-Specific Options

Using the ATP Packet Header User Bytes

Using General Open Transport Functions With ATP

OTSndURequest

OTRcvURequest

OTSndUReply

OTRcvUReply

Option	Default	Description
`OPT_RETRYCNT`	8 retries	Sets the number of times ATP retries a request before returning an error to the client.
`OPT_INTERVAL`	2 seconds	Sets the interval for ATP to wait between retries.
`ATP_OPT_RELTIMER`	30 seconds	Sets the amount of time the responder must wait for a transaction release packet before it purges a request entry from its transactions list. Acceptable values are 0 (30 seconds), 1 (1 minute), 2 (2 minutes), 3 (4 minutes), 4 (8 minutes).
`ATP_OPT_REPLYCNT`	8 replies	Specifies the number of replies (1-8) to expect in reply to a request.
`ATP_OPT_DATALEN`	578 bytes	Sets maximum individual packet size.
`ATP_OPT_TRANID`	`true`	Requests a transaction ID.