TYPERUN

Used to specify both the parameters that affect the general functioning of the utility, and the execution mode of the utility. Mandatory.

Only one TYPERUN statement can be specified for each run of this utility. Valid subparameters are:

• MODE — Operation mode. Mandatory.

  - NORMAL — Normal operation is performed. The Media database is updated as required by the CTTRTM utility.

  - SIMULATION — Simulation is performed. No changes are made to the Media database. In this mode, Control-M/Tape keeps in memory a list of Media database records that would have been updated if the utility ran in NORMAL mode.

Note: Running the CTTRTM utility in SIMULATION mode requires a much larger region than running the utility in NORMAL mode. The required region size depends on the number of updated Media database records that this utility stores in memory.

You cannot run more than one instance of the CTTRTM utility in NORMAL mode at the same time.

• DATE — Operation date in 6-character or 8-character format according to site standard. For example, the date can be specified in mmddyy or mmddyyyy format. Optional.
• TRACE — Specifies whether the Trace file is used during CTTRTM run. Optional. Valid values are:

  - Yes — The Trace file is used. Default.

  - No — The Trace file is not used.

• RESTART — Specifies whether to enable Automatic Restart mode when the utility is run after an abend or cancellation of the previous run of the utility. Valid values are:

  - Yes — Enable Automatic Restart mode. Default.

  - No — Disable Automatic Restart mode.

• LIST — Specifies whether diagnostic messages CTT301I, CTT302I, CTT493I and CTT494I are be produced. The messages are sent to SYSPRINT. Valid values are:

  - No — None of these messages are produced.

  - Yes — Messages CTT301I, CTT302I and CTT493I are produced. Default.

  - FULL — All of these diagnostic messages are produced.

• MAXDSNO — Maximum number of data sets that can be scratched by this run of the utility. Optional. A value from 1 through 999999 can be specified.
  If this limit is exceeded, the utility stops, a message is issued, and no changes are made to the Media database.
  Default: Any number of data sets can be scratched by the utility (that is, no limit is assumed).
• MAXVOLNO — Maximum number of volumes that can be scratched by this run of the utility. Optional. A value from 1 through 999999 can be specified.
  If this limit is exceeded, the utility stops, a message is issued, and no changes are made to the Media database.
  Default: Any number of volumes can be scratched by the utility (that is, no limit is assumed).

Note: A Scratch report is only produced by the CTTRTM utility if a REPORT control statement describing the report was specified.

TYPERET

Retention management type. Optional if parameter REPORT is specified. If TYPERET is not specified, retention processing is not performed, but the report produced by the last run of the utility is regenerated. Valid values are:

• MODE — Retention management mode. Valid values:

  - REGULAR — Retention management is performed according to the retention criteria currently specified in data set records in the Media database.

  - CONVERT — This parameter is used after conversion from a different tape management system (for example, CA-TLMS). When MODE is set to CONVERT, expiration date information is extracted from one of the following locations, depending on Control-M/Tape installation parameters:
  Control-M/Tape rules
  JCL EXPDT parameters
  SMS Management Classes
  Default values defined in member CTTPARM

  The extracted retention information is used to update data set records in the Media database. However, no actual expiration is performed. This enables the user to check that the conversion works as planned, before retention management is implemented.

Note: Set MODE to CONVERT only in the following cases:

• This is the first run of the CTTRTM utility since conversion from the previous tape management system, and retention information does not exist in the data set records created as a result of this conversion (for example, CA-TLMS).
• Rules were defined with new retention information that must be incorporated into the data set records in the Media database.

TYPERET (cont.)

- RECALC — Retention information in data set records in the Media database is updated and expiration is performed. Running the CTTRTM utility with MODE set to RECALC has the same effect as running this utility twice—once with MODE set to CONVERT and a second time with MODE set to REGULAR. If MODE is set to RECALC, a special RECALC report can be generated. For more information, see the REPORT control statement in this table.

- CA1CONV — This parameter is used only after CA-1 conversion. In this mode, no retention actions are taken. This mode is used to fill in the data set name’s prefix length (as defined in Control-M/Tape rules) in the Media database data set records. If the CTTRTM utility has already been run with MODE set to CONVERT, it is not necessary to run it again with MODE set to CA1CONV. This information is later used for retention management of cyclic data sets.

Basic Scheduling parameters are checked when rules are loaded and not when data sets are created or retention information is updated. Therefore, when running the CTTRTM utility with MODE set to RECALC, CONVERT, or CA1CONV, the rules applied may differ from the rules normally applied at data set creation. For more information, see the Online Facilities chapter in the Control-M/Tape User Guide.

TYPERET (cont.)

• UNCTLG — Whether to uncatalog data sets after scratching the data set records from the Media database. Optional. Valid values are:

  - YES — Uncatalog the data sets. Default.

  - NO — Do not uncatalog the data sets.

• UPDVOL — Whether to copy the retention information from the data set records to the volume where the data sets reside. The highest retention period is stored in the volume record. Applies only if MODE is set to RECALC or CONVERT. Valid values are:

  - YES — Copy retention information to the volume record.

  - NO — Do not copy the retention information to the volume record. Default. Setting UPDVOL to NO can significantly improve performance time when running the utility in CONVERT or RECALC mode.

  However, accurate retention information is only available using inquiry of data set records in the Media database (that is, an inquiry of the volume records may not yield accurate retention information).

