Open/EOV Nonspecific Tape Volume Mount Exit

This user exit gives you the option of identifying a specific tape volume to be requested in place of a nonspecific (scratch) tape volume. An X'17' in the DCB exit list (EXLST) activates this exit (see DCB Exit List). This exit, which supports only IBM standard labeled tapes, was designed to be used with the Open/EOV volume security and verification user exit. However, this exit can be used by itself.

Open or EOV calls this exit when either must issue mount message IEC501A or IEC501E to request a scratch tape volume. Open issues the mount message if you specify the DEFER parameter with the UNIT option, and either you did not specify a volume serial number in the DD statement or you specified 'VOL=SER=SCRTCH'. EOV always calls this exit for a scratch tape volume request.

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

Return code: Meaning
00 (X'00'): Continue with the scratch tape request as if this exit had not been called.
04 (X'04'): Replace the scratch tape request with a specific volume serial number. Register 0 contains the address of a 6-byte volume serial number.

Note: A value other than 0 or 4 in register 15 is treated as a 0.

If OPEN or EOV finds that the volume pointed to by register 0 is being used either by this or by another job (an active ENQ on this volume), it calls this exit again and continues to do so until you either specify an available volume serial number or request a scratch volume. If the volume you specify is available but is rejected by OPEN or EOV for some other reason (I/O errors, expiration date, password check, and so forth), this exit is not called again.

When this exit gets control, register 1 points to the parameter list described by the IECOENTE macro. Figure 1 shows this parameter list.

Figure 1. IECOENTE Macro Parameter List

               Length or
   Offset     Bit Pattern        Description

   0          4                  OENTID       PLIST ID ('OENT')

   4          1                  OENTFLG      FLAG BYTES

              1... ....          OENTOEOV     Set to 0 if OPEN called this exit; set to 1 
                                              if EOV or FEOV called this exit

              .... ...1          OENTNTRY     Set to 1 if this is not the first time this exit 
                                              was called because the requested tape volume
                                              is being used by this job or other job

   5          1                  OENTOPTN     Contains the options from the OPEN parameter
                                              list (OUTPUT, INPUT, OUTIN, INOUT, and so forth).
                                              For EOV processing, the options byte in the DCB
                                              parameter list indicates how EOV is processing
                                              this volume. For example, if you open a tape
                                              volume for OUTIN and EOV is called during an 
                                              output operation on this tape volume,
                                              OENTOPTN is 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

              xxxx ....          RESERVED

              0000 1111          OENTMASK     TO MASK OFF UNNECESSARY BITS

   6          2                  OENTRSVD     RESERVED

   8          4                  OENTDCBA     ADDRESS OF USER DCB

   12(X'C')   4                  OENTVSRA     Points to the last volume serial number you 
                                              requested in this exit but was in use either
                                              by this or another job. OENTVSRA is set to 0 the 
                                              first time this exit is called.

   16(X'10')  4                  OENTJFCB     Points to the OPEN or EOV copy of the JFCB. The 
                                              high order bit is always on, indicating that
                                              this is the end of the parameter list.

                                 OENTLENG     PLIST LENGTH (Current value is 20.)

When this user exit is entered, the general registers contain the information in Table 1 for saving and restoring.

Table 1. Saving and restoring general registers
Register	Contents
0	Variable
1	Address of the parameter list for this exit
2-13	Contents of the registers before the OPEN, FEOV, 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.