Organization and Administration

This chapter includes the following topics:

• Real-Time Environment

• Control-M/Tape Main Components

  • Real-time Operations

  • Maintenance

  • Initialization

  • Termination

  • Environment Verification

• Control-M/Tape Rules

  • Loading and Accessing Rules in Memory

  • Action Categories

  • Rule Order

  • Best Match Order

  • Sample Rule List

  • Rule Search

• Volume Processing

  • NL/BLP

  • Scratch Processing

  • Dynamic Volume Chaining

  • External Volumes

  • SL-NAME Concept

  • External Data Manager Volumes

  • Robotic Tape Library Support

• Data Set Processing

  • Recreating Data Sets

  • Temporary Files

  • Control-M/Tape Handling of Data Set Generations

  • Control-M/Tape in a VTS Environment

• BLP Processing

  • Control-M/Tape Bypass

• Displaying Media Database Information on a z/OS Console

  • Display Commands

  • Defining and Loading Views

  • Example Commands and Views

• Media Database Update

• Fast Positioning a Tape

  • Implementing Fast Positioning

  • Requirements for Fast Positioning

  • DO FASTPOS Values

  • Considerations

• IOA Functions

  • IOA Functional Monitor

• Operation Modes

  • Production Mode

  • Phased Mode

  • Test Mode

• Stacking

  • Batch Stacking

  • Dynamic Dataset Stacking

  • Stacking Conditions

• Retention Management

  • RETPD and EXPDT JCL Parameters

  • Retention Algorithm

  • Retention Update

  • Volume Retention

  • Retention Processing

• Vault Management

  • Example

  • Vault Locations

  • Vaulting By Boxes

• Control-M/Tape to DFSMS Interface

  • Retention by Management Class

  • Pool Assignment by Management Class

  • DFSMS Class Definitions

  • Stacking of DFSMS-Controlled Data Sets

  • Automatic Class Selection (ACS) Routine Adjustments

Real-Time Environment

The Control-M/Tape Real-Time environment (1) is activated when Control-M/Tape is started. The Real-Time environment is responsible for maintaining the integrity of data, and for recording rule specifications and other media management information in the Media Database.

Once the Real-Time environment is established, Control-M/Tape takes control of volumes processed in the system. Control-M/Tape performs extensive validity checks to ensure the data integrity of the media library at the site. In addition, stacking can be performed for nonspecific mount requests.

As a data set moves through the system, Control-M/Tape gathers relevant information, searches rules to determine the required actions, such as retention and vaulting information, and updates the Media Database.

The Control-M/Tape Real-Time environment is also responsible for the execution of rules containing user-defined instructions. Control-M/Tape rules are stored in Rule Definition libraries. Similarly, vault and pool specifications are stored in Vault and Pool Definition libraries. These libraries are standard partitioned data sets and users can define their own definition libraries (2).

When access to removable media is attempted, the Control-M/Tape Real-Time environment scans all rules and performs the appropriate rules.

Control-M/Tape utilities (3) facilitate production processing by handling maintenance, backup and archiving of the repository, and many other necessary functions.

The repository (4) is accessed by all Control-M/Tape components. Every action performed by Control-M/Tape is recorded in the repository. The repository contains the Media Database (5), Trace file (6), Stacking Database (called the Stacking Statistics file prior to version 5.1.4) (7) and IOA files (8). The repository can be scanned and updated using the IOA Online facility (9).

The Reporting facility (10) accesses the repository to produce various reports that are useful in an active data center.

Control-M/Tape Main Components

Figure 214 Control-M/Tape Main Components

Real-time Operations

Many Control-M/Tape features operate "behind the scenes" in order to protect data. Control-M/Tape controls all media access operations (for example, open, close, mount) as they are performed.

The Life Cycle of a Data Set

During production activity, data sets are constantly being accessed (mounted, opened, closed, kept, and so on). Control-M/Tape controls all media access behind the scenes in the following manner:

Job Initialization

The volume serial number can be changed by dynamic stacking.

Mount

Mount messages can be altered by Control-M/Tape to increase their relevance (for example, add pool name to mount messages).

Open

Checks are performed to ensure that the specified operation is valid for the mounted volume (for example, verification that the mounted volume is a scratch volume, verification that the mounted volume was allocated from the appropriate pool, verification that only EDM can write on EDM volumes).

Close

The Media Database is updated (for example, number of blocks in the data set, space used). Retention and vaulting periods are recorded in the Media Database.

Features provided by Control-M/Tape real-time operations include:

• Protection against overwriting data sets accidentally.

• Verification that mounted tapes are taken from the correct pool.

• Dynamic data set stacking.

• Statistics on all media operations (when volumes are mounted, opened, and closed).

Maintenance

Maintenance procedures run automatically on a daily basis. The Media Database is scanned and the following maintenance operations are performed:

Table 176 Control-M/Tape Maintenance Procedures

Reports are produced informing the operator of the above operations.

Initialization

The first step in using Control-M/Tape is to initialize Control-M/Tape in each CPU. This is done by starting procedure CTTINIT, and is usually performed as part of the IPL process. The initialization process establishes the Control-M/Tape Real-Time environment, by

1. creating the main Control-M/Tape Control Table (TCT) in Extended Common Storage Access (ECSA)

2. creating a Control-M/Tape subsystem if dynamic subsystem installation was requested

   The subsystem is named CTTD, and cannot be renamed.

3. loading and defining the Control-M/Tape SVC, if dynamic SVC installation was requested by setting the DYNSVC installation parameter to Y in the CTTPARM member

   The SVC number can be specified as an installation parameter.

4. establishing the Write to Operator (WTO) intercept so that mount messages can be modified.

5. establishing the VOLSTAT intercept, so that I/O errors on tapes can be tracked by Control-M/Tape

6. establishing interfaces between Control-M/Tape and the operating system, if dynamic interface installation was requested by setting the DYNINTR parameter to Y in the CTTPARM member

   This is accomplished by setting intervention points in the operating system where Control-M/Tape obtains control. These interfaces remain until a termination process is run

7. opening the files necessary for the Real-Time environment: Media Database, Trace file and Stacking Database

8. loading modules into ECSA and setting their entry point in the TCT

9. loading rule tables, pool definitions, vault definitions, and view definitions into ECSA, and setting their address in the TCT

10. activating the Control-M/Tape subsystem

    The block of information in common storage containing key control data and pointers is called the Control-M/Tape Control Table (TCT). Its common storage address is used by all real-time components (that is, the Control-M/Tape SVC and the subsystem). All activity starts from this block, which contains pointers to all Control-M/Tape tables and modules in storage. The control block, along with its related routines, remains in common storage until Control-M/Tape is shut down.

Upon completion of the initialization process, the Control-M/Tape Real-Time environment is established and Control-M/Tape takes control of removable media processing.

After initialization, no address space is needed for the Control-M/Tape environment, even though Control-M/Tape is active in the system.

Termination

Operate Control-M/Tape from computer startup to shutdown (meaning, all the time) so that it can intercept all removable media management activities. Information for jobs that access removable media while Control-M/Tape is inoperative is not tracked.

When Control-M/Tape is terminated, a check is triggered for active jobs that access removable media in the system. If such jobs exist, you are prompted to cancel the termination, retry the termination, or continue (force) the termination.

When Control-M/Tape is terminated, all traces of the Control-M/Tape Real-Time environment are removed from the system, including the following:

• Interfaces established between Control-M/Tape and the operating system (that is, intervention points in the operating system) are removed.

• The Control-M/Tape SVC is removed from the system.

• The WTO Intercept is disabled; mount messages are no longer modified.

• The VOLSTAT intercept is disabled; I/O errors on tapes can no longer be tracked by Control-M/Tape.

Environment Verification

Whether Control-M/Tape performs real-time operations during volume access depends on:

• Whether the Control-M/Tape Real-Time environment has been established.

• Whether Control-M/Tape is currently in an active state, and not in a suspended or dormant mode.

Whenever Control-M/Tape takes control during volume processing, it attempts to locate the Control-M/Tape Control Table. The Control-M/Tape Control Table is loaded into memory during Initialization. For additional information, see Environment Verification.

If the Control-M/Tape Control Table is not found, Control-M/Tape halts the job and issues a message to the operator. The operator can then choose to:

• Let the job continue without Control-M/Tape intervention.

• Abend the job.

• Start up Control-M/Tape and continue job processing.

  • If the Control-M/Tape Control Table is found, the current status of Control-M/Tape is checked.

If Control-M/Tape is active, processing continues normally.

• If Control-M/Tape is dormant, the job continues without Control-M/Tape intervention.

• If Control-M/Tape is suspended, any job trying to access tape volumes is halted and the operator is notified.

