gtpa2m0qApplication Programming

Message Recovery

The message editor program must be aware of the application message recovery options to be applied for this application. Message recovery is an optional feature of TPF SNA support, which varies with the type of system and the requirements of the application.

SNA Input Messages

For SNA systems, TPF maintains information on every SNA input message currently being processed. The level of recovery is user-selected, and it extends from full recovery of all input and output messages to simply keeping track of each input message in process. See TPF ACF/SNA Data Communications Reference for a complete description of this feature. For the host application programmer, the important aspect of message recovery is input recovery.

As each SNA input message is received, its origin and sequence number are recorded. The message is then passed to a TPF or a user-written transaction analysis routine to determine its input time-out interval and recoverability. Messages determined to be recoverable are written to file.

Note:
Because of storage constraints in the routing control parameter list (RCPL), message recovery cannot be activated for 3600 multithread devices.

The input time-out interval is the time period TPF should wait for the application to respond. If no response is received before the time interval expires, the message is considered lost and is resubmitted to the application. The data resubmitted to the application is the original input if the input was recoverable or a canned message if the input was unrecoverable. It is critical that the application editor recognize this resubmitted input and supply the logic to complete the transaction or to cancel it. A bit in RCPL control word 0 (RCPL2POS in rcplctl0) identifies the message as returned or possible duplicate input.

SNA Output Messages

TPF SNA support also provides output message recovery. A message that cannot be delivered to its destination because the session between TPF and the logical unit has been lost is returned to the application with the returned message indicator bit (RCPL0RET in rcplctl0, the RCPL control byte 0) set. In addition, the origin and destination fields in the original outgoing RCPL are reversed when the message is returned.

The application may then:

When TPF returns an output message, the RCPL0RET bit is used to tell the application that it is a returned message. The application editor must recognize this returned output message and also must contain the logic to process the message according to its own requirements.

Note:
If an application sends a message with a return request again, it must include appropriate code to prevent an infinite loop of returned messages.

An alternate method of handling returned output is for the application to place a unique application name associated only with returned output in the origin field of the output RCPL. This application name must be present in the RCAT in addition to the name for normal input. With this method, when a message is returned, TPF passes control to the editing program associated in the RCAT with the application name for returned messages. The point of this discussion is not to recommend a method but to mention the options, and to emphasize the application's responsibility to implement this logic.

Application Recovery Package

TPF also supplies an application recovery package (ARP) that may be used by any system, SNA or non-SNA. The functions provided are similar in concept to SNA message recovery, but are designed to allow users maximum flexibility in its implementation. This package makes message recovery available for non-SNA systems, and it may be used by SNA systems as an alternative or supplement to support provided by TPF systems.

The ARP package is designed to allow the application to determine the extent of message recovery features, when they are performed, and the time-out factors. By using the application recovery table (ART), a unique reference is maintained for every active message in the system. At any point in the life of a message, the application can refer to the message and its control data (RCPL) and can file and retrieve the message block, or another related data block. The ART resides in main storage and contains the reference to the message plus an optional data area of up to 82 bytes, and the address of the data block on file. The filed block may or may not be a message block. For non-SNA systems, dependent on ARP alone for message recovery, the most common use is to file the message. SNA systems can depend on TPF to file the message block and can use ARP to file an additional data block such as financial totals affected by the transaction. Once the message is transmitted successfully, these totals can be considered secure and the filed block released. Should the message fail, the filed block can be retrieved and the affected amounts canceled.

The application passes control to ARP via an Enter to an external function call to an E-type assembler language program. In C language generally, the TPF_regs struct must be set up with a parameter list specifying the functions required before calling ARP. For TARGET(TPF) C language programs a #pragma linkage statement must be coded before calling ARP to allow the correct linkage to be made. Whether in assembler or in C language, although ARP can be used for output message recovery, for non-SNA systems the application must have a method of determining when the message is successfully delivered or has failed. This is an application responsibility; TPF does not supply it for non-SNA systems.

For details on the use of the Application Recovery Package, see TPF Data Communications Services Reference.