gtps2m3gACF/SNA Data Communications Reference

Process Selection Vector (PSV)

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.

Input Message PSV Processing

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:

Output Message PSV Processing

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.




PSV Interface

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:

ECB Level 0
The address of message block.

EBW000-EBW0nn
The RCPL.

EBX012-EBX017
The 6-character PSV name.

EBX018
The length of the LEID field (on entry from SNA Comm Source only).

EBX019-EBX021
The LEID defined for the LU (on entry from SNA Comm Source only).

EBX022-EBX027
The NETID of the remote LU, left-justified and padded with blanks (on entry from SNA Comm Source only).

EBX028-EBX035
The NAME of the remote LU, left-justified and padded with blanks (on entry from SNA Comm Source only).

EBX036
The device type of the remote LU as in NODEQ (on entry from SNA Comm Source only).

EBCM01 bits 0-5
Reserved for system use only.

EBCM01 bit 6
Input/Output indicator:

0 (Input message handling)

1 (Output message handling)

EBCM01 bit 7
Return/Exit indicator:

0 (caller expects return, issue BACKC)

1 (caller does not expect return, issue EXITC)

EBCM02-EBCM04
User data:

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
  • IPSIEXIT X'80' discard and exit
  • IPSIINDX X'04' index is passed (COBT)
  • IPSIOUTP X'02' output processing
  • IPSINRET X'01' do not return to caller

The exit routine passes the following information to SNA Comm Source:

EBCM01 bit 0
Continue/Exit indicator:

0 (continue processing input message)

1 (discard message, issue EXITC)

The user may activate PSV routines by entering segment COBT with the following interface:

ECB Level 0
The address of the message block.

EBW000-EBW0nn
The RCPL.

EBX012-EBX017
The 6-character PSV name (if EBCM01 bit 5 is off).

EBX012
The 1 byte PSV name index (if EBCM01 bit 5 is on).

EBX018
The length of the LEID field (0 if no LEID).

EBX019-EBX021
The LEID defined for the LU (irrelevant if length is 0).

EBCM01 bits 0-4
Reserved for system use only.

EBCM01 bit 5
PSV activation type indicator:

0 (EBX012-17 contains name of PSV to be activated)

1 (EBX012 contains the RVT name index of the PSV to be activated)

EBCM01 bit 6
Input/Output indicator:

0 (Input message handling)

1 (Output message handling)

EBCM01 bit 7
Return/Exit indicator:

0 (caller expects return, issue BACKC)

1 (caller does not expect return, issue EXITC)

EBCM02-EBCM04
Available for user use (passed to PSV).

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.

Input Considerations

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:

Output Considerations

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 PSV routine issues ROUTC to send the message to its final destination and issues EXITC macro to return control to the system.

PSV Output Message Queueing

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:

Defining PSV Routines

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, Terminals, and PSV Routines

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:

One-to-One
This is the simplest case where an LU is associated with an LEID. For example, an LU is associated with an LEID value of 123. In this case, every message from the LU is passed to the application as if it came from terminal 123, and every message sent by the application to terminal 123 is forwarded to the LU.

One-to-Many
This implies that a single LEID could represent multiple destinations, for example, a distribution list. In this case, the PSV routine intercepts output messages destined for an LEID and forwards a copy of the message to each terminal implied by the LEID.

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.

Many-to-One
This implies that several LEIDs could represent the same destination. For example, a hard copy terminal uses multiple LEIDs to imply multiple forms. A single terminal uses one LEID for administrative traffic, one for batch data and one for tickets. The PSV routine handling these LEIDs needs to queue and schedule output traffic based upon the particular printer forms that are loaded.