Volume-not-in-library processing

When a volume is requested for a job and is not in a system-managed tape library, the DFSMSrmm supplied CBRUXVNL exit is called so the volume can be inserted into a library to prevent job failures from occurring. The CBRUXVNL exit can be modified to suit your requirements.

When called, the supplied, sample CBRUXVNL exit determines whether the request is for a tape volume. If so, CBRUXVNL calls EDGLCSUX to retrieve the DFSMSrmm information for the volume. An informed decision can be made when catalog information is available that confirms whether a volume is a tape or not. To obtain the best results for your installation, you might need to customize CBRUXVNL to change the criteria for calling EDGLCSUX, which is partly selectable by conditional assembly to enable easy customization by you. By default, the initial call to EDGLCSUX is made in these cases:

A TCDB entry for the volume exists.
Job information is unavailable.
Catalog information is available, and the device type is a tape device. When catalog information is available, but the device type is not tape, the exit skips the link to EDGLCSUX.

DFSMSrmm provides the possibility to further enhance the EDGLCSUX calls by providing an option to compare the JCL esoteric unit name against a list of your known tape unit names. You can enable this additional option by customizing the default processing by:

Turning on the tape unit name checking code by changing the setting &TAPEDEC SETC to 'YES', and
Customizing the hardcoded list of tape unit names. The tape unit names are listed in the shipped table called TAPEUNITS. Ensure that you include in this table all the tape unit names your users code in their JCL. You can include esoteric, generic, and specific unit names. The default table is also shown.

Figure 1. Contents of the shipped table: TAPEUNITS

TAPEUNITS DC   A(TAPFIRST,8,TAPLAST)
******************************************************
*  Tape units list - may be customized
******************************************************
TAPFIRST DC    CL8'TAPE'
* insert your location tape unit names here
* or edit any entry
         DC    CL8'3400-6'
         DC    CL8'3420-8'
         DC    CL8'CART'
         DC    CL8'3480'
         DC    CL8'3480X'
         DC    CL8'3490'
         DC    CL8'3490E'
         DC    CL8'3590'
         DC    CL8'3590-1'
         DC    CL8'3590-E'
         DC    CL8'3590-B'
         DC    CL8'3590-H'
         DC    CL8'3590L'
         DC    CL8'3592'
         DC    CL8'3592-J'
         DC    CL8'SYS3480R'
         DC    CL8'SYS348XR'
         DC    CL8'VTS'
         DC    CL8'MTL'
         DC    CL8' '      any blank entry is ignored
TAPLAST  DC    CL8'ATL'

When you have &TAPEDEC set to 'YES', CBRUXVNL checks the supplied unit name and calls EDGLCSUX only in the case where it matches some tape unit name within the TAPEUNITS table. Otherwise, the EDGLCSUX call is skipped.

In addition, the decision to issue message EDG8197I for non-RMM managed volumes is made selectable by an option flag in the EDGLCSUP parameter list. The CBRUXVNL exit shipped by DFSMSrmm sets this option flag ON when a TCDB entry of the volume exists, when the device type supplied by catalog is a tape device, or when &TAPEDEC is set to 'YES'. Otherwise, this option flag is OFF. To change this decision, you can customize the CBRUXVNL source code. This ensures that you will see message EDG8197I when you believe the volume is a tape volume, and the tape volume is not managed by DFSMSrmm.

CBRUXVNL calls DFSMSrmm once to retrieve volume information, and then for a limited set of circumstances, it calls DFSMSrmm a second time to request the operator to enter the volume into a system-managed tape library. The second call is made under these conditions:

CBRUXVNL is called from other than job setup.
CBRUXVNL is called from job setup and one of the following is true:
- A TCDB entry for the volume exists, or
- &ALWAYSPROMPT set to 'YES', or
- The volume resides in a system-managed library, or
- The volume needs to be directed to a system-managed tape library, or
- The volume is an exported logical volume, or
- The volume resides in location SHELF or in a location with type STORE,HOME, and is not moving to a storage location nor a SHELF location, and its home location is system-managed
The CBRUXVNL exit does not allow a volume to be used under these conditions:
- If the volume resides in a loan location and &FAILONLOAN set to 'YES' and the volume is system-managed, the exit fails the request.
- The volume is pending release or is in scratch status.
- The initialize volume action is pending.
- The volume is not to be used on MVS.

CBRUXVNL checks for the requested volume as follows:

If the volume resides in a loan location and the volume is system-managed, the exit fails the request.
The exit attempts to get a volume entered into a system-managed library if the volume can be used on the system and when:
- The volume is in location SHELF and is not moving to a storage location, and its home location is system-managed.
- DFSMSrmm volume information indicates the volume resides in a system-managed library.
- The volume destination is a system-managed location.

DFSMSrmm uses the information to build a WTOR message that includes the volume location and that prompts the operator to enter the volume into the system-managed library. For volumes that reside in a VTS, DFSMSrmm returns additional information for a volume. DFSMSrmm indicates if the volume is a physical volume or a logical volume and provides the stacked volume on which the logical volume is exported.

The CBRUXVNL exit does not allow a volume to be used under these conditions:

The volume is pending release or is in scratch status.
The initialize volume action is pending.
The volume is not to be used on z/OS.

In all other cases, the CBRUXVNL exit allows the volume to be used, but a non-system managed tape drive is allocated by the system.

The sample CBRUXVNL exit includes simple customization options that you can easily change with little or no assembler language knowledge:

&ALWAYSPROMPT

Controls when CBRUXVNL is to call DFSMSrmm a second time to request the operator to enter the volume into a system-managed tape library. The default processing in the sample exit does not need to be changed unless you do not retain TCDB volume entries when volumes are ejected.

NO: CBRUXVNL calls DFSMSrmm a second time to request the operator to enter the volume into a system-managed tape library only for a limited set of circumstances (as previously described). NO is the default.
YES: A DFSMSrmm-managed volume is always to be re-entered into a system managed library, regardless of the system managed volume information defined to DFSMSrmm and regardless of the presence of a TCDB.

&API

Controls whether the DFSMSrmm API can be used within the system exit to obtain DFSMSrmm information about volumes and data sets.

NO: CBRUXVNL does not permit use of the DFSMSrmm API within the system exit routine. NO is the default.
YES: CBRUXVNL is to permit the use of the DFSMSrmm API within the system exit routine. The customer must provide the necessary changes within the exit routine to invoke the desired DFSMSrmm commands and process their output. See the sample CBRUXVNL for more information.

&FAILONLOAN

Controls the handling of requests to use volumes that are on loan.

YES: Specifies that attempts to use volumes that are on loan should be failed in PROTECT mode, but allowed with a warning in WARN mode. YES is the default.
NO: Disables the on loan check and allows them to be processed. If you need to process volumes not defined to DFSMSrmm that duplicate those defined to DFSMSrmm, and the volumes defined to DFSMSrmm are on loan, it is best to select the NO value. The EXPDT=98000 required to have DFSMSrmm ignore the undefined volume is processed after the CBRUXVNL processing has occurred.

&TAPEDEC

Controls when CBRUXVNL is to call DFSMSrmm, based on the tape unit name.

NO: Disables the tape unit name check. CBRUXVNL does not use the supplied unit name when deciding whether to call EDGLCSUX. NO is the default.
YES: Turns on the tape unit name check. CBRUXVNL calls EDGLCSUX only when the supplied unit name matches a tape unit name in the TAPEUNITS table.