Open/EOV Volume Security and Verification Exit

This user exit lets you verify that the volume that is currently mounted is the one you want. You can also use it to bypass the OPEN or EOV expiration date, password, and data set name security checks. An X'18' in the DCB exit list (EXLST) activates this exit (see DCB Exit List). This exit, which supports IBM standard label tapes, was designed to be used with the OPEN/EOV nonspecific tape volume mount user exit, but you can use this exit by itself (see Open/EOV Nonspecific Tape Volume Mount Exit).

This exit is available only for APF-authorized programs.

This user exit gets control in the key and state of the program that issued the OPEN or EOV request, and no locks are held. This exit must provide a return code in register 15.

Return code

Meaning

00 (X'00')

Use this tape volume. Return to OPEN or EOV as if this exit had not been called.

04 (X'04')

Reject this volume and:

Output
- If the data set is the first data set on the volume, request a scratch tape. This causes OPEN or EOV to issue demount message IEC502E for the rejected tape volume, and mount message IEC501A or IEC501E for a scratch tape volume. If the nonspecific tape volume mount exit is active, it is called.
- If the data set is other than the first one on the volume, process this return code as if it were return code 08.
Input
- Treat this return code as if it were return code 08.

08 (X'08')

Abnormally terminate OPEN or EOV unconditionally; no scratch tape request is issued.

OPEN abnormally terminates with a 913-34 ABEND code, and EOV terminates with a 937-44 ABEND code.

12 (X'0C')

Use this volume without checking the data set's expiration date. Password, RACF authority, and data set name checking still occurs.

16 (X'10')

Use this volume. A conflict with the password, label expiration date, or data set name does not prevent the new data set from writing over the current data set if it is the first one on the volume. To write over other than the first data set, the new data set must have the same level of security protection as the current data set.

When this exit gets control, register 1 points to the parameter list described by the IECOEVSE macro. The parameter list is shown in Figure 1.

Figure 1. IECOEVSE macro parameter list

               Length or
   Offset     Bit Pattern        Description

   0                             OEVSE        DSECT name

   0          4                  OEVSID       ID field = "OEVS"

   4          1                  OEVSFLG      A flag field

              1... ....          OEVSEOV      Set to 0 if OPEN called this exit and
                                              set to 1 if EOV called this exit

              .... ...1          OEVSFILE     Set to 0 if the first data set on the volume
                                              is to be written and set to 1 if this is not
                                              the first data set on the volume to be
                                              written. This bit is always 0 for INPUT 
                                              processing.

              .xxx xxx.                       Bits 1 through 6 reserved

   5          1                  OEVSOPTN     OPEN options from the DCB parameter list
                                              (OUTPUT, INPUT,INOUT, and so forth). For
                                              EOV processing, this byte indicates how EOV
                                              is processing this volume. For example, if
                                              you opened a tape volume for OUTIN and EOV
                                              is called during an output operation on
                                              the tape volume, the DCB parameter list
                                              and OEVSOPTN are set to indicate OUTPUT.

                                              Possible values follow:

                                              xxxx 0000   INPUT or reading at EOV with 
                                                          INOUT, OUTIN, or OUTINX
                                              xxxx 0001   RDBACK
                                              xxxx 1111   OUTPUT or EXTEND or writing at
                                                          EOV with INOUT, OUTIN, or OUTINX
                                              xxxx 0011   INOUT during OPEN
                                              xxxx 0111   OUTIN or OUTINX during OPEN

              0000 1111          OEVSMASK     Mask

   6          2                  OEVSRSVD     Reserved

   8          4                  OEVSDCBA     Address of user DCB

   12(X'C')   4                  OEVSVSRA     A pointer to the current volume serial
                                              number that OPEN or EOV is processing

   16(X'10')  4                  OEVSHDR1     A pointer to an HDR1 label, if one exists,
                                              or to an EOF1 label, if you are creating
                                              other than the first data set on this volume

   20(X'14')  4                  OEVSJFCB     A pointer to the OPEN, CLOSE, or EOV copy of the
                                              JFCB. The high-order bit is always on, indicating
                                              that this is the end of the parameter list.

              24                 OEVSLENG     OEVSID PLIST LENGTH

When this user exit is entered, the general registers have the following contents.

Register: Contents
0: Variable
1: Address of the parameter list for this exit.
2-13: Contents of the registers before the OPEN or EOV was issued
14: Return address (you must preserve the contents of this register in this user exit)
15: Entry point address to this user exit

You do not have to preserve the contents of any register other than register 14. The operating system restores the contents of registers 2 through 13 before it returns to OPEN or EOV and before it returns control to the original calling program.

Do not use the save area pointed to by register 13; the operating system uses it. If you call another routine or issue a supervisor or data management macro in this user exit, you must provide the address of a new save area in register 13.