If a job is failed by Control-M/Tape, the job abends with user code 242 and a specific reason code. The abend is preceded by a message describing the problem.

Whenever possible, Control-M/Tape checks are performed before the operator mounts the volume, thus saving operator time and computer resources.

Control-M/Tape Rules

Most Control-M/Tape decisions are driven by parameters specified in the user-defined rules.

Loading and Accessing Rules in Memory

All requested rule tables are loaded during initialization from the definition library. A reload of these tables can be requested at any time.

If a reload is requested, a new rule table is created in memory. Rule searches that started prior to the completion of the new rule table continue using the old table. When these rule searches are completed the old table is deleted from memory. Rule searches that begin after the new table is completed use the new table.

Action Categories

At the first real-time intervention point for a given data set, Control-M/Tape searches through the list of rules to establish the following Action categories:

• Stacking

• Pool Allocation

• Retention Criteria

• Vault Patterns

• Other Actions (for example, SHOUT message to a user, add or delete prerequisite conditions)

As Control-M/Tape searches through the list of rules, it locates handling instructions for each of these Action categories.

"Generic" rules can be defined to ensure that Control-M/Tape always has default actions to perform for each Action category.

Rule Order

The order that rules are loaded into memory has a direct impact on Control-M/Tape operations. (For additional information, see Rule Search.) The order is established at the time of rule definition. Either of the following orders can be selected:

Table 177 Control-M/Tape Rule Orders

To sort the rules in a table, specify Y (Yes) in the AUTOMATIC RULE SORTING field in the Rule Definition entry panel. When automatic rule sorting is enabled, Control-M/Tape maintains the rules in sorted order at all times. For example, when the insert option is specified, the newly inserted rule is automatically placed in the appropriate position in "Best Match Order."

To keep rules in non-sorted order, specify N (No) in the AUTOMATIC RULE SORTING field in the Rule Definition entry panel. Rules remain in the order that the user defined them.

Rule order applies to the order of rules within each table. The order of the tables, however, is controlled by the rule list specified in the initialization procedure CTTINIT. For more information, see "Control-M/Tape Initialization – Procedure CTTINIT" in the INCONTROL for z/OS Administrator Guide.

Best Match Order

Best Match Order sorts the rules according to the following order of precedence:

1. PRIORITY: Assigned priority values in descending alphabetic order.

2. ON DATASET: Data set name (alphabetic values) in descending alphabetic order.

3. ON JOBNAME: Job name (alphabetic values) in descending alphabetic order.

4. ON: Rules containing ON statements other than ON DATASET have a higher priority than rules not containing such ON statements.

Rules with the most detailed, specific criteria are listed before more generic rules. This way, Control-M/Tape can locate the rule that meets exact search criteria quickly. If no best match rule is located, generic rules listed at the end of the list can be used (similar to defaults).

Table 178 Generic Rules Applied When No Best Match Rule is Located

Sample Rule List

The following Rule List screen lists Control-M/Tape rules in Best Match Order:

Figure 215 Control-M/Tape Sample Rule List – Best Match Order

RULES OF LIBRARY: CTT.PROD.RULES                                TABLE: AAM17
  COMMAND ===>                                                    SCROLL===> CRSR
  OPT  RULE ---  PRI  DATASET ------------------------------------  JOBNAME  MORE
       NEWTAPE    09  *
       BWEEK      01  BACKUP.WEEK.*
       BMONTH     01  BACKUP.MONTH.*
       BACKUP     01  BACKUP.*
       VAULTVOL   01  ACC*
       TAPEUTIL   01  ?ACC?
       STARTLBL   01  *ACC
       SETMODE    01  *ACC
       DEFAULT    01  *
   ======= >>>>>>>>>>>>>>>>> NO MORE RULES IN THIS TABLE <<<<<<<<<<<<<<<<<<< ====










  OPTIONS:  S SELECT   D DELETE   I INSERT                               10.57.59

Rule Search

The purpose of the rule search is to fill in (locate actions for) all Action categories. (Action categories are described under "Loading and Accessing Rules in Memory" on the preceding pages.) For example, Control-M/Tape tries to determine, based on rule specifications, how stacking, pool allocation, retention, vaulting, and so on are performed.

Control-M/Tape may have to search several rules until all Action categories are located. The search continues until all Action categories are located, or until a matching rule is found that specifies the expression CONTINUE SEARCH=N (No).

Action categories that are not filled in by a specific rule for a given data set can be filled in by more generic rules.

To understand how the rule search works, examine the examples below:

Examples

Volume Processing

As access to a certain volume is attempted, the Media Database is checked to make sure that the volume is controlled by Control-M/Tape. If the volume does not exist in the Media Database, Control-M/Tape can either add it automatically (by Automatic Check-In), or prompt the operator to determine how to handle the situation (for example, ignore, define, abend).

If the volume is found in the Media Database, Control-M/Tape checks to see if the volume resides in the active library (MAINLIB). If the volume is not listed in the active library (meaning, the volume has an Out Location associated with it, or it is being stored in a local vault), a warning message is issued to the operator. If the volume is assigned to a Remote vault, the operator is given the option to abend the job or let it continue.

Control-M/Tape controls all types of label processing supported by the operating system:

• SL–Standard Label

• AL–ANSI Label

• NSL–Nonstandard Label

• NL–No Label (NL)

• BLP–Bypass Label Processing

NL/BLP

For NL/BLP requests, the operator can be prompted to confirm that the mounted volume is the volume requested by the user (by JCL, dynamic allocation, and so on). Installation parameters determine whether or not confirmation is required. Nonspecific (SCRATCH) tape requests always result in a prompt.

After mounting a scratch NL tape in response to a user request for a nonspecific NL/BLP tape, the operator is prompted by Control-M/Tape twice (or more, if necessary) to confirm the volser of the mounted volume. Control-M/Tape does not accept the mounted tape until the operator replies two consecutive times with the same volser. Once the operator replies two consecutive times with the same volser, that volser is used by Control-M/Tape for processing Media Database access and by the operating system for cataloging, keep message, and so on.

After mounting a tape in response to a user request for a specific NL/BLP tape, the operator is prompted by Control-M/Tape to confirm the volser of the mounted volume.

If the operator replies with the same volser that was requested by the user, Control-M/Tape accepts the request and processing continues.

If, however, the operator replies with a volser that is different from the volser requested by the user, Control-M/Tape keeps prompting the operator for the volser of the volume mounted until the operator provides two consecutive identical replies. Once two identical, consecutive replies have been received, Control-M/Tape proceeds as follows:

• If the volser specified in the reply is identical to the volser requested by the user, processing continues.

• If the volser specified in the reply is different from the volser requested by the user, the current volume is rejected (by normal MVS reject). The mount request is issued again and this entire process repeats.

The message ID of the mount message (IEF233 or IEC501) is changed by Control-M/Tape to CTT100A. If a pool name is inserted in the message the message ID is changed to CTT101A. For more information, see "Scratch Processing" in this chapter.

Because Control-M/Tape is responsible for data integrity, the operating system expiration protection message IEC507D, "E ... REPLY ‘U’-USE OR ‘M’-UNLOAD," is usually suppressed. This message is not suppressed when:

• Control-M/Tape is operating in Global Test or Phased mode.

• A rule specifies that the current data set is managed in Test mode.

• The volume is not controlled by Control-M/Tape (meaning, the volume is not registered in the Media Database, even if the volume is to be defined dynamically to Control-M/Tape).

If the volume is marked as in a remote vault, this indication is corrected at this time, and the tape is returned from borrowed status.

Scratch Processing

When a scratch volume is requested, Control-M/Tape rules are searched to determine if the output volume belongs to a specific pool. If so, the mount message is modified to request a specific pool. Instead of SCRTCH/PRIVAT, the message contains the name of the pool from that the volume is to be taken (meaning, not a specific VOLSER).

After a volume is mounted, Control-M/Tape verifies that the mounted volume is a scratch volume and that the volume belongs to the requested pool. If the volume does not belong to the pool, it is rejected and another volume is requested.

Pool definitions are loaded during initialization into memory and are incorporated as part of the Real-Time environment. They can be reloaded at any time without bringing Control-M/Tape down. This allows you to enlarge the pool at any time.

You can prevent read access to scratch volumes. This means that if a job requests a specific volume that is marked as scratch, Control-M/Tape fails this job for security reasons. This process is controlled by installation parameter SCRPROT.

Dynamic Volume Chaining

Volumes are normally chained into a group when a data set spans more than one volume. This can happen when the data set is created or recreated, or when the data set is extended (using DISP=MOD access).

