DCB ABEND Exit

The DCB ABEND exit is provided to give you some options regarding the action you want the system to take when a condition occurs that may result in abnormal termination of your task. This exit can be taken any time an abend condition occurs during the process of opening, closing, or handling an end-of-volume condition for a DCB associated with your task. However, it is not taken if an EOV abend condition occurs during the CLOSE issued by task termination. The exit is taken only for determinate errors that the system can associate with the DCB.

When an abend condition occurs, your DCB ABEND exit is given control, provided there is an active DCB ABEND exit routine address in the exit list contained in the DCB being processed. If your exit does not give return code 20, then a write-to-programmer message about the abend is issued. If STOW called the end-of-volume routines to get secondary space to write an end-of-file mark for a PDS, or if the DCB being processed is for an indexed sequential data set, the DCB abend exit routine is not given control if an abend condition occurs. When your exit routine is entered the contents of the registers are the same as for other DCB exit list routines, except that the 3 low-order bytes of register 1 contain the address of the parameter list described in Figure 1.

Figure 1. Parameter List Passed to DCB Abend Exit Routine

               Length or
 Offset        Bit Pattern      Description

 0(0)          2                System completion code in first 12 bits.
 2(2)          1                Return code associated with system completion code.
                                For example, with abend 213-30, this byte will have
                                X'30'.

Input to exit:

 3(3)          1                Option mask.
               xxxx ...x        Reserved.
               .... 1...        Okay to recover.
               .... .1..        Okay to ignore.
               .... ..1.        Okay to delay.

Output from exit:

 3(3)          1                Option. See Table 1 
 4(4)          4                Address of DCB.
 8(8)          4                For system diagnostic use.
12(C)          4                Address of recovery work area.  Must be below 16 MB.

Your ABEND exit routine can choose one of four options:

To terminate your task immediately
To delay the abend until all the DCBs in the same OPEN or CLOSE macro are opened or closed
To ignore the abend condition and continue processing without making reference to the DCB on which the abend condition was encountered, or
To try to recover from the error.

Not all of these options are available for each abend condition. Your DCB ABEND exit routine must determine which option is available by examining the contents of the option mask byte (byte 3) of the parameter list. The address of the parameter list is passed in register 1. Figure 1 shows the contents of the parameter list and the possible settings of the option mask when your routine receives control.

When your DCB ABEND exit routine returns control to the system control program (this can be done using the RETURN macro), the option mask byte must contain the setting that specifies the action you want to take. These actions and the corresponding settings of the option mask byte are in Table 1.

Table 1. Option mask byte settings
Decimal Value	Action
0	Write a message to the user and abnormally terminate the task immediately.
4	Write a message to the user and ignore the abend condition. Valid only when the 'Okay to ignore' bit is on. Return code 20 causes a similar action.
8	Write a message to the user and delay the abend until the other DCBs being processed concurrently are opened or closed.
12	Write a message to the user and make an attempt to recover.
16 - 31	Return codes 16 to 31 have the same effect. Ignore the abend condition without writing a message. Valid only when the 'Okay to ignore' bit is on. In some cases a message has been issued before the exit routine is entered. Return code 4 causes a similar action.

Your exit routine must inspect bits 4, 5, and 6 of the option mask byte (byte 3 of the parameter list) to determine which options are available. If a bit is set to 1, the corresponding option is available. Indicate your choice by inserting the appropriate value in byte 3 of the parameter list, overlaying the bits you inspected. If you use a value that specifies an option that is not available, the abend is issued immediately.

If the contents of bits 4, 5, and 6 of the option mask are 0, you must not change the option mask. This unchanged option mask results in a request for an immediate abend.

If bit 5 of the option mask is set to 1, you can ignore the abend by placing a value of 4 in byte 3 of the parameter list. If you also wish to not have the determinant abend message issued as well, then either set bit 3 in byte 3 of the option mask on, or place a value of 20 in byte 3 of the parameter list. Either way, this action causes processing on the current DCB to stop and sets bit DCBOFOPN to off. There is no need to issue CLOSE. If you subsequently attempt to use this DCB other than to issue CLOSE or FREEPOOL, the results are unpredictable.

