EXLST—Create an exit list

Purpose

The EXLST macroinstruction builds a list of exit routine addresses. Each operand in this macroinstruction represents a class of events for which an exit routine can be invoked by VTAM®. The address supplied for each operand indicates the user-written routine to be given control when an event that it handles occurs. For example, the SYNAD operand supplies the address of a routine that handles exception conditions (other than logic errors) for RPL-based macroinstructions, and the NSEXIT operand supplies the address of a routine that handles certain network services requests from VTAM. Refer to Using exit routines, for detailed information about each of the exit routines that can be specified by EXLST, including the parameter lists passed to the exit routines and register usage for each exit routine.

Usage

The application program places the address of the exit list created by the EXLST macroinstruction in the EXLST field of an ACB or of an NIB. See the ACB and NIB macroinstructions for details.

An EXLST macroinstruction causes an EXLST control block to be built during program assembly. The control block is built on a fullword boundary. The EXLST control block can also be built during program execution with the GENCB macroinstruction. The EXLST control block can be modified during program execution by using the MODCB macroinstruction or by using the DSECT created by the IFGEXLST mapping macroinstruction. After OPEN is done for an ACB that specifies an EXLST, or after OPEN (for a CNM application program), OPNDST, or OPNSEC is done for an NIB that specifies an EXLST, the exit routines defined by that EXLST cannot be modified or freed for the application program represented by the ACB or for the session represented by the NIB.

When you examine your program listing, you might discover that the assembler has reserved space for exit list addresses that you never specified. Unspecified exits are not, however, used by VTAM, and you cannot use MODCB to insert an address in a field you never specified in the EXLST (or GENCB) macroinstruction. An address of 0 can never be specified.

Note: Only exit routines that VTAM recognizes can be specified with the VTAM EXLST macroinstruction. For example, VSAM exit routines are not allowed.

The expansion of the EXLST macroinstruction is identical for 24- and 31-bit addressing mode application programs.

Syntax


>>-+------+--EXLST--AM--=--VTAM--,------------------------------>
   '-name-'                          

>--+------+--EXLST--AM--=--VTAM--,-----------------------------><
   '-name-'

Input parameters

AM=VTAM

Identifies the exit list generated by this macroinstruction as a VTAM exit list (as distinguished from a VSAM exit list). This operand is required.

ATTN=exit_routine_address

Indicates the address of a routine to be entered to notify a VTAM LU 6.2 application program of the occurrence of the following LU 6.2 related events:

Session limit changes
Incoming conversation requests
Session deactivation.

Refer to the z/OS Communications Server: SNA Programmer's LU 6.2 Guide for information on the use of the ATTN exit routine.

DFASY=exit_routine_address

Indicates the address of a routine to be entered when an expedited-flow data-flow-control request is received. Data-flow-control requests received by the primary end of the session are SBI, QEC, RELQ, SIG, RSHUTD, and SHUTDC. Data-flow-control requests received by the secondary end of the session are SBI, QEC, RELQ, SIGNAL, and SHUTD.

The EXLST containing a DFASY exit routine address can be pointed to by an NIB, as well as by an ACB (see the EXLST operand of the NIB macroinstruction).

LERAD=exit_routine_address

Indicates the address of a routine to be entered when the application program makes an RPL-based request that results in a logic error. Before the LERAD exit routine is given control, VTAM sets a recovery action return code. These codes are explained in Handling errors and special conditions. The LERAD exit routine is entered for all recovery action return codes of 20 and 24 (decimal).

LOGON=exit_routine_address

Indicates the address of a routine to be entered when a CINIT request is sent to the application program as a result of a session-initiation request (such as a logon from a device-type logical unit).

LOSTERM=exit_routine_address

Indicates the address of a routine to be entered when, for example, a logical unit has requested that a session be terminated, or when there are not enough buffers available to queue data that has been received.

NSEXIT=exit_routine_address

Indicates the address of a routine to be entered when the application program receives certain network services request units.

RELREQ=exit_routine_address

Indicates the address of a routine to be entered when another application program requests a session with a device-type logical unit that is currently in session with your application program. This can occur when the other application program issues a SIMLOGON macroinstruction (with the RELRQ and Q options specified) for the device-type logical unit.

RESP=exit_routine_address

Indicates the address of a routine to be entered when certain normal-flow responses arrive on a session.

The EXLST containing the RESP exit routine address can be pointed to by an NIB, as well as by an ACB (see the EXLST operand of the NIB macroinstruction).

SCIP=exit_routine_address

Indicates the address of a routine to be entered when a BIND, UNBIND, Clear, STSN, SDT, or RQR request is received by an application program.

The EXLST containing the SCIP exit routine address can be pointed to by an NIB, as well as by an ACB (see the EXLST operand of the NIB macroinstruction).

Note: A BIND request does not cause an NIB-specified SCIP exit routine to be scheduled. Any application program that is to receive a BIND request (that is, acts as an SLU application program) must, therefore, have a SCIP exit routine defined in the EXLST associated with the program's ACB.

SYNAD=exit_routine_address

Indicates the address of a routine to be entered if an unrecoverable input or output error (physical error) or other unusual condition occurs during the processing of an RPL-based request. (Errors that result from requests that are not valid are handled by the LERAD exit routine.) Before the SYNAD exit routine is given control, VTAM sets a recovery action return code. These codes are explained in Handling errors and special conditions. The SYNAD exit routine is entered for all recovery action return codes of 4, 8, 12, and 16 (decimal).

TPEND=exit_routine_address

Indicates the address of a routine to be entered when any of the following occur:

A VTAM operator issues a HALT command (or VARY INACT command for the application program).
VTAM detects an internal problem that necessitates halting itself.
VTAM abnormally ends
An alternate application takes over sessions from an application that has enabled persistence.