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

TMSCLEAN Utility—List Scratch, Clean and Scratch Inventory Volumes

Use the TMSCLEAN multipurpose program to perform scratch functions based on parameters specified in the JCL.

TMSCLEAN reads the complete TMC or specified ranges of volumes looking for eligible volumes (expired volumes) and passes the volsers to a subroutine called TMSSCR, which performs the scratch process. TMSSCR can be called from the online interface (for immediate scratch requests).

As the TMC is read sequentially, only volume records with a VOLSEQ=1 are examined. If the volumes are eligible for scratch processing, all secondary volumes and secondary files are processed. If chain errors are detected, a warning message is issued and the entire chain is bypassed, preventing invalid scratching of a tape with a chain error.

The TMSCLEAN utility enables you to select a subset of volumes for processing based on a volume range or a data set name pattern that is matched against file 1 on a volume. Volume range processing does not change how volumes are processed, once selected. All existing functions of TMSCLEAN can be used in conjunction with range processing.

Range control statements are specified in the SYSIN DD, which has standard SYSIN attributes (80 byte fixed length records, either blocked or unblocked). If the SYSIN DD is not found, TMSCLEAN processes the entire TMC. If the SYSIN DD is found with valid range control statements, only the volumes that fall in the specified ranges are processed. If a volume range is specified and a FILE1DSN is also specified, only data sets in the range that also match the FILE1DSN pattern are processed.

The function of TMSCTLG is moved to TMSCLEAN if the system option OCTLG is set to N (the default is Y). This option indicates if the old TMSCTLG program should be used or the new catalog processing in TMSCLEAN. The old TMSCTLG program should be used if the TMC is shared with a system not yet active on Version r5.2 or higher. Once all systems that share the TMC have been upgraded to r5.2 or higher and the TMSOSCAT utility has been run with the parameter of SYNC, the OCTLG parameter can be changed to N. After CA 1 has been reinitialized to make the change in options take effect, the next time TMSCLEAN runs it uses the new catalog process. At this time, the TMSCTLG utility no longer needs to be run.

Note: This option has no effect on the realtime interface to the OS catalog. It indicates if TMSCLEAN may trust the new catalog indicators maintained by the realtime interface. If all systems that share the TMC have not yet been upgraded to Version r5.2 or higher, and have not all had the TMSOSCAT utility executed with a PARM=SYNC; the catalog indicators should not be trusted and the old TMSCTLG utility should continue to be executed. Once the old version of TMSCTLG no longer needs to be executed, the OCTLG option can be changed to N.

Catalog processing examines the OS catalog indicator for every file under Catalog Control if the primary volume meets one of the following:

• The primary volume has an expiration date of CATALOG
• The primary volume has an expiration date of permanent and was created by CA 1 Copycat

If either condition is met, all secondary data sets are examined and processing does not stop until the end of the DSNB chain has been reached. Any file found under Catalog Control with the OS catalog indicator OFF has its expiration date changed to the current date plus the R9 value if one of the following conditions is met.

• The file has been previously cataloged
• The file is at least 24 hours old (CDATE is less than current date minus 1)

Note: There is still the potential for changing the expiration date of an active file. If your site has long-running jobs where a single-step runs more than 24 hours, and you wish to use Catalog Control to manage the retention of files created by this job, use the CATLG/ddd retention method where ddd is the longest time (plus 1) the job can run. For example, if a job runs for 5 days, CATLG/005 should be used as the retention (90006 in the JCL). This prevents the premature change in retention while the file is still being created but not yet cataloged at step-end.

The UNCATA system option controls the uncataloging of data sets. YES specifies to uncatalog all files when they are scratched. G specifies to uncatalog all non GDG files when they are scratched. NO specifies that no uncatalog operations take place.

The SCRCAT system option indicates if any file currently cataloged should be scratched (even if it is not Catalog Controlled). This option only applies to TMSCLEAN and not when the scratch program is executed using the online interface or the TMSARCTV program. If SCRCAT is set to Y (the default), the current catalog status is not used to determine if a volume can be scratched. If set to G (for GDG), GDG files are not scratched if they are still cataloged (regardless of whether the retention has been met). If set to N or NO, any file currently cataloged is not scratched. If this option is set to N or G, and any secondary file has been found to still be cataloged, the volume chain is not scratched. This option is ignored if the OCTLG option is set to Y.

Files controlled by LDATE/ddd or CATLG/ddd have their expiration dates changed (if they pass the ddd days test) even when they reside at an off-site location. However, they are not scratched until they have been returned from the off-site location. This allows for the correct rotation of tapes from off-site locations when the EXP keyword is used and the files are controlled with either LDATE/ddd or CATLG/ddd keyword values.