However, Control-M/Tape also chains a set of volumes that is accessed in sequence when an active volume is dismounted and a scratch volume is mounted during End-of-Volume processing. In this case, the volumes are kept as one chain in the Media Database (meaning, they point to each other) if the dismounted (active) volume is not part of a different volume chain.

External Volumes

Many data centers regularly receive volumes from other sites. Such data centers can introduce these volumes to Control-M/Tape by checking them in using the Online facility, or using Automatic Check-In.

In either case, these volumes are marked as External volumes. (In Automatic Check-In, this is controlled by an installation parameter.)

External volumes are listed in a separate pool in the report produced by Retention Management utility CTTRTM.

External volumes can optionally be deleted from the Media Database when they are expired by utility CTTRTM.

When deleted, External volumes are actually deleted from the Media Database, unlike regular volumes, that are marked Deleted but remain in the Media Database.

SL-NAME Concept

When checking in external volumes, the volser of a volume being checked-in may be identical to the volser of a volume already in the Media Database. This creates a problem because the volser must be a unique identifier of a volume in the Media Database.

To solve this problem, Control-M/Tape uses fields VOLSER and SL-NAME (Standard Label Name) to provide MVS override logic, as described below:

When checking in a volume (normally by screen TC), the user should:

• Assign a new, unique volser to the checked-in volume. This volser is specified in field VOLSER.

• Specify the original volser (the volser in the Standard Label of the volume) in field SL-NAME.

• Specify the new (unique) volser on the label physically applied to the tape (meaning, the gummed label).

From this point on, the new volser is used to identify the volume (including in the MVS Catalog if cataloged, JCL references to the volume, and so on).

When a job requests a specific volume by JCL, the operating system checks that the volser on the volume’s standard label matches the requested volser to ensure that the mounted volume is the volume that was requested.

If the requested volser and the standard label of the mounted do not match, the operating system normally rejects the volume. However, when a volume is defined in Control-M/Tape with different values in the SL-NAME and VOLSER fields, Control-M/Tape intervenes in operating system processing.

In this case, if the value in field SL-NAME matches the volser in the mounted tape’s standard label, Control-M/Tape allows the volume to be accepted by the operating system.

External Data Manager Volumes

External Data Managers, such as DFHSM, DMS/OS and ASM-2, normally have their own retention management mechanisms for tapes created under their control. Rules can be defined to identify those External Data Managers to Control-M/Tape by their program name, job name, data set name, and so on.

If an External Data Manager creates a data set on a scratch volume, this volume is marked as an External Data Manager (EDM) volume. Only an External Data Manager is able to modify EDM volumes.

An External Data Manager is allowed to create data sets only on scratch volumes, or volumes that are already marked as EDM volumes (meaning, controlled by a DO RETENTION=EDM statement in Control-M/Tape rules).

Control-M/Tape does not expire a data set or a volume that belongs to an External Data Manager. A special interface exists for the expiration of such volumes. For more information, see the Control-M/Tape chapter of the INCONTROL for z/OS Administrator Guide.

External Data Manager volumes are managed at the volume level and not at the data set level. This means that for a multifile volume, only the first data set is recorded and the rest are ignored. For a multi-volume data set, no volume chaining occurs between different volumes. Each volume shows the same data set as a single volume data set. External Data Manager input operations are ignored by Control-M/Tape. Only the creation of the first file of a volume is recorded.

Robotic Tape Library Support

Control-M/Tape supports various robotic tape libraries (for example, StorageTek, IBM 3495). If one or more robotic tape libraries exist at your site, specify the types of robotic tape libraries by installation parameter RBTTYPE in member CTTPARM.

When a tape volume is expired by Control-M/Tape, each robotic tape library is informed of the new status of the volume. Whenever a tape volume is vaulted by Control-M/Tape, the robotic tape library is instructed to eject the volume so that it is available for the operator.

The Control-M/Tape interface with robotic tape libraries is performed by program CTTRBM, that is executed as an additional step in utilities CTTRTM and CTTVTM. CTTRBM is also called when you expire a volume using an online screen (Immediate Scratch) or using an External Data Manager interface. CTTRBM optionally calls user Exit CTTX008 before performing any robotic tape library request. Exit CTTX008 is called separately for each type of robotic library being processed. You can use this exit to influence robotic tape library processing. For more information, see the robotic tape library interface and virtual tape server chapter of the Control-M/Tape Implementation Guide.

Data Set Processing

When access to an existing data set is attempted, Control-M/Tape checks the entire data set name supplied in the JCL against the entries in the Media Database. The operating system compares only the last 17 characters against the data set header label.

When an output request is issued for multi-data set volumes, Control-M/Tape checks that the file sequence is valid:

• A file can be created only if the previous file sequence number exists.

• A file cannot be overwritten if files with higher sequence numbers exist.

If, during a read or update request for an existing data set, the data set is not found in the Media Database, Control-M/Tape can optionally define the data set dynamically. This can happen if the data set was created outside Control-M/Tape control (for example, at another site).

Recreating Data Sets

Under certain special circumstances, Control-M/Tape allows an existing data set to be recreated (meaning, overwritten).

The following restrictions apply:

• This is the last data set on the volume.

• The data set name is the same as that of the existing data set.

• The disposition is OLD (DISP=OLD).

• Y or P has been specified for either Control-M/Tape installation parameter RECREATE, or statement DO RECREATE in a Control-M/Tape rule.

There is an exception when the job that is accessing the data set is the same job that created the data set (that is, the job name and job ID of the job that is accessing the data set match the job name and job ID of the job that created the data set). In this case, the expression DISP=NEW is acceptable.

Temporary Files

Control-M/Tape does not record tape activity that is performed on temporary files. If a temporary file is created on a scratch tape, the tape remains a scratch tape throughout the life cycle of that temporary file.

Control-M/Tape considers a file to be temporary only when it did not previously exist (that is, it is newly created), the volume that the data set is to be read from or written to is scratch, and one of the following applies:

• the expression DSN=&&name was specified

• the expression DISP=(NEW, DELETE) was specified

• the expression RETPD=0 has been specified in the LABEL parameter

Control-M/Tape Handling of Data Set Generations

Data set generations are successive versions of a data set. These versions may be identified as a Generation Dataset Group, or as Cycles of a data set (used to determine Control-M/Tape data set retention).

Generation Data Groups (GDG)

Generation Data Groups (that is, GDG data set groups) are groups of data sets that can all be referred to by a common name. The operating system keeps generations in chronological order. The operating system retains a certain number of generations for each data set, and deletes obsolete generations as necessary.

Each generation of a data set is identified by a suffix that is added to the data set name. The suffix is in the following format:

GxxxxVyy

Where xxxx is a four-digit generation number (0001 through 9999) and yy is a two-digit version number (00 through 99).

For more information, see IBM document DFSMS/MVS USING DATA SETS.

Examples

A.B.C.G0001V00 is generation data set 1, version 0, in generation data group A.B.C.

A.B.C.G0009V01 is generation data set 9, version 1, in generation data group A.B.C.

Control-M/Tape Handling of GDG Data Sets

Control-M/Tape records GDG data sets using their full names (meaning, the GxxxxVyy suffix is included in the data set name). When Control-M/Tape searches for rules to apply to a GDG data set, it first searches for a rule that matches the complete data set name (with the GDG suffix). If no rule matches the data set name with the GDG suffix, Control-M/Tape searches for a rule that matches the data set name without the GDG suffix.

When collecting stacking statistics, Control-M/Tape ignores the GxxxxVyy suffix (meaning, the same statistics are used for all generations of a specific data set).

CYCLE Type Retention and GDG Data Sets

Control-M/Tape can recognize multiple data sets as different versions of the same data set. The criteria for determining if a data set is a new cycle (meaning, generation) of an existing data set, is specified using installation parameter CYCLECNT. Depending on the value specified for this parameter, a cycle may refer to a group of data sets with:

• The same name.

• The same name and the same creation date.

• The same name and the same job name.

• The same name, same creation date, and same job name.

Retention for a data set by Control-M/Tape can be set according to cycle number. For example, if a rule indicates that only 10 cycles of a data set are retained, when the 11th cycle of the data set is created, the oldest cycle (generation) of the data set is automatically expired by the next run of Control-M/Tape retention management utility CTTRTM.

Depending on how a DO RETENTION statement is specified, you can either indicate that only data sets with matching names are considered cycles of the same data set, or all data sets with a specified prefix are considered cycles of the same data set.

Query of a Data Set Generation

The Inquire/Update screen of Control-M/Tape can be used to display information about a specific generation of a data set or data sets.

To display a specific generation, indicate the generation number in parentheses after the data set name in the DSNAME field of the Inquiry/Update entry panel. For example, DS1.LOG(-1).

