gtpa2m0sApplication Programming

Output Message Control

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:

Step 1
Prepare the data to be transmitted (as is described in the AM0SG DSECT or in the c$am0sg.h header) in a main storage block attached to any data level. If the entire message cannot be contained in a single block, the remainder must be placed in file pool records of the same size and chained from the prime main storage block. The DSECT or header for the AMSG record is the same for output or input: AM0SG DSECT or header c$am0sg.h. The symbolic names may be used by including the header. In assembler use the specified register with the CBRW of the data level chosen. In C use the ecbptr macro to point to the CBRW of the data level chosen. It is important that the chain fields in the record header be zeroed if not used; TPF will use the presence of a nonzero value in am0fch to indicate that an overflow file record exists.

Step 2
Construct the output RCPL, describing the destination and origin of the message. The output RCPL is similar in content to the input RCPL. It describes the origin, destination, and various indicators used for processing the output. Normally, the application preserves the input RCPL in order to construct the output RCPL. In most cases, the output RCPL can be constructed by swapping the origin and destination fields and setting the required indicators.

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.

Step 3
Request the TPF system to send the message by calling the ROUTC macro or the routc function, as described in TPF General Macros or TPF C/C++ Language Support User's Guide. This is a simple coding routine once steps 1 and 2 are completed. The ROUTC macro or the routc function call specifies a pointer to the RC0PL DSECT or the rc0pl structure and the data level of the block in which the message resides.

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.