The cartridge eject installation exit (CBRUXEJC) is called to approve or disapprove a request to eject a volume from a tape library, as a notification call when a logical volume has been exported, as a notification call when a volume eject has failed, and to determine the TCDB volume record disposition and contents for each volume.
The cartridge eject installation exit is supplied by DFSMSrmm. If your installation is not using DFSMSrmm, the supplied exit returns a return code of 16, indicating that the installation exit not be invoked again. For more information, see z/OS DFSMSrmm Managing and Using Removable Media, z/OS DFSMSrmm Implementation and Customization Guide, and z/OS DFSMSrmm Diagnosis Guide.
If your installation is not using DFSMSrmm and your tape management vendor has not supplied an exit, OAM provides a sample cartridge eject installation exit (CBRSPUXJ) in SAMPLIB that can be customized to fit your needs. The discussion that follows will assist in determining whether the exit is needed on your system. For more information on this SAMPLIB member, see SAMPLIB member CBRSPUXJ.
The exit is also informed of the disposition of the volume record (KEEP or PURGE), and of the volume eject status.
Parameter | Parameter description | Input/Output |
---|---|---|
UXJVDISP | Volume record disposition | Output/Verified |
UXJNCALL | Notification call indicator | Input only |
UXJSTKVS | Stacked “container” volume | Input only/with export call |
UXJVOLSR | Volume serial number | Input only |
UXJFLAGS/UXJCBACK | Failed eject notification call indicator | Output |
UXJUSEA | Volume use attribute | Output/Verified |
UXJWPROT | Write protection status | Output/Verified |
UXJCHKPT | Checkpoint volume indicator | Output/Verified |
UXJLOC | Volume location code | Input only |
UXJTDSI | Tape device selection information | Input only |
UXJGROUP | Storage group name | Output/Verified |
UXJSHLOC | Shelf location | Output |
UXJOWNER | Volume owner information | Output |
UXJCREAT | Volume record creation date | Input only |
UXJENTEJ | Last entry or eject date | Input only |
UXJMOUNT | Last mounted date | Output/Verified |
UXJWRITE | Last written date | Output/Verified |
UXJEXPIR | Volume expiration date | Output/Verified |
The fields that are not marked as input only may be modified by the exit. If it is described as output, it may be updated by the installation exit. If it is further described as verified, the contents or format of the field is validity checked before updating the TCDB volume record with information from the installation exit. Date fields are in ISO format (YYYY-MM-DD).
The 16-byte pass-through value specified with the EXITINFO keyword on the CBRXLCS FUNC(EJECT) macro invocation is passed to the installation exit as an input-only value. If the eject request has come from any source except CBRXLCS, the field contains binary zeros.
If a volume record disposition of purge (P) is returned by the installation exit, the only value retained from the parameter list is the shelf location. This enables the proper shelf location to be displayed upon eject completion.
S (SCRATCH) or P (PRIVATE) can be specified.
For a volume use attribute of SCRATCH, OAM sets the storage group name to *SCRTCH*. Any name supplied by the exit is ignored. For a volume use attribute of PRIVATE, the storage group name may be set to blanks. If a nonblank value is provided, the storage group must be part of the active configuration, and it must be a tape storage group.
Y, N, or blank can be specified.
Y, N, or blank can be specified.
The date specified must be in ISO format (YYYY-MM-DD) or blanks.
The date specified must be in ISO format (YYYY-MM-DD) or blanks.
The date specified must be in ISO format (YYYY-MM-DD) or blanks.
Shelf location and owner information are not validity checked.
If the installation exit returns with an invalid value in a volume record field, returns with an invalid return code, or abnormally terminates, cartridge eject processing is discontinued until OAM has been stopped and restarted, or the LIBRARY RESET,CBRUXEJC command has been issued to re-enable the cartridge eject installation exit.