• FASTCAT – Whether to utilize a faster catalog lookup facility or the standard catalog lookup function, LOCATE. Optional. Valid values are:

  - YES - Use the faster catalog lookup facility.

  - NO - Use the standard catalog lookup function, LOCATE. Default.

  Depending on the number of volumes to be expired, there may be no noticeable difference between the faster and the standard catalog lookup functions. In fact, it is even possible that the standard lookup function will be faster. BMC recommends you use the faster catalog lookup facility if the CTTRTM utility at your installation usually runs for an hour or more.

• SCREVOL – Whether empty volumes (that is, volumes with no active datasets, where ACTIVEDS=0) are to be scratched.

  - YES - Scratch empty volumes.

  - NO - Do not scratch empty volumes (default).

  A warning message provides you with a list of the empty volumes.

• UNCATMSG – Whether to issue catalog-related messages CTT305I and CTT306I for scratched datasets.

  - YES - Issue messages CTT305I and CTT306I for scratched datasets.

  - NO - Do not issue messages CTT305I and CTT306I (default).

INCLUDE / EXCLUDE

The scope of the utility can be limited by one or more INCLUDE / EXCLUDE statements. INCLUDE / EXCLUDE statements are specified immediately after the TYPERET parameter and are applied to retention processing.

For additional information on INCLUDE / EXCLUDE statements, see Record Selection Logic (INCLUDE / EXCLUDE Statements) (CTM) and the appendix that discusses logical field names for the Control-M/Tape Repository in the INCONTROL for z/OS Administrator Guide.

With few exceptions, the parameters and options of the REPORT, FIELDS, SORTBY, ATTR and BREAK statements are identical to those found in the CTTRPT utility. For a complete description of these parameters and options, see the CTTRPT – Database extraction and report utility. Differences between the parameters and options of the CTTRTM and CTTRPT utilities are noted where applicable.

REPORT

Produces one of the following reports. Optional if a TYPERET parameter is specified.

• NAME — Report name. Mandatory. Valid values are:

  - SCRATCH — Report listing volumes that expired based on the execution results of the CTTRTM utility.

Note: Full scratch report FULLSCR is no longer generated by the CTTRTM utility. Instead, this report can be generated as part of the GENERAL report by the CTTRPT utility. A sample Full Scratch report can be found in the REPFSCR member of the Control-M/Tape JCL library.

- RECALC — Report listing data sets whose expiration date changed during this run of the utility. This report can only be generated if MODE is set to RECALC in the TYPERET statement when the utility is run.

Note: Either or both of these reports can be generated during a single run of the CTTRTM utility.

FIELDS

Fields to print in the report. The fields are printed in the order they are specified. The fields that can be specified for each report type are as follows:

• Fields of the SCRATCH Report
• MEDIA — Media type.
• POOL– Pool name.
• VOLSER — Volume serial number.
• SL-NAME — Standard label name of the volume.
• UNITGNAM — Generic unit name.
• FIRSTVOL — First volser in a multi-volume chain.
• DSNAME — Name of the first data set in the volume.
• CREDS — Creation date of the first data set in the volume.
• EXPDS — Expiration date of the first data set in the volume.
• EXPDT — Expiration date of the volume.
• LACCDT — Last access date of the volume.
• LOCATION — Location.
• CHKINDT –Check-in date.
• IOERR –Number of input or output errors.
• LCLNDT — Last clean date.
• VOLSTAT — Statuses of the volume.

Fields of the RECALC Report

Each of the following fields can be specified for each data set in a RECALC report:

• VOLSER –Volume serial number
• LABEL — Data set label number
• VOLSNUM — Number of volumes on which the data set resides
• CREDT — Creation date
• CRETM — Creation time
• READDT — Date the data set was last opened for READ access
• READTM — Time the data set was last opened for READ access
• WRITEDT — Date the data set was last opened for WRITE access
• WRITETM — Time the data set was last opened for WRITE access
• DSSTAT — Data set status
• LASTACC — Type of last access (meaning, CREATE, READ or WRITE)
• SMSCL — SMS management class
• CREUSER — User ID that created the data set
• CREJOBID — Creating Job ID
• JCLEXPDT — Data set expiration date as specified in the JCL

Retention Type Fields for Report RECALC

The following fields describe the retention types specified for each data set and the and/or relationships between them. Fields prefixed by OLD indicate retention types before the utility was run. Fields prefixed by NEW indicate retention types after the utility was run.

• OLDEXDT1 — First expiration criterion before recalculation
• OLDXDTR1 — Relation between the first and second old expiration dates
• OLDEXDT2 — Second expiration criterion before recalculation
• OLDXDTR2 — Relation between second and third old expiration dates
• OLDEXDT3 — Third expiration criterion before recalculation
• NEWEXDT1 — First expiration criterion after recalculation
• NEWXDTR1 — Relation between first and second new expiration dates
• NEWEXDT2 — Second expiration criterion after recalculation
• NEWXDTR2 — Relation between second and third new expiration dates
• NEWEXDT3 — Third expiration date after recalculation

SORTBY

Order in which the report is sorted. (Available fields are listed above under parameter FIELDS.) The /B (or /BRK) option (or /BRK) can be added as a suffix to any field to indicate that a page break is inserted in the report when the field changes its value.

ATTR

Override of default attributes defined for a field. For more information, see the FIELDS parameter in this table. Optional.

BREAK

Attributes of the summary header lines printed when a field break occurs. Optional.

Note: For a description of the options of these statements, see the FIELDS, SORTBY, ATTR, and BREAK statements of the CTTRPT utility in Table 357 in Special CTTRPT Fields.