gtpa2m0s | Application Programming |
An efficient design for most applications is to concentrate the output message processing into a single program or package. Individual processing programs can pass requirements to the output processor usually with a single indicator or message number. Commonly used message texts can be formatted in a message file and referenced by number.
Whether handled by a single package or by the individual programs, the requirements for sending an output message consist of 3 steps:
The destination field on output contains the symbolic network address of the terminal/logical unit to receive the message. For SNA systems it also contains the sequence number identifying the input to which this message is replying. This field, therefore, must be an exact copy of the input message origin field.
The origin field specifies the four-character name of the application sending the message. For SNA systems, when the message cannot be delivered to its destination, it will be returned to the application specified as the destination field of the input RCPL.
The application can enter a unique application name in the origin field on output so that undeliverable messages can be returned to that unique application. If so, the user must ensure that the alternate name is defined in the RCAT.
There are 4 or 8 bytes of control data, depending on whether the expanded RCPL is used. Sometimes only minimal changes to the input will suffice; in other cases, extensive resetting will be required. See the summary chart under Routing Control Parameter List and, for more detail, to the RC0PL DSECT, the c$rc0pl.h header and to the TPF ACF/SNA Data Communications Reference.
Examples:
routc(&(ecbptr->ebw000),D6); ROUTC LIST=R1,LEV=D6
Error conditions detected by the associated system service routine (routc) may cause a system error to be issued and the ECB exited. Error conditions include:
Transmission of the message does not necessarily occur during the execution of the ROUTC system service routine, so the application may not be notified of transmission failure. However, when a detectable failure occurs (such as with SNA systems or applications able to use the application recovery package for output messages) the application specified in the RCPL origin field will be activated; the input RCPL will indicate this is a returned output message.
On return from the macro or the function, the CBRW indicates that the core block for the specified level is released to the system and no longer available to the application.
Table 5. Output Application Message Format: The c$am0sg.h Header
Data Type | Displacement (Bytes) | Symbolic Name | Description |
---|---|---|---|
char | 0-1 | am0rid | Record identification: OM for output (application must enter) |
unsigned char | 2 | am0rcc | Record code check (not used) |
unsigned char | 3 | am0ctl | Control byte |
char | 4-7 | am0pgm | Filing program (for TPF use) |
unsigned long int | 8-11 | am0fch | Forward chain - Must contain address of next file record (must be zero if no chain) |
unsigned long int | 12-15 | am0bch | Last record in chain - must contain address of last record in chain (zero if no chain); used in prime record only, must be zero in all chain records |
short int | 16-17 | am0cct |
Character count from byte 18 to end of text (text + 5) |
unsigned char | 18-20 | am0lit | Origin address; sequence number, record identification, or LNIATA |
char | 21 | am0np1 | Control byte |
char | 22 | am0np2 | Control byte |
char | 23-N | am0txt | Text of message, including any function management header or terminal control characters |
Note that am0bch, which you might expect to be a back chain, is not used as such by the TPF message router.