Control-M/Tape Utilities

Overview of the Control-M/Tape utilities

This chapter provides a detailed description of the Control-M/Tape utilities.

Several Control-M/Tape database utilities have been replaced by new IOA Access Method database utilities. For more information, see the section about Control-M/Tape technical considerations in the INCONTROL for z/OS Upgrade Guide.

Control Statement Syntax (CTM)

The following rules apply to the syntax for control statements specified for Control-M/Tape utilities:

  • Multiple INCLUDE / EXCLUDE statements can be specified for each run of a utility.

  • Each control statement (meaning, an INCLUDE / EXCLUDE statement or a Control-M/Tape TYPERUN statement) can span multiple lines.

  • Specification for each parameter in a control statement must be contained in a single line.

  • To specify a value that includes blank spaces, the value must be enclosed in single quotes (for example, ‘This is a value with spaces’).

  • All control statements must be specified in columns 1 through 71. (Comments can be specified in any column.)

  • If not all parameters of a statement fit on a line, place a comma immediately after the last parameter that fits on the line and continue specifying subsequent parameters on the next line.

  • To add a comment to a line, separate it from the code on the line by one or more blank spaces. For example

    Copy 
    INCLUDE DSNAME=DB2*   Select all DB2 data sets for processing

Record Selection Logic (INCLUDE / EXCLUDE Statements) (CTM)

General (CTM)

Certain utilities accept selection criteria that determine which records are processed when the utility runs. These selection criteria are specified as expressions in INCLUDE / EXCLUDE statements that are supplied as parameters to the utility.

INCLUDE / EXCLUDE statements are grouped into blocks. An INCLUDE / EXCLUDE block consists of INCLUDE statements followed by corresponding EXCLUDE statements.

A combined maximum of 1000 INCLUDE / EXCLUDE statements can be specified.

INCLUDE / EXCLUDE expressions, statements and blocks are described on the following pages.

The fields specified in a INCLUDE / EXCLUDE block must be from the same types of table records.

Expressions (CTM)

Expressions are used to specify selection criteria. The format of an expression is

Copy 
key operator value

where

  • key is a parameter (field) in the record. Each key listed in each INCLUDE / EXCLUDE statement must be unique.

  • operator is a relational symbol used to compare the key to the value. Supported symbols include:

    • = – equal

    • ¬ or ! – not equal

    • < – less than

    • > – greater than

  • value – Number or character string (that can include mask characters) against which to compare the key.

When specifying Hexadecimal numbers, these values must be prefixed with an X (for example, DVLRBA=X01234567 instead of DVLRBA=01234567), except in relation to VER and REP fields. For valid values that can be specified in INCLUDE / EXCLUDE statements in Control-M/Tape, see the discussion in the appendix to the INCONTROL for z/OS Administrator Guide that discusses logical field names for the Control-M/Tape Repository.

Only the =, ¬ and ! operators can be specified when the key and value are of type character (meaning, non-numeric).

Mask characters can be specified:

  • for expressions whose operator is either =, ¬ or !

    -and-

  • as part of a character string

For additional information about masking, see the online facilities chapter in the appropriate user guide.

INCLUDE Statements (CTM)

INCLUDE statements determine which records are processed by the utility according to selection criteria.

INCLUDE statements are composed of expressions (at least one) separated by commas.

The format of an INCLUDE statement is

Copy 
INCLUDE Expression1, Expression2, ... , ExpressionN

All the expressions in an INCLUDE statement must be true for the statement to be true (meaning, the relationship between the expressions within one INCLUDE statement is AND).

EXCLUDE Statements (CTM)

EXCLUDE statements determine which records are not processed by the utility according to selection criteria.

EXCLUDE statements are composed of expressions (at least one) separated by commas.

The format of an EXCLUDE statement is

Copy 
EXCLUDE Expression1, Expression2, ... , ExpressionN

All the expressions in an EXCLUDE statement must be true for the EXCLUDE statement to be true (meaning, the relationship between the expressions within one EXCLUDE statement is AND).

INCLUDE / EXCLUDE Block (CTM)

An INCLUDE / EXCLUDE block is composed of any number of INCLUDE statements followed by any number of its corresponding EXCLUDE statements.

The format of an INCLUDE / EXCLUDE block is

Figure 120 INCLUDE / EXCLUDE Statements

The relationship between multiple INCLUDE statements in a block is OR.

The relationship between multiple EXCLUDE statements in a block is OR.

The relationship between an INCLUDE statements and the following EXCLUDE statements in a block is AND.

Single INCLUDE / EXCLUDE Block Processing (CTM)

If even one EXCLUDE statement of a block is true (meaning, a record satisfies the EXCLUDE statement), the record is not selected and the next record is examined.

If all EXCLUDE statements in the block are false, the INCLUDE statement is evaluated against the record

  • If the INCLUDE statement is true, the record is selected.

  • If the INCLUDE statement is false, the record is not selected and the next record is examined.

Multiple INCLUDE / EXCLUDE Blocks (CTM)

Multiple INCLUDE / EXCLUDE blocks can be specified.

  • If multiple INCLUDE / EXCLUDE blocks are specified, the relationship between the blocks is OR and the blocks are checked sequentially.

  • If a record is not selected after being checked against an INCLUDE / EXCLUDE block, it is checked against the next INCLUDE / EXCLUDE block. Once a record is selected based on an INCLUDE / EXCLUDE block, the record is included and not checked against other blocks.

  • If only EXCLUDE statements are specified in the first block (meaning, no INCLUDE statements are specified), only records not excluded by the first block are considered for selection by subsequent INCLUDE / EXCLUDE blocks.

Figure 121 INCLUDE / EXCLUDE Blocks

INCLUDE / EXCLUDE Examples (CTM)

The following examples illustrate INCLUDE / EXCLUDE logic. For all but the last example, assume the following expressions, all of which evaluate to True.

Table 324 Expressions for INCLUDE / EXCLUDE Examples

Expression

Evaluates To:

Key1=Value1

True

Key2=Value2

True

Key3=Value3

True

(CTM) Example 1

Select all records that match these expressions:

Copy 
INCLUDE Key1=Value1,Key2=Value2,Key3=Value3

(CTM) Example 2

Select all records that match these expressions, using another method:

Copy 
INCLUDE Key1=Value1
EXCLUDE Key2ØValue2
EXCLUDE Key3ØValue3

(CTM) Example 3

Select all records that match the first expression and either the second or third expressions:

Copy 
INCLUDE Key1=Value1
EXCLUDE Key2ØValue2,Key3ØValue3

(CTM) Example 4

Select all records that do not match these expressions:

Copy 
INCLUDE Key1ØValue1
INCLUDE Key2ØValue2
INCLUDE Key3ØValue3

(CTM) Example 5

Select all records that match either the second or third expression, but do not match the first expression:

Copy 
INCLUDE Key2=Value2
EXCLUDE Key1=Value1
INCLUDE Key3=Value3
EXCLUDE Key1=Value1

(CTM) Example 6

The following example utilizes actual values (instead of the terms KeyN and ValueN).

Select the records of all volumes starting with FD whose data set name starts with BACKUP, except for those volumes starting with FD but ending with 102. Furthermore, independent of the preceding selection criteria, select records created by jobs whose job names start with CTT.

Copy 
INCLUDE VOLSER=FD*,DSNAME=BACKUP*
EXCLUDE VOLSER=FD?102
INCLUDE CREJBN=CTT*

CTTACP – Retrieve database tracking information

This utility can be used to

  • Print historical update events that occurred in the Media database, using the information in the Trace file.

  • Copy a Trace file to another preformatted Trace file, or to a sequential variable-blocked file.

  • Copy a sequential, variable-blocked file containing Trace data back to a formatted Trace data set. If this Trace data set contains data, the contents of the sequential file are appended to it.

If the Trace file is 100% full, no tape activity can be recorded in it. In this case, use JCL parameter EXPDT=00000 when the Trace file is copied to tape.

Activating the CTTACP Utility

Figure 122 CTTACP Activation

Copy 
//EXEC       CTTACP
//SYSIN      DD    *
    COPY       FROM=TRACE|SEQ,TO=TRACE|SEQ
    <INCLUDE/EXCLUDE STATEMENTS>
    OUTPUT     TYPE=T|C|X|D|F,LINESIZE=size
//

CTTACP Parameters

The following parameters can be specified to the utility in the EXEC statement that invokes the CTTACP JCL procedure:

Table 325 CTTACP EXEC Parameters

Parameter

Description

TRCIN

Name of source file

TRCOUT

Name of target file

Parameters can also be supplied using DD statement SYSIN:

Table 326 CTTACP SYSIN Parameters

Parameter

Description

COPY

Copy statement type. Mandatory.

  • FROM – Source data set type. Valid values are:

    • TRACE – Source is a Control-M/Tape Trace file.

    • SEQ – Source is a sequential, variable-blocked file.

  • TO – Target data set type. Valid values:

    • TRACE – Target is a Control-M/Tape Trace file.

    • SEQ – Target is a sequential, variable-blocked file.

INCLUDE /
EXCLUDE

The records written to the output data set can be filtered by one or more INCLUDE / EXCLUDE statements. INCLUDE / EXCLUDE statements for this utility can filter records according to any of the keywords used with trace type records, listed in the appendix that discusses logical field names for the Control-M/Tape Repository in the INCONTROL for z/OS Administrator Guide. For more information, see Record Selection Logic (INCLUDE / EXCLUDE Statements) (CTM).

OUTPUT

Output formatting. Valid values are:

  • LINESIZE – Output record size. Valid values: 70 to 132 characters; Default: 80.

    The LINESIZE parameter is valid only when the output is a sequential data set.

  • TYPE – Output format type. Valid values are:

    • T – Trace file records are unchanged. Default.

    • C – Output contains only printable characters.

    • X – Output is written in Hexadecimal format.

    • D – Output is written in dump format (a combination of C and          X types).

    • F – Output is formatted. A comprehensive list of Logical Field Names and relevant values is written for each trace record. For more information see the discussion of the keywords used with trace type records, in the appendix of the INCONTROL for z/OS Administrator Guide that deals with logical field names for the Control-M/Tape Repository.

      The C, X, D and F values for the TYPE parameter are valid only when the output is a sequential data set.

CTTACP Return Codes

Table 327 CTTACP Return Codes

Code

Description

0

Operation ended successfully

8

Missing DD statements or open failed

12

Control card error

16

Loading Control-M/Tape environments failed

20

I/O error on input or output files

Examples for CTTACP

CTTACP Example 1

Prints to a sysout all historical updates that are done on the Media database by the TAPEJOB job. The output is formatted, meaning that each field name and its value are printed consecutively in the output file.

Figure 123 CTTACP – Example 1

Copy 
//EXEC       CTTACP
//DAOUTTRC   DD   SYSOUT=*
//SYSIN      DD   *
    COPY       FROM=TRACE,TO=SEQ
    INCLUDE    JOBNAME=TAPEJOB
    OUTPUT     TYPE=F
//

CTTACP Example 2

Copy a Trace file to a second preformatted Trace file:

Figure 124 CTTACP – Example 2

Copy 
//EXEC       CTTACP,TRCOUT=‘CTT.BACKUP.TRC’
//SYSIN      DD    *
    COPY       FROM=TRACE,TO=TRACE
//

CTTAFR – Format and Initialize Trace File

The CTTAFR utility formats and initializes the Trace file. The physical block number of the Trace file is automatically specified in the PARM parameter of the JCL EXEC statement. This value is the same as the IOA variable TRCBLKS, which was set in the ICE environment.

For more information about calculating the trace file size, see the Control-M/Tape installation chapter of the INCONTROL for z/OS Installation Guide.

Activating the CTTAFR Utility

Copy 
//EXEC  CTTAFR
//

CTTAFR Parameters

No parameters are specified for this utility.

CTTAFR Return Codes

Table 328 CTTAFR Return Codes

Code

Description

0

Operation performed successfully.

8

DCB open error.

12

The utility cannot run because Control-M/Tape is active.

16

Loading Control-M/Tape environment failed.

Example for CTTAFR

Format the Trace file.

Copy 
//EXEC  CTTAFR
//

CTTBIX – Rebuild Media database index

The CTTBIX utility rebuilds the index file for the Media database. The new index file corresponds to information currently contained in the Media database data file.

The index file to be rebuilt must be allocated and formatted prior to activating the utility.

Run the CTTBIX utility only if Control-M/Tape is down or suspended. For further information, see Table 329 CTTBIX EXEC Parameters.

Use this utility

  • when the amount of space remaining for the existing index file is insufficient

    In this case

    1. Delete the index file.

    2. Redefine and format the index file with the required amount of space, using the IOADBF utility.

    3. Rebuild the index file.

  • for performance improvement

  • after recovery

  • after converting volumes from other tape management systems (for example, CA-1, CA-TLMS) to Control-M/Tape

Activating the CTTBIX Utility

Copy 
//EXEC CTTBIX,TYPERUN={B|C|F|N}
//

CTTBIX Parameters

The TYPERUN parameter is contained in the EXEC statement.

Table 329 CTTBIX EXEC Parameters

Parameter

Description

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:

  • B — The utility is run in BUILD mode; the index file is rebuilt. If Control-M/Tape is active, the CTTBIX utility must not run.

  • C — The utility is run in CONVERT mode. This mode is specified when converting the database from another tape management system to Control-M/Tape. If Control-M/Tape is active, the CTTBIX utility must not run.

  • F — The utility is run in FORCED BUILD mode; the index file is rebuilt. No checking is performed for Control-M/Tape status. This mode forces building of the index file.

  • N — The utility is run in FORCED CONVERT mode. No checking is performed for Control-M/Tape status. This mode forces the building of the Index file.

Specify this mode when converting the database from another tape management system to Control-M/Tape. This index file can be built and checked in a test environment while the production environment is still active.

Do not set parameter TYPERUN to F if the CTTBIX utility is running on the production Media database (that is, Control-M/Tape is active). Running this utility on the production Media database can cause unpredictable results.

CTTBIX Return Codes

Table 330 CTTBIX Return Codes

Code

Description

0

Operation performed successfully

8

Inconsistency error detected – execution continues – index file built successfully (manually correct logical errors in the data)

12

Error in parameters – Execution terminates

16

Error opening DCB – Execution terminates

24

Unsuccessful sort

28

Media database access error

32

Loading Control-M/Tape environment failed

40

Index is not empty. Before running the utility, format the index using the IOADBF utility.

44

Control-M/Tape is active – The CTTBIX utility cannot run in the specified mode while Control-M/Tape is active.

Example for CTTBIX

Copy 
//EXEC  CTTBIX,TYPERUN=B
//

CTTCTRC – Allocate and Format Trace File

The CTTCTRC utility creates and formats Control-M/Tape Trace files.

Activating the CTTCTRC Utility

Copy 
//EXEC CTTCTRC

This utility is used during Control-M/Tape installation by the job that creates the Control-M/Tape trace file.

CTTCTRC Parameters

Parameters are supplied to the utility by invoking a JCL procedure.

Table 331 CTTCTRC Parameters for Data File Creation

Parameter

Description

DBPREFT

The high level qualifier of the data set trace file. The default is the value of the ICE variable &DBPREFT, set during ICE installation step 3.1.

The full name of the newly-created trace file is &DBPREFT..TRC.

TRCUNITT

The unit on which the file is to be created. The default is the value of the ICE variable &TRCUNITT, set during ICE installation step 3.1.

TRCVOL

The volume on which the file resides. The default is the value of the ICE variable &TRCVOL, set during ICE installation step 5.3.

TRCBLKS

The number of blocks that the data file contains. The default is the value of the ICE variable &TRCBLKS, set during ICE installation step 5.3.

To calculate the required number of records, see the topics on Media database and Stacking database calculations in the Control-M/Tape chapter of the INCONTROL for z/OS Installation Guide.

TRCBLK

The block size of the newly-created trace file. The default is the value of the ICE variable &TRCBLK, set during ICE installation step 5.3.

CTTCTRC Return Codes

Table 332 CTTCTRC Return Codes

Code

Description

0

Operation performed successfully.

8

DCB open error.

12

Loading Control-M/Tape environment failed.

16

The utility cannot run because Control-M/Tape is active.

Example for CTTCTRC

Copy 
//EXEC CTTCTRC,DBUNITT=3390,TRCBLKS=1700

CTTDBIB – Rebuild indexes of stacking database

The CTTDBIB utility rebuilds an index file from the Control-M/Tape Stacking database Data file. The new index file corresponds to information currently contained in the Stacking database data file.

Previous contents of the index file are erased.

Before activating the utility, the index file to be rebuilt must be allocated and formatted using the IOADBF utility.

Use this utility

  • when the amount of space remaining in the existing index file is insufficient.

    In this case

    1. Delete the index file.

    2. Redefine and format the index file with the required amount of space, using the IOADBF utility.

    3. Rebuild the index file with the utility CTTDBIB.

  • for performance improvement

Activating the CTTDBIB Utility

Copy 
//EXEC CTTDBIB

CTTDBIB Parameters

The following parameter can be specified to the utility in the EXEC statement that invokes the CTTDBIB JCL procedure:

Table 333 CTTDBIB Parameters

Parameter

Description

DBRPEFT

The high level qualifier of the database files. The default in the high-level qualifier of the Control-M/Tape database installation.

SYSIN parameters are provided in the KEYSTK member in the PARM library for your convenience. The information in this member is predefined and is used internally by the utility.

CTTDBIB Return Codes

Table 334 CTTDBIB Return Codes

Code

Description

0

The operation was performed successfully.

8

The SYSIN parameter was set to a non-numeric string.

12

Memory allocation error

16

Loading Control-M/Tape environment failed.

Other

The operation failed.

Example for CTTDBIB

Copy 
//EXEC  CTTDBIB
//SYSIN DD DSN=CTT.PROD.PARM(KEYSTK),DISP=SHR

CTTDLD – Add, Delete, or Convert Volumes

The CTTDLD utility adds volumes to, and deletes volumes from, the Media database. It can also convert volumes from other tape management systems (for example, CA-1, CA-TLMS).

Use this utility

  • to add a range of scratch or non-scratch volumes to the Active library (MAINLIB)

  • Records for these volumes are added to the Media database. This is called ADD mode.

  • to delete a range of scratch volumes from the Active Library (MAINLIB)

  • Records for these volumes are deleted from the Media database. This is called DELETE mode.

  • to build data from an external source of information and add it to the data component of the Media database

  • This is called CONVERT mode. Usually, CONVERT mode is used to convert the database of another tape management system (such as CA-1 or CA-TLMS) to Control-M/Tape.

Activating the CTTDLD Utility

ADD mode

Copy 
//EXEC       CTTDLD
//SYSIN      DD      *
    TYPERUN    MODE=ADD
    RANGE      FIRST=firstvol,LAST=lastvol,MEDIA=type,
               SCRATCH=Y|N,VENDOR=vendor,RENAME=prefix
//

DELETE mode

Copy 
//EXEC       CTTDLD
//SYSIN      DD      *
    TYPERUN    MODE=DELETE
    RANGE      FIRST=firstvol,LAST=lastvol
//

CONVERT mode

Copy 
//EXEC       CTTDLD,INP='source-data set'
//SYSIN      DD      *
    TYPERUN    MODE=CONVERT
    RANGE      FIRST=firstvol,LAST=lastvol,MEDIA=type,
    VENDOR=vendor,RENAME=prefix
//

The INP parameter in the CTTDLD procedure is mandatory and valid only in CONVERT mode.

The CTTDLD utility is used by the following jobs in the Control-M/Tape installation library:

Table 335 CTTDLD Jobs

Job

Description

CONVTMDB

Converts CA-TLMS tape management system reports to the Control-M/Tape Media database

CONVC4MD or CONVC5MD

Converts from CA-1 (version 4 or 5) to the Control-M/Tape Media database

CONVLCTL

Converts from MVS Catalog to the Control-M/Tape Media database

CONVRMDB

Converts from RMM to the Control-M/Tape Media database

To browse these jobs, use the ICE minor option 3 (TAILOR JOB), available by selecting Maintain your Environment => ICE refresh.

CTTDLD Parameters

Table 336 CTTDLD Parameters

Parameter

Description

The following parameter is specified in the EXEC statement:

INP

Name of the input file containing the data (VWR records) to be converted. Mandatory and valid only in CONVERT mode.

The following parameters are supplied using DD statement SYSIN:

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. Valid values are:

  • ADD — Add volume entries to the Media database.

  • DELETE — Delete scratch volume entries from the Media database.

  • CONVERT — Convert volume entries from another tape management product’s database to Control-M/Tape Media database format.

RANGE

Volume range and attributes. Valid values are:

  • FIRST–First volume serial number in the range. Mandatory.

  • LAST–Last volume serial number in the range. Mandatory.

MEDIA

One of the media types defined in member CTTPARM. Mandatory and valid only in ADD and CONVERT modes.

SCRATCH

Indication of whether the volume is added as scratch. Mandatory and valid in ADD mode only. Valid values are:

  • Y - Yes – Volume is added as scratch.

  • N - No – Volume is not added as scratch.

VENDOR

Vendor of the media. Optional. Valid only in ADD and CONVERT modes.

RENAME

String to replace the prefix of the volume serial number (volser). The SL-name of the volume remains unchanged. Optional. The use of this parameter is valid only in ADD and CONVERT modes. The length of this string must not exceed the length of the prefix in parameters FIRST and LAST (above).

CTTDLD Return Codes

Table 337 CTTDLD Return Codes

Code

Description

0

Operation performed successfully

4

Minor errors occurred – Operation continues

8

See Error message - Execution terminates

12

Loading Control-M/Tape environment failed

16

Error opening DCB – Execution terminates

Greater than 16

Other error – the error is accompanied by an appropriate message indicating the problem – Execution terminates

Examples for CTTDLD

CTTDLD Example 1

Add 3400 type media non-scratch volumes numbered K00100-K00500, made by IBM.

Copy 
//EXEC CTTDLD
//SYSIN DD *
    TYPERUN MODE=ADD
    RANGE FIRST=K00100,LAST=K00500,MEDIA=3400,
        SCRATCH=N,VENDOR=IBM
//

CTTDLD Example 2

Delete volumes numbered K00100-K00500.

Copy 
//EXEC       CTTDLD
//SYSIN      DD *
    TYPERUN  MODE=DELETE
    RANGE    FIRST=K00100,LAST=K00500
//

CTTDLD Example 3

Convert 3490 type volumes numbered K00100-K00500 to Control-M/Tape.

Copy 
//EXEC       CTTDLD,INP='tape.convert'
//SYSIN      DD *
    TYPERUN  MODE=CONVERT
    RANGE    FIRST=K00100,LAST=K00500,MEDIA=3490
//

CTTDLD Example 4

If you are consolidating two tape libraries and both libraries contain tapes with the same volsers, you can rename the volsers for one set of tapes so that no conflict appears in the Media database.

In this example, active 3490 type volumes made by IBM with volsers FX0001-FX0100 are converted to Control-M/Tape, renamed and added to the Media database.

Volsers FX0001-FX0100 are renamed MA0001-MA0100. The SL-names (the internal labels of the volumes) remain FX0001-FX0100.

Copy 
//  EXEC     CTTDLD,INP='TAPE.CONVERT'
//SYSIN      DD *
    TYPERUN  MODE=CONVERT
    RANGE    FIRST=FX0001,LAST=FX0100,MEDIA=3490,
             VENDOR=IBM,RENAME=MA
//

CTTGVL – User Interface to Stacking Facility

The CTTGVL utility assigns a volume to a specific data set before the data set is allocated. The utility returns a volume serial number (according to user specifications) for the file that the user wants to create.

When the CTTGVL utility returns a volume serial number, the volume is assigned a status of In-Use. This status prevents selection of the volume by other users. When a data set is written to the selected volume, the In-Use status is removed from the volume.

If, for some reason, (for example, because no data set was written to the volume) a volume selected by the CTTGVL utility remains with a status of In-Use for three days, the status is removed by the CTTRTM retention management utility, which is normally run as part of the Control-M/Tape New Day procedure.

To select the appropriate volume, the CTTGVL utility scans the Control-M/Tape rules (according to supplied parameters) so that the volume that is returned is allocated from the appropriate pool.

The utility can optionally activate the Control-M/Tape Stacking facility that searches the Media database to locate a volume that has enough free space to hold the new file. Upon user request, or if such a volume cannot be located, a scratch volume can be returned instead.

The CTTGVL utility uses the active Control-M/Tape environment (in ECSA). Therefore, the utility can be called only on a CPU on that the Control-M/Tape environment is initialized.

If the CTTGVL utility is run simultaneously on more than one CPU, an enqueue manager, such as GRS, must be used to ensure that no volume is selected more than once by the utility.

The utility requires APF authorization. Therefore, it must reside in an authorized library and the load module that contains it (if linked to the user program) must also be authorized (parameter AC must be set to 1).

Activating the CTTGVL Utility

This utility is not a standalone utility. It must be called by an application using one of the following methods. See the CTTGVLD sample in the IOA SAMPLE library.

Using a Call Command

Copy 
CALL CTTGVL,(data_set,jobname,stackid,volser,label),VL

Using a Link command

Copy 
LINK EP=CTTGVL,PARAM=(data_set,jobname,stackid,volser,label),VL

CTTGVL Parameters

The CTTCTTGVL Input Parameters

Table 338 CTTGVL Input Parameters

Parameter

Description

DATASET

Name of the data set. Maximum length: 44 characters. Mandatory.

JOBNAME

Name of the job. Maximum length: 8 characters. Optional.

STACKID

Indicator (one character in length) specifying whether stacking is enabled or disabled. Valid values are:

  • Y (Yes) – Stacking is enabled.

  • N (No) – Stacking is disabled.

GVL utility receives parameters in the standard method (Register 1 points to a list of addresses). The following parameters are passed to the utility:

CTTGVL Output Parameters

Table 339 CTTGVL Output Parameters

Parameter

Description

VOLSER

Volume serial number. Six characters must be specified.

LABEL

Hexadecimal representation (two bytes in length) of the label number.

CTTGVL Return Codes

Table 340 CTTGVL Return Codes

Code

Description

0

Function completed successfully

4

No matching volume found

8

Invalid stacking indicator

12

Control-M/Tape is not active

16

Database access failed – a detailed message can be found in the Job log or System log

Example for CTTGVL

Example for CTTGVL

This utility must be called from an application program using one of the following methods:

Using a Call command:

Copy 
CALL CTTGVL,(DSN,JOBNAME,STACKID,VOLSER,LABEL),VL

Using a Link command:

Copy 
CALL CTTGVL,(DSN,JOBNAME,STACKID,VOLSER,LABEL),VL

Assume the following definitions for either of the above methods:

Copy 
DSN        DC    CL44'MY.DSN'     data set name
JOBNAME    DC    CL8'MYJOB'       jobname
STACKID    DC    C'Y'             Stacking indicator
VOLSER     DS    CL6'123456'      Volume serial number
LABEL      DS    H'01'            Label

CTTIDB – Check logical integrity of the Media database

The CTTIDB utility checks the logical integrity of the Media database (MDB) and Stacking database (STK), and checks the relationships between

  • index entries and data records

  • the high and low level entries in the index file

  • records and fields

The CTTIDB utility checks the logical integrity of the database, while the IOADIG utility checks the integrity of the physical structure of the database without referring to its logical data.

When the CTTIDB utility finishes running, it also provides Media Database, Stacking Database, and Trace file statistical information. This includes file size, usage percent, and record type attributes.

If you had previously implemented Dynamic Stacking (by setting DYNSTK to Y in the CTTPARM member), the CTTIDB utility also performs checks on the Stacking Database.

CTTIDB Execution Modes

The CTTIDB utility operates in the following major execution modes:

  • CHECK

    • In CHECK mode the CTTIDB utility

      • checks the logical integrity of the databases

      • issues error messages if inconsistencies are detected

  • REPAIR

    • In REPAIR mode the CTTIDB utility

      • checks the logical integrity of the databases

      • issues error messages if inconsistencies are detected

      • generates CTTMUP input control statements to correct the found errors

      • writes CTTMUP control statements to the &OLPREFT.MTU file.

Not all errors reported by CTTIDB can be repaired in REPAIR mode.
In addition, even for those errors that can be repaired, you may need to run CTTIDB in REPAIR mode and then run CTTMUP several times, until CTTIDB no longer reports any errors. This is because the REPAIR mode does not create CTTMUP control statements that are able to repair all reported errors in the Media Database in a single execution.

Running the CTTIDB Utility

BMC recommends that the CTTIDB utility be run

  • immediately after a system crash

  • after a Control-M/Tape utility abends during processing

  • whenever database statistics are desired

The CTTIDB utility requires exclusive access to the Media Database. Other utilities that access the Media Database (for example, CTTRTM or CTTVTM) cannot run concurrently with this utility. Since the Media Database is being constantly updated when tape datasets are read or written, an accurate state of the database can only be obtained when there is no tape activity.

The TYPERUN Parameter

The TYPERUN parameter is supplied using the SYSIN DD statement. It is used to specify subparameters that affect the general functioning of the CTTIDB utility, and subparameters that affect the execution mode of the utility. The subparameters of the TYPERUN parameter are described below:

Subparameter

Description

MODE

Operation mode. Mandatory. Valid values are:

  • CHECK – Checks the logical integrity of Control-M/Tape databases and issues appropriate error messages when errors are found. Default.

  • REPAIR – Checks the logical integrity of Control-M/Tape databases and issues appropriate error messages when errors are found. A corresponding CTTMUP control statement is generated and sent to the &OLPREFT.MTU file to correct the reported errors.

  • DATACHK – Checks the logical integrity of the data files in Control-M/Tape databases and issues appropriate error messages when errors are found. The index file is not accessed or checked.

USEDAYS

Threshold number of days since the volume was last accessed. Messages are only generated for volumes that are in use for more than the specified number of days. Default: 3 (days)

DELDUP

Deletes duplicate records in REPAIR mode. Optional.
Valid values are:

  • FIRST – Generates a CTTMUP control statement to delete the record with the earliest creation date. Default.

  • LAST – Generates a CTTMUP control statement to delete the record with the latest creation date.

  • NONE – Does not generate any CTTMUP control statement.

ADDRET

Retains newly added dataset in REPAIR mode, only when

  • the volume retention is unknown

  • the volume is marked as active

  • the volume has no datasets.

Optional. Valid values are:

  • NONE – Does not generate any CTTMUP control statement that would add records of new dataset. Default.

  • days – Sets retention date of the newly added datasets to be the current date plus the number of specified days. Numeric.

Syntax for CTTIDB

Use the following command line syntax to activate the CTTIDB utility:

Copy 
//EXEC CTTIDB
//SYSIN DD *
    TYPERUN MODE={CHECK|REPAIR|DATACHK}[,USEDAYS=n]
    [,DELDUP=LAST|FIRST|NONE][,ADDRET=NONE|days]

In the following example, the CTTIDB utility checks the logical integrity of the Control-M/Tape databases and generates input control statements for the CTTMUP utility to correct possible errors:

Copy 
//EXEC CTTIDB
//SYSIN DD *
    TYPERUN MODE=REPAIR

CTTIDB Return Codes

The CTTIDB utility also generates the following return codes:

Return Code

Description

0

Operation performed successfully. No errors found.

8

Problem detected in the Media Database. Execution continues.

10

Problem detected in the Media Database. CTTMUP input control statements have been generated to correct the errors. Execution continues.

12

Severe errors detected. Execution terminates.

CTTMER – Merge records into the Media database

The CTTMER utility is used to merge Media database records into a target Media database using an extract file created by the CTTSPL utility.

There is no need to shut down Control-M/Tape while running this utility.

The CTTMER utility is used together with the CTTSPL utility in the split and merge process. Before using the CTTMER utility, see Split and merge processing (CTTSPL).

After running the CTTMER utility, BMC recommends that you run the CTTVTM utility in SLOTBLD mode to rebuild the slot definitions. After completion of the CTTVTM utility, run the CTTIDB utility to check the integrity of the target Media database.

The CTTMER utility automatically updates the Media database index component. There is no need to run the CTTBIX utility after the run of this utility.

Activating the CTTMER Utility

Copy 
//EXEC       CTTMER,MRGIN=repdata-file
//DAIN       DD *
    TYPERUN  MODE=NORMAL|SIMULATION|RSIMULATE
/*

CTTMER Parameters

Table 341 CTTMER Parameters

Parameter

Description

repdata-file

Extract file created by the CTTSPL utility. The name of this file is supplied using parameter MRGIN. Mandatory.

The extract file is a predefined sequential file (olpreft.olvert.REPDATA) allocated as one of the Control-M/Tape operations libraries at time of Control-M/Tape installation (at the site containing the source Media database).

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. Specify this parameter using DD statement DAIN.

Specify the MODE mandatory subparameter (for the operation mode) using one of the following valid values:

  • NORMAL — Normal operation mode. Records in the extract file are merged into the Media database. Default.

  • SIMULATION — Simulation mode. No changes are made to the Media database. Messages describing simulated operations are sent to the Utility log.

  • RSIMULATE — Restart simulation. If a first run of the CTTMER utility abended, the utility can be rerun in this mode prior to rerunning it in NORMAL mode and thus causing an automatic restart. Only the deletion of records already merged into the Media database is simulated.

Only the deletion of data records, V-keys, D-keys and T-keys is simulated. Deletion of L-keys is not simulated.

Example for CTTMER

In this example the CTTMER utility merges all records in the extract file (CTT.V600.REPDATA) into the Media database.

Copy 
//EXEC        CTTMER,MRGIN=CTT.V600.REPDATA
//DAIN        DD *                             
    TYPERUN  MODE=NORMAL    
/*

CTTMER Return Codes

Table 342 CTTMER Return Codes

Code

Description

12

Merge failed – some of the records to be merged already exist in the target Media database.

16

Unable to access the restart information from the Trace file

20

Simulation mode is not allowed while restart is required.

24

Another utility is currently executing – the Media database is locked.

28

Restart processing failed.

Greater than 28

Severe error – the error is accompanied by a message describing the problem.

CTTMUP – Manually Update the Control-M/Tape Repository

The CTTMUP utility can be used to update information in the Media database, the Stacking database and the Trace file. This utility is especially useful for modification of information for a small number of data sets or volumes (for example, to correct file integrity errors that resulted from a system crash or a utility abend).

WARNING: The CTTMUP utility modifies your tape management information. Use this powerful utility with caution.

Before running the CTTMUP utility, it is important to familiarize yourself with the structure of the file you are planning to update, as described in Control-M/Tape chapter of the INCONTROL for z/OS Administrator Guide. Attempting to update tape management information without proper understanding of the structure of the relevant file can lead to integrity errors.

Updating the Media database (CTTMUP)

The CTTMUP utility can update fields of a volume or data set record in the Media database (MDB). Update is performed independently for volume and/or data set records. When updating a volume record, the CTTMUP utility does not automatically update the corresponding data set records and vice versa. (For example, the data set count in a volume record is not updated when the CTTMUP utility adds a data set.) Therefore, when using this utility, be sure to update all connected records. For more information, see Special notes regarding Media database control statements (CTTMUP)).

When a data set is added, the CTTMUP utility can optionally search the rules (as if the data set is being created on removable media) to determine retention and vaulting criteria to be assigned to the data set and the volume containing the data set.

For a general description of how this utility can be used to update the Media database, see the Control-M/Tape chapter of the INCONTROL for z/OS Administrator Guide.

Updating the Stacking database (CTTMUP)

Run the CTTMUP utility to update fields in the Stacking database. For example, the CTTMUP utility can modify the expected length of a data set, or indicate if a data set is stackable.

Before updating the Stacking database using the CTTMUP utility, BMC recommends that you run the CTTSTKR utility to generate a report from information currently in the Stacking database. This report helps you determine what (if any) changes need to be made to the Stacking database.

Activating the CTTMUP Utility

Copy 
//EXEC       CTTMUP
//SYSIN      DD *
    TYPERUN  MODE=NORMAL|SIMULATION[,RULEINFO=YES|NO][,             CHECK=YES|NO][,APPLY=GROUP]
    <CONTROL STATEMENTS>

CTTMUP Parameters

The following parameters can be specified for the CTTMUP utility:

Only parameter MODE is relevant for updates to the Stacking database. If other parameters are specified, they are ignored while the utility is updating stacking statistics records.

Table 343 CTTMUP Parameters

Parameter

Description

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.

    • SIMULATION — Simulation mode is performed.

  • RULEINFO — Whether to apply rule information (for example, Retention criteria) when adding a data set to the Media database.

    • Yes — Apply rule information to the Media database record. Default.

    • No — Do not apply rule information to the Media database record.

  • CHECK — Whether to check Media database integrity after performing the requested changes.

    • Yes — Check the integrity of the Media database. Default.

    • No — Do not check the integrity of the Media database.

  • APPLY — Determines which volumes are affected by the VOLUPD control statement. Optional. Valid value:

    • GROUP — The VOLUPD statement is applied to all volumes in the multi-volume chain containing the volume specified in the VOLSER field of the VOLUPD statement.

If parameter APPLY is not specified, the VOLUPD statement is applied only to the volume specified in the VOLSER field of the VOLUPD statement.

CTTMUP Control Statements

Control statements specify the update function to be performed, the fields to be updated and the update values.

This topic lists valid control statement functions for Media database updates, Stacking database updates, and Trace updates, followed by information on specifying fields and values.

Media database update control statements (CTTMUP)

Some of the functions are valid for volume type records only and some functions are valid for data set records only. For a list of Media database fields that can be updated by this utility, see the appendix that discusses logical field names for the Control-M/Tape Repository in the INCONTROL for z/OS Administrator Guide. (They are the same fields that can be specified in INCLUDE / EXCLUDE statements of other utilities.)

Table 344 CTTMUP Media database update control statements

Statement

Description

DSDELL

Delete L-type key for a volume. Two fields are mandatory for this function:

  • DSVOLSER – Data set volume serial number

  • DSLABEL – Data set label number

DSNADD

Add data set record. Three fields are mandatory for this function:

  • DSVOLSER – Data set volume serial number

  • DSLABEL – Data set label number

  • DSNAME – Data set name

When adding a new dataset record to a scratch volume, all data sets of the volume are automatically deleted and the volume becomes active.

DSNDEL

Delete data set record. The record to be deleted must be identified by specifying both

  • DSVOLSER – Data set first volume

and

  • DSLABEL – Data set label number

or

  • DDSRBA – Internal database record identifier

One of these two sets of fields is mandatory

If DDSRBA is used to identify the record, DSVOLSER and DSLABEL can also be specified for verification

If DSNAME is specified, it is used for verification only

DSNEXT

Extend the retention of a data set by a specific number of days. Three fields are mandatory for this function:

  • DSVOLSER – Data set volume serial number

  • DSLABEL – Data set label number

  • DAYS – Number of days by which to extend the data set

DSNUPD

Update data set record. The record to be updated must be identified either by specifying both

  • DSVOLSER– Data set volume serial number

and

  • DSLABEL–Data set label number (file sequence),

or by specifying

  • DDSRBA– Internal database record identifier

One of these two sets of fields is mandatory.

If DSNAME is specified, it is used for verification only. The data set name cannot be modified.

DSNUPDN

Update data set name (the DSNAME field in the data set record). Only the following parameters are valid for this control statement:

  • NEWNAME – New data set name. Mandatory.

  • DSNAME – The current data set name (before update). This parameter is used for verification only. The data set cannot be modified.

The record to be updated must be identified either by specifying both

  • DSVOLSER – Data set volume serial number

and

  • DSLABEL – Data set label number (file sequence)

or by specifying

  • DDSRBA – Internal database record identifier

One of these two sets of fields is mandatory.

GRPBIX

Rebuild the indexes of all the volumes and of all the data sets in the group. One of the volumes in the group must be identified by one of two fields (either field is mandatory):

  • VOLSER – Volume serial number of a volume in the group.

or

  • DVLRBA – Internal database record identifier of a volume in the group.

If DVLRBA is used to identify the volume, VOLSER can also be specified for verification.

GRPSCR

Expire all data sets of all the volumes in the group and change the status of those volumes to scratch.

  • VOLSER – Volume serial number of one of the volumes in the group.

  • DEFERRED – Choose deferred (or immediate) scratch. Optional. Valid values are:

  • - Yes – Perform deferred scratch.

  • - No – Perform immediate scratch. Default.

RECDEL

Delete Media database record (any type). One field is mandatory for this function: The field is RBA, the internal database record identifier.

RECUPD

 

Modify records of any type in the Media database (for example, Restart Control records, Slot Definition records).

This function includes the following control statements:

Copy 
RECUPD RBA=rba
VER    offset data
REP    offset data
ENDUPD

Statement RECUPD selects a records from the Media database for update. It must be the first statement specified. This statement includes the following parameters:

  • RBA – Update internal database record identifier.

  • VER – Verify existing data before updating the record.

  • REP – Replace existing data with new data.

  • ENDUPD – Identifies the end of the RECUPD function. It must be the last statement in this function.

An unlimited number of paired VER and REP statements can follow the RECUPD statement. These statements are formatted like the VER and REP statements of MVS utility AMASPZAP:

Data is provided in both the VER and REP statements, as follows:

  • offset – Offset of the data from the beginning of the record (four digits in hexadecimal format, from 0000 through 01CC).

  • data – Record data for verification or replacement (in hexadecimal ZAP format).

This example updates the volume record with the statement RBA=00000104. Two status bytes are verified on offset 0005 and status IN-USE then set.

Copy 
RECUPD    RBA=00000104
VER       0005 8000
REP       0005 8002
ENDUPD

VOLADD

Add volume. One field is mandatory for this function, :VOLSER, the volume serial number.

VOLBIX

Rebuild the indexes of a volume and of all its data sets. The volume must be identified by one of two fields (either field is mandatory):

  • VOLSER – Volume serial number

or

  • DVLRBA – Internal database record identifier

If DVLRBA is specified to identify the volume, VOLSER can also be specified for verification.

VOLDEL

Delete volume. The volume to be deleted must be identified by one of two fields (either field is mandatory):

  • VOLSER – Volume serial number

or

  • DVLRBA – Internal database record identifier

If DVLRBA is used to identify the volume, VOLSER can also be specified for verification.

VOLSCR

Expire all the data sets in the volume and change the status of the volume to scratch.

  • VOLSER – Volume serial number. Mandatory.

  • DEFERRED – Choose deferred (or immediate) scratch. Optional. Possible values are:

    • Yes – Perform deferred scratch.

    • No – Perform immediate scratch. Default.

VOLSCRF

Scratch a volume in the Media database regardless of integrity errors. BMC recommends that you use this function only if an error occurred while trying to scratch a volume using the VOLSCR or GRPSCR functions. In addition to scratching the volume, all datasets of the volume are deleted from the Media database, and others volumes of that multi-volume group may not be cleared.

This function affects the current volume only. To scratch a multi-volume group, use this function separately for each volume that belongs to the multi-volume group.

VOLUPD

Update volume. The VOLSER field (volume serial number) is mandatory for this function:

Stacking database update control statements (CTTMUP)

Stacking database fields that can be updated by this utility are listed in the appendix to the INCONTROL for z/OS Administrator Guide that discusses logical field names for the Control-M/Tape Repository.

Table 345 CTTMUP Stacking database update control statements

Statement

Description

STKADD

Add a record to the Stacking database. The following fields are mandatory for this function:

  • JOBNAME – Name of the job that created the first generation of the data set

  • DSNAME – Data set name

STKUPD

Delete a record from the Stacking database (STK). The following fields are mandatory for this function:

  • JOBNAME – Name of the job that created the first generation of the data set

  • DSNAME – Data set name

STKDEL

Update a record in the Stacking database. The following fields are mandatory for this function:

  • JOBNAME – Name of the job that created the first generation of the data set

  • DSNAME – Data set name

Trace Update Control Statement (CTTMUP)

Table 346 Trace Update Control Statement

Statement

Description

TRCUPDQ

Change the QNAME in the Control-M/Tape Trace file to the QNAME in the IOAPARM member.

Special notes regarding Media database control statements (CTTMUP)

DSNEXT function

This function is intended for use with data sets that have a specific retention date. Data sets that have a non-specific retention type (for example, MVS Catalog, Permanent) cannot be extended using this function. When data set retention is extended, the retention date is added to the number of specified days.

This function can be used with DAYS set to 0 to remove "pending-scratch" status from a data set, without actually extending its retention date.

This function can also be used to unscratch data sets. When DSNEXT is used against a scratch data set, the data set becomes active. If the volume itself was also scratch, the entire volume and its data sets become active. The new retention date becomes the current date plus the number of days specified.

VOLBIX function

This function is intended for use only when the CTTIDB utility detected errors with V-indexes (volume indexes). Do no use this function for L-index problems.

GRPBIX function

Be sure that you have corrected all V-indexes before using this function.

This function corrects problems of L-indexes and D-indexes. It can be applied for a single volume as well as for a multi-volume group.

VOLUPD function

  • When this function is used to update the MEDIA, LOCATION, or SLOTNUM fields of the volume, the slot in which a vaulted volume resided remains in status INUSE.

    In this case, to synchronize the Slot Definition Records in the Media database, run the CTTVTM utility with the following control statement:

    Copy 
    TYPEVLT MODE=SLOTBLD

  • A single status bit can be set in a specific status byte of a volume or data set record.

    For example, to turn on the PVLT (Potential Vault) status on a volume record, include the following statement:

    To turn off the above status bit include the following:

    Copy 
    VOLUPD.....,VOLIND=-PVLT

VOLSCR and GRPSCR functions

Immediate scratch of volumes or groups of volumes is not reflected in subsequent scratch reports of the CTTRTM utility. If you want to include these volumes in the next scratch report, set DEFERRED to YES. This way, volumes are scratched during the next run of the CTTRTM utility.

VOLSCRF function

This function is intended for use only after integrity errors occurred while trying to scratch records using the VOLSCR or GRPSCR function.

This function affects single volumes only. To scratch a multi-volume group, specify this function for each volume separately.

Specifying CTTMUP Fields and Values

Consider the following points when specifying fields and values for this utility:

Table 347 CTTMUP Fields

Field

Description

Date Fields

Format is yymmdd or yyyymmdd.

Time Fields

Format is hhmmss.

Numeric Fields

Leading zeroes are not required. Hexadecimal values must be prefixed with an X (for example, DVLRBA=X01234567 instead of DVLRBA=01234567). The only exception to this is the VER and REP fields.

Embedded Blanks

Use only if the value is enclosed in either single or double quotes.

Quotation Marks (‘ or ")

If the value begins and ends with either single or double quotes, the quotation marks are interpreted as markers of the beginning and end of the value. To include a quote mark in a string (value), use the other type of quote mark to mark the beginning and end of the string. For example, a single quote (apostrophe) can only be included in the value if the value is enclosed in double quotes (").

Null Values

Specify a null value for a field by specifying the field without a value (for example, VOLSER=).

Retention Criteria Fields

Specification of retention criteria requires two fields or values:

  • Retention type

  • Retention data

If retention data is specified without specifying the retention type, the retention type defaults to DATE.

Fields with Predefined Valid Values

Certain fields have a predefined set of valid values (for example, valid values for field VOLSTAT are ACTIVE, VAULTED).

Valid values for these fields are listed in the appendix to the INCONTROL for z/OS Administrator Guide that discusses logical field names for the Control-M/Tape Repository. Values can also be specified in hexadecimal format (for example, VOLSTAT=X88 meaning Active and Vaulted).

Status Bits

A single status bit can be set in a specific status byte of a volume or data set record.

For example, to turn on status PVLT (Potential Vault) on a volume record, include the following statement:

VOLUPD.... ,VOLIND=+PVLT

To turn off the above status bit, include the following:

VOLUPD.... ,VOLIND=-PVLT

Specific Recommendations (CTTMUP)

Table 348 CTTMUP Parameter Recommendations

Field

Description

LBLNUM

Last active label number on the volume. The value of this parameter can be greater than, but cannot be less than the value of ACTIVEDS (the number of active data sets on the volume).

If the value of the LBLNUM field is lower than the value of ACTIVEDS, the value will be automatically copied from the ACTIVEDS field. If the value of the ACTIVEDS field is zero, the LBLNUM value will be automatically set to zero.

CTTMUP Return Codes

Table 349 CTTMUP Return Codes

Code

Description

0

Operation performed successfully

4

Minor errors occurred during the update process. Operation continues.

8

Either an error occurred during execution, or errors were encountered during the logical integrity check of the database. If it is an execution error, the utility continues to process the next statement.

12

A severe error occurred during execution. The utility stopped execution.

16

Data Base integrity errors occurred during execution

20

Input Control Statement error

24

Authorization failure (by security exit)

28

Invalid return code from routine CTTEXM

32

Error while trying to delete the data set records of the volume

Examples for CTTMUP

CTTMUP Example 1

Convert scratch volume DDD020 to active status and add data set FILE7 to the volume.

Copy 
//EXEC      CTTMUP
//SYSIN     DD *
  TYPERUN   MODE=NORMAL
  VOLUPD    VOLSER=DDD020,ACTIVEDS=1,VOLSTAT=ACTIVE
  DSNADD    DSVOLSER=DDD020,DSLABEL=1,DSNAME=FILE7,
  CREDT=990622,CRETM=142500,CREJBN=JOB1

CTTMUP Example 2

Rebuild a chain of two volumes. The first volume, PRD001, has two data sets on it. The second data set reached the end of the first volume and continued on the second volume, PRD002.

Copy 
//JOB NAME   JOB ....
//CTTMUP     EXEC CTTMUP
//SYSIN      DD *
  TYPERUN    MODE=NORMAL,RULEINFO=YES,CHECK=NO
  VOLUPD     VOLSER=PRD001,VOLSTAT=ACTIVE,VOLSEQ=1,
             ACTIVEDS=2,LBLNUM=2,MEDIA=3490,
             LOCATION=MAINLIB,FIRSTVOL=PRD001,
             NEXTVOL=PRD002,PREVVOL=
  VOLUPD     VOLSER=PRD002,VOLSTAT=ACTIVE,VOLSEQ=2,
             ACTIVEDS=1,LBLNUM=2,MEDIA=3490,
             LOCATION=MAINLIB,FIRSTVOL=PRD001,
             NEXTVOL=,PREVVOL=PRD001
  DSNADD     DSVOLSER=PRD001,DSLABEL=1,
             DSNAME=PROD.BACKUP.G0001V00,VOLSNUM=1
  DSNADD     DSVOLSER=PRD001,DSLABEL=2,
             DSNAME=PROD.BACKUP.G0002V00,VOLSNUM=2
//

Considerations

  • This example assumes that PRD001 and PRD002 are defined in the Media database and are in SCRATCH status. If these volumes are not defined in the Media database, you must change the first two control cards from VOLUPD to VOLADD.

  • Parameter ACTIVEDS is set to 2 for PRD001 because PRD002 contains the two data sets. PRD002 contains only the second data set, so ACTIVEDS is set to 1 for PRD002.

  • LBLNUM is set to 2 for both volumes because the highest label number on both of volumes is label 2.

  • The second data set, PROD.BACKUP.G0002V00 has VOLSNUM set to2 because it spans the two volumes.

  • The expression RULEINFO=YES indicates that retention and vaulting attributes are automatically taken from the rules. It is therefore unnecessary to specify retention and vaulting information.

CTTMUP Example 3

Update a record in the Stacking database to indicate that data set ACCT.JAN1 is stackable and update a different record in this file to indicate new maximum and minimum lengths for data set ACCT.FEB2.

Copy 
//CTTMUP     EXEC CTTMUP
//SYSIN      DD *
  TYPERUN  MODE=NORMAL,CHECK=NO
  STKUPD   DSNAME=ACCT.JAN1,JOBNAME=JOB1,STATUS=STK
  STKUPD   DSNAME=ACCT.FEB2,JOBNAME=JOB2,MAXSIZE=20480,MINSIZE=1024
//

CTTRCV – Recover the Media database using trace file

The CTTRCV utility recovers damaged Media database (MDB) contents according to trace data recorded during MDB update operations. The utility can perform either a physical or a logical recovery.

  • Physical Recovery (Roll Forward)

    • Physical recovery assumes that the last available backed up MDB was restored to disk, as described in the topic CTTTRB – Synchronize Trace file and Media database backup. From this point forward, recovery is performed according to trace data.

      By default, the Control-M/Tape daily job uses the DFSMSdss to back up the MDB. In this case, you must use the DFSMSdss RESTORE command to restore the backed up MDB

    • Trace records are read starting with the first record after the Media database backup record. Recovery continues until the last trace record is reached. When the process is finished, the MDB returns to the condition it was in before it was damaged.

    • In situations where no MDB backup has been performed, the recovery can be started from the first trace record.

    • To prevent unpredictable results, the Control-M/Tape environment must be inactive while the physical recovery process is running.

  • Logical Recovery (Roll Back)

    • Logical recovery rolls back selected changes from the current MDB. This type of recovery can be performed when a user modifies the status of one or more MDB records and then discovers that these modifications must be reversed. A good example of this scenario is when a job is run that scratches a series of active volumes or moves a series of volumes to a vault incorrectly.

    • When this type of recovery is used, the trace records are read backward (that is, starting from the last record towards the first record). The improper modifications are reversed in a way that restores the MDB to the condition it was in prior to the improper modifications.

    • To maintain the logical consistency of the MDB, the CTTRCV utility verifies that the current contents of the MDB match the tracked information in the Trace file.

  • For example, if the status of a volume was changed from Active to Scratch by TSO user ABC and a logical recovery is performed on all operations performed by user ABC, the utility verifies that the current volume status in the MDB is Scratch before the recovery reverses the operation.

    You can bypass this check by setting FORCE to either YES or LOGICAL. However, this may cause unpredictable results.

Activating the CTTRCV Utility

Copy 
//EXEC      CTTRCV
//SYSIN     DD *
    RECOVER TYPE=PHYSICAL|LOGICAL[,
            MODE=SIMULATION|NORMAL][,
            FROMREC=LASTBKP|FIRSTREC][,CHECKACT=YES|NO][,
            RECAT=YES|NO][,FORCE=YES|NO]
    <INCLUDE/EXCLUDE STATEMENTS>
//

WARNING: This utility updates the database using the tracked RBA record from the Trace file. To prevent a possible integrity error in the database, you must perform the following steps in sequence after running the CTTRCV utility:

  • Run the IOADIG utility with the FUNC parameter set to W.

  • Rebuild the index with the CTTBIX utility.

CTTRCV Parameters

Utility parameters are supplied using DD statement SYSIN:

Table 350 CTTRCV SYSIN Parameters

Parameter

Description

RECOVER

Determines which type of recovery is performed

  • TYPE — Type of the recovery. Mandatory.

    • PHYSICAL — A physical (roll forward) recovery is to be    performed.

    • LOGICAL — A logical (roll back) recovery is to be performed.

  • MODE — Mode of recovery. Optional.

    • SIMULATION — Simulation mode. Trace records, and    Media database records when needed, are read. The Media database is not updated and data sets are not recataloged.

    • NORMAL — Normal mode. Default. Trace records, and     Media database records when needed, are read. Updates are actually performed on the Media database (that is, the Media database is updated).

  • FROMREC — Starting point of the recovery. Can only (and must) be specified when TYPE is set to PHYSICAL.

    • LASTBKP — The recovery starts from the point where the Media database was last backed up.

    • FIRSTREC — The recovery starts from the first Trace record. This option is useful for new sites that have not yet performed any Media database backups.

  • CHECKACT — Check if Control-M/Tape is active before starting the recovery. When recovery is performed, the Control-M/Tape Real-time environment must not be active (that is, it must be down or suspended). In simulation mode, this parameter has no effect.

    • Yes — If Control-M/Tape is active, recovery is not started. Default.

    • No — Recovery is started regardless of whether Control-M/Tape is active.

Warning: If No is specified when Control-M/Tape is active, Media database integrity can be lost and unpredictable results can occur.

Use this value to initiate a recovery in a test environment on a test Media database while the production environment is still active.

  • RECAT — In logical (roll back) recovery, recatalog data sets that were uncataloged by the CTTRTM utility.

    • Yes — Recatalog all data sets that were uncataloged.

      The same catalog environment that existed for the CTTRTM utility is required by the CTTRCV utility.

    • No — Do not recatalog data sets.

  • FORCE–In logical (roll back) recovery, indicates whether a check is performed to verify that the current contents of the Media database match the operation that is reversed.

    • Y (Yes) — Perform the reversal operation without performing the check.

      Warning: Specifying Y (Yes) can cause unpredictable results and the loss of Media database integrity.

    • L (Logical)–Perform the check. The changes for the Media database records that pass this check (and therefore match the operation being reversed) are rolled back. Records that do not pass the check are not affected.

    • N (No)–Perform the reversal operation only if all checks were completed successfully.

INCLUDE / EXCLUDE

The scope of the utility can be limited by one or more INCLUDE / EXCLUDE statements. INCLUDE / EXCLUDE statements are optional and are valid only when a logical (rollback) recovery is performed (meaning, TYPE is set to LOGICAL).

For more information about INCLUDE / EXCLUDE statements for this utility, see the discussion in the appendix to the INCONTROL for z/OS Administrator Guide that discusses logical field names for the Control-M/Tape Repository.

For additional information on INCLUDE / EXCLUDE statements, see Record Selection Logic (INCLUDE / EXCLUDE Statements) (CTM).

CTTRCV Return Codes

Table 351 CTTRCV Return Codes

Code

Description

0

Recovery operation performed successfully.

4

Input statements missing.

8

DCB open error occurred.

12

Input statement parsing error or validation error occurred.

16

Loading Control-M/Tape environment failed.

24

Media database or Trace file I/O error occurred.

28

Logical error in Media database (for TYPE=LOGICAL).

32

Control-M/Tape Real-time environment is active.

Examples for CTTRCV

CTTRCV Example 1

Recover a damaged Media database. The last available Media database backup has been restored to disk.

Copy 
//EXEC   CTTRCV
//SYSIN  DD *
         RECOVER TYPE=PHYSICAL,FROMREC=LASTBKP

CTTRCV Example 2

Reverse all changes performed by user M27A from July 19th, 13.40.00, to July 22nd, 12.24.45:

Copy 
//EXEC        CTTRCV
//SYSIN       DD *
            RECOVER TYPE=LOGICAL,RECAT=YES
            INCLUDE
            JOBNAME=M27A,DATE=20000719,TIME>134000
            INCLUDE JOBNAME=M27A,DATE>20000719
                EXCLUDE DATE>20000721
            INCLUDE JOBNAME=M27A,DATE=20000722,TIME<122445

CTTRLPT – Rule simulation report utility

The CTTRLPT utility simulates the application of rules to dataset records in the Media database (MDB). It generates reports with dataset fields, showing the effect of rules’ ON statements, and the corresponding rules’ DO statements, on the selected dataset. Various parameters can be used to format and to filter the report produced by this utility (for example, to describe only report for specified datasets).

Activating the CTTRLPT Utility

Copy 
//EXEC CTTRLPT
//SYSIN DD *
<INCLUDE/EXCLUDE STATEMENTS>
REPORT NAME=RULE
FIELDS ...|ALL
[SORTBY ...]
[ATTR ...]
[BREAK ...]
//

CTTRLPT Parameters

Table 352 CTTRLPT Parameters

Parameter

Description

INCLUDE/
EXCLUDE

The information to be processed can be filtered by one or more INCLUDE EXCLUDE statements. Valid values that can be specified in these INCLUDE/EXCLUDE statements are listed in the appendix that discusses logical field names for the Control-M/Tape Repository in the INCONTROL for z/OS Administrator Guide.

If no INCLUDE/EXCLUDE statement is specified, a report is created for all records in the MDB Database. For more information about INCLUDE/EXCLUDE statements, seeRecord Selection Logic (INCLUDE / EXCLUDE Statements) (CTM). Optional.

REPORT

The report to be produced by the utility. Mandatory.

  • NAME – Report name. Mandatory. Valid value is:

    • RULE – Rule Selection Report listing all requested information for the Control-M/Tape-controlled datasets.

  • FOLD – Indicates whether all report data is printed in uppercase. Valid values are:

    • YES – Print all report data in uppercase.

    • NO – Print report data in upper and lowercase. Default.

  • PAGESIZE – Maximum lines on a page, where p is a numeric value greater than 20. Optional. Default: 63.

  • LINESIZE – Maximum characters in a line, where s is a numeric value not greater than 255. Optional. Default: 127.

  • MARGINS=m-n – Lowest (m) and highest (n) columns in a line, where m is a numeric value greater than 0 and n is a numeric value greater than m but not greater than s (the value of LINESIZE). Optional. Defaults: m=1 and n=s.

  • SUMMARY=YES|NO – Indicates whether to show a summary line for each field break. Optional. Default: NO.
    A field break occurs when there is a change in value for a field that is specified in a SORTBY statement with option /BRK(or/B).

  • OUTDD – JCL DD name of the output. Default: REPOUT.

FIELDS

Fields to print in the report. The fields are printed in the order specified. Available values:

  • ALL – Special value indicated to print special report including full rules information and summary of rule usage.

Dataset and volume fields (ONoptions):

  • CREJBN – Name of the job that created the dataset.

  • DSNAME – Name of the dataset.

  • DSVOLSER – First volume in which dataset resides.

  • CREPGM – The name of the program, which creates the dataset.

  • CREUSER – The name of the user, who creates the dataset.

  • SMSMC – SMS management class.

  • MEDIA – Volume media type.

  • ACCOUNT – Account information for this dataset.

  • JCLEXPDT – JCL parameter JCLEXPDT for this dataset.

DO options:

  • DOSTACK – DO STACK condition for this dataset

  • DOPOOL – DO POOL condition for this dataset

  • DOVAULT – DO VAULT condition for this dataset

  • DORET – DO RETENTION condition for this dataset

  • DORET2 – DO RETENTION_2 condition for this dataset

  • DORET3 – DO RETENTION_3 condition for this dataset

  • RRULNM – Rule name for DO RETENTION condition

  • SRULNM – Rule name for DO STACK condition

  • VRULNM – Rule name for DO VAULT condition

  • PRULNM – Rule name for DO POOL condition

  • RRULTB – Rule table name for DO RETENTION condition

  • SRULTB – Rule table name for DO STACK condition

  • VRULTB – Rule table name for DO VAULT condition

  • PRULTB – Rule table name for DO POOL condition

SORTBY

Order in which the report is sorted. Optional. (Available fields are listed above, under parameter FIELDS.) The /B (or /BRK) option 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.

This parameter cannot be used when FIELDS=ALL is specified.

ATTR

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

This parameter cannot be used when FIELDS=ALL is specified.

BREAK

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

This parameter cannot be used when FIELDS=ALL is specified.

For a description of the options of these statements, see the FIELDS, SORTBY, ATTR, and BREAK statements inCTTRPT – Database extraction and report utility.

CTTRLPT Return Codes

Table 353 CTTRLPT Return Codes

Code

Description

0

Operation performed successfully

8

Missing DD statements or open error occurred

12

Control card error

16

Loading Control-M/Tape environment failed

Example for CTTRLPT

The following example extracts dataset records with the name BACKUP.DAYLY from the Media database, and produces a full rule selection report for these datasets:

Copy 
//EXEC CTTRLPT
//SYSIN DD *
 INCLUDE DSNAME=BACKUP.DAYLY
 REPORT NAME=RULE
 FIELDS ALL
/*

Figure 125 CTTRLPT output report example

Copy 
BMC SOFTWARE, INC.  CONTROL-M/Tape REPORT (REL 6.1.11) DATE 01 02 2004 TIME 15.39      PAGE     1
                             Rules simulation report
                             -----------------------
+------+-----------------------------+---------+---------+---------+------+----------+
|Volume|    Dataset Name             | Jobname | Program |  User   |  SMS | Account  | |  |            
+----+-+-----------------------+-----+-----+---+--------++---------+------+----------+
|       Do Condition      | Rule Name | Table Name | Rule Table Library Name | |     
+-------------------------+-----------+------------+-------------------------+

111111  BAKUP.DAYLY                   K27ABCKP  IEBGENER   K27A

      DO STACK = Y                BACKUP      RULE1        CTTP.V610.RULES
      DO POOL  = PAYROLL          BACKSYS     RULE3        CTTP.V610.RULES
      DO VAULT = REMOTE03         BACKUP      RULE1        CTTP.V610.RULES
           UNTIL DAYS   0015
                 BASEMENT
           UNTIL DS EXPIRE
      DO RET   = CATALOG          BACKUP      RULE1        CTTP.V610.RULES
      DO ABRET = DAYS   0001      BACKUP      RULE1        CTTP.V610.RULES
......................................................................................
222222  BAKUP.DAYLY                   K27ABCKP  ADRDSSU    J406

      DO STACK = Y                BACKUP      RULE1        CTTP.V610.RULES
      DO VAULT = REMOTE01         BACKUP      RULE2        CTTP.V610.RULES
           UNTIL DAYS   007
      DO RET   = DAYS   0007      RETRULE     RULE5        CTTP.V610.RULES
      DO ABRET = DAYS   0003      *CTTARM ...............................................

BMC, INC. CONTROL-M/Tape REPORT (REL 6.1.11)  DATE 01 02 2004 TIME 15.39      PAGE     2

          Summary rules usage statistics
          ------------------------------

  Usage     Rule Name  Rule Table  Table Library
----------  ---------  ----------  -----------------------------
NOT IN USE  BACKGEN1   RULE3       CTTP.V610.RULES
NOT IN USE  BACKGEN2   RULE3       CTTP.V610.RULES
  00003     BACKSYS    RULE3       CTTP.V610.RULES
NOT IN USE  BACKTEST   RULE3       CTTP.V610.RULES
  00005     BACKUP     RULE1       CTTP.V610.RULES
  00001     BACKUP     RULE2       CTTP.V610.RULES
NOT IN USE  BACKUP1    RULE1       CTTP.V610.RULES
  00001     RETRULE    RULE5       CTTP.V610.RULES
NOT IN USE  VAULT1     RULE3       CTTP.V610.RULES
NOT IN USE  VAULT2-S   RULE3       CTTP.V610.RULES

CTTRPT – Database extraction and report utility

The CTTRPT utility extracts data from the Media database (MDB) using Extract parameters and generates reports from the extracted data using Report Formatting parameters.

Data extraction and report generation are performed in a single utility run. Both Extraction parameters and Report Formatting parameters are specified in the utility run.

Instead of extracting entire records, the utility only extracts information required for the report from the Media database (or from the extracted data set described above) and produces the report. There is no need to create a data set for saving the extracted information, although this can be done if desired.

This method of report generation is the most efficient when a single report is required.

It is also most efficient when all the data requirements of subsequent reports can be satisfied from the extracted data (meaning, when no additional data is required by subsequent reports). In this case, the extracted data is saved in a data set for subsequent runs of the utility.

At least one group of parameters must be specified, such as Extract parameters or Report Formatting parameters.

The data set for holding extracted information is specified in DD statement REPDATA.

Primary Key, Primary Fields and Primary Lines in Report Generation

The user can define up to two lines that comprise the report output (meaning, the user determines which fields are included in the report lines).

Many fields in a report maintain the same value for many records (for example, vault name for a multi-volume group). These fields are called primary fields and one of them is the primary key. (The field that is the primary key and the fields that are the primary fields are determined by the type of report being created.)

By setting parameter ID to P (Primary) or S (Secondary), the user can designate a report line as a primary line. Primary lines are only printed when the primary key changes value.

The primary key and the primary fields are determined as follows:

  • In the GENERAL report, the primary key is determined by the PATH parameter specified in the EXTRACT statement.

    • If PATH is set to VOLUME/ALLDATASETS or to VOLUME/FIRSTDATASET, the primary key is the volser and the primary fields are the fields extracted from volume record.

    • If PATH is set to DATASET/ALLVOLUMES or to DATASET/FIRSTVOLUME, the primary key is the volser and sequence number of the data set; and the primary fields are the fields extracted from the data set record.

  • In the DISTRIB report, the primary key is the volser of the volume (or the volser of the first volume in a multi-volume chain) and the primary fields are the fields that have the same value for all volumes in the chain (for example, From Location and To Location) and the fields extracted from the data set record that determined the vaulting pattern.

  • In the SCRATCH report, the primary key is the volume’s volser (or the first volume’s volser in a multi-volume chain) and the primary fields are the fields extracted from the expiration data set record.

Activating the CTTRPT Utility

Copy 
//EXEC     CTTRPT
//REPDATA  DD DSN=extract-data_set
//SYSIN    DD *
  [
<EXTRACT parameters>
<REPORT parameters>
  ]

CTTRPT Parameters

Utility parameters are supplied using DD statement SYSIN:

CTTRPT EXTRACT Parameter

Copy 
EXTRACT PATH=path[,RCLLOC=ASIS|VAULT]
<INCLUDE/EXCLUDE statements>

In the EXTRACT parameter statement, PATH specifies the type of records to be extracted. Valid values are described in Table 354.

Table 354 CTTRPT Extract Parameter PATH Values

Value

Description

VOLUME

Volume records are extracted.

VOLUME/
FIRSTDATASET

Volume records with only their first data set records are extracted. Abbreviation: VOLUME/FIRSTDS.

VOLUME/
ALLDATASETS

Volume records with all their data set records are extracted. Abbreviation: VOLUME/ALLDS

DATASET

Data set records are extracted.

DATASET/
FIRSTVOLUME

Data set records with only their first volume records are extracted. Abbreviation: DATASET/FIRSTVOL

DATASET/
ALLVOLUMES

Data set records with all their volume records are extracted. Abbreviation: DATASET/ALLVOLS

In the EXTRACT parameter statement, RCLLOC controls the report of the LOCATION field from the volume record for recalled volumes. Valid values are described in Table 355.

Table 355 CTTRPT Extract Parameter RCLLOC Values

Value

Description

VAULT

Report the LOCATION as the vault name where the volume should be returned. If, while recalling the volume, the slot in the vault was freed, the LOCATION field will be reported as MAINLIB. In addition, the VAULTED flag of the volume will be reported as turned on, although it is not in the Media database. Default.

ASIS

Report the LOCATION field as currently saved in the Media database. During recall the LOCATION is always MAINLIB. Be aware that the slot number field, SLOTNUM, will be zero or the vault or MAINLIB slot number, according to the recall parameter (whether the vault slot number was freed or not) and whether there are slots in MAINLIB

Multiple EXTRACT statements can be specified in the SYSIN DD statement, but each additional EXTRACT statement must follow the INCLUDE and EXCLUDE statements (if any), and the Report Parameter statements of the preceding EXTRACT statement. When saving extracted data in a data set, if several EXTRACT statements are specified, only the data extracted by the last EXTRACT statement is stored.

CTTRPT INCLUDE / EXCLUDE Statements

The scope of extraction can be limited by a combined maximum of 1000 INCLUDE / EXCLUDE statements.

INCLUDE / EXCLUDE statements can be specified only immediately after the EXTRACT statement.

Subparameters specified in INCLUDE / EXCLUDE statements must not contradict the PATH parameter of the EXTRACT statement. For example, if PATH is set to DATASET, subparameters specified in the INCLUDE / EXCLUDE statements must not include fields from volume records.

For a list of subparameters that can be specified in INCLUDE / EXCLUDE statements, see the appendix that discusses logical field names for the Control-M/Tape Repository in the INCONTROL for z/OS Administrator Guide. For additional information about INCLUDE / EXCLUDE statements, see Record Selection Logic (INCLUDE / EXCLUDE Statements) (CTM).

CTTRPT Report Formatting Parameters

Figure 126 CTTRPT Report Formatting Parameters

Copy 
REPORT NAME=GENERAL,TITLE='text',FOLD=YES|NO,
       PAGESIZE=p,LINESIZE=s,MARGINS=m-n,
       SUMMARY=YES|NO,OUTDD=ddname
FIELDS field 1/options-1,field 2/options-2,...,
                       field n/options-n,ID=P|S
SORTBY field 1/options-1,field 2/options-2,...,
                       field n/options-n
ATTR   FIELD=name,LENGTH=t,TITLE='text',EDIT='mask'
BREAK  FIELD=name,COLUMN=c,SUMTITLE='text',
       EDIT='numeric mask'

Table 356 CTTRPT Report Formatting Parameters

Parameter

Description

REPORT

Activates report formatting. The following subparameters can be specified:

  • NAME – Report name. Mandatory. The only valid value is GENERAL; general report of information extracted from the Media database.

  • TITLE – Report title. Optional. The maximum length is 64 characters. Default: ‘General Report’.

  • FOLD – Indicates whether all report data is printed in uppercase. Valid values are:

    • Yes – Print all report data in uppercase.

    • No – Print report data in upper and lowercase. Default.

  • PAGESIZE – Maximum lines in a page, where p is a numeric value between 21 and 16383. Optional. Default: 63.

  • LINESIZE – Maximum characters in a line, where s is a numeric value not greater than 255. Optional. Default: 127.

  • MARGINS=m-n – Lowest (m) and highest (n) columns in a line, where m is a numeric value greater than 0 and n is a numeric value greater than m but not greater than s (the value of LINESIZE). Optional. Defaults: m=1 and n=s.

  • SUMMARY=YES|NO – Indicates whether to show a summary line for each field break. Optional. Default: NO.

  • A field break occurs when there is a change in value for a field that is specified in a SORTBY statement with option /BRK, (or /B).

  • OUTDD–JCL DD name of the output. Default: REPOUT.

FIELDS

Output fields (meaning, fields required in the report) and the options that can be applied to each field. Mandatory.

The GENERAL report can contain volume and data set fields that can be specified as INCLUDE / EXCLUDE subparameters and special fields that cannot be specified as INCLUDE / EXCLUDE subparameters (described with their attributes later in this utility).

  • Options – Options can be added as a suffix to any output field in the list (optional for each field). The slash (/) preceding the option is required to distinguish the option from the field. Any number of options can be added to an output field. Available options are:

    • /Ln – Length of the output field. n must be a numeric value that does not exceed the length defined in the list of available fields. This option is used for Alphanumeric   and Hexadecimal fields only. Optional. This value, if specified, overrides a LENGTH value specified in the ATTR statement, described in this table.

    • /Cn – Column in which the field begins in the printed output. If specified for a field, it must be specified for all preceding fields. n must be a numeric value greater than the last column of the preceding field (determined by the preceding field’s beginning column and field length).

  • ID–P|S Output line indicator. This parameter designates an output line as a Primary Line (P) or Secondary Line(S). These values determine whether duplicate lines are printed from Volume and Dataset data. Optional.

    • P – Primary line indicator. The line is only printed when a primary key changes value.

    • S – Secondary line indicator. A line is printed for each record. Default.

SORTBY

Sort order of the output fields, described in FIELDS in this table. Optional.

Options – Options can be added as a suffix to any output field in the list (optional for each field). The slash (/) preceding the option is required to distinguish the option from the field. Any number of options can be added to an output field. Available options are:

  • /BRK or /B–Insert a page break in the report when the field changes its value. If specified for a field, it must be specified for all preceding fields.

  • /ASC – Sort the field in ascending order. Default.

  • /DSC – Sort the field in descending order.

  • /RSR – Reset the row number whenever the value of the   field changes. This option is effective only when field   ROWID is specified in the FIELDS statement

  • /RSP – Reset the row number whenever the value of the   field changes. This option automatically activates option   /RSR.

Primary fields in a SORTBY statement must be specified before non-primary fields.

Example 1

Copy 
SORTBY LOCATION /BRK (or /B) POOL/BRK/DSC,MEDIA/ASC

Output is sorted by vault (LOCATION) in ascending order (the default) by pool (POOL) within a vault in descending order and by media (MEDIA) within a pool in ascending order. A page break is inserted each time the vault or pool changes.

Example 2

Copy 
SORTBY LOCATION /BRK/RSP,
MEDIA/BRK/RSR,EXPDT/DSC

Output is sorted by vault (LOCATION) in ascending order (the default) by media (MEDIA) within a vault in ascending order (by default) and by expiration date (EXPDT) within a media in descending order. A page break is inserted for every change in vault and media and the page number (and, by default, the row number) is also reset each time the vault changes. The row number is reset each time the media changes.

ATTR

Overrides default attributes defined for a field. Optional.

At least one optional parameter must be specified for statement ATTR.

An ATTR statement can be specified for any field, even a field not included in a FIELD statement. The report, however, is not effected by an ATTR for a field until the field is included in a FIELD statement. (This means that an ATTR statement can be defined in advance for each field, for use when the field appears in a FIELD statement.)

Member ATTRGEN in the Control-M/Tape PARM library contains sample ATTR statements for the GENERAL report.

The following parameters apply to the field whose attributes are changed:

  • FIELD – name Name of the field. Mandatory.

  • LENGTH – Length of the output field. Must be a numeric value that must not exceed the field length specified in the list of available fields. Optional. A /Ln value, if specified for the same field in the FIELDS statement, overrides this value.

  • TITLE – ‘text’ Field header. ‘text’ is any character string (enclosed in apostrophes). To split the header between lines, insert a slash (/) before each line break. The number of header lines in the report is determined by the field whose TITLE parameter text has the highest number of lines. Optional.

    For example, if the following is specified:

    ATTR FIELD VOLSER

    TITLE="Volume or Serial or Number"

    The header for field VOLSER spans three output lines as follows:

    Volume

    Serial

    Number

  • EDIT=‘mask’ – Field format, as specified through a mask. The mask must be enclosed in apostrophes. Parameter EDIT cannot be specified for character and hexadecimal fields. Valid mask formats:
    Numeric Format – For numeric fields only. The mask can consist of Z’s and 9’s and commas, where 9 represents any digit, Z represents a digit that is suppressed if its value is a leading zero and comma is a separator between digits.
    When specifying a numeric format, the following rules apply:

    • A 9 cannot precede a Z in the mask.

    • A comma cannot be the first or last character of the mask.

      Assume number 1234 is being edited (and b indicates blank)
      Mask Specified   Result
      ‘ZZ,ZZ9’               b1,234
      ‘Z,999’                 1,234
      ‘999999’              001234
      ‘ZZZ,ZZZ’            bb1,234

      Date Format
      For Date fields. Valid mask combinations can have no more than one day symbol, one month symbol and one year symbol.
      Valid symbols:

      • DD – Day (values 1 – 31).

      • MM – Month (values 1 – 12).

      • MMM – Month (values Jan – Dec).

      • YY – Year (last two digits, meaning, 00 – 99).

      • YYYY – 4-digit year (for example, 2000).

      Symbols can be optionally separated by one or more separation characters: ‘/’, ‘.’, ‘-’, blank, and so on.


      Assume the date being formatted is August 23, 2000.
      Mask Specified                  Result
      ‘DD/MM/YY’              23/08/00
      ‘YYYY.MM.DD’            2000.08.23
      ‘MM-DD-YYYY’            08-23-2000
      ‘DD MMM YYYY’         23 Aug 2000
      ‘MMM – DD – YYYY’   Aug – 23 – 2000
      ‘YY/MM’                          00/08

 

Boolean Format

For Boolean fields (meaning, fields that contain a True or False, or Yes or No condition). The specified FIELD is checked for a true or false condition in the record.

The mask can contain either one value or two values separated by a slash (/). A null value can be specified on either side of the slash.

When one mask value is specified, the value is printed in the report only if the FIELD checks "true" in the record. (If the FIELD checks "false", the mask value is not printed; blanks are printed instead.)

When two values are specified, the first value is printed in the report if the FIELD checks "true" in the record. The second value is printed if the field checks "false".

Copy 
(1) ATTR FIELD=SCRATCH, TITLE=‘Scratch’,EDIT=‘Yes or No’
(2) ATTR FIELD=ACTIVE,TITLE=‘Type’,EDIT=‘Active or Scratch’
(3) ATTR FIELD=VAULTED, TITLE=‘V’,EDIT=‘v’
(4) ATTR FIELD=EDM, TITLE=‘Edm’,EDIT=‘/No’

The following table shows the results of Boolean editing for these examples:

Example

Field Tested

(1)

SCRATCH

(2)

ACTIVE

(3)

VAULTED

(4)

EDM

BREAK

Attributes of the summary line printed at the bottom of the page when a field break occurs. Optional.

For each field break, the user can specify a header and variables that indicate the number of primary and secondary lines printed and the value of the field before the break occurred.

At least one optional parameter of the BREAK statement must be specified.

A BREAK statement can be specified for any field, even a field that is not included in a SORTBY statement. The report, however, is not effected by a BREAK for a field until the field is included in a SORTBY statement with option /BRK and SUMMARY=YES has been specified in the REPORT statement.

This means that a BREAK statement can be defined in advance for each field when the field appears in a SORTBY statement and report summaries are included.

  • FIELD – name – Name of the field. Mandatory.

  • COLUMN – Column of the output line in which the summary title begins printing. column must be numeric. Optional. The default is the report start margin specified in parameter MARGINS of the REPORT statement.

  • SUMTITLE=‘text’ – Summary text to be printed when the   value of a field changes. text can be any string of characters. It must be enclosed in apostrophes and can contain one or more of the following variables:

    • - %FIELD – Value of the field before the break occurred.

    • - %COUNTP – Number of primary lines printed before the break occurred.

    • - %COUNT – Number of secondary lines printed before the break occurred.

The default value of SUMTITLE ‘text’ is:

‘TOTAL IN %FIELD IS %COUNT’

If parameter ID is not specified in the FIELDS statement or there is only one FIELDS statement, the value of %COUNT is equal to the value of %COUNTP.

EDIT=‘numeric mask’ – Numeric format of %COUNT and %COUNTP variables. Optional. The default is ‘ZZ,ZZ9’. For more information, see the Numeric format example for the EDIT parameter of the ATTR statement, described in this table.

Copy 
REPORT NAME=DISTRIB,SUMMARY=YES
FIELDS ...
SORTBY
TOLOC/BRK/RSR/RSP,
FROMLOC/BRK (or /B) 
TOSLOT,FROMSLOT,
VOLSER
BREAK
FIELD=TOLOC,
SUMTITLE=‘Total Volumes Moved To %FIELD is %COUNT’,
EDIT=‘Z,ZZ9’
BREAK
FIELD=FROMLOC,
SUMTITLE=‘Total Volumes Moved From %FIELD is 
%COUNT’, EDIT=‘Z,ZZ9’
ATTR ...

Special CTTRPT Fields

The following table contains a list of derived fields that can be included in the GENERAL report. These fields do not exist in the Media database records, but their values are derived from either volume or data set records, as indicated, where

V

indicates the source is a volume record

D

indicates the source is a data set record

ROWID is a calculated field and therefore no source is indicated.

These fields cannot be subparameters of INCLUDE / EXCLUDE statements.

Table 357 CTTRPT Fields

Field Name

Source

Type

Default Size in Bytes

Description

DSEXPDTA

D

Character

36

Complete data set expiration information

DSPOOL

D

Character

15

Pool name derived from the volser of the data set record

DSSTAT

D

Character

12

Data data set statuses as shown below the header STATUS in Screen TI. For more information, see the description of Screen TI in the online facilities chapter of the Control-M/Tape User Guide.

DSTATX

D

Hexadecimal

4

Data set statuses in Hexadecimal representation

POOL

V

Character

15

Pool name derived from the volser of the volume record

ROWID

 

Numeric

5

Row (line) number. Can be specified for either Primary or Secondary lines but not for both.

VOLSTAT

V

Character

12

Volume statuses as shown below the header STATUS in Screen TI. For more information, see the description of Screen TI in the online facilities chapter of the Control-M/Tape User Guide.

VSTATX

V

Hexadecimal

8

Volume statuses in Hexadecimal representation

CTTRPT Return Codes

Table 358 CTTRPT Return Codes

Code

Description

0

Operation performed successfully

4

Minor errors detected. For more information, see accompanying messages.

8

Major errors detected. For more information, see accompanying messages.

12

Control card error

16

Operation code not found

20

Invalid operation code

24

Syntax error in REPORT, FIELDS, or SORTBY statement

28

Field name specified in FIELDS or SORTBY list is undefined.

32

Same parameter specified more than once.

36

Field name exceeds maximum length.

40

Invalid relation specified (must always be an equal sign).

44

Report NAME is undefined.

48

BRK not specified for the preceding field in the SORTBY list.

52

FIELDS statement not specified.

56

Total of all field lengths requested in the FIELDS statement exceeds the line size.

60

Continuation card expected but not received.

64

Invalid numeric value

68

Option in the FIELDS or SORTBY statement already specified.

72

ROWID specified in the BREAK or SORTBY statement.

76

EDIT parameter in the ATTR statement is invalid for specified FIELDS.

80

EDIT mask is not valid.

84

Specified number not in permitted range.

For example, end column of a MARGIN statement exceeds the LINESIZE or a column in a FIELDS statement is outside the report’s margins.

88

Column option (/C) not specified in the preceding field.

92

One of the following has occurred:

  • No column is specified in the current FIELDS statement.

  • The specified column in a FIELDS statement is inconsistent with the column specified in another FIELDS statement

96

Second EXTRACT statement did not come after report statements.

100

Load of Control-M/Tape programs failed.

104

Load of POOL table failed.

108

Insufficient memory

112

All fields specified for the primary or secondary line have the BRK attribute.

116

Loading Control-M/Tape environment failed.

200

Fields in the FIELDS or SORTBY statements do not fit the PATH parameter of the EXTRACT statement.

CTTRPT Sample Reports

The reports listed below can be created using the CTTRPT utility. These reports are located in the IOA SAMPLE library.

Some of these sample reports contain question marks (??) where customization is necessary. Replace the question marks with the desired values and use the appropriate job to produce the report.

Table 359 CTTRPT Sample Reports

Report

Description

CTTRFSCR

Full-scratch report. Lists all volumes with SCRATCH status in the Media database

CTTRINV

Vault inventory report. Lists all vaulted volumes and data sets in a specified location

CTTRINVT

Comprehensive inventory report. Lists all volumes and data sets in the Media database

CTTRSCRD

Lists all volumes scratched on a specified date and the data sets residing on these volumes

CTTRDELV

Lists all volumes with DELETED status

CTTRCLN

Clean report. Lists volumes that need to be cleaned (meaning, each volume that has more than a specified threshold number of permanent I/O errors)

CTTRRTNP

Lists all data sets (and their volumes) according to expiration date type (for example, CYCLE or CATALOG)

CTTRLACV

Lists all volumes accessed today

CTTRDCRE

Lists all data sets created yesterday

CTTRMOVW

Lists all volumes moved within the last seven days

CTTRCHKI

Lists all external volumes checked-in during the last 30 days)

CTTRUTIL

Lists volumes that are under-utilized (less than less than 10 megabytes)

CTTRLAVJ

Lists all volumes that were last accessed by a certain job since a specified date

CTTRWDCP

Lists all data sets that were written in a certain system (CPU) since a specified date

CTTROUTL

Lists all volumes in an out-location (borrower volumes)

CTTRLRTV

Lists all volumes with high retention dates (for example, after year 2001)

CTTRM10V

Lists all multi-volume data sets that span more than ten volumes

CTTRMACV

Lists the most active volumes (accessed more than ten times since they became active)

CTTREDM

Lists all EDM volumes

CTTRRCLV

Lists all RECALLed volumes

CTTRVUPD

Lists all volumes that were manually updated by a specified user

CTTRDUPD

Lists all data sets that were manually updated by a specified user

CTTRM25D

Lists all volumes containing more than 25 active data sets

CTTRVBOX

Lists the volumes stored in a specified box

CTTRBXLC

Lists all volumes that are stored in boxes, according to location and BOXID

CTTRNRTR

Lists all borrowed volumes that have not yet been returned

Jobs for Report Production

The above reports are produced using the following jobs (that are located in the JCL library):

Table 360 CTTRPT Jobs

Job

Description

REPFSCR

Produces report CTTRFSCR (full-scratch report)

REPINV

Produces report CTTRINV (comprehensive inventory report)

REPSJOB

Produces all other reports. This job requires customizations to indicate the desired report.

Examples for CTTRPT

CTTRPT Example 1

Extract all data sets from location VAULT1 and generate a report showing all VAULT1 data sets and their volumes sorted by their pool name (DSPOOL) that is derived from data set volser.

Figure 127 CTTRPT – Example 1

Copy 
//EXTRACT EXEC CTTRPT
//SYSIN   DD *
    EXTRACT PATH=DATASET/ALLVOLS
    INCLUDE LOCATION=VAULT1
    REPORT NAME=GENERAL,SUMMARY=YES,MARGINS=1-080,LINESIZE=080,
        TITLE='Datasets in Vault VAULT1'
    FIELDS ROWID,FIRSTVOL,
        DSNAME,DSLABEL,CREJBN,CREDT,LRECL,RECFM,
        ID=P
    FIELDS VOLSER/C13,MOVEDATE,VOLSEQ,SLOTNUM,
        ID=S
    SORTBY DSPOOL/BRK/RSP,FIRSTVOL,DSLABEL,VOLSEQ,SLOTNUM
    BREAK FIELD=DSPOOL,COLUMN=10,EDIT='Z,ZZ9',
        SUMTITLE='%FIELD Datasets in VAULT1:  %COUNTP'
    ATTR FIELD=ROWID,TITLE='Row/Id',EDIT='ZZ,ZZ9'
    ATTR FIELD=FIRSTVOL,TITLE='First/Volume'
    ATTR FIELD=DSNAME,TITLE='/Dataset Name',LENGTH=24
    ATTR FIELD=DSLABEL,TITLE='Ds/Seq.',EDIT='ZZ9'
    ATTR FIELD=CREJBN,TITLE='Create/Job'
    ATTR FIELD=CREDT,TITLE='Create/Date',EDIT='DD MMM YY'
    ATTR FIELD=LRECL,TITLE='Record/Length',EDIT='ZZ,ZZ9'
    ATTR FIELD=RECFM,TITLE='Record/Format'
    ATTR FIELD=DSPOOL,TITLE='Pool/Name'
    ATTR FIELD=VOLSER,TITLE='/Volser'
    ATTR FIELD=MOVEDATE,TITLE='Move/Date',EDIT='DD MMM YYYY'
    ATTR FIELD=VOLSEQ,TITLE='Vol/Seq.',EDIT='Z9'
    ATTR FIELD=SLOTNUM,TITLE='Slot/No.',EDIT='Z,ZZ9'

A sample of the output report from the above example is illustrated as follows:

Figure 128 CTTRPT Sample Report 1

Copy 
BMC,INC.       CONTROL-M/TAPE REPORT  (VER 6.1.00)

    Datasets in Vault VAULT1
    -------------------------
       
Pool Name:  POOL-NUMBER-1
       
Row    First   Ds    Create   Create    Record Record
Id     Volume Dataset Name     Seq.  Job      Date      Length Format
    MoveVol     Slot
    Volser  DateSeq.    No.
------ ------------------------------------- ------------------ ------ ------
 58 016475 FDRABR.VTSO006.C1004900     27 ZCOBKUPD 13 Jun 00      0 U
    012517  23 Jun 2000     55     74
    015692  23 Jun 2000     56    163
    015646  23 Jun 2000     57    162
    016024  23 Jun 2000     58    177
       
 59 016475 FDRABR.VESAD1A.C1002800     28 ZCOBKUPD 13 Jun 00      0 U
    016024  23 Jun 2000     58    177
    015722  23 Jun 2000     59    167
    016048  23 Jun 2000     60    178
    012771  23 Jun 2000     61     90
       
 60 016475 FDRABR.VVSAM00.C1001300     29 ZCOBKUPD 13 Jun 00      0 U
    012771  23 Jun 2000     61     90
    010096  23 Jun 2000     62     16
    018862  23 Jun 2000     63    223
    018839  23 Jun 2000     64    222
    012914  23 Jun 2000     65     96
    016314  23 Jun 2000     66    190
    016296  23 Jun 2000     67    187
    016211  23 Jun 2000     68    184
 61 016475 FDRABR.VSCLM02.C1003500     30 ZCOBKUPD 13 Jun 00      0 U
    016211  23 Jun 2000     68    184
    016201  23 Jun 2000     69    183
    016127  23 Jun 2000     70    181
    016337  23 Jun 2000     71    193
    016322  23 Jun 2000     72    192
    015072  23 Jun 2000     73    148
62 016475 FDRABR.VVSAM12.C1006800     31 ZCOBKUPD 13 Jun 00      0 U
    015072  23 Jun 2000     73    148
    015062  23 Jun 2000     74    147
    011488  23 Jun 2000     75     44
    011035  23 Jun 2000     76     31
    010970  23 Jun 2000     77     29
    010967  23 Jun 2000     78     28
63 017244 CA.BKUPMSTR.G0502V00 1 CALDPBK  12 Jun 00  8,287 VB
    017244  23 Jun 2000      1    113
    013076  23 Jun 2000      2    110
    018149  23 Jun 2000      3    114
    015278  23 Jun 2000      4    112
    019308  23 Jun 2000      5    115
    013099  23 Jun 2000      6    111
       64 018042 TS63.CATALOG.VWGL507.BAC     1 ZTSVSMB4 13 Jun 00 32,756 VBS
    018042  23 Jun 2000      1      9
    018137  23 Jun 2000      2     10
    013684  23 Jun 2000      3      7
    011951  23 Jun 2000      4      5
    011932  23 Jun 2000      5     61
               
BMC,  INC.CONTROL-M/TAPE REPORT  (VER 6.1.00)    
    Datasets in Vault VAULT1
    -------------------------
Pool Name:  POOL-NUMBER-1
       
   Row    First      Ds    Create   Create    Record Record
   Id     Volume Dataset NameSeq.  Job      Date      Length Format
    Move Vol    Slot
    Volser  Date Seq.   No.
------ ------------------------------------- ------------------ ------ ------
       64 018042 TS63.CATALOG.VWGL507.BAC     1 ZTSVSMB4 13 Jun 00 32,756 VBS
    011257 23 Jun 2000       6     40
    010885 23 Jun 2000       7     25
    010870 23 Jun 2000       8     24
    017991 23 Jun 2000       9    209
    017509 23 Jun 2000      10    203
    014339 23 Jun 2000      11    136
    015050 23 Jun 2000      12    145
    015097 23 Jun 2000      13    149
       
       65 018228 TS63.CATALOG.VMVSCAT.BAC     1 ZTSVSMB1 13 Jun 00 32,756 VBS
    018228 23 Jun 2000       1     11
       
       66 018288 TS63.CATALOG.VWGL83A.BAC     1 ZTSVSMBA 13 Jun 00 32,756 VBS
    018288 23 Jun 2000       1     13
    018280 23 Jun 2000       2     12
       
       67 018358 TS63.CATALOG.VWGL514.BAC     1 ZTSVSMB3 13 Jun 00 32,756 VBS
    018358 23 Jun 2000       1     14
       
POOL-NUMBER-1 Datasets in VAULT1:  67

CTTRPT Example 2

Extract all volumes located in VAULT1 that were created by job ZCOIBKUP during June 2000.

Figure 129 CTTRPT – Example 2

Copy 
//EXTRACT EXEC CTTRPT
//SYSIN  DD *
    EXTRACT PATH=VOLUME/ALLDS
    INCLUDE LOCATION=VAULT1,CREJBN=ZCOIBKUP
    EXCLUDE CREDT<20000601
    EXCLUDE CREDT>20000630
    REPORT NAME=GENERAL,SUMMARY=YES,MARGINS=1-80,LINESIZE=80,
        TITLE='Inventory Report'
    FIELDS ROWID,VOLSER,VOLSTAT,MOVEDATE,VOLSEQ,SLOTNUM,VOLEXPDT,
        ID=P
    FIELDS DSNAME/C13,DSLABEL,CREJBN,CREDT,BLOCKCT,DSEXPDT,
        ID=S
    SORTBY ACTIVE/BRK/RSP,POOL/BRK/RSP,
        LOCATION/BRK/RSR,VOLSER,DSLABEL
    BREAK  FIELD=LOCATION,EDIT='ZZ9',
        SUMTITLE='Total number of volumes in %FIELD:  %COUNTP'
    BREAK  FIELD=ACTIVE,EDIT='ZZ,ZZ9',
        SUMTITLE='Number of %FIELD Volumes:  %COUNTP'
    BREAK  FIELD=POOL,EDIT='ZZ9',
        SUMTITLE='Total number of volumes in %FIELD:  %COUNTP(%COUNT)'
    ATTR FIELD=ROWID,TITLE='Row/Id',EDIT='ZZ,ZZ9'
    ATTR FIELD=VOLSER,TITLE='/Volser'
    ATTR FIELD=VOLSTAT,TITLE='Volume/Status'
    ATTR FIELD=MOVEDATE,TITLE='Move/Date',EDIT='DD MMM YYYY'
    ATTR FIELD=VOLSEQ,TITLE='Vol/Seq.',EDIT='Z9'
    ATTR FIELD=SLOTNUM,TITLE='Slot/No.',EDIT='Z,ZZ9'
    ATTR FIELD=VOLEXPDT,TITLE='Volume/Expiration',EDIT='DD MMM YYYY'
    ATTR FIELD=DSNAME,TITLE='/Dataset Name',LENGTH=24
    ATTR FIELD=DSLABEL,TITLE='Ds/Seq.',EDIT='ZZ9'
    ATTR FIELD=CREJBN,TITLE='Create/Job'
    ATTR FIELD=CREDT,TITLE='Create/Date',EDIT='DD MMM YY'
    ATTR FIELD=BLOCKCT,TITLE='Block/Count',EDIT='ZZ,ZZ9'
    ATTR FIELD=DSEXPDT,TITLE='Dataset/Expiration',EDIT='YYYY-MMM-DD'
    ATTR FIELD=ACTIVE,TITLE='Type',EDIT='ACTIVE/SCRATCH'
    ATTR FIELD=LOCATION,TITLE='Location'
    ATTR FIELD=POOL,TITLE='Pool/Name'
/*

The following is a sample output produced by the above example. Note the following about the output:

  1. The page number, date and time are not printed unless the LINESIZE specified in the REPORT statement is at least 127.

  2. During printing, if there is insufficient room on the current page for secondary lines, the primary line is reprinted as part of the page header on the next page.

  3. A field specified with option /BRK in a SORTBY statement is shown in the page header following the report title and any slashes (/) specified in the TITLE definition are suppressed to blanks.

Figure 130 CTTRPT Sample Report 2

Copy 
    BMC,  INC.  CONTROL-M/TAPE REPORT  (VER 6.1.00)   
                          Inventory Report
                          ----------------
    Type:  ACTIVE    Pool Name:  POOL-NUMBER-1     Location:  VAULT1
   
    Row             Volume         Move          Vol     Slot    Volume
    Id     Volser   Status         Date          Seq.    No.     Expiration
                                Ds     Create    Create     Block   Dataset
Dataset Name            Seq.   Job       Date       Count   Expiration
----------------------------  ---------------------------------------------
     1    010222   Vaulted        Jun 20-2000       2     427   21 Jun 2000
  FDRABR.VPROD02.C1005204       6  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
  FDRABR.VPROD01.C1008804       5  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
  FDRABR.VSAS001.C1006504       4  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
  FDRABR.VTSO006.C1004804       3  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
  FDRABR.VTSO003.C1015904       2  ZCOIBKUP  14 Jun 00     999  2000-Jun-21
   
   2    010372   Vaulted        Jun 20-2000       1     433   21 Jun 2000
  FDRABR.VTSO003.C1015904       2  ZCOIBKUP  14 Jun 00     999  2000-Jun-21
  FDRABR.VTSO002.C1015904       1  ZCOIBKUP  14 Jun 00     999  2000-Jun-21
   
   3    011938   Vaulted        Jun 20-2000      14     487   21 Jun 2000
  FDRABR.VWGLE00.C1035504      17  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
  FDRABR.VWGLE1C.C1027404      16  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
  FDRABR.VMVS89C.C1005304      15  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
  FDRABR.VMVS89D.C1005304      14  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
  FDRABR.VMVSR1A.C1028204      13  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
  FDRABR.VWGL800.C1006704      12  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
   
   4    011954   Vaulted        Jun 20-2000      15     492   21 Jun 2000
  FDRABR.VWGL514.C1041704      20  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
  FDRABR.VWGLE13.C1031304      19  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
  FDRABR.VMVSRES.C1018704      18  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
  FDRABR.VWGLE00.C1035504      17  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
   
   5    012016   Vaulted        Jun 20-2000      13     506   21 Jun 2000
  FDRABR.VWGL800.C1006704      12  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
  FDRABR.VSCLM03.C1001304      11  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
   
   6    012191   Vaulted        Jun 20-2000       3     529   21 Jun 2000
  FDRABR.VPROD04.C1016204       7  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
  FDRABR.VPROD02.C1005204       6  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
   
   7    012271   Vaulted        Jun 20-2000       9     539   21 Jun 2000
  FDRABR.VSCLM03.C1001304      11  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
  
   8    012313   Vaulted        Jun 20-2000      12     544   21 Jun 2000
  FDRABR.VSCLM03.C1001304      11  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
   
   9    013315   Vaulted        Jun 20-2000       4     551   21 Jun 2000
  FDRABR.VPROD06.C1016204       9  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
  FDRABR.VPROD05.C1015904       8  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
  FDRABR.VPROD04.C1016204       7  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
   
  10    014347   Vaulted        Jun 20-2000      11     568   21 Jun 2000
  FDRABR.VSCLM03.C1001304      11  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
   
  11    014743   Vaulted        Jun 20-2000      10     572   21 Jun 2000
  FDRABR.VSCLM03.C1001304      11  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
   
  12    016465   Vaulted        Jun 20-2000       5     583   21 Jun 2000
  FDRABR.VSCLM01.C1008904      10  ZCOIBKUP  14 Jun 00       0  2000-Jun-21



                          Inventory Report
                          ----------------
Type:  ACTIVE    Pool Name:  POOL-NUMBER-1     Location:  VAULT1
   
Row             Volume         Move          Vol     Slot    Volume
Id     Volser   Status         Date          Seq.    No.     Expiration
                               Ds     Create    Create     Block   Dataset
   DataSet Name             Seq.  Job       Date       Count   Expiration
----------------------------  --------------------------------------------
   12    016465   Vaulted        Jun 20-2000       5     583   21 Jun 2000
 FDRABR.VPROD06.C1016204       9  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
   13    017248   Vaulted        Jun 20-2000       6     587   21 Jun 2000
 FDRABR.VSCLM01.C1008904      10  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
   14    018377   Vaulted        Jun 20-2000       8     596   21 Jun 2000
 FDRABR.VSCLM03.C1001304      11  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
 FDRABR.VSCLM01.C1008904      10  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
   15    018393   Vaulted        Jun 20-2000       7     596   21 Jun 2000
 FDRABR.VSCLM01.C1008904      10  ZCOIBKUP  14 Jun 00       0  2000-Jun-21
   
Total number of volumes in VAULT1 :  15
   
POOL-NUMBER-1 Volumes:  73 ,  POOL-NUMBER-1 Datasets:  581
   
Number of ACTIVE  Volumes:  221

CTTRSM – Recover tape activity from SMF records

The CTTRSM utility recovers tape activity not recorded in the Media database from data in SMF records. This utility can be used to extract information about tape activity performed when Control-M/Tape was not active.

Before running the CTTRSM utility, SMF records must be accumulated and loaded into one or more sequential files using appropriate MVS utilities (for example, IFASMFDP). Specify the sequential files containing the SMF records in DD statement DASMFIN of the CTTRSM utility. The SMF records in the sequential file must be only type 14 and type 15 SMF records.

Since the CTTRSM utility only processes type 14 and 15 SMF records, the utility cannot determine whether a job ended successfully or abended. Thus, the normal retention type is used to determine retention. The abend retention type is never used.

Activating the CTTRSM Utility

Copy 
//EXEC    CTTRSM
//DASMFIN DD DISP=SHR,DSN=SMF-file-#1
//        DD DISP=SHR,DSN=SMF-file-#2
...
//SYSIN DD *
        TYPERUN MODE=NORMAL|SIMULATION[,DYNVOL=Y|N][,
                DYNDS=Y|N][,ACCTYPE=CREATE|UPDATE|ALL][,
                 SYNCHLVL=MATCH|FORCE][,X98000=SKIP|UPDATE]
<INCLUDE/EXCLUDE statements>
REPORT NAME=SMFRCV
FIELDS ...
[SORTBY ...]
[ATTR ...]
[BREAK ...]
//

CTTRSM Parameters

Table 361 CTTRSM Parameters

Parameter

Description

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 — Mode in which the utility runs. Mandatory. Valid values:

    • NORMAL — SMF records are read and the Media database is updated according to the tape activity recorded in the SMF records. Default.The utility produces a report that lists the tape activity extracted from SMF records.

    • SIMULATION — SMF records are read but the Media database is not updated. The utility produces a report of tape activity from SMF records without updating the Media database.

  • DYNVOL — Instructions for handling volumes that were accessed but do not exist in the Media database. Optional.

    • Y — Create a volume record for each of these volumes automatically. This value is not valid if DYNDS is set to N (see below). Default.

    • N — Do not create a volume record for the volume. Information about data sets on the volume and the volume chain to which it belongs is not recorded in the Control-M/Tape Media database.

  • DYNDS — Instructions for handling data sets that were accessed for Read or Update but are not defined in the Media database. This parameter is ignored if CREATE is specified for parameter ACCTYPE (described below). Optional.

    • Y — Create a data set record for each of these data sets and insert the appropriate information. Default.

    • N — Do not create data set records for these data sets (meaning, do not record tape activity for these data sets).

  • ACCTYPE — Types of tape activity to be processed during this run of the utility. Optional.

    • CREATE — Process only SMF records that describe creation of new data sets.

    • UPDATE — Process only SMF records that describe an update of a tape data set (including creation of new data sets).

    • ALL — Process all SMF records of tape activity that were stored in the sequential files specified as input to the utility. Default.

TYPERUN (cont)

  • SYNCHLVL — Instructions for handling conflicts (for example, when an SMF record indicates creation of a data set that overwrites an existing data set) between the Media database and the SMF records. Optional.

    • MATCH — If a conflict occurs, the conflict is described in the utility report. The Media database is not updated with the conflicting information. Default.

    • FORCE — If a conflict occurs, the Media database is modified to reflect the changes described in the SMF record.

  • X98000 — Instructions for handling data sets for which LABEL=EXPDT=98000 was specified. Optional.

    • SKIP — Do not process data sets specified with LABEL=EXPDT=98000. Default.

    • UPDATE — Process all data sets regardless of their EXPDT specification.

INCLUDE / EXCLUDE

SMF records are in sequential files referenced by DD statement DASMFIN. These records can be filtered by one or more INCLUDE / EXCLUDE statements.

The INCLUDE / EXCLUDE statements can reference the following fields:

  • BLOCKCT

  • BLKSIZE

  • CPUID

  • CREDT

  • DDNAME

  • DSEXCP

  • DSLABEL

  • DSNAME

  • DSOPNTIM

  • DSVOLSER

  • JCLEXPDT

  • JOBNAME

  • JSTRTDAT

INCLUDE / EXCLUDE (cont)

The CTTRSM utility reads SMF records that describe tape access.

  • JSTRTTIM

  • LBLTYP

  • LRECL

  • RECFM

  • RFORMAT

  • TRTCH

  • UNITADR

  • USERID

  • VOLSER

For more detailed information on these fields, see the INCONTROL for z/OS Administrator Guide.

For more information about INCLUDE / EXCLUDE statements, see Record Selection Logic (INCLUDE / EXCLUDE Statements) (CTM). Optional.

REPORT

Indicates the report to be created by the utility. Mandatory.

The following parameter must be specified:

NAME=SMFRCV

An SMF recovery report is produced by the utility, listing all data sets whose access (or creation) is described in the SMF records processed by the utility. The fields in this report are determined by the FIELDS statement (described below).

FIELDS

Indicates which fields to include in the report that the utility creates. You can include the following fields:

  • ACCTYPE

  • BLOCKCT

  • BLKSIZE

  • CPUID

  • CREDT

  • DDNAME

  • DSEXCP

  • DSLABEL

  • DSNAME

  • DSOPNTIM

  • DSVOLSER

  • JCLEXPDT

  • JOBNAME

  • JSTRTDAT

  • JSTRTTIM

  • LBLTYP

  • LRECL

  • RECFM

  • RFORMAT

  • TRTCH

  • UNITADR

  • USERID

  • VOLSER

For more detailed information on these fields, see the INCONTROL for z/OS Administrator Guide.

In addition to the fields above, you can include the following special field:

  • STATUS–Indicates the action performed on the data set record by the CTTRSM utility. This field is empty if the data set was processed successfully. Otherwise, this field contains a rejection reason that explains why the data set was not processed.

SORTBY

Order in which the report is sorted. Optional. Valid sort fields are all data set record and volume record fields, described in the appendix that discusses logical field names for the Control-M/Tape Repository in the INCONTROL for z/OS Administrator Guide.

ATTR

Override of default attributes defined for a field in the report. Optional.

BREAK

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

For a description of the parameters for these statements, see the FIELDS, SORTBY, ATTR and BREAK statements in CTTRPT – Database extraction and report utility.

Example for CTTRSM

The following example recovers all tape data sets accessed by jobs with names prefixed by ABC. Volumes and data sets that are not defined in the Media database are automatically defined. Conflicts with the Media database are reported as errors.

Copy 
//EXEC    CTTRSM
//DASMFIN DD DISP=SHR,DSN=N00.ACCUM.SMFRECS
//SYSIN   DD *
    TYPERUN  MODE=SIMULATION,DYNDS=Y,DYNVOL=Y
    INCLUDE  CREJBN=ABC*
    REPORT   NAME=SMFRCV
    FIELDS   DSNAME,DSVOLSER,DSLABEL,STATUS

CTTRTM – Perform Retention Management

The CTTRTM utility performs batch retention management functions. Perform batch retention management daily to check expiration criteria and determine which data sets are marked scratch. When all the data sets on a volume have expired, the volume becomes a scratch volume. Run the utility as part of the Control-M/Tape New Day procedure (CTTDAY).

The CTTRTM utility supports a number of different types of retention. For a list of the supported retention types, see the discussion about retention management in the organization and administration chapter in the Control-M/Tape User Guide.

The CTTRTM utility does not perform retention management for the following volumes:

  • Vaulted volumes

  • Volumes with a status of Pend-Vault

  • Volumes that have been recalled from a vault

  • Volumes with a status of Act-Use

  • Deleted volumes

  • EDM controlled volumes

  • Volumes not in the currently active library (meaning, volumes with a status of Act-Out)

Retention information for these volumes is updated by the CTTRTM utility if either CONVERT or RECALC is specified for the TYPERET parameter (described in CTTRTM Parameters). However, these volumes (and the data sets they contain) are not expired by the utility (meaning, they are not marked as scratched). The CTTRTM utility requires exclusive access to the Media database. Jobs can access tapes during the run of this utility. However, other utilities that access the Media database (for example, CTTIDB or CTTVTM) are not allowed to run concurrently with this utility.

Scratch Report

The CTTRTM utility can produce a Scratch report at the end of processing. The Scratch report contains a list of all volumes that have expired (become scratch) as a result of this utility run.

Full Scratch report FULLSCR is no longer generated by utility CTTRTM. Instead, this report can be generated as part of the GENERAL report by utility CTTRPT. For more information, see CTTRPT – Database extraction and report utility.

Utility CTTRTM adds the following special pool names in the POOLNAME field of certain volume records in the Scratch report:

Table 362 CTTRTM Pool Names

Pool

Description

EXTERNAL

External volumes not deleted from the Media database

EXT-DEL

External volumes deleted from the Media database

EXT-DUP

External volumes whose SL-NAME and VOLSER are different

DUPLICATE VOL

Internal volumes whose SL-NAME and VOLSER are different

The special pool name is written over the previous name in field POOLNAME (if one existed).

Using utility CTTTPI, re-initialize scratched volumes with different SL-NAMEs and VOLSERs. Set the SL-NAME to the value of the VOLSER as listed in the EXT-DUP and DUPLICATE VOL pools.

Use parameters MAXDSNO and MAXVOLNO of utility CTTRTM to indicate a maximum number of data sets and/or volumes that can be scratched during a run of the utility. Before scratch is performed, the utility checks if the maximum specified (using one of these parameters) was exceeded.

If a specified maximum is exceeded, no changes are made to any data sets or volumes. An error message is issued and the utility stops execution.

RECALC Report

If the CTTRTM utility is used to recalculate retention periods (meaning, the MODE parameter is set to RECALC in the TYPERET statement) a RECALC report can optionally be generated.

The RECALC report contains information about data sets whose expiration dates were changed as a result of the run of the utility.

The information provided about each data set depends on the field names specified in the FIELDS control statement for the RECALC report. Special field names can be used to indicate the various retention types that were specified for a data set and the AND/OR relationship between them. For more information, see Table 365 in CTTRTM Parameters

Exits Used by Utility CTTRTM

The following exits can be used to influence a run of the CTTRTM utility:

Table 363 CTTRTM Exits

Exit

Description

CTTX006

Receives control immediately before updates are made to data set or volume records in the Media database. This exit can be used to accept or reject expiration of a data set record and/or to update a data set or volume record before it is marked as scratched.

CTTX008

Receives control when the Scratch report is used to update the information in the automated tape library (if one exists at your site). This exit can be used to scan the scratch report and to determine which volume records are updated in the automated tape library database.

Relevant Installation Parameters (CTTRTM)

Installation parameters, specified in the CTTPARM member, determine how the CTTRTM utility operates. The following table describes these parameters:

Table 364 CTTRTM Installation Parameters

Parameter

Description

CTLGWAIT

Defines the number of wait days before the CTTRTM utility checks a catalog-controlled data set (meaning, one for that the DO RETENTION parameter is set to MVS CATALOG). In some cases, a data set is created during a job step and cataloged at the end of a later job step. If the CTTRTM utility is executed after the data set is created but before it is cataloged, the utility expires the data set. The CTLGWAIT parameter causes the CTTRTM utility to wait a specified number of days before checking if the data set is cataloged.

CYCLECNT

Defines how to calculate cyclic data sets. Valid values are:

  • DATE — Handles data sets with the same data set name and creation date as a single cycle. Default.

  • NONE — Handles data sets with the same data set name as separate cycles. The creation date is ignored.

  • JOB — Handles data sets with the same data set name and job name as a single cycle. The creation date is ignored.

  • JOBDATE — Handles data sets with the same data set name, creation date and job name as a single cycle.

EXPCAT

Controls whether to expire cataloged datasets or not. Valid values are:

  • Y (Yes) – Expire cataloged datasets according to the Control-M/Tape retention logic. Default.

  • N (No) – Do not expire cataloged datasets. Only after the dataset expires according to Control-M/Tape retention logic, and it is removed from the catalog, does Control-M/Tape expire the dataset.

  • G – Do not expire GDG cataloged datasets.

EXPDTYPE

Determines expiration logic depending on the type of retention criteria and value specified.

When DATE or DAYS retention criteria are assigned to a data set

  • CA1 — CA-1 expiration logic applies. DATE or DAYS specifies the day on that the data set volumes with "vault until date" are moved to the next vault or are returned to mainlib on the same day as mentioned in the rule. Default.

  • TLMS — TLMS expiration logic applies. DATE or DAYS specifies the last day of retention. Volumes only move to the next vault on the next day, one day later than mentioned in rule.

  • NONE — Expiration date in standard MVS format.

When cyclic retention criteria are specified

  • CA1 — CA-1 expiration logic applies. Only primary data sets (data sets with LABEL set to 1) are considered in the expiration calculation. Default.

  • Other — All cyclic data sets are considered regardless of label number.

GRACECAT

Defines the number of extended retention days added to the catalog controlled data set (when DO RETENTION is set to MVS CATALOG).

GRACECYC

Defines the number of extended retention days added to the cycle controlled data set (when DO RETENTION is set to CYCLES).

MODE

Determines whether to uncatalog expired data sets in the operating system catalog. Valid values are:

  • TEST — Data sets are not uncataloged.

  • PROD or PHASE — Data sets are uncataloged if no TEST rules match the expired data sets. For details, see the TESTRUL parameter in this table.

RTNTYPE

Determines whether retention is performed on a data set level or on a volume level, or on a multi-volume group. The parameter statement includes two options separated by a comma. The first option is the retention type for a single volume. The second option is the retention type for a multi-volume group.

Valid values for a single volume are:

  • DSN   - Each data set expires according to its own specified expiration date. That is, the data set becomes scratched regardless of the volume.

  • VOL   - All files of a multifile volume expire at the same time (meaning, when the last one expires). This is compatible with other tape management retention methods. Default.

Valid values for a multi-volume group are:

  • DSN   - - Each data set expires according to its own specified expiration date. That is, the data set becomes scratched regardless of the multi-volume group.

  • GROUP - All files of a multi-volume group expire at the same time (meaning, when the last one expires). This is compatible with other tape management retention methods. Default.

A volume becomes SCRATCH by the CTTRTM utility only after all its data sets have expired. The CTTRTM utility ignore the retention of the volume except for external volumes, or volumes without any datasets.

SMSINTR

Determines whether the Control-M/Tape to DF/SMS interface is active. If this interface is active and expiration dates are defined by SMS-managed classes, retention is dependent on expiration dates specified in SMS Management Classes.

  • Yes — The Control-M/Tape to DF/SMS interface is active.

    If CDAM files are allocated on SMS volumes, these volumes must be defined with PARTIAL RELEASE set to NO

  • No — The Control-M/Tape to DF/SMS interface is not active.

TESTRUL

Determines whether test rules are used in the production environment (global MODE is set to PROD or PHASED). If an expired data set matches a test rule, do not uncatalog the data set.

  • Yes — Test rules are used. The utility loads and scans the Control-M/Tape rules.

  • No — Test rules are not used. The utility does not load and scan the Control-M/Tape rules. Default.

For additional information see the discussion on specifying retention and vault parameters in the Control-M/Tape chapter of the INCONTROL for z/OS Installation Guide.

Activating the CTTRTM Utility

Copy 
//EXEC   CTTRTM
//SYSIN  DD *
    TYPERUN MODE=NORMAL|SIMULATION|[,DATE=date][,
            TRACE=YES|NO][,
            RESTART=YES|NO][,LIST=YES|NO|FULL][,
            MAXDSNO=nnn][,MAXVOLNO=nnn]
    TYPERET MODE=REGULAR|RECALC|CA1CONV|CONVERT[,
            UNCTLG=YES|NO][,UPDVOL=YES|NO][,FASTCAT=YES|NO]
 <INCLUDE/EXCLUDE statements>
 REPORT NAME={SCRATCH|RECALC}
 FIELDS ...
 SORTBY ...
 ATTR   ...
 BREAK  ...
//

CTTRTM Parameters

Utility parameters are supplied using DD statement SYSIN:

Although both the TYPERET and the REPORT parameters are optional, at least one of them must be specified.

Table 365 CTTRTM Parameters

Parameter

Description

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.

      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 the site standard set by the DATETYP parameter in IOAPARM. You can optionally include / (slash) characters as delimiters between the day, month, and year. For example, for a date in the American format, you can specify the date as mmddyy, mm/dd/yy, mmddyyyy, or mm/dd/yyyy. 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).

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.

      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.

    • 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 Online Facilities in the Control-M/Tape User Guide.

  • 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:

    • 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.

      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.

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

      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.

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.

CTTRTM Return Codes

Table 366 CTTRTM Return Codes

Code

Description

0

Operation performed successfully.

4

Minor errors detected. For more information, see accompanying messages.

8

Major errors detected. For more information, see accompanying messages.

12

Control card error

16

Load of Control-M/Tape routines failed.

20

Sort error occurred.

24

Media database input or output error occurred.

28

Internal error occurred.

32

Error in report printing utility occurred.

36

Load of rule, pool or vault table failed.

40

Authorization error (by security exit)

44

Media database file in use

48

Insufficient storage

52

Logical error in Media database

56

Number of data sets or volumes to be scratched exceeded the limit.

Examples for CTTRTM

The following series of examples demonstrate the usage of the CTTRTM utility.

CTTRTM Example 1

In the following example, retention management is performed according to the current retention specifications in the Media database. Report SCRATCH is printed, listing volser and media type and is sorted according to pool name. The list for each media type starts on a new page.

Copy 
//EXEC       CTTRTM
//SYSIN      DD *
    TYPERUN  MODE=NORMAL
    TYPERET  MODE=REGULAR
    REPORT   NAME=SCRATCH
    FIELDS   POOL,VOLSER,MEDIA
    SORTBY   POOL,MEDIA/B,VOLSER
//

CTTRTM Example 2

In the following example, retention information is updated for all data sets whose name begins with prefix BKP and all volumes where these datasets reside:

Copy 
//EXEC     CTTRTM
//SYSIN    DD *
    TYPERUN  MODE=NORMAL
    TYPERET  MODE=CONVERT,UPDVOL=YES 
    INCLUDE  DSNAME=BKP*
    REPORT   NAME=SCRATCH
    FIELDS   EXPDT,MEDIA,VOLSER,POOL
    SORTBY   EXPDT
//

CTTRTM Example 3

In the following example, the utility is used to produce the scratch report from the last finished run of the CTTRTM utility:

Copy 
//EXEC     CTTRTM
//SYSIN    DD *
    TYPERUN  MODE=NORMAL
    REPORT   NAME=SCRATCH
    FIELDS   fields
    SORTBY   fields
//

CTTRTM Example 4

In the following example, retention information is recalculated for all data sets in the Media database. A RECALC report is produced listing the data sets whose retention information changed and the old and new expiration information for these data sets.

Copy 
TYPERUN MODE=NORMALTYPERET MODE=RECALC               
REPORT  NAME=RECALC
FIELDS  VOLSER/C4/L6,LABEL/C12/L3,DSNAME/C17/L44,
        OLDEXDT1/C63/L10,OLDXDTR1/C75/L1,
        OLDEXDT2/C78/L11,OLDXDTR2/C91/L1,
        OLDEXDT3/C94/L10,ID=P
FIELDS  NEWEXDT1/C63/L10,NEWXDTR1/C75/L1,
        NEWEXDT2/C78/L11,NEWXDTR2/C91/L1,
        NEWEXDT3/C94/L10,ID=S
ATTR    FIELD=OLDXDTR1,TITLE=' ',LENGTH=1
ATTR    FIELD=OLDXDTR2,TITLE=' ',LENGTH=1
ATTR    FIELD=NEWXDTR1,TITLE=' ',LENGTH=1
ATTR    FIELD=NEWXDTR2,TITLE=' ',LENGTH=1
ATTR    FIELD=OLDEXDT1,TITLE='OLD-'
ATTR    FIELD=NEWEXDT1,TITLE='NEW-'
ATTR    FIELD=OLDEXDT2,TITLE='EXPIRATION-'
ATTR    FIELD=NEWEXDT2,TITLE='EXPIRATION-'
ATTR    FIELD=OLDEXDT3,TITLE='DATA'
ATTR    FIELD=NEWEXDT3,TITLE='DATA'
ATTR    FIELD=LABEL,TITLE='LBL',EDIT='999'

The following report is generated:

Copy 
BMC, LTD.        CONTROL-M/TAPE REPORT (Ver 6.1.00)      DATE 27/11/2000 TIME 15.10   PAGE 1

                                                    List of Datasets With Recalculated Expiration
                                                    ---------------------------------------------


First   LBL  DATASET                    OLD-           EXPIRATION-     DATA
 Volume       NAME
                                        NEW-           EXPIRATION-     DATA
------  ---  --------------------------------------------  ----------  -  ---
 B21002  001  M27.BACKUP.BD1.D971111            Catalog   O  01/04/2000
                                 Cycl+0003   A  Catalog    O  25/05/2000

 B21002  002  M27.BACKUP.BD2.D971111                       01/04/2000
                                 Cycl+0003   A  Catalog    O  25/05/2000

B21003  001  M27.BACKUP.NBD3.D971112                      Catalog
                                 Cycl+0003   A  Catalog    O  25/05/2000

B21003  002  M27.BACKUP.NBD4.D971112                     Cycl+0005   A  Catalog
                                                         Cycl+0003   A  Catalog     O  25/05/2000

CHKINE  001  N89.CHKIN.SET                                 01/01/2000  O  Cycl+0005
                                                                               23/09/1999

CHKINF  001  N89.CHKIN.SET                                 01/01/2000
                                                                               23/09/1998

CHKING  001  N89.CHKIN.SET                                 01/01/2000
                                                                               23/09/1998

CHKINH  001  N89.CHKIN.SET                                 01/01/2000
                                                                           24/09/1998

CTTSBD – Perform Data Set Stacking in Batch Mode

The CTTSBD utility copies data sets residing on removable media. It supplements the Control-M/Tape Dynamic Dataset Stacking facility, which controls the placement of data sets at time of creation.

The CTTSBD utility enables you to copy existing data sets (input data sets) from one location to another. Output data sets (the new copies) can be new data sets with their own names and retention or they can replace input data sets by "taking over" relevant catalog entries and assuming certain attributes of the input data sets.

If you are working in an SMS-managed environment, it is important to ensure that no DATACLASS ACS routines modify or set attributes of data sets created by the CTTSBD utility (for example, using keywords RECFM, LRECL or BLKSIZE).

The CTTSBD utility enables you to

  • copy multiple input data sets to a single output volume or a multi-volume chain (stacking)

  • copy each data set from an input volume or volume chain to a separate output volume (unstacking)

  • select input data sets and volumes according to various criteria

  • control grouping of output data sets in a volume (or volume chain)

  • copy the attributes of input data sets to the output data sets. Attributes describing data set name, catalog reference, retention information, creating job, and so on, can be copied

  • analyze free (available) space in the tape library and associated costs

Running the CTTSBD utility to stack multiple data sets is called Batch stacking. Batch stacking helps you

  • increase the number of available (scratch) tapes in a tape library

  • free scratch volumes to satisfy immediate production needs

  • simplify stacking implementation at your site

  • control the growth of your cartridge inventory

  • refresh old media

  • migrate data sets from one media type to another

  • implement new or modified site standards regarding which data sets (for example,data sets created by different applications) can or cannot reside on the same volumes

  • create additional copies of existing data sets for backup, shipping off-site or usage by other applications

  • reclaim space occupied by expired data sets on multi-file volumes

Utility Logic (CTTSBD)

The CTTSBD utility searches the Media database for data sets and volumes that satisfy selection criteria specified in INCLUDE / EXCLUDE statements.

Selected volumes are sorted according to the volser of the first volume in each input volume chain. Each data set on each selected volume chain is then copied to a new volume or volume chain. Various parameters are used to control the actions taken by the CTTSBD utility, such as

  • whether to copy expired data sets

  • which data sets can reside together on the same output volume chain

  • how many data sets or volumes can be in a volume chain

When a data set is successfully copied, the CTTSBD utility updates the relevant Media database records and catalog information according to user specifications. Using the CTTSBD utility parameters, the user can indicate

  • cataloging of the output data set (OUTCAT parameter)

  • retention of output and/or input data sets (OUTRET and INRET parameters)

  • Vault pattern of output and/or input volumes (INVAULT and OUTVAULT parameters)

  • copying of certain historical information about the input data set to the output data set record (COPYATTR parameter)

The CTTSBD utility terminates when one of the following occurs:

  • All selected volumes have been processed.

  • An operator command is issued (see "Modify Command").

  • A specified number of input volumes have been processed (NUMVOL parameter).

  • A specified maximum amount of time has passed (TIMELIM parameter).

  • Processing of a specified maximum allowed number of input volume chains is stopped due to runtime errors (MAXERR parameter).

Execution Considerations

Run the CTTRTM utility after running the CTTSBD utility to scratch newly freed volumes. If you run CTTSBD with VAULT=YES, then the CTTVTM utility should also be run after running the CTTSBD utility to perform volume movement. For more information, see Batch Stacking and Vault Management.

The CTTSBD utility does not handle external or EDM-managed volumes

Resource Requirements

Resource requirements can help you decide when is the best time to run the CTTSBD utility. The duration of resource consumption depends primarily on the number of volumes selected for processing by the CTTSBD utility. Shown below is a description of the various resources used by this utility.

Table 367 CTTSBD Resource Requirements

Resource

Description

Disk processing

CTTSBD disk processing includes sequential processing of the Media database and multiple sort phases.

  • In NORMAL mode, disk processing is performed during the selection phase only. After the first volume is mounted for copying, disk processing becomes minimal.

  • In SIMULATION mode, volume selection is the primary action performed by the utility. In this mode, the utility runs faster even though disk processing continues during most of the run.

Tape processing

CTTSBD tape resource consumption is similar to that of any other tape-to-tape copy or backup program that uses two tape drives.

Memory Requirements

CTTSBD uses memory resident information about volumes and data sets. Storage is allocated as new volume chains are created. Virtual storage requirements for this utility depend on

  • The number of output volume chains created by the utility.

  • The maximum number of data sets allowed in each output volume chain.

Exit CTTX011

Control-M/Tape Exit CTTX011 enhances the functionality of the CTTSBD utility by allowing placement of output files to be dependent on stacking criteria that cannot be specified using utility parameters (for example, security constants).

Information passed to this exit describes

  • The input data set name

  • The candidate output volume

  • The data sets already residing on the output volume chain being considered as a location for the output data set

This exit examines the information provided and does one of the following:

  • Allows placement of the output data set on the candidate output volume

  • Rejects placement of the output data set on the candidate output volume

  • Forces placement of the output data set on a scratch volume

  • Grants the candidate output volume preferred status

  • Passes (meaning,the exit does not influence CTTSBD processing)

For more information about this exit, see member CTTX011 in the IOA SAMPEXIT library.

Retention

When an output data set is written by the CTTSBD utility, it is subjected to Control-M/Tape rules for retention. When the data set is successfully copied, retention of the input and/or output data sets can be modified according to the setting of the parameters INRET, OUTRET and OUTCAT.

BMC recommends that you run the CTTRTM utility after running the CTTSBD utility to scratch newly freed volumes.

If data sets with CYCLE type retention are to be handled by the CTTSBD utility, a specific number must be specified for the INRET and OUTRET utility parameters. If a data set with CYCLE type retention is detected and no specific value was specified for at least one of these parameters, the data set is ignored (skipped) and the utility continues to process the next data set in the current input volume chain.

Batch Stacking and Vault Management

The CTTSBD utility copies data sets on volumes that reside in the main library and are not scheduled for storage in an off-site vault. By default, volumes that are in a vault or are scheduled to be transferred to a vault, are not selected by CTTSBD, even if specified INCLUDE / EXCLUDE statements explicitly state otherwise.

Some sites use vault management for administrative purposes other than off-site storage. At such a site, use the VAULTED parameter to indicate that vaulted (and to-be-vaulted) volumes are processed by the CTTSBD utility.

When an output data set is written by the CTTSBD utility, it is subjected to Control-M/Tape rules for vaulting. When the data set is successfully copied, vaulting of the input and output volumes can be modified according to the setting of the INVAULT and OUTVAULT parameters.

Volume and Data Set Information

When an output data set is created by the CTTSBD utility, the Media database initially describes the data set as a new file. There is no indication that this file is a copy of another data set.

After the output data set is successfully written, various attributes can be set by the CTTSBD utility in the relevant Media database records. For more information, see the COPYATTR parameter in CTTSBD General Utility Parameters.

Data Set Record

When a data set is copied, Control-M/Tape assigns various attributes to it. For example

  • Creation date (the date the CTTSBD utility was run).

  • Retention information (subject to active Control-M/Tape rules).

The CTTSBD utility can optionally be instructed to copy certain attributes of the input data set to the data set record of the output data set and to override the above settings. For more information, see the OUTRET and COPYATTR parameters in CTTSBD General Utility Parameters.

Certain physical attributes of the output data set are not modified by the CTTSBD utility. These physical attributes include volume serial numbers label number, blocking and size.

Volume Record

The CTTSBD utility can optionally be instructed to copy the vault pattern of the input volume to the volume record of the output volume by setting the OUTVAULT parameter. Except for the vaulting pattern, no volume information from the input volume records is copied to the output volume records. Output volume records are not modified by the CTTSBD utility. They contain information that is relevant to only the output volumes.

Stacking Logic

The CTTSBD utility augments the Control-M/Tape Dynamic Dataset Stacking facility by allowing multiple pre-existing data sets to be copied and stacked according to specified criteria.

Data sets are placed on output volumes according to stacking parameters and runtime parameters specified by the user.

Output data set size is calculated according to the known size of input data sets and runtime information about output volumes. The output data set size is used to determine whether there is sufficient space in a given volume chain to stack the data set.

Output data sets are stacked only on volumes that became active during the current run of the CTTSBD utility. If no appropriate volume is found, the data set is written on a scratch volume.

Batch Stacking and Dynamic Data Set Stacking

Data sets written by the CTTSBD utility are not stacked by the Control-M/Tape Dynamic Dataset Stacking facility. DO STACK, DO STKRULE and DO STKGROUP statements in relevant Control-M/Tape rules are ignored by the CTTSBD utility.

Use the CTTSBD utility to implement data set grouping similar to the grouping produced by DO STKGROUP statements. Also, to force stacking of data sets that are not normally stacked by the Dynamic Dataset Stacking facility.

Batch stacking can be used to complement the Dynamic Dataset Stacking facility in the following way:

  • Data sets are normally stacked using the Control-M/Tape Dynamic Dataset Stacking facility at time of creation.

  • The CTTSBD utility can be run periodically to consolidate under-utilized volumes and to alter data set placement according to site needs.

Data Set Groups

A data set group is a collection of data sets for which stacking statements can be specified.

  • A group name is assigned to each data set.

  • Each group name is associated with a set of stacking statements that determine where (and with which data sets) members of the data set group can be stacked.

  • To apply a stacking statement to a data set, the data set must first be associated with a data set group.

  • Group names are re-assigned each time the CTTSBD utility is run.

All statements specified for data set groups are applied using input data set names. Prefixes and/or suffixes (OUTPREF and OUTSUFF parameters) added to data set names do not affect application of data set group stacking statements during the current run of the utility. However, these prefixes may affect future runs of the utility.

Assume the following:

  • Input data sets ACCT.JAN00 and ACCT.FEB00 are assigned to group ACCT.

  • A prefix of NEW is added to output data set names for group ACCT.

  • Input data sets NEW.ACCT.NOV99 and NEW.ACCT.DEC99 are assigned to group NEW. (These data sets may have been created by a previous run of the CTTSBD utility.)

  • No prefix is added to output data set names for group NEW.

  • The CTTSBD utility selects all data sets from group ACCT and group NEW.

The following output data sets are created by this run of the CTTSBD utility:

Table 368 CTTSBD Data Sets

Input Data set Name

Input Data set Group

Output Data set Name

Output Data set Group

ACCT.JAN00

ACCT

NEW.ACCT.JAN00

ACCT

ACCT.FEB00

ACCT

NEW.ACCT.FEB00

ACCT

NEW.ACCT.NOV99

NEW

NEW.ACCT.NOV99

NEW

NEW.ACCT.DEC99

NEW

NEW.ACCT.DEC99

NEW

The group name assigned to each input data set is automatically assigned to the corresponding output data set (regardless of the output data set name).

Determination of Output Data Set Location

The CTTSBD utility determines placement for output data sets in the following way:

The CTTSBD utility first attempts to place the current data set on the current output volume chain (meaning, the chain on that the previous data set was stacked).

  • If the data set cannot be placed on the current volume chain, the CTTSBD utility attempts to place the data set on the first volume chain created during this run of the utility.

  • If the first volume chain is not suitable, the second one is considered, and so on. The CTTSBD utility considers each chain created during this run (in the order in which they were created) as a possible location for the current data set until either a suitable volume chain is found or all chains have been considered.

  • If no suitable volume chain is found, the data set is placed on a scratch volume.

Data sets can be stacked on volumes (or multi-volume chains) created during a run of the CTTSBD utility even after the volumes have been dismounted.

Each volume chain considered as a possible location for the current data set is processed in the following way:

  1. The data set group definition associated with the current data set is compared with the data set group definition of each data set on the candidate volume chain.

    If a statement specified in any data set group definition does not allow the data sets to coexist in the same volume chain (due to group name, job name or data set name) the CTTSBD utility rejects the volume chain and attempts to place the data set on the next volume chain. (Data set group stacking parameters are described in detail later is this guide.)

  2. The CTTSBD utility searches the data set group definitions for a WITHGRP statement that indicates that the current data set must be stacked together with the data sets on the candidate volume chain. Anappropriate WITHGRP statement can exist in the data set group definition of the current data set and/or a data set on the candidate volume chain. (WITHGRP statements are described in detail later in this guide.)

    • If a matching WITHGRP statement is found, the CTTSBD utility copies the data set to the volume chain (as long as limits specified to the utility have not been exceeded).

      You can maximize media utilization by instructing the CTTSBD utility to create output volume chains containing a large number of volumes (using the OUTMVLIM parameter). You can also control the number of data sets in an output volume chain using the MAXLABEL parameter. If the specified maximum number of volumes in a chain is exceeded during the writing of a multi-volume data set (for example,due to an inaccurate prediction concerning data set length) the utility CTTSBD continues writing the data set on as many volumes as required.

    • If no matching WITHGRP statement is found, the CTTSBD utility rejects the volume chain and attempts to place the data set on the next volume chain.

      Exit CTTX011 (if implemented) is invoked at various stages in the above process to modify or force a stacking decision. For more information, see Exit CTTX011 and the CTTX011 member in the IOA SAMPEXIT library.

Masking

Mask characters are supported for many of the parameters of the CTTSBD utility. The ability to use mask characters is indicated in the description of the relevant parameters. The following mask characters can be used:

Table 369 CTTSBD Masks

Mask

Description

?

Represents any one character

*

Represents any number of characters (or no characters). This mask character is only supported when at the end of a mask.

Table 370 CTTSBD Mask Examples

Example

Description

JBN?

Matches JBN1, JBN2, and so on

J?N?

Matches JBN1, JAN1, JUN2, and so on

JBN*

Matches JBN1, JBN2, JBN123, JBN, JBN1234, and so on

*BN

Invalid mask

Stopping Utility CTTSBD

The CTTSBD utility may run for a long time. If you need to free up resources (for example, tape drives) for other processing, you can stop the CTTSBD utility using the following operator command:

Copy 
F  jobname,STOP

where jobname is the name of the job or started task that is executing the CTTSBD utility

When the above STOP command is issued, the CTTSBD utility acknowledges this fact (using an operator message) and continues processing the remaining data sets in the current input volume chain. When the current chain has been completely processed, the CTTSBD utility stops.

If the CTTSBD utility is restarted, you may need to modify the INCLUDE / EXCLUDE statements so that previously processed volume chains are not processed again.

Reports

The CTTSBD utility produces a variety of reports detailing information relevant to the run of the utility.

  • The Media Utilization report lists the number of volumes and the amount of available space in each of several media categories (scratch tapes, non-scratch tapes, and so on.)

  • The Input Volume Inventory report lists all input volumes selected for the run of utility CTTSBD and the data sets residing on those volumes.

  • The Output Volume Inventory report lists all output volumes created during the run of utility CTTSBD and the data sets residing on those volumes.

    The Output Volume Inventory report identifies output data sets whose names are identical to the corresponding input data set names. Neither the input nor the output data set is cataloged. Using this report, such data sets can be tracked, making it easier for you to take action (if necessary).

  • The Detailed Input or Output report lists the input data sets and the corresponding output data sets, output volumes, label numbers and retention information.

    Expiration dates listed in this report for input data sets are the expiration dates after the data sets have been processed by the CTTSBD utility. Theoriginal expiration date for these data sets is listed in the Input Volume Inventory report, described above.

  • The Output Volume Access report lists output data sets (in the order in which they were created) and the output volume on which each output data set was written. This report serves as a log for output volume mounts.

You can generate additional reports from the Media database using the CTTRPT utility. For more information, see CTTRPT – Database extraction and report utility.

Simulation Reports

The CTTSBD utility can be run in simulation mode. This mode can be used to experiment with various stacking configurations (meaning, data set group definitions) without effecting data set location in the tape library.

In simulation mode, the CTTSBD utility calculates output volume capacity according to the value specified for the OUTVOLMB parameter. A very large value can be specified for the OUTVOLMB parameter to indicate virtually unlimited capacity for output volumes. This is useful for determining how many logical sets of output files are produced by a run of the CTTSBD utility.

Multiple runs of the CTTSBD utility in simulation mode can be used to compare the results of batch stacking with various combinations of input volumes. The reports produced are described above.

The reports generated by a run of the CTTSBD utility in simulation mode assume that arbitrary scratch volumes are mounted and numbered with fictitious volume serial numbers (volsers) such as 000001, 000002, 000003, and so on. Simulated mounts are listed according to the volsers of the fictitious scratch volumes.

Unstacking

The CTTSBD utility can unstack volume chains containing multiple data sets. Unstacking is the process of copying each data set to a different scratch tape, without stacking additional data sets on the output volumes.

Input data sets are unstacked by specifying stacking statements (in data set group definitions) that prohibit each data set in a specified group from coexisting on a volume with any other data set or by limiting the number of data sets that can be stacked on a single volume.

For more information, see CTTSBD Example 2.

Recovery from abends

The CTTSBD utility can perform recovery operations

  • upon encountering a recoverable error during a run of the utility

  • upon initialization of the utility following a run of the utility that was terminated due to a nonrecoverable error or a system crash

Recovery is performed as follows:

  • If an input data set was uncataloged and failure occurred before the corresponding output data set was cataloged, the CTTSBD utility attempts to recatalog the input data set during the recovery process.

    The CTTSBD utility attempts to recatalog a data set only once. If the recatalog attempt fails, the data set has to be recataloged manually.

  • In all other cases, input and output data sets remain in the state they were in at time of failure (meaning,the abend or system crash).

This recovery logic ensures that at least one copy of each data set is always retained and, if necessary, cataloged. It may be necessary to scratch a single unneeded output data set created by an incomplete run of the CTTSBD utility.

During recovery, the CTTSBD utility must process no more than one data set - the data set that was being processed at time of abend. Data sets processed prior to the abend require no further processing.

If the CTTSBD utility abended due to a physical or logical error in the Media database, use standard Control-M/Tape methods to perform recovery. For more information, see the section that discusses repository backup and recovery in the Control-M/Tape chapter of the INCONTROL for z/OS Administrator Guide.

Relevant Installation Parameters

Certain Control-M/Tape installation parameters (specified in the CTTPARM member) may be relevant to CTTSBD utility operations. These parameters are described below.

Table 371 Relevant Control-M/Tape Installation Parameters

Parameter

Description

DYNSTK

Determines whether the Control-M/Tape Dynamic Dataset Stacking facility is activated. The CTTSBD utility performs batch stacking even if DYNSTK is set to N (No).

MEDIA

Specifies a Control-M/Tape logical media definitions.

The CTTSBD utility uses media definitions specified during Control-M/Tape installation (and other information) during calculation of output volume capacity.

If volume capacity information produced during a run of CTTSBD appears to be inaccurate, it may be necessary to modify the media definition for the relevant volumes.

MODE

Determines Control-M/Tape operation mode. The CTTSBD utility is fully functional only when MODE is set to PROD. However, CTTSBD can be run in simulation mode while Control-M/Tape is operating in any mode (TEST, PHASED or PROD) or even when Control-M/Tape is not active.

RTNTYPE

Determines whether retention is performed on a data set level or on a volume level.

Input data sets are considered expired by the CTTSBD utility only if they have already been marked as expired by Control-M/Tape (for example, using the CTTRTM utility).

If RTNTYPE is set to DSN in member CTTPARM, data sets whose expiration conditions are met are expired by Control-M/Tape. If COPYEXPF is set to NO in the CTTSBD utility, these data sets are not copied during batch stacking.

If RTNTYPE is set to VOL in member CTTPARM, data sets whose expiration criteria are met are not expired by Control-M/Tape until all data sets on the volume can be expired. These data sets are copied during batch stacking regardless of the value specified for CTTSBD parameter COPYEXPF.

STKMODE

Determines the search algorithm to be used by the Control-M/Tape Dynamic Dataset Stacking facility. The CTTSBD utility ignores the setting for this parameter. The CHAINRET parameter (described in CTTSBD General Utility Parameters) provides similar controls for utility CTTSBD.

For more information on the above installation parameters, see the topic about specifying stacking parameters in the Control-M/Tape chapter of the INCONTROL for z/OS Installation Guide.

Preparation Steps

The following steps must be performed before the first run of the CTTSBD utility at your site:

  1. Allocate and format the CTTSBD utility Checkpoint-Restart data set using the CTTSBF batch job in the Control-M/Tape JCL library.

  2. Implement security considerations.

    The CTTSB Control-M/Tape utility reads and writes data sets in the library for your site. Relevant Media database records are subsequently updated. Therefore, the user ID associated with the job or started task that executes the utility must be authorized to

    • Read selected input data sets.

    • Create and write the output data sets (whose names may or may not be the same as the names of the input data sets).

    • Read and update Media database records.

Consult your security administrator to ensure that the required authorization is defined for the user that runs the CTTSBD utility.

Activating the CTTSBD Utility

Copy 
//EXEC      CTTSBD
//SYSIN     DD *
    TYPERUN MODE=NORMAL|SIMULATION[,NUMVOL=n][,
            TIMELIM=n],INUNIT=xxxx,OUTUNIT=xxxx,
            OUTRET=RULE|SAME|nnnn,COPYATTR=YES|NO[,
            CHAINRET=ONE|ANY][,OUTPREF=xxx|NONE][,
            OUTSUFF=xxx|NONE]OUTCAT=YES|NO|RECAT[,
            COPYEXPF=YES|NO][,OUTMVLIM=n][,MAXLABEL=n][,
            VAULTED=YES|NO|ONLY],INRET=nnnn|SAME[,
            OUTVOLMB=nnnnnn][,MAXERR=n][,CARTCOST=n][,
            PROCESS=CHAIN|DATASET][,INVAULT=SAME|nnnn]
[,OUTVAULT=RULE|SAME]
    [INCLUDE/EXCLUDE statements]
/*
//CTTSBGRP  DD *
    GROUP   NAME=groupname[,OUTMVLIM=n][,
            MAXLABEL=nnnn][,OUTPREF=xxx|NONE][,
            OUTSUFF=xxx|NONE][,INUNIT=xxxx][,
            OUTUNIT=xxxx]
          DATASET  [DSNAME=dsname-mask][,
                   CREJBN=jobname-mask]
          DATASET ...
          [WITHGRP NAME=SAME|mask]
          ...
          [NOTWGRP NAME=SAME|mask|OTHER]
          ...
          [NOTWJOB  NAME=SAME|mask]
          ...
          [NOTWDSN  NAME=SAME|mask]
          ...
    GROUP ...
...

CTTSBD Parameters

Parameters specified for the CTTSBD utility are arranged in the following way:

  • General utility parameters are specified using the SYSIN DD statement. These parameters are arranged in one mandatory TYPERUN statement followed by one or more INCLUDE / EXCLUDE statements. The parameters that can be included in these statements are described below.

  • Data set group parameters are specified using DD statement CTTSBGRP. Each group is defined by a single GROUP statement followed by any number of DATASET, WITHGRP, NOTWGRP, NOTWDSN and NOTWJOB statements in any order. For valid statements and parameters for data set group stacking, see Data set Group Stacking Parameters.

CTTSBD General Utility Parameters

Utility parameters are supplied using the SYSIN DD statement, and are shown in Table 372.

Table 372 CTTSBD General Utility Parameters

Parameter

Description

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. Valid values are:

    • NORMAL — The CTTSBD utility copies specified data sets and updates the MVS Catalog and the Control-M/Tape Media database as specified by utility parameters. The utility also produces various reports that describe the operations it performed.

    • SIMULATION — The CTTSBD utility selects input volumes       according to specified INCLUDE or EXCLUDE statements and produces a report indicating how input data sets are distributed in output volume chains if the CTTSBD utility were run in NORMAL mode. No input or output volumes are accessed.

  • NUMVOL — Specifies a maximum number of input volumes to be processed. Optional. Avalue from 0 through 9999 can be specified. When the specified number of input volumes is reached, the CTTSBD utility finishes processing the data sets in the current input volume chain before stopping. If no value is specified for this parameter, all selected volumes and data sets are processed.

  • TIMELIM — Elapsed time (in minutes) beyond which the utility is stopped. Avalue from 0 through 9999 can be specified. Default: No time limit. If the specified time limit is reached, the CTTSBD utility finishes processing the data sets in the current input volume chain before stopping.

  • INUNIT — Unit name or unit address to be used by the CTTSBD utility for allocation of each input data set. Aname of up to eight characters can be specified. Mandatory. This parameter can be overridden for specific data sets using the INUNIT parameter in a data set group definition.

  • OUTUNIT — Unit name or unit address to be used by the CTTSBD utility for allocation of each output data set. Aname of up to eight characters can be specified. Mandatory. This parameter can be overridden for specific data sets using parameter OUTUNIT in a data set group definition.

  • INRET — Indicates retention for input data sets. This parameter specifies how long input data sets are retained after they are copied. Mandatory. Valid values are:

    • nnnn — Retain input data sets nnnn days before scratching them. Anumber from 0 through 9999 can be specified.

    • SAME — Do not modify type or duration of retention for input data sets.

  • OUTRET — Indicates retention information to be used for the output data set. Mandatory. Valid values are:

    • nnnn — The specific number of days to retain output data sets. Anumber from 1 through 9999 can be specified.

    • SAME — Copy retention information (for example, retention type and expiration date) from input data set. Fields RTNFROM, JCLEXPDT, DSEXPTYP, and DSEXPDT are copied from the input data set record.

    • RULE — Apply Control-M/Tape rules to determine retention of the newly created output data set.Default.

  • COPYATTR — Indicates whether certain attributes of an input data set are copied to the corresponding output data set. Mandatory. Valid values are:

    • Yes — Copy data set attributes (for example,creation date, creating job and creating program) from the input data set to the output data set. This information replaces the attributes assigned by Control-M/Tape to the newly created data set.

      The following fields are copied from the input data set record:

             ACCOUNT

             CREDDN

             CREJOBID

             CREUAD

             DSUSECT

             READCC

             READDT

             READSTEP

             WRITECCL

             WRITEDT

             WRITESTP

          CRECC

          CREDT

          CRESTEP

          CREUSER

          DUSRDATA

          READCPU

          READJBN

          READTM

          WRITECPU

          WRITEJBN

          WRITETM

      CRECPU

      CREJBN

      CRETM

      DSEXCP

      LASTACCS

      READDDN

      READPGM|

      READUAD

      WRITEDDN

      WRITEPGM

      WRITEUAD

      For more information on the content of these fields, see the appendix that discusses logical field names for the Control-M/Tape Repository in the INCONTROL for z/OS Administrator Guide.

      - No — Do not copy attributes from the input data set to the output data set.

  • CHAINRET — Determines whether the CTTSBD utility forces a uniform retention type on output volume chains. Valid values are:

    • ONE — All data sets placed on a given output chain must have the same retention type (for example, specific date or CATALOG). An output data set is added to an existing chain only if its retention type is identical to that of data sets already in the chain.

    • ANY — Data sets with different retention types can reside on the same output volume chain. Default.

  • OUTPREF — Prefix to be added to the names of output data sets. Aperiod is inserted between the new prefix and the original data set name. Valid values are:

    • xxx — Prefix to be added (1 to 20 characters). Aperiod can be specified as part of the OUTPREF value.

    • NONE — Add no prefix to the data set name. Default.

This parameter can be overridden for specific data sets using parameter OUTPREF in a data set group definition.

If a new data set name exceeds 44 characters, the CTTSBD utility stops processing the current input volume chain.

  • OUTSUFF — Suffix to be added to output data set names. Aperiod is inserted between the original data set name and the new suffix. Valid values are:

    • xxx — Suffix to be added (1 to 20 characters). A period can be specified as part of the OUTSUFF value.

    • NONE — Add no suffix to the data set name. Default.

    This parameter can be overridden for specific data sets using parameter OUTSUFF in a data set group definition.

    If a new data set name exceeds 44 characters, the CTTSBD utility stops processing the current input volume chain.

  • OUTCAT — Indicates whether the output data set must be cataloged. Mandatory. Valid values are:

    • Yes — The action taken depends on whether the input and output data sets have the same name. If the input data set and the output data set have the same name (meaning, no prefix or suffix was added) catalog the output data set. If the input data set was cataloged, uncatalog it. If the input and the output data sets do not have the same name, catalog the output data set. If the input data set was cataloged, it remains cataloged. If the output data set name was already cataloged, the utility stops processing the current input volume chain.

    • No — Do not catalog the output data set.

    • RECAT — Catalog the output data set only if the input data set was cataloged. Uncatalog the input data set.

  • COPYEXPF — Specifies whether input data sets with expired retention should be copied during this run of the CTTSBD utility. Optional. Valid values are:

    • Yes — Copy all data sets to output volumes.

    • No — Do not copy data sets marked as expired. Default.

    • COPYEXPF – Do not copy ACTIVE data sets.

      If an expired data set is copied by the CTTSBD utility, its status is changed to ACTIVE (meaning, it is unscratched).

  • OUTMVLIM — Specifies a maximum number of volumes for multi-volume chains created by the CTTSBD utility. Optional. Default: 1
    The OUTMVLIM parameter in a data set group definition can override this parameter for specific data sets.

    Data sets can be stacked on volumes (or multi-volume chains) created in a given run of the CTTSBD utility even after they have been dismounted. If the specified limit is exceeded during the writing of a multi-volume data set (for example, due to inaccurate information about data set length) the CTTSBD utility continues writing the data set on as many volumes as required.

  • MAXLABEL — Specifies a maximum number of data sets to be stored in an output volume chain created by the CTTSBD utility. Avalue from 1 through 9999 can be specified.
    Default: 100
    This parameter can be overridden for specific data sets using parameter MAXLABEL in a data set group definition.

    Data sets can be stacked on volumes (or multi-volume chains) created in a given run of the CTTSBD utility even after they have been dismounted.

  • VAULTED — Specifies if selected input volumes that are in a vault or are scheduled to be vaulted, are processed by the CTTSBD utility. Valid values are:

    • YES — Process vaulted (and to-be-vaulted) volumes.

    • NO — Do not process vaulted (or to-be-vaulted)| volumes. Default.

    • ONLY — Process only vaulted (and to-be-vaulted) volumes.

      If either YES or RECAT is specified for the OUTCAT parameter and the retention type of the input data set is CATALOG, the input data set is expired when it is uncataloged by the CTTSBD utility.

      To retain these input data sets for a longer period, you must indicate a specific retention period using the INRET parameter.

  • INVAULT— Indicate vault retention for input volumes. This parameter specifies how long the input volumes are to be retained in their current vault and whether to move them to the next vaults. Valid values are:

    • 0 – Input volumes will be recalled permanently and will not continue moving to the next vaults. Default

    • nnn – Retain input volumes nnn days in current vault, and then continue moving to next vaults.

    • SAME – Do not modify vault retention for input volumes

      Maximum value for INVAULT is 999.

  • OUTVAULT— Indicate vault pattern to be used for the output volume. Valid values are:

    • RULE— Apply Control-M/Tape rules to determine vault pattern of the newly created output volume. Default.

    • SAME — Copy vault pattern from input volume to the output volume. When using this option the utility will ensure that only input volumes with the same vault pattern will be copied to the same output volume.

  • OUTVOLMB — Indicates the capacity (in megabytes) of an output volume. This parameter is most useful for prediction of utility results when running in simulation mode.

    A value from 1 through 1000000 can be specified. Default: 200
    A very large value can be used during simulation to determine how many logical sets of output data sets are created by a run of the CTTSBD utility. For more information, see Simulation Reports.

  • MAXERR – Maximum number of severe runtime errors before the utility shuts down. Normally, when the program encounters a severe error, the CTTSBD utility abandons the current input volume chain and skips to the next input volume chain. This parameter can be used to specify a maximum number of severe errors that can be encountered during a run of the CTTSBD utility. If the specified number of severe errors is reached, the utility shuts down. Valid values are 0-100. This parameter is relevant only when the utility is running in normal mode. Default: 1

    If MAXERR is set to 0, the CTTSBD utility continues no matter how many severe errors are encountered.

  • PARALLEL – Run more than one job of the CTTSBD utility at the same time. Valid values are:

    • NO – Only one job of the CTTSBD utility can run at any one time. Default.

    • YES – More than one job of the CTTSBD utility can run at any one time.

  • CARTCOST — Cost of a single volume (cartridge) in the tape library. This value includes media, slot space, automated tape library, and management costs. A value from 1 through 1000000 can be specified. Default:20
    This parameter can be used to estimate savings resulting from a run of the CTTSBD utility at your site.

  • PROCESS — Instructions for handling data sets that exist on the same input volume chain as a data set that matches an INCLUDE / EXCLUDE statement. Valid values are:

    • CHAIN — The INCLUDE / EXCLUDE statement applies to all data sets in the same input volume chain (meaning, either all or none of the data sets are processed). Default.

      If one or more data sets in an input volume chain match and INCLUDE statement, all data sets in the chain are selected. If one or more data sets in an input volume chain were rejected by the INCLUDE / EXCLUDE statements, no data sets in the chain are processed.

    • DATASET — Only data sets that match the specified INCLUDE selection criteria and are not rejected by subsequent EXCLUDE statements are processed.

The following examples describe how parameter PROCESS can influence the processing of an input volume chain.

All examples below apply to an input volume chain containing the following data sets:

  • SYS1 — Begins on volume VOL001 and ends on VOL002.

  • SYS2 — Begins on volume VOL002 and ends on VOL003.

  • SYS3 — Resides on VOL003.

Example 1

The following INCLUDE / EXCLUDE statements are specified:

Copy 
INCLUDE VOLSER=*
EXCLUDE DSNAME=SYS1

The results are as follows:

  • If PROCESS is set to CHAIN, none of the data sets are processed by the utility.

  • If PROCESS is set to DATASET, only SYS2 and SYS3 data sets are processed by the utility.

Example 2

The following INCLUDE / EXCLUDE statements are specified:

Copy 
INCLUDE VOLSER=
INCLUDE DSNAME=SYS3
EXCLUDE DSNAME=SYS1

The results are as follows:

  • If PROCESS is set to CHAIN, none of the data sets are processed by the utility.

  • If PROCESS is set to DATASET, only data sets SYS2 and SYS3 are processed by the utility.

Example 3

The following INCLUDE / EXCLUDE statements are specified:

Copy 
INCLUDE VOLSER=VOL003

The results are as follows:

  • If PROCESS is set to CHAIN, all data sets (SYS1, SYS2 and SYS3) are processed by the utility.

  • If PROCESS is set to DATASET, only SYS2 and SYS3 data sets are processed by the utility.

    Copy 
    [,INVAULT=SAME|nnnn][,OUTVAULT=RULE|SAME]

INCLUDE / EXCLUDE

Statements specifying the volumes and data sets to be used as input for the CTTSBD utility. These statements are specified immediately after the TYPERUN statement. At least one INCLUDE / EXCLUDE statement must be specified.

If no INCLUDE statement is specified (meaning, only EXCLUDE statements are specified) an implicit INCLUDE statement, which selects all volumes and data sets, is assumed.

Each INCLUDE / EXCLUDE statement specifies conditions for the selection of a volume record and/or a data set record from the Media database. If volume and data set information are specified in an INCLUDE / EXCLUDE statement, the CTTSBD utility checks each data set record together with the record of the each volume in the chain on that the data set resides.

If a data set on a volume chain matches an EXCLUDE statement, the other data sets that exist together with it on the same volume chain may or may not be processed depending on the value specified for parameter PROCESS (described earlier).

The following fields can be specified in INCLUDE / EXCLUDE statements for the CTTSBD utility:

Data set Record Fields

ACCOUNT

CRECPU

CREPGM

DSEXPDT

DSSTAT

DSNAME

SMSMC

BLKSIZE

CREDT

DCHANGED

DSEXPTYP

DSFLAGS

DSVOLSER

VOLSNUM

BLOCKCT

CREJBN

DSCSIZE

DSLABEL

DSFLAG2

DUSRDATA

Volume Record Fields

ACTIVEDS

LBLNUM

VAULT

VOLEXPTY

VOLGROUP

VOLPCT

VOLSEQ

VUSED

MEDIA

LOCATION

VFREEKB

VOLFLAGS

VOLIND

VOLODESC

VOLSER

LACCDT

USERDATA

VOLEXPDT

VOLFLAG2

VOLOWNER

VOLSBAGE

VOLSTAT

These fields enable you to select data sets and volumes according to application, age, usage, size, free space, and so on.

For more information on these fields and INCLUDE / EXCLUDE statement format, 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.

The following additional fields are created from information calculated by the CTTSBD utility and can also be specified in INCLUDE / EXCLUDE statements as selection criteria for input data sets and input volumes:

Table 373 CTTSBD Additional Fields

Field

Description

VOLGROUP

Data set group name

VOLPCT

Percent of occupied space on a single volume or the last volume of an input volume chain

Volumes in a volume chain that are not the last volume of the chain are always considered 100 percent full.

VOLSBAGE

For volume chains created by a previous run of the CTTSBD utility, the number of days that have passed since the volume chain was created.
Copy 
INCLUDE    VOLPCT<5,DSNAME=ACCT.*

Selects all data sets on volume chains in which the last (or only) volume is less than 5 percent full and contains a data set with a prefix of ACCT.

Data set Group Stacking Parameters

Data set groups are groups of data sets for which special stacking information is specified. A group name is assigned to each data set in a sequential matching process. Each data set is assigned the group name of the first group whose description matches the attributes of the data set. The group name assigned to each data set remains assigned to the data set for the duration of the current run of the CTTSBD utility.

Data set groups and relevant information are defined in the file referenced by DD statement CTTSBGRP.

Each data set group is defined by a GROUP statement followed by one or more DATASET statements. Many additional statements can be added in any order to determine how data sets in the group are stacked.

Table 374 CTTSBD Data set Group Statements and Parameters

Parameter

Description

GROUP

 

 

Statement used to specify characteristics of a data set group. This statement is followed by various other statements that indicate stacking rules for the data set group. All statements listed between this GROUP statement and the next GROUP statement determine stacking rules for this data set group.

All data sets that are in the same group will not be stacked together unless the input statement WITHGRP NAME=SAME is included in the relevant group definition.

Valid values are:

  • NAME – Name of the data set group, from 1 through 20 characters. Data sets that satisfy at least one of the DATASET statements below are assigned this group name.

  • OUTMVLIM – Maximum number of volumes in a chain, from 1 through 20. Data sets in this group are not added to multi-volume chains with more than the specified number of volumes.
    Data sets in this group are also not added to a multivolume chain with the specified number of volumes if the anticipated data set size is larger than the remaining space on the volume.
    If no value is specified for this parameter, the value specified in parameter OUTMVLIM in the TYPERUN statement of the CTTSBD utility is used.

  • MAXLABEL – Maximum number of data sets in an output volume (or multi-volume chain), from 1 through 999. Data sets in this group are not added to a volume (or chain) that already contains the specified number of data sets or more.
    If no value is specified for this parameter, the value specified in parameter MAXLABEL in the TYPERUN statement of the CTTSBD utility is used.

  • OUTPREF – Prefix to be added to the names of output data sets in this group. Aperiod is inserted between the new prefix and the original data set name. Valid values:

    • xxx–Prefix to be added (1 to 20 characters). Aperiod can be specified as part of the OUTPREF value.

    • NONE–Add no prefix to the data set name. If a value is specified for OUTPREF in the group definition, that value overrides the OUTPREF value specified in the TYPERUN statement of the CTTSBD utility.

  • OUTSUFF – Suffix to be added at the end of output data set names in this group. A period is inserted between the original data set name and the new suffix.

    • xxx–Suffix to be added (1 to 20 characters). A period can be specified as part of the OUTSUFF value.

    • NONE–Add no suffix to the data set name. If a value is specified for OUTSUFF in the group definition, that value overrides the OUTSUFF value specified in the TYPERUN statement of the CTTSBD utility.

  • INUNIT – Unit name to be used by the CTTSBD utility for allocation of each input data set in this group. Aname of up to eight characters can be specified.
    If a value is specified for INUNIT in the group definition, that value overrides the INUNIT name specified in the TYPERUN statement of the CTTSBD utility.

  • OUTUNIT – Unit name to be used by the CTTSBD utility for allocation of each output data set in this group. Aname of up to eight characters can be specified.
    If a value is specified for OUTUNIT in the group definition, that value overrides the OUTUNIT name specified in the TYPERUN statement of the CTTSBD utility.

DATASET

Statement used to determine which data sets belong to the group.

All data sets that match the specified masks are associated with the last specified group name. Multiple values specified in a single DATASET statement have an AND relationship. Multiple DATASET statements have an OR relationship.

The following fields can be specified:

  • DSNAME – Data set name or mask

  • CREJBN – Creating job name or mask

    You can set a default group name by specifying DATASET DSNAME=* in the last GROUP definition.

For Generation Data Groups (GDG data sets) the last qualifier (GnnnnVnn) is excluded from the comparison of data set names.

WITHGRP

Specifies a data set group (or groups) with which data sets in this group are stacked.

  • grpname–Group name or mask with which data sets in the current group are stacked. A name from 1 through 20 characters in length can be specified.

  • SAME–Stack the data sets in the current group with data sets from the same group.

If more than one WITHGRP statement is included in a group definition, an OR relationship is assumed (meaning, the output data set can be stacked with any of the specified groups).

If no appropriate output volume (or volume chain) is located, the data set is written to a scratch volume.

NOTWGRP

Specifies a data set group name or mask with which the data sets in the current group will not be stacked. If more than one NOTWGRP statement is specified, the output data set is not stacked with data sets from any of the specified groups.

  • grpname–Group name or mask with which data sets in the current group are not stacked. A name from 1 through 20 characters in length can be specified.

  • SAME–Do not stack data sets in the current group with other data sets from the same group.

  • OTHER–Do not stack data sets in the current group on volumes with data sets from any other group (meaning, allow stacking only with data sets from the group specified in the WITHGRP statement).

NOTWJOB

Specifies a job (or jobs) that create data sets that are not stacked with the data sets in the current data set group.

  • jname–Job name or mask. Data sets in the current group are not stacked with data sets created by the specified jobs. Specify a jobname or mask from 1 through 8 characters in length.

  • SAME–Do not stack a data set in the current group with other data sets that have the same creating job name.

NOTWDSN

Specifies a data set name or mask with which data sets in the current data set group are not stacked.

  • dsname–Data set name or mask. Do not allow data sets from the current group to be stacked on volumes with data sets whose original names match the specified name or mask.
    Prefixes and/or suffixes added to output data set names are ignored by this parameter. The CTTSBD utility compares the specified data set name (or mask) with the input data set names that correspond to the output data sets on the candidate volumes.

  • SAME–Do not allow data sets in the current group to be stacked on volumes containing data sets with the same original input data set name.

For Generation Data Groups (GDG data sets) the last qualifier (GnnnnVnn) is excluded from the comparison of data set names.

CTTSBD Return Codes

Table 375 CTTSBD Return Codes

Code

Description

0

Utility completed successfully without errors.

4

Utility completed successfully, but at least one recoverable error was encountered.

8

The processing of the current chain or dataset failed. The utility continues processing the next chain or dataset.

12

Utility failed and stopped processing.

Examples for CTTSBD

CTTSBD Example 1

This example copies all data sets residing on chains whose last volume is less than 5% utilized. The data sets are divided into three data set groups that are stacked separately:

  • System files (SYS*)

  • Accounting files (ACCT*)

  • All other files

SYSIN DD Statement – Example 1A

Copy 
TYPERUN MODE=NORMAL,INRET=2,
    OUTRET=SAME,OUTPREF=NONE,
    OUTSUFF=NONE,COPYEXPF=NO,
    OUTMVLIM=3,MAXLABEL=100,
    VAULTED=NO,CARTCOST=10,
    INUNIT=460,OUTUNIT=461,
    MAXERR=30,OUTCAT=RECAT,
    COPYATTR=YES,CHAINRET=ANY,
    OUTVOLMB=200
INCLUDE DSNAME=*,VOLPCT<5

CTTSBGRP DD Statement (Data Set Group Definitions) – Example 1B

Copy 
GROUP NAME=SYS
    DATASET DSNAME=SYS*
    WITHGRP NAME=SAME
GROUP NAME=ACCT
    DATASET DSNAME=ACCT*
    WITHGRP NAME=SAME
GROUP NAME=ALL
    DATASET DSNAME=*
    WITHGRP NAME=SAME

CTTSBD Example 2

This example unstacks all multi-volume chains that contain at least one data set beginning with a prefix of ACCT and whose last volumes are less than 10% utilized.

SYSIN DD Statement – Example 2A

Copy 
TYPERUN MODE=NORMAL,INRET=2,
        OUTRET=SAME,OUTPREF=NONE,
        OUTSUFF=NONE,COPYEXPF=NO,
        OUTMVLIM=1,MAXLABEL=1,
        VAULTED=NO,CARTCOST=10,
        INUNIT=460,OUTUNIT=461,
        MAXERR=30,OUTCAT=RECAT,
        COPYATTR=YES,CHAINRET=ANY,
        OUTVOLMB=200
INCLUDE DSNAME=ACCT*,VOLSEQ>1,VOLPCT<10

CTTSBGRP DD Statement (Data Set Group Definitions) – Example 2B

The site’s standard group definitions can be included in this file. Unstacking is indicated by setting parameter MAXLABEL to 1 (specified in the TYPERUN Statement) and there is therefore no need for additional group definitions.

Copy 
GROUP NAME=ANY
               DATASET DSNAME=*

CTTSBD Example 3

This example stacks all data sets with the prefix ACCT and makes sure that no two data sets with the same name are written to the same output volume chain.

SYSIN DD Statement – Example 3A

Copy 
TYPERUN MODE=NORMAL,INRET=2,
    OUTRET=SAME,OUTPREF=NONE,
    OUTSUFF=NONE,COPYEXPF=NO,
    OUTMVLIM=3,MAXLABEL=100,
    VAULTED=NO,CARTCOST=10,
    INUNIT=460,OUTUNIT=461,
    MAXERR=30,OUTCAT=RECAT,
    COPYATTR=YES,CHAINRET=ANY,
    OUTVOLMB=200
INCLUDE DSNAME=ACCT*

CTTSBGRP DD Statement (Data Set Group Definitions) – Example 3B

Copy 
GROUP NAME=ACCT
    DATASET DSNAME=ACCT*
    NOTWDSN NAME=SAME

CTTSBD Example 4

This example performs a run of the CTTSBD utility in simulation mode. In this run, copying of all the site’s data sets from 3490 cartridges to 3590 cartridges is simulated. New names are assigned to the output data sets.

Data set groups are determined according to first letter of each input data set name.

SYSIN DD Statement – Example 4A

Copy 
TYPERUN MODE=SIMULATION,INRET=SAME,
        OUTRET=7,OUTPREF=TST3590,
        OUTSUFF=TST,COPYEXPF=YES,
        OUTMVLIM=20,MAXLABEL=999,
        VAULTED=NO,CARTCOST=1,
        INUNIT=3490,OUTUNIT=3590,
        MAXERR=30,OUTCAT=YES,
        COPYATTR=YES,CHAINRET=ANY,
        OUTVOLMB=30000
INCLUDE DSNAME=*   

CTTSBGRP DD Statement (Data Set Group Definitions) – Example 4B

Although the NOTWGRP statements in these data set group definitions may appear redundant, they are included to protect each group definition from new or modified group definitions (specifying current group names in WITHGRP statements) that can be added to the file.

Copy 
GROUP NAME=GROUP-A   DATASET DSNAME=A*
    WITHGRP NAME=SAME
    NOTWGRP NAME=OTHER
GROUP NAME=GROUP-B
    DATASET DSNAME=B*
    WITHGRP NAME=SAME
    NOTWGRP NAME=OTHER
GROUP NAME=GROUP-C
    DATASET DSNAME=C*
    WITHGRP NAME=SAME
    NOTWGRP NAME=OTHER
.
.
.
GROUP NAME=GROUP-Z
    DATASET DSNAME=Z*
    WITHGRP NAME=SAME
    NOTWGRP NAME=OTHER

CTTSCA – Data set Contention Detection

The CTTSCA utility analyzes SMF records to detect potential data set contentions, meaning, a situation in which two data sets on the same volume need to be accessed at the same time.

The SMF records processed by the CTTSCA utility are read from a sequential file referenced by DD statement DASMFIN. The sequential file must contain relevant accumulated type 14 and type 15 SMF records.

The CTTSCA utility performs one or both of the following tasks for each potential contention:

  • Creates Control-M/Tape rules that disallow stacking the data sets on the same volume

  • Adds the data set pair to a report produced by the utility

Run this utility before implementing the Dynamic Dataset Stacking facility. Review rules created by the utility and, if appropriate, add them to a rule table that is listed in Control-M/Tape Rule Table member RULLIST in the Control-M/Tape PARM library.

After implementing the Dynamic Dataset Stacking facility, run the CTTSCA utility periodically (for example, once a month) to check for new data set contentions. How often this utility is run depends on the number of tape mounts performed daily at your site.

Activating the CTTSCA Utility

Copy 
//EXEC       CTTSCA,RULELIB=‘rule-library’,
             RULEMEM=rule-table-name
//DASMFIN    DD  DISP=SHR,DSN=smf=flat-file
//SYSIN      DD  *
    TYPERUN  LEVEL={ALL|JOB}[,JOBPREF=prefix][,
             DURATION=nn]
    RULEINFO CREFULE={YES|NO},RULEPREF=prefix[,
             CONTSEAR=Y|N][,MODE=PROD|TEST][,
             PRIORITY=nn]
INCLUDE/EXCLUDE STATEMENTS
REPORT NAME=CONFLICT
FIELDS ...
[SORTBY ...]
[ATTR ...]
[BREAK ...]
//

CTTSCA Parameters

The following parameters are supplied using the EXEC statement:

Table 376 CTTSCA EXEC Parameters

Parameter

Description

RULELIB

Library to contain Control-M/Tape rules that are created by the utility

RULEMEM

Name of the member to contain the Control-M/Tape rules that are created by the utility

Any previously assigned value of the RULEMEM parameter is overwritten when the CTTSCA utility is run.

The following control statements and parameters are supplied using DD statement SYSIN:

Table 377 CTTSCA SYSIN Parameters

Parameter

Description

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:

  • LEVEL — Level of contention to be detected. Mandatory. Valid values are:

    • JOB — Search only for pairs of data sets that are accessed   simultaneously by the same job.

    • ALL — Search for all pairs of data sets opened simultaneously regardless of whether they are accessed by the same job. This is the recommended value.

  • JOBPREF — Prefix for jobs whose SMF records are checked for contention problems. A prefix of one to eight characters can be specified. Optional.

    • If LEVEL is set to JOB, the utility searches for pairs of data sets that are accessed simultaneously by the same job (for jobs with the specified prefix).

    • If LEVEL is set to ALL, the utility searches for all data sets that are accessed by jobs with the specified prefix at the same time as other data sets accessed by jobs with the specified prefix. Default.

  • DURATION — Tolerated contention duration in minutes. Optional. Default: 5 minutes.
    Contention duration is the amount of time during which a pair of data sets was simultaneously accessed. For example, if data set DSA was accessed from 10:00 until 10:10 and data set DSB was accessed from 10:05 until 10:30, the duration of contention between these two data sets is five minutes.
    If the detected data set contention lasts for less than the specified duration, the contention is tolerated (meaning, no rule is created to prevent stacking these two data sets together).

RULEINFO

Used to specify rule information parameters that affect the general functioning of the utility. Mandatory. Only one RULEINFO statement can be specified for each run of the CTTSCA utility.
The following parameters can be included in the RULEINFO statement:

  • CRERULE — Indicates whether Control-M/Tape rules are created by the utility. Mandatory.

    • Yes — Create two rules for each pair of data sets detected by the utility.
      For example, if data sets DSA and DSB are accessed at the same time, one rule is created to prevent DSA from being stacked with DSB. Another rule is created to prevent DSB from being stacked with DSA.

    • No — Do not create rules during this run of the CTTSCA utility.

  • RULEPREF — Prefix for rules created by the utility. The value of this parameter must be alphanumeric. Maximum length: 4 characters. Mandatory if CRERULE is set to YES.

  • CONTSEAR — Value to be inserted in the CONTINUESEARCH field of Control-M/Tape rules created in this run of the utility. Optional.

    • Yes — Set the CONTINUE SEARCH field to Y (Yes). Default.

    • No — Set the CONTINUE SEARCH field to N (No).

  • MODE — Value to be inserted in the MODE field of Control-M/Tape rules created in this run of the utility. Optional.

  • PROD — Set the MODE field to PROD. Default.

  • TEST — Set the MODE field to TEST.

  • PRIORITY — Value to be inserted in the SEQUENCEPRIORITY field in Control-M/Tape rules created in this run of the utility. Optional.
    The value specified must be two alphanumeric characters. For more information about valid values for this parameter, see the rule parameters chapter of the Control-M/Tape User Guide.
    If no value is specified, the SEQUENCEPRIORITY field is blank in rules created by the utility.

INCLUDE / EXCLUDE

SMF records that describe tape access are used as input for the CTTSCA utility. The SMF records to be processed by the utility can be filtered by one or more INCLUDE / EXCLUDE statements. For more information about INCLUDE / EXCLUDE statements, see Record Selection Logic (INCLUDE / EXCLUDE Statements) (CTM). Optional.

Values that can be specified in INCLUDE / EXCLUDE statements of the CTTSCA utility are listed in the appendix that discusses logical field names for the Control-M/Tape Repository in the INCONTROL for z/OS Administrator Guide.

If no INCLUDE / EXCLUDE statement is specified for the CTTSCA utility, all SMF records describing actions on tape data sets are processed by the utility.

REPORT

Report to be generated by the utility. Mandatory.

The NAME parameter must be set to CONFLICT.

A contention detection report, produced by the utility, lists all detected pairs of data sets. The fields in this report are determined by the FIELDS statement (described below).

FIELDS

Fields that are printed in the report produced by the utility. Mandatory.

Fields are included in the report produced by the utility in the order in which they are specified in the FIELDS control statement. Valid field names:

  • CPUID1 – CPU ID of the first data set.

  • CPUID2 – CPU ID of the second data set.

  • DSNAME1 – First data set name.

  • DSNAME2 – Second data set name.

  • DURATION – The duration of the detected contention.

  • JOBNAME1 – Jobname of the first data set.

  • JOBNAME2 – Jobname of the second data set.

  • VOLUME1 – First volume of the first data set.

  • VOLUME2 – First volume of the second data set.

  • DATE1 – Date the first data set was opened.

  • DATE2 – Date the second data set was opened.

  • TIME1 – Time of day first data set was opened.

  • TIME2 – Time of day second data set was opened.

  • CRERULE1 – Indication whether a rule was generated to prevent the first data set from being stacked with the second data set.

  • CRERULE2 – Indication whether a rule was generated to prevent the second data set from being stacked with the first data set.

  • REASON1 – Reason for not creating a rule to prevent the first data set from being stacked with the second data set.
    Possible reasons:

    • USER REQ – The user set CRERULE to NO.

    • TOLERATED – The time during which the two data sets were both accessed was shorter than the time specified for parameter DURATION.

  • REASON2R – Reason for not creating a rule to prevent the second data set from being stacked with the first data set.

  • RULENAM1 – Name of the rule created to prevent the first data set from being stacked with the second data set.

  • RULENAM2 – Name of the rule created to prevent the second data set from being stacked with the first data set.

SORTBY

Order in which the report is sorted. Optional. Available fields are listed in under the FIELDS parameter in this table. The /B (or /BRK) option 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.

For a description of the options of these statements, see the FIELDS, SORTBY, ATTR, and BREAK statements in CTTRPT – Database extraction and report utility.

CTTSCA Return Codes

Table 378 CTTSCA Return Codes

Code

Description

0

Operation performed successfully.

4

Report statement not provided. Report not created.

8

Missing DD statements or open error occurred.

12

An error was detected in a control statement specified to the utility.

16

Sort error occurred. For more information about the error, see the SYSOUT file.

20

Loading Control-M/Tape environment failed.

Example for CTTSCA

The following example requests detection of all possible contentions, creation of preventive rules and a contention report:

Example for SYSIN Statements

Copy 
//SYSIN     DD * 
    TYPERUN      LEVEL=ALL
    RULEINFO     CRERULE=YES,RULEPREF=NEWR,CONTSEAR=Y
    REPORT       NAME=CONFLICT
    FIELDS       CPUID1/C3,JOBNAME1/C12,DSNAME1/C23,
                DATE1/C69,TIME1/C78,DURATION/C87,
                CRERULE1/C98,REASON1/C107,RULENAM1/C119,ID=P
    FIELDS      CPUID2/C4,JOBNAME2/C13,DSNAME2/C24,
                DATE2/C69,TIME2/C78,
                CRERULE2/C98,REASON2/C107,RULENAM2/C119,ID=S
/*

Below is a sample portion of a report produced by the CTTSCA utility. Each line in the report describes a pair of data sets that can be in possible contention. Rules created by the utility (to prevent Data set 1 from being stacked together with Data set 2 and vice versa) are also listed in this report.

Figure 131 CTTSCA Sample Report

Copy 
BMC, INC.     CONTROL-M/TAPE REPORT (Ver 6.1.00)        DATE 16/11/2000 TIME 15.30      PAGE     1
                    Contention Detection Report
                    ---------------------------


CpuId 1  Jobname 1  Dataset 1                             Open     Open     Possible   Rule 1   Reason 1    Rule
                                                          Date 1   Time 1   Contention Created?             Name 1
 CpuId 2  Jobname 2  Dataset 2                            Open     Open     Duration   Rule 2   Reason 2    Rule
                                                          Date 2   Time 2              Created?             Name 2
-------- ---------- ------------------------------------- -------- -------- ---------- -------- ----------  -----
MVSP     DFHSM      DFHSM.HMIGTAPE.DATASET (GDG)          12/10/00 08:12:36 00:03:34   NO       TOLERATED
 MVSP     UH56VPM0   HZ.PROD.RDADLSQC.SEQ                 12/10/00 08:10:10            YES      NEWR0001

MVSP     DFHSM      DFHSM.HMIGTAPE.DATASET (GDG)          12/10/00 09:47:19 00:00:44   NO       TOLERATED
 MVSP     DFHSM      DFHSM.BACKTAPE.DATASET (GDG)         12/10/00 09:45:58            YES      NEWR0002

MVSP     UC95VPM0   HZ.PROD.RDADLSQC.SEQET                12/10/00 09:47:40 00:01:09   NO       TOLERATED
 MVSP     DFHSM      DFHSM.HMIGTAPE.DATASET (GDG)         12/10/00 09:47:19            YES      NEWR0003

MVSP     UC95VPM0   HZ.PROD.RDADLSQC.SEQET                12/10/00 09:47:40 00:00:23   NO       TOLERATED
 MVSP     DFHSM      DFHSM.BACKTAPE.DATASET (GDG)         12/10/00 09:45:58            YES      NEWR0004

MVSP     PMS6105M   MS.PROD.MGSRT.SEQSEQET                12/10/00 09:48:36 00:05:30   YES      NEWR0005
 MVSP     UC95VPM0   HZ.PROD.RDADLSQC.SEQET               12/10/00 09:47:40            YES      NEWR0006

MVSP     PMS6105M   MS.PROD.MGSRT.SEQSEQET                12/10/00 09:48:36 00:00:13   NO       TOLERATED
 MVSP     DFHSM      DFHSM.HMIGTAPE.DATASET (GDG)         12/10/00 09:47:19            YES      NEWR0007

MVSP     PMS6105M   MS.PROD.MDSRT.SEQSEQET                12/10/00 09:50:07 00:03:59   NO       TOLERATED
MVSP     UC95VPM0   HZ.PROD.RDADLSQC.SEQET               12/10/00 09:47:40            YES      NEWR0008

CTTSPL – Copies or moves Media database records

The CTTSPL utility extracts (meaning, moves or copies) Media database records for transfer to a different Media database. Before using this utility, it is important to review the information in "Split and Merge Processing" below.

There is no need to shut down Control-M/Tape while running this utility. The CTTMER utility (used to merge information extracted using the CTTSPL utility) automatically updates the Media database index component. There is no need to run the CTTBIX utility after running this utility.

Split and merge processing (CTTSPL)

The split and merge process is the method by which information is extracted (split) from one Media database and inserted (merged) into another Media database (usually at a different site). This process is especially useful when a decision is made to join two Media databases or to split a large Media database in two or more smaller Media databases.

The split and merge process is performed using the CTTSPL and CTTMER utilities.

  • The CTTSPL utility extracts records from the source Media database according to specified selection criteria. This utility can be used with either of two functions.

    Table 379 CTTSPL functions

    Function

    Description

    MOVE

    Moves selected records to the extract file and deletes them from the source Media database

    COPY

    Copies selected records from the source Media database to the extract file. The source Media database is not altered when this function is specified.

    The output of the CTTSPL utility (the extract file) is a predefined sequential file (&OLPREFT.REPDATA) allocated as one of the Control-M/Tape operations libraries at time of Control-M/Tape installation.

  • The CTTMER utility merges the extracted Media database records into the Media database in the target system. The CTTMER utility uses the extract file created by CTTSPL, as input.

If the CTTSPL utility is being used to move (not copy) Media database records, the selected records are deleted from the source Media database.

If the target Media database is in a different site, the extract file (REPDATA) produced by the CTTSPL utility must be transferred to the target site.

Data integrity (CTTSPL)

Utilities CTTSPL and CTTMER do not check Media database integrity.

It is highly recommended that the CTTIDB utility be used to check the integrity of the source Media database before execution of the CTTSPL utility. To avoid transfer of data errors to the target Media database, integrity errors detected by the CTTIDB utility must be fixed in the source Media database before execution of the CTTSPL utility.

It is also recommended that the CTTIDB utility be used after the split and merge process to check the integrity of the

  • Source Media database after running the CTTSPL utility (if the MOVE function was specified)

  • Target Media database after execution of the CTTMER utility

Simulation mode (CTTSPL)

The CTTSPL and CTTMER utilities can be executed in simulation mode. In this mode, no Media database updates are performed. In simulation mode, messages are sent to the utility log to record the updates that had been performed on the Media database if the utility were running in normal mode.

If the last run of the utility abended, simulation mode is not allowed. If an attempt is made to run the utility in simulation mode, the utility is terminated and an appropriate message is displayed.

A special restart simulation mode is available for the CTTMER utility. For more information, see the description of the MODE parameter in CTTMER – Merge records into the Media database.

Since the Media database is not updated in simulation mode, it is possible that a run of one of these utilities in simulation mode could end successfully. However a corresponding run in normal mode could abend, perhaps due to a lack of free space in the Media database.

Volume status (CTTSPL)

Utilities CTTSPL and CTTMER do not check volume status. Volume records are split and merged regardless of volume status. For some volumes (for example, those with a status of VAULTED or PENDING-VAULT) this can result in inaccurate slot definitions.

To correct this problem, it is necessary to run the CTTVTM utility in SLOTBLD mode to rebuild the Slot Definition Records. The CTTVTM utility is run against both the source Media database and the target Media database after completion of the split and merge process.

Recovery from abends (CTTSPL)

Control-M/Tape can recover from abends occurring during the run of utilities CTTSPL and CTTMER. If the utility has abended during update of the Media database (deletion of records in the CTTSPL utility or addition of records in the CTTMER utility), when the utility is run again it automatically enters RESTART mode and recovers from the abend.

The extract file (REPDATA) must not be altered (or deleted) prior to restart of utilities CTTSPL or CTTMER. It is highly recommended that this file be backed up after each run of the CTTSPL utility to facilitate recovery.

Undoing Splits and Merges (CTTSPL)

You can choose to undo the actions of the Split and Merge utilities as follows:

Table 380 CTTSPL functions

Function

Description

Splits

If the CTTSPL utility was run with the MOVE function, use the CTTMER utility to merge the extracted records from the extract (REPDATA) file back into the source Media database. Specify the source Media database as the target Media database.

If the extract file no longer exists but the extracted records have been merged into the target Media database, they can be extracted (copied or moved) from the target Media database into another extract file and then merged back into the source Media database.

If the CTTSPL utility was run with the COPY function, the source Media database is unchanged and there is no need to "undo" anything.

 

Merges

To remove records that have been merged into the target Media database, use the CTTSPL utility with the MOVE function to extract the necessary Media database records from the target Media database. The selection statements passed to the utility must include only the volumes added previously by the CTTMER utility.

Activating the CTTSPL Utility

Figure 132 CTTSPL Activation

Copy 
//EXEC   CTTSPL
//SYSIN  DD *
    EXTRACT PATH=ALL
    <INCLUDE/EXCLUDE statements>
/*
//DAIN   DD *
    TYPERUN FUNCTION=COPY|MOVE[,MODE=NORMAL|SIMULATION][,
            TRACELEVEL=XXX]
/*

CTTSPL Parameters

Table 381 CTTSPL Parameters

Parameter

Description

EXTRACT PATH=ALL

EXTRACT statement specified using DD statement SYSIN. This is the only EXTRACT statement allowed with the CTTSPL utility. Mandatory.

INCLUDE / EXCLUDE

The scope of the utility can be limited by one or more INCLUDE and/or EXCLUDE statements.

INCLUDE / EXCLUDE statements are specified immediately after the EXTRACT statement in the SYSIN DD statement. For more information, see Record Selection Logic (INCLUDE / EXCLUDE Statements) (CTM).

For the MOVE function, no dataset parameter can be used in the INCLUDE/EXCLUDE statement.

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. Specify this parameter using DD statement DAIN.

Valid subparameters are:

  • FUNCTION — The function to be performed. Mandatory. Valid values are:

    • COPY — Records are copied from the source Media database to the extract file (REPDATA). Copied records are not deleted from the source Media database.

    • MOVE — Records are moved from the source Media database to the extract file. Moved records are deleted from the source Media database.

  • MODE — The operation mode. Optional. Valid values are:

    • NORMAL — Normal operation mode. Default.

    • SIMULATION — Simulation mode. No changes are made to the Media database. Messages are sent to the utility log to show which changes would have been made to the Media database if the run were in NORMAL mode.

The result of running the CTTSPL utility in simulation mode is identical to running it with the FUNCTION parameter set to COPY. The resulting extract file (REPDATA) can be used as input for a regular (or simulation mode) run of the CTTMER utility.

Examples for CTTSPL

CTTSPL Example 1

In this example, the CTTSPL utility extracts the records for all volumes beginning with VOL. The records for the volumes and their associated data sets are removed (deleted) from the source Media database and placed in the extract file (REPDATA) to be used later as input for the CTTMER utility.

Copy 
//EXEC   CTTSPL
//SYSIN  DD *
    EXTRACT PATH=ALL
    INCLUDE VOLSER=VOL*
/*
//DAIN   DD *
    TYPERUN FUNCTION=MOVE

CTTSPL Example 2

In this example, the CTTSPL utility extracts the records of all data sets beginning with MY.FILE. The records for these data sets and the associated volumes are copied (not deleted) from the source Media database and placed in the extract file (REPDATA) to be used later as input for the CTTMER utility.

Copy 
//EXEC   CTTSPL
//SYSIN  DD *
    EXTRACT PATH=ALL
    INCLUDE DSNAME=MY.FILE*
/*
//DAIN   DD *
    TYPERUN FUNCTION=COPY
/*

CTTSPL Return Codes

Table 382 CTTSPL Return Codes

Code

Description

0

Operation performed successfully.

4

Minor errors detected. For more information, see accompanying messages.

8

Initialization problem

12

Extract failed.

16

Split failed.

20

Simulation mode is not allowed while restart is required.

Greater than 20

Severe error – the error is accompanied by a message describing the problem.

CTTSTK – Build and update Stacking database

The CTTSTK utility builds and updates the Stacking database. Run the utility on a regular basis using the CTTDAY job.

The utility accepts input from one of the following three types of data sets:

  • System Management Facilities (SMF) accumulated type 15 records (not the actual SMF files)

  • Media database records

  • Trace file records

The purposes, advantages, and disadvantages of using Media database and Trace file input are described in the table below. SMF type 15 records can be used to supplement Trace file input, if necessary, to decrease the time required to accumulate comprehensive statistics in the Statistics database.

Table 383 CTTSTK Media database and Trace file

 

Media database

Trace file (and SMF type 15 records)

Purpose

To load the Stacking database when installing the Dynamic Dataset Stacking facility.

To update the Stacking database with the latest statistics on a daily basis.

Advantages

The Stacking database has statistics for most data sets.

All statistics transferred to the Stacking database are accurate and up-to-date.

Disadvantages

Some data transferred to the Stacking database comes from scratched data set records. This data may be inaccurate and out-of-date.

When the Trace file is full, its oldest records are overwritten. Consequently, only statistics for recently used data sets are transferred to the Stacking database. It may require several updates for the Stacking database to accumulate comprehensive statistics.

Input records can be selected according to INCLUDE / EXCLUDE statements supplied to the utility. Record timestamps are inserted in the data set. Records from different utility runs with earlier timestamps are considered duplicate records and are dropped. Therefore, records with overlapping timestamps from different source computers must not be supplied to the utility in the same run.

Activating the CTTSTK Utility

Copy 
//EXEC   CTTSTK
//SYSIN  DD *
    TYPERUN MODE=SMF|TRC|MDB
    <INCLUDE/EXCLUDE STATEMENTS>
//

CTTSTK Parameters

Utility parameters are supplied using the SYSIN DD statement.

Table 384 CTTSTK Parameters

Parameter

Description

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 — Source of input records. Mandatory. Valid values are:

    • SMF — Input records come from accumulated SMF type 15 records.

      In this mode, parameter SMFIN (supplied to the CTTSTK procedure) specifies the name of a file containing accumulated SMF records.

    • TRC — Input records come from the Trace file. Use this mode for regular updates of the Stacking database as part of the Control-M/Tape New Day procedure.

    • MDB — Input records come from the Media database. Use this mode only for the first run of the CTTSTK utility when the Stacking database is empty.

INCLUDE / EXCLUDE (CTTSTK)

The scope of the utility can be limited by one or more INCLUDE / EXCLUDE statements. The subparameters that can be specified in INCLUDE / EXCLUDE statements are listed in Table 385.

Table 385 Keywords Used With Stacking Type Records

EXTERNAL NAME

VALID VALUES

 

DESCRIPTION
SKFORMAT

 

Tape recording format of the data on the volume

BPI200

200 bits per inch

BPI556

556 bits per inch

BPI800

800 bits per inch

BPI1600

1600 bits per inch

BPI6250

1625 bits per inch

TRACK18

18 tracks

TRACK36

36 tracks

TRACK128

128 tracks

TRACK256

256 tracks

TRACK384

384 tracks

EFMT1

Enterprise Recording Format 1

STKBLKCT

integer

Dataset’s block count

STKBLKSZ

integer

Dataset’s block size

STKCOMPF

integer

Stacking compression factor

STKDATE

date

Creation date

STKDSN

char (44)

Dataset name for which stacking statistics are kept

STKIND

NOSTK

Indication whether the dataset can be stacked

STKJBN

char (8)

Job name by which stacking statistics are kept for the dataset

STKPGM

char (8)

Name of the program that created the stacked dataset

STKTIME

time

Creation time

STKUNIT

char (8)

Generic unit name used to create the dataset

STKVOL1

char (6)

First volume in the group of volumes

STRTCH

COMP
NOCOMP

Indicates whether data is compressed (for example, IDRC)

For additional information on INCLUDE / EXCLUDE Statements, see Record Selection Logic (INCLUDE / EXCLUDE Statements) (CTM).

Gathering Statistics for Data Sets with Non-Specific Retention

The CTTSTK utility gathers additional statistical information for data sets with non-specific retention (meaning, retention types CYCLES, CATALOG and LAST ACCESS). The average life span of a scratched data set with non-specific retention is calculated by the utility and saved in the Stacking database. This information is calculated only for data sets that were scratched during execution of the CTTRTM utility. The average life span is not calculated for data sets that are manually scratched (meaning, scratched by using option E in the TI screen).

For information about how a data set’s average life span is used by the Dynamic Stacking facility, see the topic that discusses stacking data sets with non-specific retention in the organization and administration chapter of the Control-M/Tape User Guide.

CTTSTK Return Codes

Table 386 CTTSTK Return Codes

Code

Description

0

Operation performed successfully.

4

Input statements missing.

8

DCB open error occurred.

12

Input statement parsing error occurred.

16

Loading Control-M/Tape environment failed.

20

Sort error occurred.

24

Media database or Stacking database or Trace file I/O error occurred.

CTTSTKR – Stacking Statistics Report Utility

The CTTSTKR utility extracts data from the Stacking database and generates reports from the extracted data. Various parameters can be used to format and to filter the report produced by this utility (for example, to describe only statistics for specified data sets).

Activating the CTTSTKR Utility

Copy 
//EXEC   CTTSTKR
//SYSIN  DD  *
    <INCLUDE/EXCLUDE STATEMENTS>
        REPORT NAME=STACKING
        FIELDS ...
        [SORTBY ...]
        [ATTR ...]
        [BREAK ...]
//

CTTSTKR Parameters

Table 387 Enterprise Recording Format 1

Parameter

Description

INCLUDE / EXCLUDE

The information to be processed can be filtered by one or more INCLUDE / EXCLUDE statements. Valid values that can be specified in these INCLUDE / EXCLUDE statements are listed in the appendix that discusses logical field names for the Control-M/Tape Repository in the INCONTROL for z/OS Administrator Guide.

If no INCLUDE / EXCLUDE statement is specified, a report is created for all records in the Stacking database.

For more information about INCLUDE / EXCLUDE statements, see Record Selection Logic (INCLUDE / EXCLUDE Statements) (CTM). Optional.

REPORT

The report to be produced by the utility. Mandatory.

  • NAME — Report name. Mandatory. Valid value is:

    • STACKING — Stacking Statistics Report listing all requested statistics for the Control-M/Tape controlled data sets.

  • FOLD – Indicates whether all report data is printed in uppercase. Valid values are:

    • YES — Print all report data in uppercase.

    • NO — Print report data in upper and lowercase. Default.

  • PAGESIZE — Maximum lines in a page, where p is a numeric value between 21 and 16383. Optional. Default: 63.

  • LINESIZE — Maximum characters in a line, where s is a numeric value not greater than 255. Optional. Default: 127.

  • MARGINS=m-n — Lowest (m) and highest (n) columns in a line, where m is a numeric value greater than 0 and n is a numeric value greater than m but not greater than s (the value of LINESIZE). Optional. Defaults: m=1 and n=s.

  • SUMMARY=YES|NO — Indicates whether to show a summary line for each field break. Optional. Default: NO
    A field break occurs when there is a change in value for a field that is specified in a SORTBY statement with option /BRK, (or /B).

  • OUTDD — JCL DDname of the output. Default: REPOUT

FIELDS

Fields to print in the report. The fields are printed in the order specified. Available fields:

  • JOBNAME – Name of the job that created the data set

  • DSNAME – Name of the data set

  • STATUS – Whether the data set is stackable

  • UNIT – Unit name on which the data set was created

  • RFORMAT – Track recording format with which the data set was recorded

  • OBSERVE – Number of observations of the data set that were used to determine statistics for the data set

  • MAXSIZE – Maximum data set size in Kilobytes (KB)

  • MINSIZE – Minimum data set size in Kilobytes (KB)

  • TOTSIZQ – Sum of the square of data set size for all previous observations in Kilobytes (KB)

  • STDDEV – Standard deviation (in Kilobytes) of data set size for all observations

  • AVGSIZE – Average data set size in Kilobytes (KB)

  • PREDICTD – Predicted data set size in Kilobytes (KB)

  • AVGSIZEU – Average uncompressed data set size in Kilobytes

  • DATEUPD – Last update date of the stacking record

  • TIMEUPD – Last update time of the stacking record

  • PREDICTU – Average predicted uncompressed data set size in Kilobytes

  • LIFEOBS – Total number of observations of the data set (including observations that were not used to calculate data set statistics). This field is relevant only for data sets with nonspecific retention (for example, CATALOG or LAST ACCESS).

  • LIFESPAN – Average life span of the data set in days. This field is relevant only for data sets with nonspecific retention (for example, CATALOG or LAST ACCESS).

SORTBY

Order in which the report is sorted. Optional. (Available fields are listed above, under parameter FIELDS.) The /B (or /BRK) option 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.

For a description of the options of these statements, see the FIELDS, SORTBY, ATTR, and BREAK statements in CTTRPT – Database extraction and report utility.

CTTSTKR Return Codes

Table 388 CTTSTKR Return Codes

Code

Description

0

Operation performed successfully.

8

Missing DD statements or open error occurred.

12

Control card error

16

Loading Control-M/Tape environment failed.

24

Media database or Stacking database or Trace file I/O error occurred.

Example for CTTSTKR

The following example extracts stacking statistics information and produces reports for data sets that

  • Have a maximum size of less than 70 Kilobytes

  • Were created and monitored under the control of Control-M/Tape less than 15 times (generations)

    Copy 
    //EXEC   CTTSTKR
    //SYSIN  DD  *
        INCLUDE OBSERVE<15,MAXSIZE<70
        REPORT  NAME=STACKING
        FIELDS  JOBNAME,DSNAME,STATUS,RFORMAT,MAXSIZE,
                MINSIZE,TOTSIZQ,OBSERVE,AVGSIZE
    /*

Figure 133 CTTSTKR Output Report Example

Copy 
1BMC, INC.              CONTROL-M/TAPE REPORT (VER 6.1.00)            DATE 20/11/2000 TIME 11.21      PAGE     1

          Stacking Statistics Report
    --------------------------


 Jobname   Dataset name                               Stackable?  Track     Maximum  Minimum    Total   Observ-  Average
                                                                    Recording Size(KB) Size(KB)   Square  ations   Size
                                                                    Format                        Size             (KB)
 --------  --------------------------------------------  ----------  --------  -------  -------    ------  -------  -------
 M27EXIT   M27.NEW.DIMENS                                YES         BPI38KE         2        2         4        1        1
 M27S      M27.TRY1                                      YES         BPI38KE         2        2         4        1        1
 M27STK    M27.TRY1                                      YES         BPI38KE         2        2         4        1        1
 M27SVC    M27.SVC                                       YES         BPI38K          2        2         4        1        1
 N22SB05   N22.SB.F001                                   YES         BPI38KE        28       28       784        1        3
 N22SB05   N22.SB.F002                                   YES         BPI38KE        67       67      4489        1        6
 N22SB05   N22.SB.F003                                   YES         BPI38KE        28       28       784        1        3
 N22SB05   N22.SB.F004                                   YES         BPI38KE        67       67      4489        1        6
 N22T01    N22.SB.F001                                   YES         BPI38K         28       28       784        1        3
 N22T01    N22.SB.F002                                   YES         BPI38K         67       67      4489        1        6
 N22T01    N22.SB.F003                                   YES         BPI38K         28       28       784        1        3
 N22T01    N22.SB.F004                                   YES         BPI38K         67       67      4489        1        6
 N65CHAIN  N65.TRY.DS                                    YES         BPI38KE         2        2         4        1        1
 N65DFDSS  N65.TRY.DFDSS                                 YES         BPI38KE         5        5        25        1        1
 N70STACK  N70.STACK.DSN1                                YES         BPI38KE         2        2         8        2        1
 N70STACK  N70.STACK.DSN2                                YES         BPI38KE         2        2        52       13        1
 N70STACK  N70.STACK.DSN3                                YES         BPI38KE         2        2         4        1        1
 N89GENER  N89.EXPDT.Y2000.FILE1                         YES         BPI38K          7        7        49        1        1
 N89GENER  N89.NON.SPECIFIC                              YES         BPI38K          7        7        49        1        1
 N89GENER  N89.PERM.FILE1                                YES         BPI38K          7        7        49        1        1
 N89GENE1  N89.ACCT.CAT3                                 YES         BPI38K          7        7        49        1        1

CTTSYNC – Synchronize automated tape libraries with the Media database

The CTTSYNC utility synchronizes information in the Control-M/Tape Media database with the following databases in use at your site:

  • Automated tape libraries and virtual tape servers.

  • DFSMShsm repository

Automated tape libraries and virtual tape servers

The CTTSYNC utility automatically performs synchronization with all other automated tape libraries used at your site, such as IBM and StorageTek. The RBTTYPE CTTPARM parameter determines which automated tape libraries to synchronize with the Media database.

For more information about the automated tape library and Control-M/Tape support, see the chapter that discusses the automated tape library interface in the Control-M/Tape Implementation Guide.

The following synchronizations are available between the Media database, automated tape library database, and virtual tape server database:

  • Checks and updates the status (that is, SCRATCH or ACTIVE) of volumes in the automated tape library database, according to their status as indicated in the Media database.

  • Checks the automated tape library database to determine whether a volume is currently in the automated tape library. If the volume is in the library, verifies that the IN-ATL flag is set in the volume record in the Media database. If the volume is in the library, also updates the LIBRARY field in the volume record of the Media database to the library name where the volume resides.

  • For volumes controlled by OAM, updates the SMS Storage Group field (SMSSG) of the volume record in the Media database according to the volume storage group that appears in OAM database.

  • For volumes controlled by OAM, updates the WORM status of the volume record in the Media database according to the volume WORM status that appears in OAM database.

  • Checks and updates the volume type field (VOLTYPE) of a volume in the Media database to LOGICAL, if the volume is a logical volume that defined an IBM Virtual Tape Server (VTS) or StorageTek VSM.

Depending on the automated tape libraries in use at your site, the CTTSYNC utility usually updates information about the internal location of each selected volume within the automated tape library.

DFSMShsm

The CTTSYNC utility automatically compares the Media database with the DFSMShsm repository and lists all inconsistencies. No updates are made to the Media database or to the repository. For more information about DFSMShsm and Control-M/Tape support, see the chapter in the Control-M/Tape Implementation Guide that discusses External Data Managers.

The utility uses the VOLEDMID field of the Media database volume record in order to verify whether the volume is controlled by DFSMShsm, or whether it is controlled by a different External Data Manager, such as CA-Disk. The VOLEDMID field is automatically updated by the Control-M/Tape real time environment and is set according to the creation PGM.

The following comparisons are available between the Media database and the DFSMShsm repository:

  • Checks that all volumes controlled by DFSMShsm are marked in the Media database as Active and EDM.

  • Checks that all volumes that are not controlled by DFSMShsm and that have a value of HSM in their EDMID field, are marked as scratch in the Media database.

To synchronize the Media database with the DFSMShsm repository, the CTTSYNC utility must be run using the CTTSYNCH job from the .CTT JCL library.

Activating the CTTSYNC Utility

Figure 134 CTTSYNC Activation for Synchronization of Automated Tape Libraries with the Media Database

Copy 
//EXEC   CTTSYNC
//SYSIN  DD  *
TYPERUN MODE=[NORMAL|SIMULATION]
TYPESYNC MODE=ATVTS,UPDATE=[MDB|RDB|BOTH|NONE]
<INCLUDE/EXCLUDE STATEMENTS>
//

Figure 134a CTTSYNC Activation for Synchronization of the DFSMShsm Repository with the Media Database

Copy 
//EXEC   CTTSYNCH
//SYSIN  DD  *
TYPERUN MODE=NORMAL
TYPESYNC MODE=HSM,UPDATE=NONE
<INCLUDE/EXCLUDE STATEMENTS>
//

CTTSYNC Parameters

The following parameters are supplied using the SYSIN DD statement:

Table 389 CTTSYNC Parameters

Parameter

Description

TYPERUN

Used to specify the execution mode of the utility. Mandatory.

Only one TYPERUN statement can be specified for each run of this utility. The MODE subparameter can be used to set the modes in which the CTTSYNC utility can be run. Optional.
Valid values are:

  • NORMAL — Checks are performed, appropriate messages are issued, and the Media database or automated tape library database is updated accordingly. Default.

  • SIMULATION — Checks are performed and messages are issued, but the Media database and automated tape library database are not updated. This mode can be used to determine the extent to which the automated tape library database and Media database are out-of-sync, without modifying either database.

TYPESYNC

Used to specify the parameters that affect the general functioning of the utility. Mandatory.

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

  • MODE—The external database to synchronized with. Mandatory. Valid values are:

    • ATLVTS—Synchronize the Media database with the automated tape libraries and virtual tape servers, as defined in the RBTTYPE parameter in the CTTPARM.

    • HSM—Synchronize the Media database with the DFSMShsm repository.

  • UPDATE—The type of data to be synchronized. Mandatory. Valid values for MODE=ATLVTS are:

    • MDB—Check if volumes that are listed in the Media database are in the automated tape library. If necessary, update the following in the Media database:

      • Tape library name

      • ATL interface name (see Interface Types in the Control-M/Tape Implementation Guide)

      • Logical volume (Vlt/EDM/Scr/Act-Logic)

      • SMS storage group name

      • WORM volume (EDM/Act-Worm)

    • RDB—Check the status (meaning, ACTIVE or SCRATCH) of each volume in the Media database. Update the automated tape library database so that it indicates the same status.

    • BOTH—Perform both of the above-described operations.

  • Valid value for UPDATE when MODE=HSM is NONE. In such a case, the CTTSYNC utility checks if volumes that are listed in the Media database as controlled by DFSMShsm are in the DFSMShsm repository. No updates are performed to the Media database or to the DFSMShsm repository. Only error messages are reported to list the inconsistencies.

INCLUDE / EXCLUDE

The volumes to be processed can be filtered by one or more INCLUDE or EXCLUDE statements. Valid values that can be specified in these statements are listed in the appendix that discusses logical field names for the Control-M/Tape Repository in the INCONTROL for z/OS Administrator Guide.

Only volume fields can be used. If no INCLUDE or EXCLUDE statements are specified for the CTTSYNC utility, all volumes in the Media database are processed.

For more information about INCLUDE / EXCLUDE statements, see Record Selection Logic (INCLUDE / EXCLUDE Statements) (CTM). Optional.

CTTSYNC Return Codes

Table 390 CTTSYNC Return codes

Code

Description

0

Operation performed successfully.

4

Utility issued warning message.

8

Inconsistencies were found between the Media database and the other software database.

12

Utility failed and stopped execution.

Examples for CTTSYNC

The following example synchronizes volumes in the Media database with a volser prefixed by V, with the automated tape library and virtual tape server databases:

Figure 135 CTTSYNC – Example 1

Copy 
//CTTSYNC EXEC CTTSYNC           
//SYSIN   DD *                   
TYPERUN  MODE=SIMULATION         
TYPESYNC MODE=ATLVTS,UPDATE=BOTH 
INCLUDE VOLSER=V*

The following example synchronizes volumes in the Media database with a DFSMShsm database:

Figure 136 CTTSYNC – Example 2

Copy 
//EXEC CTTSYNCH
//SYSIN DD *
TYPERUN MODE=NORMAL 
TYPESYNC MODE=HSM,UPDATE=NONE

CTTTPI – Tape Initialization, Information Mapping, and Tape Erasure

The CTTTPI utility provides the following major functions:

Table 391 CTTTPI Functions

Function

Description

Safe Tape Initialization (INITT)

Initializes tapes and cartridges. Checks that a volume is not active before initializing it, thereby ensuring that active volumes are not accidentally initialized.

Media Information Mapping (TAPEMAP)

Produces a detailed report about the logical and physical content of a volume including logical files, labels, tape marks and unreadable areas (I/O errors).

Safe Tape Erasure (TAPERAS)

Physically erases the contents of a volume. Checks that a volume is not active before erasing it, thereby ensuring that active volumes are not accidentally erased.

These functions are described in detail below.

Multiple jobs or started tasks can run the CTTTPI utility in parallel on separate tape drives for distinct ranges of volume serial numbers.

Safe Tape Initialization – Function INITT

The CTTTPI utility protects active volumes from initialization by checking the specified volume serial number and the mounted volume before creating tape labels. Volumes are protected regardless of whether they appear in the Media database (MDB).

The CTTTPI utility initializes magnetic media (reel tape and cartridges) with standard labels (SL) or with ANSI standard labels (AL).

The initialization function is generally invoked as a started task using command

Copy 
S  CTTTPI,V=volser,[U=unitname|devnum,]F=INIT

This command invokes the utility with the single control statement

Copy 
INITT SER=volser,NUMBTAPE=999

When invoked in this manner, the utility first checks that the specified target volume serial number is either not in the Media database or is in the Media database with scratch status.

If the target volume serial number passes the first check, the utility requests that the operator mount the physical volume. Once the volume is mounted, the utility reads it to verify that it is not an active volume in the Media database.

If both the specified target volume and the physical mounted volume pass the checks, the desired label is written on the mounted volume.

If the specified volser is numeric, the utility requests successive volumes in ascending order until stopped or canceled by the operator.

The utility issues messages (for example, CTT289A) and sometimes prompts the operator for a reply or decision.

If Control-O or Control-M/Links for Windows NT is installed at your site, responses to the messages can usually be automated.

Depending on specified parameters, the Media database can be updated by the utility.

Media Information Mapping – Function TAPEMAP

The CTTTPI utility can produce a detailed report about the logical and physical content of a volume including logical files, labels, tape marks and unreadable areas (I/O errors).

This function is especially useful when recovering files and/or data that have been partially overwritten on magnetic media (for example, a longer file partially overwritten by a shorter file or multifile volumes in which the first few files have been overwritten).

The tape mapping function is generally invoked as a started task using command

Copy 
S  CTTTPI,[V=volser,][U=unitname|devnum,]F=MAP

This command invokes the CTTTPI utility with the single control statement

Copy 
TAPEMAP SER=volser

The TAPEMAP function produces a report that contains a single line for each of the following elements:

Table 392 CTTTPI Elements

Element

Description

VOL1

Volume label

HDR1

First part (and sometimes the only part) of a header label that describes a standard label data set

HDR2

Second part of a data set label

DATA BLOCKS

Actual data portion of a file on the media

EOF1

First part of a data set trailer label

EOF2

Second part of a data set trailer label

EOV1

First part of an End-Of-Volume tape label. This element appears when the preceding standard label data set continues on another volume.

EOV2

Second part of an End-Of-Volume tape label

Tape Mark

Physical indication on the media that separates one physical file from another and separates standard labels from data. Two consecutive tape marks commonly determine the logical end of the recorded area on the media.

I/O Error

Area that could not be read by CTTTPI

The TAPEMAP function reports information extracted from the above elements such as the data set name (meaning, the full data set name if it does not exceed 17 characters, or the last 17 characters of a longer data set name) creation date, creating job name, block size, physical and logical file sequence numbers.

Physical file sequence numbers are counted by tape marks. Each tape mark on the tape indicates an end-of-file. Logical file sequence numbers are extracted from HDR1. If there is no HDR1 on the tape (for example, an NL tape) the logical file sequence number is blank.

If a map of the complete media is requested (parameter STOP set to N, described later) data sets written beyond the present logical end of the recorded area can be examined.

Safe Tape Erasure – Function TAPERAS

The CTTTPI utility protects active volumes from being erased by comparing the specified volume serial number and the volser of the mounted volume, before erasing the data on the tape. Volumes are protected regardless of whether they appear in the Media database.

CTTTPI uses an operating system function (‘Data Security Erase’ EXCP) to erase tapes. This function writes a random pattern of data on the specified tape.

The erase function is generally invoked as a started task using the following command:

Copy 
S CTTTPI,V=volser,[U=unitname|devnum],F=ERAS

where

  • volser is the volume serial number of the tape to be erased.

  • unitname is the type of the unit in which the specified tape is loaded.

  • devnum is the number of the device in which the specified tape is loaded.

This command invokes the utility with the following single control statement:

Copy 
TAPERAS SER=volser,NUMBTAPE=999

When invoked in this manner, the utility first checks that the specified target volume serial number is either not in the Media database or is in the Media database with scratch status.

If the target volume serial number passes the first check, the utility requests that the operator mount the physical volume. Once the volume is mounted, the utility reads it to verify that it is not an active volume in the Media database.

The mounted volume is erased only if the volser of the mounted volume matches the volser specified in the JCL for the utility.

If the specified volser is numeric, the utility requests successive volumes in ascending order until stopped or canceled by the operator.

The utility issues messages (for example, CTT289A) and sometimes prompts the operator for a reply or decision. If Control-O or Control-M/Links for Windows NT is installed at your site, responses to these messages can usually be automated.

Depending on specified parameters, the Media database can be updated by the utility.

CTTTPI and I/O Error Recovery

Because the CTTTPI utility thoroughly examines magnetic tapes in unknown condition, it may encounter more I/O errors than ordinary programs. In particular, CTTTPI encounters I/O errors when reading a new tape to which data has never been written. While CTTTPI handles most of these errors successfully, the user may observe pertinent error messages originated by the operating system. Normally these messages can be ignored. If automation procedures are driven by these messages, you can make adjustments to exclude tape initialization and media swapping jobs.

To minimize the overhead of I/O error recovery, CTTTPI turns off DDR/SWAP capability in the allocated device for a short duration while it reads the label of a mounted tape to be initialized. If CTTTPI is canceled during that short period, the device may be left in a state where it is not a candidate for DDR/SWAP.

The operator can increase control over DDR/SWAP using operating system commands G OFF and G ON.

In some cases the I/O error encountered by CTTTPI is due to incompatible recording formats of different device types. To avoid the destruction of media originally created by another device, take care when handling the mounted volume, examining the I/O error messages on the console and in specifying the CTTTPI protection parameters.

In particular, the CTTTPI utility recognizes volumes that have never been accessed by the occurrence of an I/O error when it reads the label. If a 3490 device attempts to read a cartridge written by a 3490 device, an I/O error message is issued by the operating system that indicates format incompatibility, and the cartridge is treated by CTTTPI as a media to which data has never been written. In some cases the cartridges can be overwritten by a 3490 device. If your site has both media types and you want enhanced protection against the accidental mounting of cartridges created by a 3490 device and their re-initialization by a 3490 device, set PROTECT to PROMPT.

Activating the CTTTPI Utility

The utility can be activated as a job, started task (STC) or program called from within another program.

Parameters can be passed to the utility in either of the following ways:

  • using the EXEC statement.

  • using the SYSIN DD statement.

However, do not use both methods at the same time.

Passing Parameters using the EXEC Statement (CTTTPI)

When passing parameters using the EXEC statement, the statement format is

Copy 
//  EXEC CTTTPI,V=volser,[U=unitname|devnum,]F=INIT|MAP|ERAS

where

  • V – 6-character volume serial number. Valid for INIT, MAP or ERAS functions. Optional.

  • F – Function to be performed using default control statements. Valid functions:

  • INIT – Initialize the tape (reel or cartridge). Create a volume label.

  • MAP – Map the tape. Provide information about the contents of a reel or cartridge.

  • ERAS – Erase the data on the tape. Write a random pattern from the beginning until the physical end-of-tape.

  • U – Tape drive to be allocated for use by the utility. Valid values are a generic or esoteric unit name or a specific device number.

Passing Parameters using DD Statement SYSIN (CTTTPI)

When passing parameters using DD statement SYSIN, the syntax is

Copy 
//EXEC   CTTTPI
//SYSIN  DD *
    TYPERUN [MODE=NORMAL|SIMULATION][,
            PROTECT=ALL|MDB|PROMPT|NOREAD][,
            MDBUPDAT=Y|N][,ADD=N|Y|E|P]
    INITT   SER=volser[,DDNAME=ddname][,OWNER=owner][,
            NUMBTAPE=number][,LABTYPE=AL][,
            ACCESS=char][,ERASE=Y|N][,
            MEDIA=media-type][,VENDOR=vendor-name][,
            VERSION=version-name]
    TAPEMAP SER=volser[,DDNAME=ddname][,
            NUMERR=number][,STOP=Y|N][,MODE=S|E]
    TAPERAS SER=volser,[DDNAME=ddname][,
            NUMBTAPE=number][,ERASELBL=Y|N]

Input Parameters – SYSIN DD File (CTTTPI)

Throughout the documentation, the term "specified volser" refers to the volume serial number specified in parameter SER. The term "mounted volume" refers to the physical volume (and its label, if one exists) that was mounted with the intent of writing a new volume label on it.

Table 393 CTTTPI SYSIN parameters

Parameter

Description

TYPERUN

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

Only one TYPERUN statement can be specified for each run of this utility.

The statement is ignored for the TAPEMAP statement.

Valid subparameters are:

  • MODE — Controls the operation of the utility. Optional.
    Valid values are:

    • NORMAL — The utility creates labels on the media and performs other requested functions. Default.

    • SIMULATION — The utility only verifies that the specified target volume either does not appear in the Media database or it appears in the Media database in scratch status. The physical mounted volume, however, is not read and not initialized. When this mode is used, mounting the target volume is not required.

  • PROTECT — Controls the protection of the physical mounted volume. Optional. Valid values are:

    • ALL — Default. Protects all mounted volumes, as follows:

      • Mounted volumes that are active in the Media database are rejected without a prompt to the operator.

      • Mounted volumes that are not formatted are accepted without a prompt to the operator.

      • Mounted SL volumes that are not in the Media database result in a prompt to the operator.

      • NL volumes that contain data result in a prompt to the operator.

      • A mounted SL scratch volume whose volume serial number is the same as the specified target volser is accepted without a prompt to the operator (re-initializing the existing volume).

      • A mounted SL volume whose volume serial number exists in the Media database in scratch status but whose volume serial number is not the same as the specified target volser results in a prompt to the operator.

    • MDB — Protects mounted volumes only if they are in the Media database. The mounted volume is protected in the same manner as in PROTECT=ALL, except that SL volumes that are not in the Media database are accepted without a prompt.

    • NOREAD — Mounted volumes are not read or otherwise protected before writing a new label on them.

      Verification of the specified target volume serial number is still performed subject to other parameters.

    • PROMPT — Mounted volumes are read and the operator is requested to approve the initialization of the mounted volume.

  • MDBUPDAT — Controls updates to the Media database record of the specified target volume. Optional. Used by functions INITT and TAPERAS only. Valid values are:

    • Y (Yes) — If the volume is already in the Media database, the information in its record is reset, including volume statistics and information regarding scratch data sets that have resided on the volume. Default.
      The value of the last job to access the volume is changed to *CTTTPI*. If the volume is not in the Media database and ADD is set to Y(Yes), the volume record is added to the Media database.

    • N (No) — No changes are made to the Media database as a result of the initialization or erase processes. If MDBUPDAT is set to N, parameter ADD is ignored.

  • ADD — Controls the handling of specified volume serial        numbers that are not in the Media database. Optional. Ignored if MDBUPDAT=N. Used by functions INITT and TAPERAS only. Valid values are:

    • N (No) — A volume record is not added to the Media     database. Default. When a volume record has to be added to the Media database, an error message is produced and the utility stops its process

    • Y (Yes) — A volume record is added to the Media database.

    • E (External) — A volume record is added to the Media    database and marked External.

    • P (Prompt) — The operator is prompted to decide whether to add a record to the Media database.

INITT

 

 

Initialization function. Controls initialization (or initialization simulation) of magnetic media volumes. Optional. If this control statement is used, at least one optional subparameter must be specified:

  • SER — Volume serial number to be initialized (up to six alphanumeric characters). Mandatory.
    This parameter is identical to the SER parameter in the IBM IEHINITT utility.

    A volume serial number specified with the command // EXEC CTTTPI,V=volser, or passed to the program using the expression PARM=‘CTTTPIV=volser’, overrides this value.

  • NUMBTAPE — Maximum number of tapes to be initialized. Optional.
    After the first specified volume is processed, the numeric suffix of the volume serial number (if one exists) is repeatedly incremented by one to generate additional serial numbers, until the number of tapes initialized equals the value of NUMBTAPE or until a volume is initialized with a volser whose suffix is all 9’s. NUMBTAPE must be an integer between 1 and 9999. The default is 1.

  • OWNER — Owner identification to be recorded on the volume label. Maximum: 10 alphanumeric characters. (This parameter is identical to the OWNER parameter in the IBM IEHINITT utility.) Optional.

  • LABTYPE — Type of label to create. Optional. (This parameter is identical to parameter LABTYPE in IBM IEHINITT utility.) If this parameter is omitted, an IBM standard label is created. Otherwise, the following value is valid:
    — AL–Create an ANSI standard label.

  • ACCESS — Protection character for ANSI standard label. This parameter is identical to the ACCESS parameter of the IBM IEHINITT utility. Optional.

  • DDNAME — DDname for the tape drive to be used by CTTTPI. The DDname must start with the characters CTTTPI. The default value is CTTTPITP. Optional.

  • MEDIA — Volume media name to be recorded in the Media database for volumes being added to the Media database as part of the initialization process. The media must be defined in member CTTPARM. If no value is specified, the media name is derived from the device type of the assigned tape drive (for example, MEDIA=3490). Optional.

  • VENDOR — Media vendor name to be recorded in the Media database for volumes being added to the Media database as part of the initialization process. Optional.

  • VERSION — When the LABTYPE parameter is set to AL, the VERSION parameter indicates whether the format will be Version 3 or Version 4. This parameter is identical to the VERSION parameter of the IBM IEHINITT utility. Optional.

  • ERASE — Indicates whether to erase all data on the tape from after the label until the physical end-of-tape. Valid values are:

    • Y (Yes) — Erase the data on the tape.

    • N (No) — Do not erase the data on the tape.

Because the ERAS function physically writes a random pattern of data until the physical end of the tape, a run of the CTTTPI utility in which ERASE is set to Y (Yes) can be a time-consuming process.

TAPERAS

Erase function. Controls erase (or erase simulation) of magnetic media volumes. Optional. These subparameters are available for this function:

  • SER — Volume serial number to be erased (up to six alphanumeric characters). Mandatory.

    A volume serial number can also be specified with the command // EXEC CTTTPI,V=volser, or it can be passed to the program using the expression PARM='CTTTPIV=volser', which overrides the volser in the EXEC statement. Both of these statements override the value specified with the SER parameter.

  • NUMBTAPE — Maximum number of tapes to be erased. Optional.
    After the first specified volume is processed, the numeric suffix of the volume serial number (if one exists) is repeatedly incremented by one to generate additional serial numbers, until the number of tapes erased equals the value of NUMBTAPE or until a volume is erased with a volser whose suffix is all 9’s. NUMBTAPE must be an integer between 1 and 9999. The default is 1.

  • DDNAME — DDname for the tape drive to be used by the CTTTPI utility. The DDname must start with the characters CTTTPI. The default value is CTTTPITP. Optional.

  • ERASELBL — Indicates whether to erase the label of the volume. Optional.

    • Y (Yes) — ERASE the label.

    • N (No) — Keep the label. Default.

TAPEMAP

Tape mapping function. Optional. If this parameter is used, at least one optional subparameter must be specified:

  • SER — The volume serial number to appear in the mount message. This volume serial number does not have to match the volume serial number recorded on the media. Optional.

  • DDNAME — The name of the DD statement identifying the tape drive to be used by CTTTPI. The DDname must start with CTTTPI. The default value is CTTTPITP. Optional.

  • NUMERR — The number of I/O errors (between 1 and 999) that cause the CTTTPI utility to terminate. Default:1. Optional.

  • STOP — Controls termination of the TAPEMAP function. Optional.

    • Y (Yes) — Default. The TAPEMAP function ends when one of the following occurs:

      • Logical End-of-Volume, which is indicated either by two consecutive tape marks, or by an End-of-Volume label followed by a tape mark

      • The maximum number of permitted I/O errors, specified by the NUMERR parameter, has occurred.

    • N (No) — Function TAPEMAP ends only when canceled by the operator or when it encounters an error it cannot ignore.

      Processing a volume with STOP set to N may cause unexpected operational problems, such as a tape running off a reel or unusual I/O errors. Set STOP to N only in a test environment where unexpected problems cannot disrupt production.

  • MODE — Controls both the extent of the report produced by the TAPEMAP function and the way in which this function reads the tape. Optional.

    • E (Extended) — Produces a report on all data sets that exist on the volume including data sets that exist after the logical end of data, as discussed in the TAPEMAP subparameter STOP. When operating in this mode, the CTTTPI utility physically reads every byte on the volume. This mode is therefore time-consuming.

    • S (Standard) — Produces a report on all data sets that exist on the volume up to the logical end of data. The utility scans the data sets on the volume, it does not physically read the data. This mode is therefore quicker than Extended mode. When MODE is set to S, the STOP subparameter is ignored and field LARGEST BLOCK produced by the CTTTPI utility is set to zero. Default.

Invoking CTTTPI From Another Program

When calling CTTTPI as a program from within another program

  • Pass input parameters for CTTTPI using DD statement SYSIN only. Do not specify input parameters in the JCL EXEC statement.

  • Linkage and parameter passing conventions for the CTTTPI utility are the same as for IBM utilities. For more information, refer to the IBM Utilities Manual.

  • The CTTTPI utility supports substitution of DD names for its SYSIN and SYSPRINT statements using the same parameters used by IBM utilities. For more information, refer to the IBM Utilities Manual.

When constructing jobs that invoke CTTTPI, copy the DD statements from the CTTTPI JCL procedure as follows:

Table 394 CTTTPI Statements

Statement

Description

SYSIN

Input Stream

SYSPRINT

Output stream for CTTTPI. This DD statement must point to a SYSOUT file or the results can be unpredictable.

DAMDB

Media database Data component

DAMDI

Media database Index component

DALOG

IOA Log file

DATRC

Control-M/Tape Trace file

CTTTPITP

Tape drive for tape initialization

Activating Utility CTTTPI From the StorageTek Host Software Component

The initialization program of the StorageTek Host Software Component (HSC) invokes a media initialization program specific to the site. To indicate that you want to use the CTTTPI utility for volume initialization, follow the instructions above and the instructions for the cartridge initialization utility in the StorageTek reference manual with the following modifications:

  1. Specify PROG(ctttpiname) to the StorageTek SLUADMIN utility.

    where

    ctttpiname is either CTTTPI or (if you renamed the CTTTPI utility as described in the final adjustments to Control-M/Tape installation) IEHINITT.

  2. Pass the CTTTPI input control statements to StorageTek’s Host Software Component using DD statement SLSINIT.

  3. Specify ****** (six asterisks) for CTTTPI parameter SER.

For a sample JCL that activates the CTTTPI utility from StorageTek’s HSC Software component, see CTTTPI Example 2.

For more information about the Control-M/Tape interface to StorageTek automated tape libraries, see the Automated Tape Library Interface and Virtual Tape Server chapter in the Control-M/Tape Implementation Guide.

CTTTPI Return Codes

Upon completion, CTTTPI returns one of the following return codes (in register 15):

Table 395 CTTTPI Return Codes

Code

Description

0

Successful completion

4

Operator requested termination by typing CANCEL in response to a program prompt.

8

The specified target volume is a non-scratch volume in the Media database.

12

The Media database could not be updated.

MDBUPDAT was set to Y (Yes), but the specified target volume is not in the Media database and the volume could not be added (meaning, either ADD was set to N (No), or the operator responded negatively to the ADD prompt).

16

Syntax error in control statements or parameters

20

IEHINITT (or the specified substitute) failed or was stopped by the operator.

24

Error while opening the IOA Log file

28

Error while loading IOA modules or tables

32

Unable to open DD file CTTTPIxx for accessing a tape drive

36

Unable to open DD file SYSPRINT or its replacement

40

Unable to open DD file SYSIN or its replacement

44

Error while accessing the Media database

48

Erase of INITT failed.

52

TAPERASE command failed.

56

TAPEMAP EXCP command failed.

60

INITT command failed.

64

Automated tape library interface load failed.

68

Unable to change a volume status to active in a 3495 silo

72

Unable to scratch a volume in a 3495 silo

76

Authorization for one or more functions failed. Check the sysout for details.

Examples for CTTTPI

CTTTPI Example 1

Below is a sample of TAPEMAP output with STOP set to N:

Copy 
15.33.04 CTT704I CONTROL-M/TAPE UTILITY CTTTPI   STARTED
15.33.04 CTT700I   TAPEMAP SER=CTTMAP,STOP=N
VOL1        V=V00001
HDR1        DSN=...NOPOOL.F.G0028V00  FIRST=V00100  VOLSEQ=0002
FILESEQ=0002 CREDT=99346
HDR2        CREAT-JOB=N77MUL01 BLKSZ=00080  LRECL=00080
RECFM=F
TAPE-MARK  ---------
DATA BLOCKS: COUNT=00000005  LARGEST-BLKSZ=00080  LOGICAL-FILE
-SEQ=0002 PHYSICAL-FILE-SEQ=00002
TAPE-MARK  ---------
EOF1        DSN=...NOPOOL.F.G0028V00
EOF2
TAPE-MARK  ---------
TAPE-MARK  ---------   **** LOGICAL END OF RECORDED AREA ****
IO-ERROR   *********
DATA BLOCKS: COUNT=00000051  LARGEST-BLKSZ=03120  LOGICAL-FILE
-SEQ=PHYSICAL-FILE-SEQ=00005
TAPE-MARK  ---------
EOF1 DSN=NNN.TSC1
EOF2
TAPE-MARK  ---------
TAPE-MARK  ---------
            . . .

CTTTPI Example 2

The following sample JCL demonstrates how to use the CTTTPI utility to initialize tapes in a StorageTek silo (automated cartridge system), from another program:

Copy 
//INITAPE   JOB  ,USER,MSGCLASS=X,CLASS=A
//INITT EXEC PGM=SLUADMIN,PARM=MIXED
//STEPLIB  DD DISP=SHR,DSN=SYS3.HSC                HCS LOADLIB
//         DD DISP=SHR,DSN=SYS2.IOA.LOAD           CTT LOADLIB
//SLSTAPE  DD DISP=NEW,UNIT=(3490,,DEFER)     <=== UPDATE UNIT
//SLSIN    DD *
            INITIALIZE CAP(000:00) PROG(CTTTPI) OPT(SCR) CNTLDD(SYSIN)
//SLSINIT  DD *
            INITT  OWNER=ABCD,SER=******
//*
//SLSPRINT DD SYSOUT=*                             SLUADMIN MSGS
//SYSPRINT DD SYSOUT=*                             CTTPI MSGS
//SYSIN    DD UNIT=DISK,SPACE=(TRK,1)              CTTTPI SYSIN
//CTTTPITP DD UNIT=AFF=SLSTAPE,DISP=NEW            UNIT=AFF=SLSTAPE
//DAMDB    DD DISP=SHR,DSN=SYS2.CTT.MDBD      <=== UPDATE CTT MDBD
//DAMDI    DD DISP=SHR,DSN=SYS2.CTT.MDBI      <=== UPDATE CTT MDBI
//DATRC    DD DISP=SHR,DSN=SYS2.CTT.TRC       <=== UPDATE CTT TRC
//DALOG    DD DISP=SHR,DSN=SYS2.CTT.LOG       <=== UPDATE CTT LOG

CTTTRB – Synchronize Trace file and Media database backup

The CTTTRB utility marks records in the Trace file that are no longer needed, so that they can be overwritten. Run this utility immediately before and after each backup of the Media database and the Trace file.

The Trace file is used primarily to trace actions performed on the Media database. When the Trace file becomes full, all Control-M/Tape functioning is halted and an appropriate message is issued. This situation can be avoided by running the CTTTRB utility on a regular basis. This utility is called by the Control-M/Tape New Day procedure before and after the daily backup of the Media database and the Trace file.

Activating the CTTTRB Utility

Copy 
//EXEC  CTTTRB,PARM='BKP=START|END'

CTTTRB Parameters

Utility parameters are supplied in the JCL PARM library.

Table 396 CTTTRB Parameters

Parameter

Description

BKP

Indicates if the Backup procedure is beginning or ending. Valid value are:

  • START — Backup procedure of Media database has started.

  • END — Backup procedure of Media database has ended.

The steps for implementing the CTTTRB utility are as follows:

  1. Run the utility before backup of the Media database and the Trace file. In this run, set the BKP parameter to START. This run of the utility marks the most recently filled record in the Trace file.

  2. Perform the necessary backups. Any local site backup procedures can be used to perform this task.

  3. After the backup has been successfully completed, run the CTTTRB utility with the BKP parameter set to END. This run marks all Trace file records before the record marked in the previous run of the utility (Step 1 above).

CTTTRB Return Codes

Table 397 CTTTRB Return Codes

Code

Description

0

Operation performed successfully.

4

Minor MDB errors

8

DCB open error occurred, TCT load failed or PARM error.

12

I/O error on Trace file occurred.

Example for CTTTRB

Copy 
//EXEC  CTTTRB,PARM='BKP=START'
//EXEC  PGM=ADRDSSU
...
//EXEC  CTTTRB,PARM='BKP=END'

CTTVTM – Perform vault management

The CTTVTM utility performs vault management functions. Run this utility on a regular basis using the CTTDAY job.

The utility checks each volume record’s vault specifications in the Media database and determines which volumes to move to a new location according to their vault patterns. The current volume location in the volume record is updated.

This utility can produce a distribution report at the end of processing, which lists all volumes that are moved to a new location or assigned a new slot number.

Inventory report INVENT is no longer produced by the CTTVTM utility. Instead, this report can be produced as part of the GENERAL report by the CTTRPT utility. For more information, see CTTRPT – Database extraction and report utility. The CTTVTM utility requires exclusive access to the Media database. Real-time jobs that access tapes can be run at the same time as the CTTVTM utility, However, other utilities that access the Media database (for example, CTTRTM or CTTIDB) cannot run concurrently with this utility.

Since the utility handles a large number of Media database records, a CANCEL operation, job abend or system crash can lead to logical inconsistencies in the database. After any of these situations, the next execution of the utility automatically operates in Restart mode. In Restart mode, the utility completes execution of the failed process, thereby eliminating the logical errors from the Media database. The utility does not move any additional volumes during Restart execution.

Certain installation parameters (specified in member CTTPARM) determine how the CTTVTM utility operates. Table 398 describes these parameters.

Table 398 Relevant Control-M/Tape Installation Parameters

Parameter

Description

VLTBYDS1

Specifies which data set can determine how the vaulting pattern of a volume is chosen. Valid values are:

  • Yes – Only the first data set of the volume determines the vaulting pattern for the volume. This improves performance of CTTVTM (and is compatible with other tape management system’s vaulting methods). Default.

  • No – Any data set can determine the vaulting pattern for the volume.

SLOTRNG1

Specifies how Control-M/Tape performs the slot assignment in the vault. Valid values are:

  • No — Each media type is assigned to a separate slot range. Default.

  • Yes — All different media types are assigned to a single slot range in each vault. When using this option in the TV screen, all vault (slot and box) definitions must be defined only with the ALLMEDIA media. When you create box definitions under MAINLIB, specify the actual media type and do not specify ALLMEDIA.

After modifying the SLOTRNG1 parameter, you must invoke CTTVTM in SLOTBLD mode to build the in-use slot bitmap inside the Media database.

Before setting this parameter to Y, make sure that no slot number is being used by more than one volume in the same vault. Use the CTTMUP utility to assign new slots to duplicate in-use slots.

CYCLECNT

Defines how to handle cyclic data sets.

EXPDTYPE

Determines expiration logic depending on the type of retention criteria and value specified:

When DATE or DAYS retention criteria are assigned to a data set:

  • CA1 – CA-1 expiration logic applies. DATE or DAYS specifies the day on that the data set volumes with "vault until date" are moved to the next vault or are returned to the Active Library (MAINLIB) on the same day as mentioned in the rule. Default.

  • TLMS – TLMS expiration logic applies. DATE or DAYS specifies the last day of retention. Volumes only move to the next vault on the next day, one day later than mentioned in rule.

  • NONE – Expiration date in standard MVS format.

For additional information refer to "Retention and Vault Parameters" in the INCONTROL for z/OS Installation Guide.

Activating the CTTVTM Utility

Copy 
//EXEC   CTTVTM
//SYSIN  DD *
    TYPERUN MODE=NORMAL|SIMULATION[,DATE=date][,
            TRACE=YES|NO][,
            RESTART=YES|NO][,BOXLIM=num]
    TYPEVLT MODE=REGULAR|RECALC|CONVERT|SLOTBLD|BOXBLD[,
            RESLOT=YES|NO]
        <INCLUDE/EXCLUDE STATEMENTS>
        REPORT   NAME=DISTRIB,...
        FIELDS...
        SORTBY...
        ATTR  ...
        BREAK ...
//

CTTVTM Parameters

Utility parameters are supplied using the SYSIN DD statement.

Table 399 CTTVTM SYSIN parameters

Parameter

Description

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.

    • SIMULATION — Simulation is performed. No actual changes are made to the Media database.

    • DATE — Operation date in 6- or 8-character format, according to the site standard set by the DATETYP parameter in IOAPARM, with separating slashes.For example, for a date in the American format, you can specify the date as mm/dd/yy or mm/dd/yyyy. Optional.
      The utility assumes that the specified date is the current date and performs vaulting accordingly. This parameter can be used together with parameter MODE set to SIMULATION (described above) to simulate vaulting to be done on a specific date in the future.

  • TRACE — Specifies whether the Trace file is used during the CTTVTM run. Optional.

    • YES — The Trace file is used. Default.

    • NO — The Trace file is not used. If NO is specified, recovery of the lost updates to the Media database is impossible. TRACE is set to NO for the run of this utility during conversion from another product, but is not otherwise recommended.

  • 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. Optional. Valid values are:

    • YES — Enable Automatic Restart mode. Default.

    • NO — Disable Automatic Restart mode. It is highly recommended not to set RESTART to NO, as this can result in integrity errors in the Media database and loss of important information.

  • BOXLIM — Minimum number of volumes a box can contain. If the number of volumes is below the minimum, the volumes are placed in a slot instead of a box. Optional. Default:1.

TYPEVLT

Vault management type. Optional if parameter REPORT is specified. If CTTVTM run without a TYPEVLT statement, vaulting is not performed, but instead reports are produced based on the data left in the REPDATA file from the previous CTTVTM run.

  • MODE — Vault management mode. Valid values are:

    • REGULAR — Vault management is performed according to the vault patterns currently specified for the volumes (in Media database volume records).

    • RECALC — Rule definitions are reloaded and the vault pattern of each volume is recalculated.

    • CONVERT — This parameter is used following conversion from another tape management system. Rule definitions are reloaded, the vault pattern for each volume is calculated and the current location of each volume is reserved within the vault pattern.

      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 CTTVTM utility in RECALC or CONVERT mode, the rules applied may differ from the rules normally applied at data set creation. For more information, see the discussion of basic scheduling parameters in Rule Parameters in the Control-M/Tape User Guide.

    • SLOTBLD — The slot map is built in the Media database. This mode cannot be specified if RESLOT is set to YES. You cannot specify INCLUDE or EXCLUDE statements when running CTTVTM in this mode.

    • BOXBLD — Box records are built in the Media database from the vault definition and volume records. This mode cannot be specified if RESLOT is set to YES. You cannot specify this mode when running CTTVTM for SIMULATION.

  • RESLOT — Specifies whether to reassign slot numbers to vaulted volumes. Optional. Valid values are:

    • Yes — New slot numbers are assigned.

    • No — Existing slot numbers are preserved. 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 TYPEVLT parameter and are applied to vault processing. The subparameters that can be specified in INCLUDE / EXCLUDE statements are listed in the appendix to the INCONTROL for z/OS Administrator Guide that discusses logical field names for the Control-M/Tape Repository.

For additional information on INCLUDE / EXCLUDE statements, see Record Selection Logic (INCLUDE / EXCLUDE Statements) (CTM).

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 CTTRPT – Database extraction and report utility.

REPORT

Activates report utility. Optional if the TYPEVLT parameter is specified.

  • NAME — Report name. Mandatory. Valid value is:

    • DISTRIB — Distribution Report listing volumes that need to change location as a result of this utility run.

Inventory report INVENT is no longer produced by the CTTVTM utility. Instead, this report can be produced as part of the GENERAL report by the CTTRPT utility. A sample Inventory report can be found in member REPINV in the Control-M/Tape JCL library.
For a description of the other parameters and options of the REPORT statement, see the REPORT statement in CTTRPT – Database extraction and report utility.

FIELDS

Fields to print in the report. The fields are printed in the order they are specified.

The following fields can be printed on the Distribution report:

  • MEDIA — Media type.

  • POOL — Pool name.

  • VOLSTAT — Status(es) of the volume.

  • VOLSER — Volume serial number.

  • SL-NAME — Standard label name of the volume.

  • VOLCNT — Number of volumes in a multi-volume chain.

  • FIRSTVOL — First volser in a multi-volume chain.

  • FROMLOC — "From" vault location of the volume.

  • TOLOC — "To" vault location of the volume.

  • FROMSLOT — "From" slot number in the vault.

  • TOSLOT — "To" slot number in the vault.

  • NEXTLOC — Next location in the vault pattern.

  • NEXTLCDT — Date the volume is moved to the next location in the vault pattern.

  • BOXID — Name of the box in which the volume resides.

  • EXPDT — Expiration date.

  • LBLTYP — Label type.

  • DSNAME — Data set name.

  • VOLSEQ — Volume sequence number.

  • LOCSEQ — Sequence number of the location in the vault pattern.

  • CREJBN — Creating job’s name.

  • CREDT — Creation date.

  • CRETM — Creation time.

For a description of the options of the FIELDS statement, see the FIELDS statement CTTRPT – Database extraction and report utility.

SORTBY

Sort order of the output fields with the options that can be applied to each field. For more information, see the FIELDS parameter in this table. Optional.

For a description of the parameters and options of the SORTBY statement, see the SORTBY statement in CTTRPT – Database extraction and report utility.

ATTR

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

For a description of the parameters of the ATTR statement, see the ATTR statement in CTTRPT – Database extraction and report utility.

BREAK

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

For a description of the parameters of the BREAK statement, see the BREAK statement inCTTRPT – Database extraction and report utility.

CTTVTM Return Codes

Table 400 CTTVTM Return Codes

Code

Description

0

Operation performed successfully.

4

Minor errors detected. For more information, see accompanying messages.

8

Major errors detected. For more information, see accompanying messages.

12

Control card error

16

Load of Control-M/Tape programs failed.

20

Sort error occurred.

24

Media database input or output error occurred.

28

Internal error occurred.

32

Error in report printing utility occurred.

36

Rule or vault or pool load failed.

40

Insufficient storage

44

Authorization failed.

48

Media database in use by another utility

52

Missing DD statement or Open failed

56

Missing box definition record

Examples for CTTVTM

CTTVTM Example 1

Vault management is performed according to the current vault pattern specifications in the Media database. Report DISTRIB is printed, listing the MEDIA, VOLSER, VOLSEQ, FROMLOC and TOLOC fields.

Copy 
//EXEC   CTTVTM
//SYSIN  DD *
    TYPERUN MODE=NORMAL
    TYPEVLT MODE=REGULAR
    REPORT NAME=DISTRIB
    FIELDS MEDIA,VOLSER,VOLSEQ,FROMLOC,TOLOC
    SORTBY FROMLOC/B,TOLOC,VOLSER
//

The report is sorted according to the location from which each volume is being moved (FROMLOC). The report is then sorted according to the destination (TOLOC) and the volser name (VOLSER). A page break is inserted after each FROMLOC location listed in the report (meaning, each group of volumes from a specific location begins a new page).

CTTVTM Example 2

The location of all volumes whose volume serial numbers start with DIV1 is modified. The volumes are assigned new slot numbers. Rule definitions are reloaded to recalculate the vaulting patterns.

Copy 
//EXEC   CTTVTM
//SYSIN  DD*
    TYPERUN  MODE=NORMAL
    TYPEVLT  MODE=RECALC,RESLOT=YES
    INCLUDE  VOLSER=DIV1*
    REPORT   NAME=DISTRIB
    FIELDS   MEDIA,VOLSER,POOL,FROMLOC,TOLOC
    SORTBY   FROMLOC/B,VOLSER,POOL
//