The generation specified with the data set name can be a number from 0 to -99, where 0 is the current (newest) version of the data set, -1 is the second newest version of the data set, and so on. For example, PAYROLL.DB(-2) refers to the third most recent version of the data set.

If a data set name mask is specified in the DSNAME field, Control-M/Tape searches for the specified generation of all of the data sets that match the specified mask.

The following logic is used to determine the requested generation of each data set:

1. Data sets that match the mask are sorted according to data set name, creation date and creation time.

2. Each group of data sets with the same name (excluding the GxxxxVyy suffix) is considered a group of generations of the same data set.

3. The most recent version of each data set is considered generation 0, the next most recent generation is -1, and so on. The requested generation for each data set is displayed.

DB.LOG.Y2000.BACKUP                               31/03/00
DB.LOG.Y2000.BACKUP                               31/07/00
DB.LOG.Y2000.BACKUP                               31/12/00
DB.LOG.Y2001.BACKUP                               31/01/01
DB.LOG.Y2001.BACKUP                               31/03/01

DB.LOG.Y2000.BACKUP                               31/07/00
DB.LOG.Y2001.BACKUP                               31/01/01

Control-M/Tape in a VTS Environment

VTS (Virtual Tape Server) is an IBM hardware component that uses fault tolerant RAID disks and IBM Magstar tape libraries to manage a series of virtual tape drives and virtual (logical) volumes for data sets at a site.

Control-M/Tape handles volumes that are inside VTS in the same way in that it handles all other removable media. Control-M/Tape manages the retention of VTS volumes and informs VTS using the Control-M/Tape robot interface when a logical volume expires.

The Control-M/Tape interface for IBM robots is used to keep the VTS database synchronized with the Control-M/Tape Media Database.

Export/Import Interface in a VTS Environment

VTS logical volumes cannot be vaulted unless they are exported onto physical tapes. Control-M/Tape automatically initiates the VTS Export/Import interface to export VTS logical volumes out of the VTS environment and to stack and vault those volumes onto physical tapes.

When exporting logical volumes, Control-M/Tape groups together volumes with similar vaulting patterns. Each group is then written to separate physical tapes to be sent to different vaults, as necessary.

During the Export process, Control-M/Tape produces the Import List Volume report that contains a list of the physical volumes that were written and the logical volumes that reside on them. After the Import List Volume report is written, a message similar to the following is displayed at the console:

CTT347I IMPORT LIST VOLUME CREATED ON VOLSER VOL0011

To import physical tapes back to the VTS environment, perform the following steps:

1. Select and then load the physical tapes onto the VTS, based on the information in the Import List Volume report.

2. Issue the Import command at the control console. When issuing this command, refer to the volser (volume serial number) that was displayed in message CTT347I.

Refer to the IBM VTS documentation for instructions on how to load tapes and to enter the Import command at the console.

For information on implementing the Control-M/Tape VTS Export/Import feature and the reports produced by the VTS Export/Import interface facility, see the robotic tape library interface and virtual tape server chapter of the Control-M/Tape Implementation Guide.

Data Set Stacking in a VTS Environment

VTS performs stacking on logical volumes that are backed up on Magstar tape cartridges. Control-M/Tape stacking is not necessary for these logical volumes.

Control-M/Tape stacking can be used in the following ways in a VTS environment:

• Non-VTS volumes can be stacked (for example, for transfer to another site) using Control-M/Tape rules with DO STACK statements and the Control-M/Tape Dynamic Dataset Stacking facility.

• Data sets on VTS volumes can be copied to non-VTS volumes using Control-M/Tape utility CTTSBD in batch mode.

For more information about utility CTTSBD, see the INCONTROL for z/OS Utilities Guide.

BLP Processing

When trying to access data sets on an SL tape using BLP (Bypass Label Processing), Control-M/Tape translates the file sequence numbers to their SL equivalents. This way, input dsname verification is performed against the correct data set in the Media Database. This also applies when a data set is created (or dynamically defined when input) on an SL tape. In this case, the original file sequence numbers are used. If the original file sequence numbers do not translate to the beginning of a data set, Control-M/Tape bypasses processing for the current data set (meaning, it is not recorded in the Control-M/Tape Media Database).

A different BLP processing method can be selected by installation parameter BLPDEF. For more information, see the INCONTROL for z/OS Installation Guide.

Control-M/Tape Bypass

By specifying the expression EXPDT=98000 in your JCL, you can instruct Control-M/Tape not to intervene in your media processing.

Since this can cause a potential break in security, this option can be controlled by user Exit CTTX003 (using an existing security package to control this option).

Control-M/Tape honors an input request or any request concerning non-Control-M/Tape volumes without confirmation. When the expression EXPDT=98000 is specified in an output request for a Control-M/Tape controlled volume, the operator may (depending on installation parameters) be asked to confirm the bypass request. The operator can instruct Control-M/Tape to honor the bypass, to abend the job, or to ignore the bypass request and continue normally.

Displaying Media Database Information on a z/OS Console

Information obtained from the Media Database volume and data set records can be displayed on a z/OS console when the Inquiry and Update screen (option TI on the IOA Primary Option menu) is not readily available through other environments (such as TSO/E or the IOA online monitor). This display is designed for operations personnel, for whom the MVS console is often more readily available than a TSO/E session. For more information on the Inquiry and Update facility, see Inquiries and Updates.

Display Commands

The command used to display Media Database information on the console depends on the type of records (volume, data set, or group (chain) of volumes) to be displayed.

Just as record information can be displayed in the Inquiry/Update screen using different display types, record information can also be displayed on the console using different "views". A predefined, default view is provided for each record type to be displayed. The INCONTROL administrator can modify these views and define other, optional views.

Format of the display command is:

CTT rectype parms[,v=viewname]

where:

• rectype is the record type indicator. Mandatory. Valid values:

  • DVL Volume record

  • DDS Data set record

  • DVG Group (chain) of volumes

• parms are the parameters identifying the desired record. Mandatory. This includes volser (volume serial number) for all record types, and labelnum (the number of the data set on the volume) for data set records only.

• viewname is the view (format) in which to display the information. Optional. If not specified, the default view is used.

  Valid display commands are shown below:

Table 182 Media Database Information Display Commands

Defining and Loading Views

The INCONTROL administrator can modify the default views for the display commands, as well as define and modify optional views. Samples of the default views are provided with Control-M/Tape that can be used as is, or modified as needed. For more information on defining views, see the Control-M/Tape chapter in the INCONTROL for z/OS Administrator Guide.

All views are loaded when Control-M/Tape is first initialized. Views can also be loaded after Control-M/Tape has been initialized, by issuing the following command at the console:

S CTTINIT,PARM=’RELOAD,TBLT=VIEW’

Modifications to views only take effect after Control-M/Tape has been reinitialized or after this command has been issued.

Example Commands and Views

The following are example display commands and the views displayed by them:

DVL Command

This example displays information about volume VOL008, using view V as defined by the INCONTROL administrator

Figure 216 Media Database Display – DVL Command Example

20:44:18.26 N70            00000290  CTT DVL VOL008,V=V
20:44:18.32 TSU20858 00000090  CTT700I VOLSER..... VOL008      VOLFLAGS... MANUPDAT

20:44:18.33 TSU20858 00000090  CTT700I VAULT...... V1          VLTENTDT... 1999/10/03
VLTEXTY1... VCAT

20:44:18.34 TSU20858 00000090  CTT700I VLTEXPD1... 1077952576
RELATN#1...            VLTEXTY2...

20:44:18.35 TSU20858 00000090  CTT700I VLTEXPD2... 1077952576
RELATN#2...            VLTEXTY3...
                                                             40404040
20:44:18.36 TSU20858 00000090  CTT700I VLTEXPD3... 1077952576

20:44:18.38 TSU20858 00000090  CTT700I VAULT......
V2          VLTENTDT...                       VLTEXTY1...
                                                             VDATE
20:44:18.39 TSU20858 00000090  CTT700I VLTEXPD1... 1999/10/04
RELATN#1...                VLTEXTY2...

20:44:18.40 TSU20858 00000090  CTT700I VLTEXPD2... 1077952576
RELATN#2...              VLTEXTY3...
                                                             40404040
20:44:18.42 TSU20858 00000090  CTT700I VLTEXPD3... 1077952576

20:44:18.43 TSU20858 00000090  CTT700I VAULT......
V3          VLTENTDT...                       VLTEXTY1...
                                                             VDATE
20:44:18.44 TSU20858 00000090  CTT700I VLTEXPD1... 1999/10/06
RELATN#1...               VLTEXTY2...

