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—CBRUXENTParameter |
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.