If the application has a DCB ABEND EXIT, and this exit ignores an open determinate abend, OPEN gets a return code equal to zero, even though the DCB is not open. In this case, the application checks DCBOFOPN to see if the DCB really is open.

If you ignore an end-of-volume error , the DCB is closed. The control is returned to your program at the point that caused the end-of-volume condition or after the FEOV macro. In this case, the application should check whether the DCB is really open before issuing any other macros using that DCB, other than CLOSE or FREEPOOL. . However, if the end-of-volume routines have been called by the CLOSE routines, control is not returned. In this situation, an ABEND macro is issued even though the IGNORE option has been selected.

Note: For certain types of data set, the DCB ABEND exit might be called during the READ or WRITE macro instead of during the CHECK macro. As described in the previous paragraph, the system might close the DCB before returning from READ or WRITE. The types of data set are PDSE, UNIX files, spooled data sets, and compressed format data sets.

If bit 6 of the option mask is set to 1, you can delay the abend by placing a value of 8 in byte 3 of the parameter list. All other DCBs being processed by the same OPEN or CLOSE invocation will be processed before the abend is issued. For end-of-volume, however, you can't delay the abend because the end-of-volume routine never has more than one DCB to process.

If bit 4 of the option mask is set to 1, you can attempt to recover. Place a value of 12 in byte 3 of the parameter list and provide information for the recovery attempt.

Table 2 lists the abend conditions for which recovery can be attempted. See z/OS MVS System Messages, Vol 7 (IEB-IEE); z/OS MVS System Messages, Vol 8 (IEF-IGD); z/OS MVS System Messages, Vol 9 (IGF-IWM); z/OS MVS System Messages, Vol 10 (IXC-IZP); and z/OS MVS System Codes.

Table 2. Conditions for which recovery can be attempted
Completion Code	Return Code	Description of Error
117	X'38'	An I/O error occurred during execution of a read block ID command issued to establish tape position.
214	X'10'	DCB block count did not agree with the calculated data block count for the tape data set.
137	X'24'	A specific volume serial number was specified for the second or subsequent volume of an output data set on magnetic tape. During EOV processing, it was discovered that the expiration date (from the HDR1 label of the first data set currently on the specified volume) had not passed. When requested to specify if the volume could be used despite the expiration date, the operator did not reply U.
214	X'0C'	An I/O error occurred during execution of a read block ID command issued to establish tape position.
237	X'04'	Block count in DCB does not agree with block count in trailer label.
	X'0C'	DCB block count did not agree with the calculated block count on a cartridge.
413	X'18'	Data set was opened for input and no volume serial number was specified.
	X'24'	LABEL=(n) was specified, where n was greater than 1 and vol=ser was not specified for a tape data set.
613	X'08'	I/O error occurred during reading of tape label.
	X'0C'	Nonvalid tape label was read.
	X'10'	I/O error occurred during writing of tape label.
	X'14'	I/O error occurred during writing of tape label.
713	X'04'	A data set on magnetic tape was opened for INOUT, but the volume contained a data set whose expiration date had not been reached and the operator denied permission.
717	X'10'	I/O error occurred during reading of trailer label 1 to update block count in DCB.
737	X'28'	The EOV DA module was passed an error return code in register 15 after issuing the IEFSSREQ macro instruction. This indicates the subsystem (JES3) discovered a functional or logical error that it could not process.
813	X'04'	Data set name on header label does not match data set name on DD statement.
413	X'58'	Reading multivolume tape data set backward, missing last volume.
413	X'5C'	Reading multivolume tape data set forward, missing first volume.
637	X'B4'	Tape volumes associated with multivolume tape data set were read out of sequence.
637	X'B8'	Reading multivolume tape data set forward, missing last volume.