gtpa2m0nApplication Programming

Routing Control Parameter List

A routing control parameter list (RCPL) is associated with each TPF input or output message. The RCPL provides information about the origin, destination, and characteristics of the message. TPF programs use this information to determine the routing required for the message. Application programs, for input messages, use the RCPL to determine the message characteristics and its origin. The application's input message editor must look at the RCPL to determine if the input is a normal new message, a resubmitted input message resulting from failure of a reply to the original, or a returned output message resulting from a failure to transmit successfully to its destination.

For output messages, the application program generates the RCPL to provide the TPF programs with the information necessary to route the message to its destination.

The RCPL is passed to the application starting at ebw000 of the ECB work area. The length of the RCPL is either the 12-byte basic format or 16-byte extended format. The extended format provides for an additional optional general data area of up to 82 bytes. The application must specify at implementation time which format will be used. This is done with the RCPL parameter of the MSGRTA macro in SIP. (See TPF System Generation.)

RCPL Data Area

The header that defines the RCPL is DSECT RC0PL or header c$rc0pl.h. The data area of the RCPL contains three major fields, whether input or output, base or expanded format:

Field
Size

 Destination 
4 bytes

 Origin 
4 bytes

 Control 
4 or 8 bytes, depending on the RCPL format

RCPL Destination Field

This field specifies the destination address of the message. Its contents depend on the type of destination, that is, whether it is an application program or a terminal. If the destination is an application program, then this field contains the 4-character EBCDIC application name. If the destination is a terminal, then this field will contain the TPF terminal address, but will be unique for SNA and non-SNA systems. When the destination is an SNA logical unit this field will contain:

When the destination is a non-SNA terminal, this field will contain:

RCPL Origin Field

This field specifies the origin address of a message. As with the destination field, the contents of this field can be either an application name (for application to terminal or application to application messages) or a TPF terminal address (for terminal to application messages) in the forms described in the destination field above.

RCPL Control Field

This field contains information describing the message origin and destination along with various control indicators. The contents of the control bytes within this field vary depending on whether this RCPL is being passed to the TPF router package (via the ROUTC macro or the routc function) by an application program, and also on whether base or expanded format is used.

In the basic format the control field consists of 4 bytes, the first 3 bytes of which are of primary significance to the application:

Note:
As shown in the following table, bit meanings in control bytes 0 and 2 vary in some cases for input and output. The table should be used with c$rc0pl.h, because the programming considerations cannot all be precisely defined in the table. You can find additional information in TPF ACF/SNA Data Communications Reference and in TPF Data Communications Services Reference.

In the expanded RCPL, there are four additional control bytes:


Table 2. Application Use of RCPL Control Bytes 0 and 2

Byte Bit Use Set Meaning On Input Meaning On Output
0 0 Destination type 0
1
Destination is terminal
Destination is application
Same as input
Same as input

1 Origin type 0
1
Origin is terminal
Origin is application
Same as input
Same as input

2 Message type 0
1
Not used
Not used
Reply to input message
Unsolicited message

3 Message priority 0
1
TPF use only
TPF use only
TPF use only
TPF use only

4 Message recovery 0
1
Normal input message
Returned output message
Return to application if undeliverable
Queue message if undeliverable

5 SLC usage 0
1
Not used
Not used
Output less than 4000 bytes
Output exceeds 4000 bytes

6 Terminal address format 0
1
LNIATA address
RID address
Same as input
Same as input

7 RCPL format 0
1
Basic 12 bytes
Expanded format
Same as input
Same as input
2 0 Release output 0
1
Not used
Not used
Release output pool file record
Don't release output pool file record

1 UIO ROUTC 0
1
Not used
Not used
ROUTC not issued by UIO
ROUTC issued by UIO

2 Resubmitted input 0
1
Not used
Not used
TPF use only
TPF use only

3 Message format 0
1
Not used
Not used
AMSG format
OMSG format

4 Brackets 0
1
No brackets (SNA)
Begin (CONTINUE) brackets
Bracket state unchanged
End bracket state

5 Release input file 0
1
Message not recoverable
Message recoverable
Don't release input file record
Release input file record

6 Change direction 0
1
Normal input
Resubmitted (possible duplicate msg.)
No change in direction of data flow
Change in direction of data flow

7 Output FM header 0
1
No FM header
FM header in text
No FM header
FM header in output text

RC0PL Data Macro

The data macro name for the DSECT that defines the RCPL is RC0PL. This DSECT contains labels to refer to each of the fields as well as labels equated to the necessary values for testing and resetting each of the bit indicators. Since new applications have the option of using the base or expanded format, the macro has a keyword for specifying which format the program requires.

Example:

    RC0PL REG=Rxx|ORG=addr (,FORM=BASE/XPND)

Where: