gtps2m3g | ACF/SNA Data Communications Reference |
TPF provides optional exits, called Process Selection Vectors (PSVs), to allow the user to extend the TPF communication support. These exits can be used to add support for additional terminal types without modifying the user's application programs. These optional exit programs operate as an extension to the TPF system; the exits are started when a message is received or sent. PSV exits are started in the main I-stream.
The PSV exits are used to convert from the various X.25 protocols to the TPF protocol and visa versa. These exits may also be used for conversion to and from 3270 and 3600 protocols. In addition to protocol conversion, users now have the ability to supply their own form of message recovery support. The TPF Message Recovery support (the System Recovery Table and the safe store of the message) is bypassed when using these exits for message processing. The user may also provide SNA-architected Data Flow Control (DFC) layer function with PSVs. For additional information on the DFC layer, see Data Flow Control (DFC) Considerations. For a high-level summary of PSVs, see Appendix F, TPF Message Processing Flow User Extensions.
Figure 93 shows the principal that the user-written exit routine can transform the terminal protocol into the standard TPF Application Program Interface.
Figure 93. Input Message Processing
The requirement for a user exit routine to be started for a specific LU or terminal is specified at network definition. For SNA terminals (LUs), exits are defined via the Offline SNA Table Generation (OSTG) package. By coding a 6-character Process Selection Vector (PSV) name, each PSV name is associated with an ECB-controlled program that receives control when a message is received.
TPF users have the opportunity to define a maximum of 96 unique PSV names that can be correlated to a maximum of 96 user exit routines. Because TPF passes the PSV name to the ECB-controlled user exit program, each user-supplied program can uniquely service a given message (by PSV name) or multiple message types (using the name to identify the type of service required). The type of pre-processing message services include the following categories:
Figure 94 illustrates the user-written exit program to transform the protocol used by the application to the protocol required by the terminal.
Identifying which specific exit program to start is part of the network definition procedure. A PSV name can be defined for each LU that requires customized output message handling. Optionally, the user can specify that messages routed to a terminal addressed by line, interchange and terminal (LIT) or Logical End-Point Identifier (LEID) should be intercepted and passed to a PSV routine. See the TPF System Installation Support Reference for additional information about user exits.
The general function categories that an exit can provide are:
Figure 94. Extended TPF Outbound Message Flow, ROUTC and PSV Exits.
When a message is received from an LU, SNA Comm Source starts the user exit routine by using an ENTRC macro (Figure 93). When a message is sent via the ROUTC macro, and the destination LU uses a PSV routine, the ROUTC macro code starts the associated PSV routine via control transfer (Figure 94). When the PSV exit routine is entered, the PSW storage protection key is set to the protect key of working storage. The information passed to the PSV exit routine includes:
0 (Input message handling)
1 (Output message handling)
0 (caller expects return, issue BACKC)
1 (caller does not expect return, issue EXITC)
If input, set to zeros
If output, user information (see the ROUTC exit in the TPF System Installation Support Reference).
The previously described PSV interface included within the EBX fields and
the equates for the EBC fields is contained in the IPSVI DSECT as shown in Table 13.
Table 13. IPSVI - PSV Interface Dsect
Label | Length (In Bytes) | Description |
---|---|---|
IPSINAME | 6 | PSV name |
IPSIPNTX | 1 | Index to PSV name table |
IPSILEIL | 1 | LEID length |
IPSILEID | 3 | LEID |
IPSINETI | 8 | Network Id of remote resource |
IPSINAUN | 8 | Name of remote resource |
IPSIDVTY | 1 | Device type of remote resource |
EBCM01 Equates |
|
|
The exit routine passes the following information to SNA Comm Source:
0 (continue processing input message)
1 (discard message, issue EXITC)
The user may activate PSV routines by entering segment COBT with the following interface:
0 (EBX012-17 contains name of PSV to be activated)
1 (EBX012 contains the RVT name index of the PSV to be activated)
0 (Input message handling)
1 (Output message handling)
0 (caller expects return, issue BACKC)
1 (caller does not expect return, issue EXITC)
If COBT cannot locate the requested PSV routine, system error CE9022 is issued and the ECB exited. In addition, if the destination in the RCPL is a RID, and a session exists, an UNBIND is scheduled.
The RCPL passed by SNA Comm Source to the exit routine contains:
ECB area EBW048-EBW051 is reserved for system use only.
The exit routine can change any of the following information:
On return, the exit routine must:
On return, the exit routine may optionally pass information to the application by:
Comm Source receives control from the exit routine and:
This field is used by the System Error routines to return a message to the terminal if an error occurs in delivering or processing the message.
The RCPL passed by ROUTC to the exit routine contains:
The exit routine can change any of the following information:
The origin field of the RCPL contains the name of the application that issued ROUTC. The origin may be:
The lower case letters 'appl' in this description are replaced with the actual 4-character TPF application name when the message is returned to the originator.
The PSV routine issues ROUTC to send the message to its final destination and issues EXITC macro to return control to the system.
Optionally, the PSV routine may need to queue the message on DASD prior to transmission. See Queue Manager for detailed information about queueing. A PSV routine may queue a message prior to delivery because:
TPF provides a generalized queuing package to allow the user to queue messages. The queuing package provides the primitives to:
If the queuing package is needed, then the user must implement the following facilities:
A PSV routine has a 6-character name and is associated with an ECB controlled program. There can be 128 PSV routines (96 user routines and 32 routines reserved for use by IBM). Each PSV name must be 1 to 6 characters with the characters limited to the letters A through Z and the numbers 0 through 9. The PSV names reserved for IBM use start with the letter I. When the PSV name is passed to the user program, the name is 6 characters, left-justified and padded with blanks (X'40's). The name chosen may imply a specific network (for example, TYMNET), a transmission protocol, or a specific device type. The ECB controlled program associated with a PSV name may be unique to the name or shared among several PSV names. Each program must be allocated and loaded before it can be used. The Online Loader is used to load a new version of a PSV program. See TPF ACF/SNA Network Generation for detailed information on PSVs.
Logical End-Point Identifiers (LEIDs) give a resource a pseudo line, interchange and terminal address. The resource may be an LU, a group of terminals attached via an LU, or any entity the user chooses. An LEID is a short hand notation for the actual resource. The PSV routines map LEIDs to devices in the following ways:
Similarly, which LEID to assign to a message from an LU is determined when the person signs in. For example, when a dial-in terminal is connected to the system, the LEID associated with the LU indicates the end user, geographical location, or authority.