When you issue the CBRXLCS macro FUNC=CUA, the ISMF ALTER line operator from the mountable tape volume list, or the LIBRARY LMPOLICY command, the Change Use Attribute installation exit (CBRUXCUA) is called before the volume record is changed.

This installation exit is designed to allow the installation the opportunity to approve or disapprove the proposed change to the volume’s use attribute, and to view, and if necessary, to change many fields in the TCDB volume record as well as outboard policy fields, if applicable. Approval or disapproval is communicated by way of the return code which is passed back in register 15. Volume record fields are updated by changing the appropriate fields in the change use attribute installation exit parameter list (CBRUXCPL).

The change use attribute 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 change use attribute exit (CBRSPUXC) 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 CBRSPUXC.

If the caller of the CBRXLCS macro specified EXITINFO on the macro invocation, the 16 bytes of free-form information provided on the invocation are passed to the exit. If the CBRXLCS invocation is called during job processing for a scratch volume, SMS TVRU S->P is passed to the exit. If EXITINFO is not specified on the CBRXLCS invocation, the field in the exit parameter list contains binary zeros.

If the volume is not library-resident, the exit parameter list indicates a library name of SHELF and all the other library fields in the exit parameter list are blank.

Both the current use attribute as it is recorded in the tape volume record and the new use attribute are passed to the exit as input variables.

On a change to SCRATCH, the fields that are passed to the exit represent the values in the tape volume record as it currently exists in the TCDB before any changes are made. If a volume is being changed from PRIVATE to SCRATCH, and if the installation exit supplies new values for any of the following fields, they are ignored. The following default scratch values are set before committing the changes to the TCDB:

On a change to PRIVATE, the fields that are passed to the exit represent the values in the volume record as updated with the parameters specified on the CBRXLCS macro invocation. The installation may override some of those parameters as described in the table below. If the installation makes no changes, the values are committed to the TCDB as presented in CBRUXCPL. If the exit changes some fields, they are processed as described below.

If a field is described as ‘input only’ in the table below, it may not be updated by the installation. 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 validated before updating the TCDB volume record with information from the installation.

For a change to PRIVATE or SCRATCH for a physical WORM tape volume, the UXCVWORM indicator is set on. For a logical WORM tape volume, this indicator is not turned on. Since a logical WORM volume is not distinguishable by a unique media type, the UXCVWORM indicator is not turned on for a logical WORM volume. If this information is needed, the CBRUXCUA installation exit can invoke the CBRXLCS FUNC=QVR interface to obtain this information from the library.

If the installation exit returns with an invalid value in a parameter field, returns with an invalid return code, or abnormally terminates, the current request fails. In addition, change use attribute processing for subsequent PRIVATE to SCRATCH requests is disabled and the change use attribute exit is not called again until either OAM is stopped and started, or the LIBRARY RESET,CBRUXCUA operator command is issued.

Table 1 lists the parameters that are passed to the exit. The fields may or may not be updated by the installation, depending on the function being performed (for example, changed to SCRATCH or PRIVATE).