20:44:18.45 TSU20858 00000090  CTT700I VLTEXPD2... 1077952576
RELATN#2...             VLTEXTY3...
                                                             40404040
20:44:18.47 TSU20858 00000090  CTT700I VLTEXPD3... 1077952576

DDS Command

This example displays information about data set 1 on volume VOL001.

Figure 217 Media Database Display – DDS Command Example

20:36:04.58 N70            00000290  CTT DDS VOL001,1                                
20:36:04.65 TSU20858 00000090  CTT700I DSNAME..... MY.DATABASE

20:36:04.68 TSU20858 00000090  CTT700I DSVOLSER... VOL001      VOLSNUM.... 6   

DVG Command

This example displays information about the group (chain) of volumes that includes volume VOL001.

Figure 218 Media Database Display – DVG Command Example

20:22:00.42 N70            00000290  CTT DVG VOL001
20:22:00.48 TSU20858 00000090  CTT700I VOLSER..... VOL001      VOLFLAGS...     
                                                                                   
20:22:00.57 TSU20858 00000090  CTT700I VOLSER..... VOL002      VOLFLAGS...     

20:22:00.58 TSU20858 00000090  CTT700I VOLSER..... VOL003      VOLFLAGS... MANUPDAT
                                                                                   
20:22:00.59 TSU20858 00000090  CTT700I VOLSER..... VOL004      VOLFLAGS...     
                                                                                   
20:22:00.60 TSU20858 00000090  CTT700I VOLSER..... VOL005      VOLFLAGS...     
20:22:00.64 TSU20858 00000090  CTT700I VOLSER..... VOL006      VOLFLAGS...

Media Database Update

As soon as validity checks have been completed and the job is allowed access to the data set on the volume, Control-M/Tape records relevant information in the volume and data set records in the Media Database.

When a new data set is created, Control-M/Tape records the data set attributes such as block size, record length, record format, and so on in the data set record of the Media Database. The open count, number of active data sets on the volume, and so on are also recorded in the volume record of the Media Database.

Whenever a volume’s data set is opened, Control-M/Tape updates "last access" information in the data set record. This information includes: Date, time, job name, step name, DD name, program name, CPU ID, device address, and step completion code. These fields are tracked and stored as separate fields for the following events: Last read access, last write access and creation time. The volume record also contains last access date, time, and job name.

When a data set is opened, Control-M/Tape updates the data set information in the Media Database with its abend retention period. If the data set is closed normally, the data set is updated with its normal retention period. This ensures that, in case of system crash before the data set is closed normally, the abend retention period for the data set is established.

When "end of volume" is encountered, Control-M/Tape chains together the volumes of a multi-volume data set. "End of volume" processing is actually a combination of "close" processing for the old volume and "open" processing for the new volume.

When a data set is closed, Control-M/Tape updates the following:

• Normal retention (for data sets)

• Vault pattern (for volumes)

• Block count (for data sets)

• EXCP count (for both volumes and data sets)

• Compressed size (for data sets)

• Uncompressed size (for data sets)

• Unused space (for volumes)

Retention and vaulting information are updated for new data sets and for data sets created dynamically by Control-M/Tape. The vault pattern is updated only if the volume contains no previous vault pattern. The retention and vaulting information are obtained from the rule table currently in memory, as described in Rule Search.

Fast Positioning a Tape

The Fast Positioning facility cuts the time required to position a tape to a data set. With Fast Positioning, the operating system does not sequentially search the tape for a data set. Instead, the operating system passes the block ID of the data set, which is the location of the data set on the tape, to the tape device. Using this block ID, the tape device positions the tape at the beginning of the data set. If a tape contains many data sets or large data sets, fast positioning can be up to14 times faster than searching sequentially for the data set.

Control-M/Tape greatly simplifies implementation of Fast Positioning. Implementation can be accomplished by defining a single Control-M/Tape rule. Control-M/Tape implementation of Fast Positioning is invisible to your applications, and requires no changes to the programs or JCL.

Fast Positioning of Control-M/Tape works as follows:

1. At the time of data set creation, Control-M/Tape retrieves the blockID of the data set from the operating system, and stores it in the Control-M/Tape Media Database. The blockID identifies the data set location.

2. During subsequent access of the data set, Control-M/Tape retrieves the blockID from the Media Database, and passes it to the operating system, that then fast positions the tape to the specific location.

Control-M/Tape can apply Fast Positioning to the following data set access situations:

• Reading a data set

• Rewriting a data set.

• Adding a data set to the end of a tape. (In this case, Control-M/Tape uses the blockID at the end of the tape volume.)

Implementing Fast Positioning

To implement Fast Positioning for a data set, define a DO FASTPOS statement in a rule that applies to a data set, as follows:

• If Control-M/Tape is to be run in production mode, set the DO FASTPOS parameter to YES or to OVERRIDE.

• If Control-M/Tape is to be run in test mode, set the DO FASTPOS parameter to TEST.

For more information, see DO FASTPOS Values.

Requirements for Fast Positioning

For Control-M/Tape to instruct the operating system to fast position a tape to a data set, all of the following conditions must be met:

• A rule is defined with an appropriate DO FASTPOS statement.

• The tape device supports Fast Positioning. Tape devices 3480, 3490, 3490E, and 3590 all support Fast Positioning.

• The tape is a standard label tape.

• Either:

  • You are reading or rewriting a data set whose position Control-M/Tape has stored in the Media Database, or

  • You are adding a data set to a tape, and Control-M/Tape has stored the position of the logical end of tape in the Media Database.

• If you are rewriting a data set, you are not appending to the data set (that is, the JCL does not include the expression DISP=MOD, and the program does not open the data set with an option that implies that expression).

DO FASTPOS Values

Any of several values can be specified in a DO FASTPOS statement. The value specified determines how Control-M/Tape handles Fast Positioning. Valid values are:

Table 183 DO FASTPOS Values

Considerations

Control-M/Tape can use Fast Positioning for a data set even if other data sets on the tape were created without Fast Positioning (meaning, a tape can contain any combination of data sets created with and without Fast Positioning).

Control-M/Tape receives the position of a data set from the operating system and records the position in the Media Database only when you create or rewrite the data set, not when you read it. Therefore, if you create a data set without recording its position (for example, with the expression DO FASTPOS=NO), Control-M/Tape cannot use Fast Positioning for that data set. Even if you later set DO FASTPOS to YES, and then read the data set, Control-M/Tape cannot use Fast Positioning for it.

If Control-M/Tape determines that the requested Fast Positioning is not appropriate (for example, the JCL includes the expression DISP=MOD) and the application does not have its own Fast Positioning mechanism, Control-M/Tape allows the operating system to use conventional sequential search positioning. In such a case, Control-M/Tape does not display or log an error message.

When Control-M/Tape passes a Fast Positioning request to the operating system, the operating system examines the request and determines whether Fast Positioning is worthwhile. If the operating system determines that Fast Positioning is not worthwhile (for example, if the requested block ID is near the beginning of the tape), the operating system uses the conventional sequential search mechanism instead. This means that a Control-M/Tape request for Fast Positioning never increases positioning time. It either decreases it or leaves it unchanged.

Because Fast Positioning can dramatically speed up jobs, it is recommended that you include the expression DO FASTPOS=YES in Control-M/Tape rules for all data sets that you write.

IOA Functions

At each intervention point, Control-M/Tape can execute a set of actions that are common to other INCONTROL products. Through these actions (meaning, DO actions specified in Control-M/Tape rules), Control-M/Tape can communicate with other INCONTROL products, trigger events, schedule jobs, and so on.

These actions are:

Table 184 IOA Functions that Control-M/Tape can execute at Intervention Points

The intervention points are:

Table 185 Intervention Points where Control-M/Tape can execute IOA Functions

IOA Functional Monitor

The IOA Functional monitor is a started task that runs constantly. It waits for actions (for example, IOA functions such as DO CONDITION and DO SHOUT) that require processing, and processes them. It also accepts requests to be passed to robot tape libraries, and processes them.

IOA functions required by Control-M/Tape in the online and real-time environments are passed to the IOA Functional monitor by the Control-M/Tape Trace file. When an event occurs (for example, volume checked in, data set created) that requires execution of an IOA function, the Control-M/Tape component writes a trace record that describes the needed function.

When the IOA Functional monitor reads the Control-M/Tape Trace file, it executes the requested functions.

The IOA Functional monitor initially passes control of each request to IOA user Exit IOAX038. When control is returned to the IOA Functional monitor, the monitor activates a different task to handle each type of request (for example, DO FORCEJOB, DO SHOUT). Each task can call a specific IOA user exit (for example, Exit IOAX007 for DO CONDITION) to control the handling of the current operation.

