DCB Exit List

The EXLST parameter of the DCB macro specifies the address of a DCB exit list. The DCB exit list may contain the addresses of special processing routines, a forms control buffer (FCB) image, a user totaling area, an area for a copy of the JFCB, and an allocation retrieval list. A DCB exit list must be created if user label, data control block, end-of-volume, block count, JFCBE, or DCB abend exits are used, or if a PDAB macro or FCB image is defined in the processing program.

The DCB exit list must begin on a fullword boundary and each entry in the list requires one fullword. Each exit list entry is identified by a code in the high-order byte, and the address of the routine, image, or area is specified in the 3 low-order bytes. Codes and addresses (including the information location) for the exit list entries are shown in Table 1.

IBM provides an assembler macro, IHAEXLST, to define symbols for the exit list codes. Those symbols are in Table 1. The macro also defines a four-byte DSECT with the following symbols:

Offset  Length     Symbol       Meaning

 0                  EXLST        Name of DSECT
 0       4          EXLENTRA     An entry in the DCB exit list
 0       1          EXLCODES     Code. Last-entry bit and seven-bit code.
         1... ....  EXLLASTE     This is the last entry.
         .xxx xxxx               Seven-bit entry code. See values in figure below. 
 1       3          EXLENTRB     Address or other value as documented for entry code
         4          EXLLENTH     Constant 4 that represents length of each entry.

For an example of coding a DCB exit list with IHAEXLST, see Figure 1.

Table 1. DCB exit list format and contents
Entry Type	Hex Code	Symbol	3 Byte Address—Purpose	Topic
Inactive entry	00	EXLINACT	Ignore the entry; it is not active.
Input header label exit	01	EXLIHLAB	Process a user input header label.	Open/Close/EOV Standard User Label Exit
Output header label exit	02	EXLOHLAB	Create a user output header label.	Open/Close/EOV Standard User Label Exit
Input trailer label exit	03	EXLITLAB	Process a user input trailer label.	Open/Close/EOV Standard User Label Exit
Output trailer label exit	04	EXLOTLAB	Create a user output trailer label.	Open/Close/EOV Standard User Label Exit
Data control block OPEN exit	05	EXLDCBEX	Take an exit during OPEN processing.	DCB OPEN Exit
End-of-volume exit	06	EXLEOVEX	Take an end-of-volume exit.	EOV Exit for Sequential Data Sets
JFCB exit	07	EXLRJFCB	JFCB address for RDJFCB and OPEN TYPE=J macros.	JFCB Exit
	08		Reserved.
	09		Reserved.
User totaling area	0A	EXLUSTOT	Address of beginning of user's totaling area.	User Totaling for BSAM and QSAM
Block count unequal exit	0B	EXLBLCNT	Process tape block count discrepancy.	Block Count Unequal Exit
Defer input trailer label	0C	EXLDFRIT	Defer processing of a user input trailer label from end-of-data until closing.	Open/Close/EOV Standard User Label Exit
Defer nonstandard input trailer label	0D	EXLDFNIT	Defer processing of a nonstandard input trailer label on magnetic tape unit from end-of-data until closing (no exit routine address).	Defer Nonstandard Input Trailer Label Exit List Entry
	0E-0F		Reserved.
FCB image	10	EXLFCBIM	Define an FCB image.	EOV Exit for Sequential Data Sets
DCB abend exit	11	EXLDCBAB	Examine the abend condition and select one of several options.	DCB ABEND Exit
QSAM parallel input	12	EXLPDAB	Address of the PDAB for which this DCB is a member.	QSAM Parallel Input Exit
Allocation retrieval list	13	EXLARL	Retrieve allocation information for one or more data sets with the RDJFCB macro.	Allocation Retrieval List
	14		Reserved.
JFCBE exit	15	EXLJFCBE	Take an exit during OPEN to let a user examine JCL-specified setup requirements for a 3800 printer.	JFCBE Exit
	16		Reserved.
OPEN/EOV nonspecific tape volume mount	17	EXLDCBSL	Option to specify a tape volume serial number.	Open/EOV Nonspecific Tape Volume Mount Exit
OPEN/EOV volume security/verification	18	EXLDCBSC	Verify a tape volume and some security checks.	Open/EOV Volume Security and Verification Exit
	1A-7F		Reserved.
Last entry	80	EXLLASTE	Treat this entry as the last entry in the list. This code can be specified with any of the above but must always be specified with the last entry.

Start of change You can activate or deactivate any entry in the list by placing the required code in the high-order byte. Care must be taken, however, not to destroy the last entry indication. The operating system routines scan the list from top to bottom, and the first active entry found with the proper code is selected. If you do not set the last entry indication, the system might scan many words or even thousands of bytes before finding a code that seems to be valid or a last entry indication. End of change

You can shorten the list during execution by setting the high-order bit to 1, and extend it by setting the high-order bit to 0.

Start of change The system ignores invalid codes but a future level of the operating system might provide support for a code that now is invalid. This would be a latent bug in your program. End of change

Start of change If your program frees storage that an entry points to, it is a good programming practice to invalidate the code for that entry but it is not always necessary. For example your program might define a JFCB entry and issue the RDJFCB macro, free the storage that it points to and issue OPEN without TYPE=J. An OPEN macro with TYPE=J requires a valid DCB exit list entry. Another example is to define a DCB ABEND entry with an invalid address. If you never have an ABEND, this program will work fine. If the system tries to call this DCB ABEND exit, your program will get a program check that covers up the original ABEND cause. End of change

Exit routines identified in a DCB exit list are entered in 24-bit mode even if the rest of your program is executing in 31-bit mode. z/OS DFSMS Macro Instructions for Data Sets has an example showing how to build a 24-bit routine in an area below the 16 MB line that acts as a glue routine and branches to your 31-bit routine above the line.