Cartridge entry installation exit (CBRUXENT)

This installation exit is called to approve or disapprove entry of a cartridge into a library and to determine TCDB volume record contents for each volume that is entered into a library. If the library supports outboard policy management, the installation exit can also obtain and set outboard policy names.

The cartridge entry 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 entry installation exit (CBRSPUXE) 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 CBRSPUXE.

The following library-related information is passed to the exit. None of the library-related information can be modified by the exit.

Library name
Library device type
Library console name
Library logical type
Library description
Library support indicator

Table 1 lists the volume-related parameters that are passed to the exit.

Table 1. Fields passed to the installation exit—CBRUXENT
Parameter	Parameter description	Input/Output
UXEVOLSR	Volume serial number	Input only
UXEVATTR	Volume attribute	Input only
UXEVINFO	Additional volume information	Input only
UXEUSEA	Volume use attribute	Output/Verified
UXEWPROT	Write protection status	Output/Verified
UXECHKPT	Checkpoint volume indicator	Output/Verified
UXETDSI	Tape device selection information	Output/Verified
UXELOC	Volume location code	Input only
UXEGROUP	Storage group name	Output/Verified
UXESHLOC	Shelf location	Output
UXEOWNER	Volume owner information	Output
UXECREAT	Volume record creation date	Input only
UXEENTEJ	Last entry or eject date	Input only
UXEMOUNT	Last mounted date	Output/Verified
UXEWRITE	Last written date	Output/Verified
UXEEXPIR	Volume expiration date	Output/Verified
UXEEXITI	Installation exit information	Input only
UXELMSG	Library manager storage group	Input only
UXELMSC	Library manager storage class	Output/Verified
UXELMMC	Library manager management class	Output/Verified
UXELMDC	Library manager data class	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. If it is further described as verified, the contents or format of the field is checked for validity before updating the TCDB volume record with information from the installation and, if applicable, updating the library with the changed outboard policy names. Date fields are in ISO format (YYYY-MM-DD).

For a previously unknown volume (no volume record exists), the volume serial number, the default volume use attribute, and the default tape device selection information are passed to the exit. The default volume use attribute is set by the storage administrator using the ISMF library define panel. The default tape device selection information (TDSI) is derived from the default entry data class, which is also set by the storage administrator using the ISMF library define panel. The default TDSI information is set as follows:

The library vision system determines the media type when the cartridge is entered. OAM uses this information to set the TDSI media type.
If a default entry data class is supplied in the library definition, the TDSI recording technology is set from the data class.
For media type MEDIA1, OAM sets 36-track recording technology if the default volume use attribute is PRIVATE and no recording technology is specified.
For media type MEDIA2, OAM always sets 36-track recording technology.
For media types MEDIA3 and MEDIA4, OAM sets 128-track recording technology if the default volume use attribute is PRIVATE and no recording technology is specified.
For MEDIA5, MEDIA6, MEDIA7, and MEDIA8, OAM sets EFMT1 recording technology if the default volume use attribute is PRIVATE and no recording technology is specified.
For MEDIA9 and MEDIA10, OAM always sets EFMT2 recording technology if the default volume use attribute is PRIVATE and no recording technology is specified.
For MEDIA11, MEDIA12, and MEDIA13, OAM always sets EFMT4 recording technology if the default volume use attribute is PRIVATE and no recording technology is specified.

The remaining volume-related values are set to blanks. A volume record creation date of blanks indicates that the TCDB volume record does not exist.

For a known volume, whatever information existed in the volume record at the time the cartridge was entered is passed to the exit.

The UXEVATTR field can be used to determine if the volume being entered is a physical (non-VTS) volume, a logical volume, or a logical volume being imported.

If the shelf location field for a logical volume being imported indicates STACKED=volser at the beginning of the field, this information is passed to the entry exit and is cleared upon successful entry of the volume. This should be the exported stacked volume that was recorded in the volume record in the TCDB when the logical volume was exported.

If the cartridge entry processing in the manual tape library, was initiated with the manual cartridge entry programming interface, the 16-byte pass through value specified with the EXITINFO keyword on the CBRXLCS FUNC(MCE) macro invocation in passed to the installation exit as an input-only value. Otherwise, UXEEXITI contains binary zeros.

Since cartridge entry processing in a manual tape library can be initiated by the MCE programming interface, or the LIBRARY ENTER command, the tape device selection field UXEMEDIA may be modified by the installation exit. If a media type is not provided before the invocation of the exit, and the exit makes no changes, entry processing for this volume fails, but processing for other volumes continues. However, if the exit explicitly modifies the media type and specifies an invalid value, entry processing is discontinued for this and all subsequent volumes. For entry processing in an automated tape library dataserver, UXEMEDIA is an input only field (the media type returned by the vision system is used).

The following values are validity checked upon return from the exit:

Volume use attribute
S(SCRATCH) or P(PRIVATE) can be specified.
Storage group name
For a volume use attribute of SCRATCH, the storage group name that is supplied by the exit is ignored. OAM sets the storage group name to *SCRTCH*. If the library supports outboard policy management, the default policy (blanks) is set at the library.

For a volume use attribute of PRIVATE, the storage group name may be set to blanks. A nonblank storage group name is always validity checked, even if the installation exit has not changed the value. The storage group name must be defined in the active SMS configuration as a tape storage group, and the library into which the volume is entered must be one of those in which the storage group resides. If the storage group name does not pass validation, and it is not provided by the installation exit, the cartridge is ejected, but cartridge entry processing continues.
Storage class name
For a volume use attribute of SCRATCH, the storage class name that is supplied by the exit is ignored. If the library supports outboard policy management, the default policy (blanks) is set at the library.

For a volume use attribute of PRIVATE, the storage class name that is supplied may be blank. If a nonblank volume is supplied, the name must only conform to SMS naming convention standards. See Syntax rules for the syntax checking that is performed.
Management class name
For a volume use attribute of SCRATCH, the management class name that is supplied by the exit is ignored. If the library supports outboard policy management, the default policy (blanks) is set at the library.

For a volume use attribute of PRIVATE, the management class name that is supplied may be blank. If a nonblank volume is supplied, the name must only conform to SMS naming convention standards. See Syntax rules for the syntax checking that is performed.
Data class name
For a volume use attribute of SCRATCH, the data class name that is supplied by the exit is ignored. If the library supports outboard policy management, the default policy (blanks) is set at the library.

For a volume use attribute of PRIVATE, the data class name that is supplied may be blank. If a nonblank volume is supplied, the name must only conform to SMS naming convention standards. See Syntax rules for the syntax checking that is performed.
Write protection status
Y, N, or blank can be specified.
Checkpoint volume indicator
Y, N, or blank can be specified.
Last mounted date
The date specified must be in ISO format (YYYY-MM-DD) or blanks.
Last written date
The date specified must be in ISO format (YYYY-MM-DD) or blanks.
Volume expiration date
The date specified must be in ISO format (YYYY-MM-DD) or blanks.
Tape device selection information:
- Tape recording technology may be specified as unknown, 18-track, 36-track, 128-track, 256-track, 384-track, EFMT1, EFMT2, EEFMT2, EFMT3, EEFMT3, EFMT4, or EEFMT4. The recording technology must be applicable for the media type. If it is returned as unknown and there is only one applicable recording technology for the media type, the applicable recording technology is set by default. If the volume is PRIVATE and the media type has more than one applicable recording technology, it is invalid for the installation exit to return unknown for the recording technology. The following are valid recording technology and media type combinations:
  - MEDIA1 and 18-track or 36-track (or unknown if volume is SCRATCH)
  - MEDIA2 and 36-track or unknown
  - MEDIA3, MEDIA4 and 128-track, 256-track, or 384-track (or unknown if volume is SCRATCH)
  - MEDIA5, MEDIA6, MEDIA7, MEDIA8 and EFMT1, EFMT2, EEFMT2, EFMT3, or EEFMT3 (or unknown if volume is SCRATCH)
  - MEDIA9, MEDIA10 and EFMT2, EEFMT2, EFMT3, EEFMT3, EFMT4, or EEFMT4 (or unknown if volume is SCRATCH)
  - MEDIA11, MEDIA12, MEDIA13 and EFMT4 or EEFMT4 (or unknown if volume is SCRATCH).
- For automated cartridge entry, the media type returned by the hardware is always used.
- Compaction may be specified as unknown, none, or compacted.
- Special attribute may be specified as none or read-compatible.

Syntax rules: The values that you specify for the storage group, storage class, data class, and management class construct (policy) names must meet the following SMS naming convention standards:

Alphanumeric and national characters only
Name must begin with an alphabetic or national character ($*@#%)
No leading or embedded blanks
Eight characters or less

Shelf location and owner information are not validity checked.

If the installation exit returns with an invalid value in a parameter field, returns with an invalid return code, or abnormally terminates, cartridge entry processing is discontinued until OAM has been stopped and restarted, or the LIBRARY RESET,CBRUXENT command has been issued to reenable the cartridge entry installation exit. This is intended to prevent the inadvertent assignment of a private volume to scratch status. For an automated tape library dataserver, the volume remains in the insert category.

Note: During cartridge entry processing in an ATLDS, it is not possible to determine which system in an SMS complex will perform cartridge entry processing for any particular occurrence unless the LIBRARY DISABLE,CBRUXENT command has been issued to disable cartridge entry installation exit processing on a system. However, to prevent unpredictable results, the installation should provide the same cartridge entry installation exit for each system in the SMS complex. If the library is being partitioned, each system in the TCDBplex must also run with the same cartridge entry installation exit. The LIBRARY DISABLE,CBRUXENT command can be used to test a new version of the exit by forcing cartridge entry processing to occur on a particular system.