When using several INCONTROL environments in conjunction with only one Control-M/Tape environment, it must be decided in which of these INCONTROL environments the IOA Functional monitor is to be brought up. When multiple IOA Functional monitors are used, IOA user Exit IOAX038 can determine which requests is processed under each environment (for example, process requests under the CPU that initiated the request).

For more information about using one or more INCONTROL and Control-M/Tape environments with the IOA Functional monitor, refer to "IOA Functional Monitor" in the INCONTROL for z/OS Installation Guide.

Operation Modes

Control-M/Tape can operate in one of three modes: Production, Phased, or Test. The mode mainly affects the actions of the Real-Time environment. The operation mode is determined by the MODE parameter in member CTTPARM (global mode) and by the MODE parameter in the rules (rule mode).

Production Mode

When in Production mode, Control-M/Tape controls volume processing in the system. Jobs that violate data integrity abends, invalid volumes are rejected and WTORs (Write To Operator and wait for Reply) are issued to the operator in certain cases.

Phased Mode

Phased mode enables Control-M/Tape to work in parallel with another tape management system. Phased mode is very similar to Production mode. Phased mode cannot be specified in a rule, only in member CTTPARM. Control-M/Tape maintains control before and after any other tape management system. Therefore, if Control-M/Tape abends a job or rejects a volume, it is not recorded by another tape management system. Likewise, if another TMS causes a job to abend or reject a volume, it is not recorded by Control-M/Tape.

Test Mode

In Test mode, Control-M/Tape records information in the Media Database but does not intervene in any way (meaning, no abends, no WTORs, no volume rejects, data sets are not uncataloged when expired). Unexpired data sets are not protected against overwriting in Test mode. Messages are issued as in Production mode. In addition to a global Test mode (set by the expression MODE=TEST in member CTTPARM), Test mode can be selectively assigned to certain applications by defining rules. In this way, Control-M/Tape can operate in Production or Phased mode and still operate in Test mode for certain jobs, volumes, data sets, and so on. The first rule that is relevant to a request (meaning, the first matching rule) determines whether that request is handled in Production or Test mode.

Stacking

Stacking is the process by which Control-M/Tape places data sets with similar attributes (for example, retention) together on a volume. Two types of data set stacking can be performed by Control-M/Tape:

• Batch stacking - Handles already existing data sets using the CTTSBD utility that is run in batch mode.

• Dynamic Dataset stacking – Handles newly created data sets during real-time operations.

Batch Stacking

The CTTSBD utility enables you to stack data sets already on tapes at your site. This utility can be used to free scratch tapes, override stacking limitations imposed by your real-time stacking definitions, and organize data sets that existed before your site’s tapes were managed by Control-M/Tape.

For more information about batch stacking, see the CTTSBD utility in the INCONTROL for z/OS Utilities Guide.

Dynamic Dataset Stacking

When a scratch volume is requested for a new data set, Control-M/Tape can automatically direct the data set to an active volume that contains one or more files with attributes similar to the new data set.

This feature is controlled by both the DYNSTK installation parameter, which much appear in the CTTPARM installation parameter, and the DO STACK statement, which must appear in the Control-M/Tape rule of the data set.

At the start of a job, Control-M/Tape searches the JCL of the job for a request for a new tape data set to be created on a scratch volume. If such a request is found, Control-M/Tape verifies the following:

