Utilities › TMSCLEAN Utility—List Scratch, Clean and Scratch Inventory Volumes › Control Parameters

Control Parameters

The following JCL parameters control the various functions of the TMSCLEAN program.

• The SCRATCHLIST parameter marks expired tapes available for use and produces a flat file which is used to produce the Scratch Listing. Although a tape volume has expired, the volume cannot be used for output until it has appeared on the Scratch Listing and the X'04' bit is on in FLAG1. The following tapes are bypassed from SCRATCHLIST processing:
  • Tapes which are out-of-area
  • 3592 WORM tapes (excluding virtual WORM tapes)
  • Tapes under CA Dynam/T control
  • Tapes under control of an External Data Manager unless expired through the EDM interface.

  This flat file contains volume serial numbers of tapes that have come into scratch status by the execution of TMSCLEAN. Tapes can also be flagged for erasure. Multivolume chaining fields are cleared as volumes are set to scratch status. DSNB records will have the active indicator turned off and the DSNB is returned to the free queue. Some fields are not reset until the volume and DSNB are used again for output.

  A flat file, defined by the EARLOUT DD, is produced for this option and the other TMSCLEAN options. For SCRATCHLIST processing, this file can be used to uncatalog data sets on other systems. This is useful in an environment where system catalogs that contain tape data set entries are not shared or available to the system where TMSCLEAN is executed. TMSCLEAN may attempt to uncatalog data sets contained on volumes being scratched. When system catalogs are not available to the system on which TMSCLEAN is running, the TMC and OS catalogs will not be synchronized. To use this flat file, save the data set defined to the EARLOUT DD and use the utility TMSUNCAT to perform the uncatalogs on other systems. For more information on TMSUNCAT, see the TMSUNCAT utility.

  TMSCLEAN also processes the TMC for volumes under Days Since Last Used Control (LDATE/ddd in control statements and online interfaces, or LABEL=EXPDT=98ddd in JCL). Tapes that have not been used for ddd number of days, based on the current system date and the last used date, are processed. TMSCLEAN resets the expiration date of the Volume record in the TMC to the current date and updates the X'02' bit in FLAG2 to indicate the volume has been expired by Days Since Last Used Control.

  Data sets under Catalog Days Control are processed by the TMSCLEAN SCRATCHLIST option. Data sets with the Catalog Days Control (CATLG/ddd in control statements and online interfaces, or LABEL=EXPDT=90ddd in JCL) expiration date are held for ddd number of days, based on the current system date and the creation date of the data set. Once ddd days have been met, TMSCLEAN modifies the expiration date of the TMC Volume or DSNB Record to Catalog Control.

  Criteria for assigning tapes to scratch tape pools and the scratch tape pool names can be defined in the TMOSCRxx and TMONSMxx members of hlq.CTAPOPTN. The flat file produced by TMSCLEAN SCRATCHLIST processing contains the appropriate scratch tape pool for the tapes being scratched. The scratch tape pool can be listed on a report produced by a report writer such as CA Earl.

  Several CA 1 system options (defined in the TMOOPTxx member in hlq.CTAPOPTN) can invoke additional SCRATCHLIST processing. If the option DSEALL is set to YES all tape volumes being scratched are flagged as requiring data set erase (DSE) before they can be used in an output scratch request. The X'08' bit is turned on in FLAG3 of the TMC record. Any attempt to use the tape with this bit on is rejected with a NOT SCRATCH 22 message. The utility TMSTPPRO is used to perform the data erasure, and is the only method available to turn off the erasure required bit.

  Another set of CA 1 system options can determine whether SMS Management Class maximum retention rules are to be applied to any nonscratch tape in the TMC. If the option SMS is set to YES (indicating that the CA 1 interface to SMS is active), and the SR option is set to YES (enforce SMS), each tape data set that contains a valid SMS Management Class will have its expiration date compared to its Management Class definition. When a tape volume exceeds the maximum retention defined by SMS, it is expired the following day, regardless of the value in the EXPDT field. A warning message is issued on the TMSCLEAN message report (TMS Report 85). Any tape expired in this manner will have the X'80' bit in FLAG4 turned on to indicate it has been expired by SMS Management Class maximum retention enforcement.

  The CA 1 keyword date USER/uuu can also be processed by the SCRATCHLIST option for TMSCLEAN. User control (USER/uuu in control statements and online interfaces or LABEL=EXPDT=88uuu in JCL) are user-defined keyword dates, and are treated in the same manner as permanent hold. With the CA 1 option UXCLN2 set to the name of the exit itself, the user exit TMSXCLN2 is invoked for each TMC Volume record containing the USER/uuu expiration date.

  Note: For more information on the TMSXCLN2 user exit see the Programming Guide.

• The SCRATCHRELIST parameter produces a flat file containing an inventory of all active tapes in scratch status, regardless of the length of time they have been in scratch status. The flat file can be used in a subsequent step with a report writer to generate the Scratch and Clean Relist. No additional scratching is performed with this parameter.
• The EXTEND parameter extends the expiration dates of tapes expiring on a specific date or within a range of days, such as company holidays or vacation shutdowns. The user exit TMSXCLN1 can optionally be invoked to modify or bypass TMC Volume records being extended.
• The RESET parameter scans the TMC and turns off the scratch bit (which had been turned on for records with a future expiration date) caused by a bad IPL date. The user exit TMSXCLN1 can optionally be invoked to modify or bypass TMC Volume records being reset.
• The RESETCAT parameter scans the TMC and resets the expiration date of Volume and DSNB records inadvertently expired by Catalog Control. The expiration date in the Volume and DSNB record is reset to the CA 1 keyword date CATALOG, and the expired Catalog Control indicator is turned off.

  If the old TMSCTLG program is no longer used (all systems sharing the TMC have been upgraded to r5.2 or higher, the OCTLG system parameter is set to N, and the TMSOSCAT utility has been run on all systems with the SYNC parameter), the TMSOSCAT utility should be rerun with the SYNC parameter to ensure the correct setting of the TMISCAT and DSNBISCA flags. These flags are not reset by executing TMSCLEAN with the RESETCAT option. Only the EXPDT and the TMECATLG FLAG2 x'08' bit are reset when RESETCAT is used. The user exit TMSXCLN1 can optionally be invoked to modify or bypass TMC volume records being reset. This method of recovery must be run before TMSCLEAN scratches the data sets.

• The TEST parameter may be used with any of the above options to prevent updating of the TMC. If present, TEST must be the first parameter specified. This option still produces the flat file which can be used to produce reports, but suppresses any updating of the TMC. If TEST is used, the Tapes scratched today count is off by the total number of secondary volumes under LDATE control or Catalog Control if R9 is set to zero and tapes will not be on the CA Earl reports.

  Note: The user exit TMSXCLN2 is only invoked if the UXCLN2 option is set to the name of the exit itself. The TMSXCLN1 exit is only invoked if the UXCLN1 option is set to the name of the exit itself.