• Control-M/Tape is operating in Global PHASED / PROD Mode.

  When Control-M/Tape is operating in TEST mode, Dynamic Dataset Stacking is controlled by the STKTEST parameter in the CTTPARM member.

  The CTTPARM member can be refreshed in memory by starting the CTTINIT procedure with the expression parm=`RELOAD,TBLT=PARM’.

• The matching rule does not specify the expression RETENTION=EDM or MODE=TEST.

• A matching record for the data set is found in the Stacking Database.

• The name of the data set to be found can be changed by Exit 2.

This check can be overridden when parameter STKDEFSZ is specified in member CTTPARM or in a rule.

• The data set is marked as stackable in the Stacking Database.

• The pool name specified in the rule points to an active (defined) pool.

Depending on the results of the check, either of the following occurs:

• If any of these checks fails, message CTT356W is issued followed by a message that identifies the cause of the failure, and stacking is not performed for the data set.

• If all checks succeed, the Media Database is scanned for a suitable volume. The maximum number of volumes that can be scanned is specified in parameter STKSRCHL in CTTPARM. Either of the following two results is possible:

• If the search limit is reached without finding a suitable volume, stacking is not performed, message CTT356W is issued followed by a message that identifies the reason that stacking could not be performed, and a SCRATCH request (mount request for a scratch volume) is issued.

• If a suitable volume is found, the job’s parameters are adjusted to direct the data set onto the selected volume. Instead of issuing a SCRATCH request, the mount message requests the selected volume.

The search for a suitable volume process calls Exit 10 (Find Stackable Volume Exit). This exit can be used to control the search algorithm. For more information regarding Exit 10, refer to "Control-M/Tape Exits" in the Exits chapter of the INCONTROL for z/OS Administrator Guide, and to member DOCTX010 in the IOA DOC library.

Each subsequent search for a suitable volume begins from the last volume scanned in the preceding search.

The space required for the new data set is estimated based on the sizes of previous versions of the data set. Previous versions must have the same data set name and must be created by the same job name. This information is kept in the Stacking Database.

For every newly created data set, Control-M/Tape writes a record containing data set attributes (such as block size and block count) in the Trace file. During the New Day procedure, a utility (CTTSTK) reads the Trace file and updates the information in the Stacking Database.

If a data set is recreated, processed with the expression DISP=MOD, or processed in a step with DD statement //NOSTACK, an entry is created in the Stacking Database marking this data set as non-stackable. The volume on which this data set resides is also marked as non-stackable (in the Media Database).

Control-M/Tape maintains the used space (megabytes used) and free space (megabytes remaining) of each volume. Whenever a volume becomes scratch, it is assigned the maximum size, according to its media. This size is specified in the MEDIA statement in member CTTPARM.

Besides having enough space and belonging to the appropriate pool, the selected volume can be forced to meet one or both requirements controlled by parameter STKMODE in member CTTPARM:

• The volume can be forced to have the same vault pattern as the data set (or not have any vault pattern if the data set is not intended for vaulting).

• The last data set on the volume can be forced to have a retention period that is equal to or greater than that of the new data set.

User Exit CTTX002 can be used to change default processing (for example, it can eliminate the job name factor so that any data set with the same name is considered a previous version of the new data set).

Stacking Datasets With Nonspecific Retention

During New Day Processing, the CTTSTK utility reads the Trace file and gathers statistical information about data sets with non-specific retention (meaning, retention types CYCLES, CATALOG and LAST ACCESS). Based on this information, the average life span of each data set of this type is calculated and stored in the Stacking Database (STK).

Stacking of data sets with non-specific retention is performed according to installation parameter STKMODE. If STKMODE is set to R or A, the Dynamic Stacking facility calculates the expected retention date of the data set based on average data set life span. The data set is then stacked as if a specific retention was specified for it (meaning, it can be stacked on volumes that contain data sets with a specific retention type).

If STKMODE is set to S, the average data set life span is not considered and the stacking algorithm is not changed.

If a stacking statistics record is not found for a data set, that data set is treated as having an unknown retention, and the data set cannot be stacked unless installation parameter STKMODE is set to S.

Stacking Conditions

Control-M/Tape stacks data sets only if the following conditions are met:

• Parameter DYNSTK in member CTTPARM is set to YES and Control-M/Tape is operating in Production mode or Phased mode.

• Stacking can be activated when Control-M/Tape is operating in TEST mode by setting STKTEST to Y in the CTTPARM member.

• A SCRATCH (meaning, nonspecific) request for a new data set is issued and the volume is accessed as Standard Label (SL).

• The data set is to be cataloged after creation with the expression DISP=(NEW,CATLG). Otherwise, it is assumed that the user probably depends on the data set being first on the volume.

• For non-SMS data sets, the UNIT parameter in the JCL is one of the units specified in parameter STKUNIT in member CTTPARM.

• For SMS-managed data sets, YES is specified for Control-M/Tape installation parameter SMSINTR, and the SMS Storage Group type of the data set is TAPE.

• There is no //NOSTACK (stacking bypass) DD statement in the JCL.

• The mount request is matched by a rule that specifies the expression DOSTACK=YES. The rule can match the data set name, job name, program name, and so on. The VOLSER is not a criterion in this case.

• The rule specifies the expression MODE=PROD. If the rule specifies the expression MODE=TEST, Control-M/Tape does not perform stacking, even if the CTTPARM member includes the expression TESTRULE=NO.

• An entry for this data set and job name exists in the Stacking Database, so that Control-M/Tape is able to estimate the size of the new data set. This value can be overridden when parameter STKDEFSZ is specified in member CTTPARM, or by a DO STKDEFSZ statement in a Control-M/Tape rule.

  The Stacking Database is updated as part of the New Day procedure.

• Either the matching rule specifies a defined pool name or it does not specify any pool name.

• An eligible volume from the same pool is found that is no more than x% full after stacking. This percentage is determined by the MEDIA statement in member CTTPARM (parameter STKPCNT).

• Parameter STKMODE in member CTTPARM specifies:

  • S (Simple), and neither the volume nor the new data set is to be vaulted.

  • V (Vaulting), and the vault pattern of the volume is the same as that of the new data set.

  • R (Retention), and the retention of the last data set on the volume is equal to or greater than that of the new data set.

  • A (All), and the conditions for both Retention and Vaulting are met.

• The volume is not marked as External, Out-of-Lib, or Vaulted. The data set is not EDM controlled.

• The DD statement does not specify the expression VOL=REF and is not the target of this expression in another DD statement.

• The value for volume-count (the fourth subparameter of JCL parameter VOLUME) is either 1, or blank (meaning, no specification).

• The DD statement does not use the expression UNIT=AFF.

• The file sequence number is either specified as 1, or has the default of 1.

• The DD statement does not specify the expression EXPT=98000.

• The volume contains data sets that are either members of the same stacking group or are compatible with the stacking group of the data set to be stacked.

• Stacking is not denied by a DO STKRULE statement in a Control-M/Tape rule.

• The volume does not already contain the maximum number of data sets specified in either installation parameter STKMXLBL or a DO STKMXLBL statement in a Control-M/Tape rule.

• The volume sequence number does not exceed the limit defined by a DO STKMXVOL statement.

• The volume’s stacking group matches the stacking group of the data set, or a stacking group is *ANY.

• The data set is allocated in a DD statement in a job’s JCL. Control-M/Tape does not stack data sets that are allocated dynamically (using SVC 99).

Retention Management

Control-M/Tape supports a variety of expiration types. These are listed in the table below:

Table 186 Control-M/Tape Expiration Types

The retention period of a data set is the combination of up to three expiration dates, with a logical relation between them (And/Or). For example:

DO RETENTION = CYCLES             0003     PREFIX N  (Y/N)     And/Or  A
               JCL EXPDT                                       And/Or
DO

The above rule determines that the data set expires when three cycles of the data set exist and the JCL EXPDT/RETPD/DATACLAS date has been reached.

The JCL EXPDT parameter can specify a special value (for example, 99365), thus causing the data set to be permanently retained.

RETPD and EXPDT JCL Parameters

Table 187 JCL Retention Parameters

Turning Off Special Treatment of EXPDT Values

To turn off special treatment of all the EXPDT values described above (except for the expression EXPDT=98000), put a special DD DUMMY statement in the JCL. The DDNAME of this special DD statement is the value of the EXPDTDDN parameter in member CTTPARM.

For example, if member CTTPARM includes the expression EXPDTDDN=DD2000, the special DD DUMMY statement would be

//DD2000 DD DUMMY

When the JCL includes this special DD statement, Control-M/Tape treats all EXPDT values except 98000 as standard dates, without any of the special meanings described earlier. The expression EXPDT=98000 retains its special meaning.

Retention Algorithm

Whenever a new data set is created, the retention specification for that new data set is taken from one of the following sources:

• retention attributes: JCL parameters EXPDT, RETPD, or DATACLAS, and, if the SMS Interface is active, relevant Management Class attributes

• the rule table currently in memory

• $DEFAULT rule

• installation default

The algorithm by which the retention specification is selected is as follows:

• If a retention specification is found in either the retention attributes or in the current rule table, but not both, that retention specification is used.

• If a retention specification is found in both locations, the retention selected depends on the OVERJCL installation parameter:

  • If OVERJCL is set to Y, the retention from the current rule table is used.

  • If OVERJCL is set to N, the retention attributes are used.

• If a retention specification is not found in either the retention attributes or the current rule table, the retention in rule $DEFAULT is used. If rule $DEFAULT does not exist, the installation default is used.

  To maintain CA-TLMS compatibility, if the JCL EXPDT / RETPD / DATACLAS parameter contains a non-keyword date, the $DEFAULT rule overrides the JCL value. The JCL value is considered only if the $DEFAULT rule specifies JCL retention.

  Retention parameters are taken from the current rule table.

  Note that when processing abend retention, the retention attributes are not considered.

• If the table does not have retention specifications, abend retention is taken from $DEFAULT.

• If $DEFAULT does not have retention parameters, the installation default is used.

Retention Update

Retention is always set or updated when the data set is first introduced to the Media Database by Create, Recreate, or Dynamic Definition.

The RTNUPD parameter in the CTTPARM member can be used to update the retention in other situations, depending on the type of access to the data set (for example, DISP=MOD access). For more information, see the description of parameter RTNUPD in the INCONTROL for z/OS Installation Guide: Installing.

Volume Retention

Because the volume retention period is the latest retention period of any of its data sets, changes made to the data sets in a volume might change volume retention information. Volume retention information consists of the following:

Table 188 Volume Retention Information

Retention Processing

Actual expiration of data sets and volumes is performed by the CTTRTM utility, which is run on a daily basis.

CTTRTM examines the retention period of all data sets listed in the Media Database. In general, when the retention period of a data set has been exceeded, the data set status in the data set record is set to "scratch" and the corresponding volume record is updated accordingly. A volume does not become scratch until all its data sets are expired.

If the RTNTYPE installation parameter is set to VOL in the CTTPARM parameter, a data set is not scratched until all the data sets on the same volume have expired. In this case, all the data sets on a multifile volume are scratched at the same time, when the last data set expires. If RTNTYPE is set to DSN, each data set is scratched according to its own retention period, even if other active data sets exist on the volume.

If the RTNTYPE installation parameter is set to GROUP in the CTTPARM parameter, a data set is not scratched until all the data sets in the group of volumes have expired. In this case, all the data sets on a multivolume group are scratched at the same time, when the last data set expires. If RTNTYPE is set to DSN, each data set is scratched according to its own retention period, even if other active data sets exist on the volume.

When a data set is expired by Control-M/Tape, if the data set is cataloged in the same volume, it is uncataloged from the operating system catalog. A vaulted volume is not scratched until it has completed its vault pattern and returns to the Active library (MAINLIB).

In addition to utility CTTRTM, volumes and data sets can be scratched through the Online facility (TI screen), the CTTMUP utility, or the CTTAPI. For an example of scratching using CTTAPI, see the CTTVEXP member in the IOA SAMPLE library.

From the Online facility, volumes and data sets can be expired using the Expire command in the Inquire/Update screen. If an Immediate scratch is requested, the volume and all the data sets residing on it expire immediately. If not, they are marked as Pending Scratch and are expired by the next run of utility CTTRTM.

Vault Management

When a data set is closed, the rule table in memory is searched to see if a vault pattern was specified for this data set. If found, this vault pattern is copied to the volume record.

The vault pattern specifies the different vaults in which the volume is to be stored, and how long the volume is kept at each vault (meaning, retention criteria for each vault). The retention criteria for each vault are the same as general retention specifications. Vault retention criteria can be composed of up to three expiration dates, each of a different type (specific date, cycles, and so on).

One DO VAULT statement can be specified per rule, but an unlimited number of vaults can be specified in the DO VAULT statement.

Vault locations, entry dates, exit dates, and retention criteria are recorded in the Media Database. The current location of a volume is updated whenever the volume is moved.

A volume residing in a vault cannot be scratched. When a volume is first created or checked in (from external sources), the volume’s first location is the active library (MAINLIB). When a volume’s vault retention in any location expires, the volume is moved to the next vault location specified in the Media Database. When no additional vault locations are specified for a volume, the volume returns to MAINLIB.

Since vaulting can only be performed on a volume and not on individual data sets, only one data set can determine the vault pattern of a volume. Installation parameter VLTBYDS1 determines which data set sets the vault pattern for the volume. If parameter VLTBYDS1 is set to Y (Yes) in member CTTPARM, the first data set on a volume determines the vaulting of the volume. If parameter VLTBYDS1 is set to N (No), the first data set that has vault criteria (regardless of its position on the volume) determines the vaulting of the volume, provided there is no previous vault pattern for this volume.

The same vault pattern is assigned to all volumes in a multi-volume chain.

Only one data set in a volume or multi-volume chain can determine the vault pattern for the volumes. The VLTBYDS1 parameter in the CTTPARM member determines the data set whose vault pattern takes effect for the multi-volume chain.

Example

Vault Locations

Vault locations are defined using the Online facility and stored in a special member in the definitions library. A vault definition contains the vault name, vault attributes (either local or remote), some documentary data, and details about the capacity and organization of the vault.

During the Initialization process, vault definitions are loaded into memory and become part of the Real-Time environment. These definitions can be changed and reloaded without shutting down Control-M/Tape.

When the Vault Management facility is run, volumes are moved to and from vaults. Each volume is assigned an empty slot in its new vault and its old slot becomes free. Data about the current capacity of a vault is kept and updated in special records (vault records) within the Media Database.

If vault capacity is not specified when defining a vault, Control-M/Tape does not manage slots in that location.

When a vault definition is modified (for example, by screen TV), the modification is stored in the Vault Definition member (for example, $$VAULT) but does not affect the vaulting of volumes until after the next run of utility CTTVTM.

Vaulting By Boxes

In addition to handling volumes on an individual basis, Vault Management can handle "boxes" of volumes. Volumes are gathered into boxes, and boxes are moved to different locations.

Boxes can only be moved to the locations specified for the volumes they contain. Therefore, all volumes in a box must have the same vault pattern. The vault pattern must contain only date related retention criteria (VAULT DAYS and DAYS SINCE CREATE). Boxed volumes cannot contain non-date retention criteria (for example, CYCLE, MVS CATALOG).A name (unique 6-character identifier) and capacity (size) is defined for each box. The number of boxes that can be defined, as well as the size of a box, are unlimited. A minimum number of volumes required in a box (BOXLIMIT) can be defined.

All boxes are defined in the vault named "MAINLIB" and are assumed to be empty. If MAINLIB is one of the destinations of the box in its vault pattern, use a vault name other than MAINLIB as an alias for the main library, and define the box slot capacity under that alias vault.

For information regarding the defining of boxes, refer to Vault Definition Facility.

When volumes are to be moved from MAINLIB, they are placed in an appropriate box and the box is moved to the appropriate location.

When a vaulted volume needs to be processed in MAINLIB, the complete box (with all its volumes) is recalled from its current location. After the volume is processed, the box returns to its original vault location.

No volumes are added or removed from a box until the box completes the vault cycle and returns to MAINLIB. At that point, the box is assumed to be empty again.

To request vaulting by boxes, the user must specify the expression BY BOX=Y in the DO VAULT statement in the rule definition. This allows the volume using that rule definition to be placed in a box. The volume is placed in a box according to other conditions such as the number of free boxes.

When utility CTTVTM is processing these volumes, it sorts them according to media type and vault pattern. It then looks for an empty box that supports the media type and places the volumes in the box.

A set of volumes that are vaulted by box, but contains fewer volumes than specified by the BOXLIMIT parameter is vaulted without a box using the regular volume vaulting process (in a slot). For more information, see utility CTTVTM in the INCONTROL for z/OS Utilities Guide.

When CTTVTM must move a volume that is vaulted in a box, the whole box is moved to the next location, including all the volumes contained in that box. When there is no next entry, or when the next entry is MAINLIB and is also the last entry in the vault pattern, all volumes are removed from the box and the box is marked EMPTY.

Unless specifically requested, utility CTTVTM does not reload the box definition on each invocation. To add, delete, or update box definitions, CTTVTM must be invoked in a special mode, by specifying parameter BOXBLD.

A user who is using box management for the first time should first run utility CTTVTM with parameter BOXBLD, so that the utility defines the boxes in the Media Database.

Utility CTTVTM produces special reports detailing the movement of boxes. The reports indicate that volumes are placed in specified boxes, and that boxes are moved between the vault locations.

For more information, see utility CTTVTM in the INCONTROL for z/OS Utilities Guide.

Control-M/Tape to DFSMS Interface

The Control-M/Tape to DFSMS interface enables you to:

• Determine the expiration date of a data set on the tape according to DFSMS Management Class definitions.

• Use Management Class as a selection parameter in rule definitions. For more information, see the description of ON MGMTCLAS in ON Statement: Selection Parameter.

For information regarding the activation of the Control-M/Tape interface to DFSMS, see the discussion on DFSMS support in the Control-M/Tape DFSMS interface chapter of the Control-M/Tape Implementation Guide.

Retention by Management Class

Real-Time Processing

If the Control-M/Tape to DFSMS interface is active, when a data set is created on tape, the DFSMS Management Class of the data set (if it exists) is recorded in the Control-M/Tape Media Database. Depending on the value of installation parameter OVERJCL, the retention is set either according to rule definitions defined for the data set or according to the retention attributes, described in the next topic, Retention Management Utility (CTTRTM) Processing and in Retention Algorithm.

Retention Management Utility (CTTRTM) Processing

During the execution of retention management utility CTTRTM, if data set retention is performed according to the retention attributes, the DFSMS Construct Access Services is invoked to obtain the Management Class definition.

DFSMS Management Class definition attributes that are relevant for the Control-M/Tape retention processing are:

• Retention Limit
• Expiration attributes (Expire After Days Non-Usage, Expire After Date/Days)
• # GDG Elements On Primary

The Retention Limit and Expiration attributes are combined with EXPDT/RETPD values (if issued) in the JCL to form a retention criterion. These values are combined in the manner described in "Defining Management Class Attributes" in the DFSMSdfp Storage Administration Reference Manual.

Attribute "# GDG Elements On Primary" specifies the number of data set cycles that Control-M/Tape should retain. If both Expiration Attributes and attribute # GDG Elements On Primary are defined for the same Management Class, a tape data set with this class is expired only if the Management Class attributes, the number of cycles, and JCL EXPDT/RETPD criteria, are satisfied.

The result of merging the retention criteria is referred to as retention attributes, described in the topic Retention Algorithm.

When using Management Class to set a tape data set expiration date, the expiration of the data set is flexible. Each time utility CTTRTM is executed, the Management Class attributes are extracted. Therefore, when changing the Management Class attributes under DFSMS, the expiration date of each data set that has this Management Class in the Control-M/Tape Media Database is also changed.

Pool Assignment by Management Class

Different pools can be assigned to different jobs based on selection criteria. When the Control-M/Tape to DFSMS interface is active, a Management Class can be used as a selection criterion. For more information, see ON MGMTCLAS in ON Statement: Selection Parameter.

DFSMS Class Definitions

It may be desirable to define special Storage Classes and Management Classes for tape data sets. As stated earlier in Retention by Management Class, few Management Class attributes and no Storage attributes are relevant to Control-M/Tape. The reason for defining special Storage Classes is that DFSMS activates the Management Class ACS routine only if a Storage Class is assigned to the data set.

Stacking of DFSMS-Controlled Data Sets

DFSMS-controlled data sets are handled by the Dynamic Dataset Stacking facility only if the following are true:

• YES is specified for Control-M/Tape installation parameter SMSINTR.

• The data set is controlled by DFSMS.

• The SMS Storage Group type of the data set is TAPE.

Automatic Class Selection (ACS) Routine Adjustments

To extract the Management Class for a tape data set, Control-M/Tape invokes the DFSMS Automatic Class Selection (ACS) routines, usually several times. ACS parameter &ACSENVIR can be used to distinguish between Control-M/Tape activation’s of the ACS routines and other activation’s (probably DFSMS) of these routines. The value of &ACSENVIR also helps distinguish between the different events in that Control-M/Tape invokes the ACS routines.

Since DFSMS activates the Management Class (MC) ACS routine only if a Storage Class (SC) is assigned for the data set, adjustments are made to both the Storage Class ACS routine and the Management Class ACS routine. The Storage Class ACS routine should assign a Storage Class for the tape data set, and the Management Class ACS routine should assign the tape data set a Management Class.

Invoking Automatic Class Selection Routines

Control-M/Tape invokes DFSMS ACS routines for each of the events in the table below. Note the following points:

1. The value of &ACSENVIR depends on the event.

2. Since different Management Classes can be assigned to the same data set in different activations of the ACS routines, different Control-M/Tape rule definitions might be applied for the same data set in different events.

3. When a Management Class (MGMTCLAS) selection criterion is used in combination with other selection criteria (for example, JOBNAME), the rule is applied only if all criteria are satisfied.

Table 189 Events for which Control-M/Tape Invokes DFSMS ACS Routines

The following table lists which ACS parameters are available. Environments for which these parameters are available are marked by an X (or by other relevant information). The environments indicate the following events under Control-M/Tape:

• CTTMNTV–A mount request is issued.

• CTTOPEN–A new data set is opened.

• CTTDSADD–A volume is checked in by the External Volume Check-In screen (TC).

Table 190 Available ACS Parameters