Control-M/Tape

• Overview

• Control-M/Tape Real-Time Environment

• New Day Procedure

• Repository Structure

• Repository Maintenance

• Repository Backup and Recovery

• Displaying Media Database Information on an OS/390 or z/OS Console

• Control-M/Restart Support for Control-M/Tape

• Control-M/Tape Application Programming Interface

OverviewLink copied to clipboard

This chapter describes how the different components and files of Control‑M/Tape are activated, controlled, and maintained on a regular daily basis. The following topics are discussed in this chapter:

• ControlM/Tape realtime environment

• new day procedure

• repository structure

• repository maintenance

• repository backup and recovery

• media database view customization

• ControlM/Tape application programming interface (API)

Some administrative tasks are performed using Control‑M/Tape utilities. For a detailed description of the available utilities, see the INCONTROL for z/OS Utilities Guide.

Additional customization and security measures can be implemented using Control‑M/Tape exits. For a description of the available Control‑M/Tape exits, see Exits.

Control-M/Tape Real-Time EnvironmentLink copied to clipboard

The Real‑Time environment of Control‑M/Tape is established during the Initialization process.

Once the Real‑Time environment is established, Control‑M/Tape takes control of tape volumes processed in the system. This is accomplished by the Control‑M/Tape MVS Tape Label Processing Exits. 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 non-specific mount requests. As a dataset 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 following sections describe these topics.

InitializationLink copied to clipboard

The first step in using Control‑M/Tape is to initialize Control‑M/Tape in each system. This is done by the CTTINIT procedure. Control‑M/Tape is usually initialized as part of the IPL process. The following table lists and describes the steps that the CTTINIT procedure performs to establish the Control‑M/Tape Real‑Time environment:

Table 216 CTTINIT initialization steps

The STEPLIB DD statement must not be removed from the CTTINIT procedure. The CTTINIT procedure does not function properly if this DD statement is removed.

The Control-M/Tape Control Table (TCT) is a block of information that contains key control data and pointers, and resides in the Common Storage Area (CSA). Its address is used by all real-time components, such as the Control-M/Tape SVC and the sub-system, and certain other components, such as EDM expiration exits. All activity starts from the TCT, which contains pointers to all Control-M/Tape tables and modules in storage. The TCT, 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, with the exception of the IOA Functional monitor (IOAFMON), if you need automated tape library support or if you need to perform IOA functions such as sending and receiving Shout messages. For more information about the IOA Functional monitor, see IOA Concepts and Components.

CTTINIT ProcedureLink copied to clipboard

The CTTINIT procedure controls the initialization, termination, and operation of Control‑M/Tape. This procedure is invoked by operator command

S CTTINIT,PARM='MODE=xxxxx[,=nnn,=xxxxxxxx]'

The PARM field can contain one of the MODE=values described in the following topics.

Parameters Relating to Initialization, Termination and RefreshingLink copied to clipboard

Table 217 Parameters Relating to Initialization, Termination and Refreshing

S CTTINIT,PARM='MODE=RELOAD,TBLT=RULE'

S CTTINIT,PARM='MODE=RELOAD,TBLT=POOL'

S CTTINIT,PARM='MODE=RELOAD,TBLT=VAULT'

S CTTINIT,PARM='RELOAD,TBLT=PARM'

S CTTINIT,PARM='MODE=RELOAD,TBLT=VIEW'

Parameters Relating to Operating System InterfacesLink copied to clipboard

Table 218 Parameters Relating to Operating System Interfaces

VERIFY can be executed only if the Control-M/Tape Real-Time environment is not active. CHECK can be executed regardless of whether Control-M/Tape is active.

Parameters Relating to Operating StatusLink copied to clipboard

Table 219 Operating Status Parameters

Problem Resolution ParametersLink copied to clipboard

Table 220 Problem Resolution Parameters

Sample JCL for procedure CTTINIT can be found in the IOA Procedure library. The following table describes the DD statements that are important for managing and maintaining Control‑M/Tape:

Table 221 DD Statements

* CTT.V900.RULES    BKPRULE      ORDER
* CTT.V900.RULES    SAVRULE      ORDER

Loading of RulesLink copied to clipboard

When Control‑M/Tape is started (or rules need to be reloaded), Control‑M/Tape attempts to read a list of rule tables from the member referenced by the DARULLST DD statement. These rule tables are automatically loaded by Control‑M/Tape. The supplied default member RULLIST is in the Control‑M/Tape PARM library. Each line in the list has the following format:

date library table operation

where

• date is the date of the rule table. If a specific date is designated, it is used to analyze the Basic Scheduling parameters. The date format is mmddyy, ddmmyy, or yymmdd (depending on the site standard).

• Specifying an asterisk (*) indicates the current ControlM/Tape Working Date.

• library is the name of the library in which the rule table is located.

• table is the name of the rule table.

• operation is the operation to be performed on the rules in the specified table. Valid values are

  • ORDER: Each rule’s Basic Scheduling parameters are compared to the specified date (or the current ControlM/Tape Working Date when * is specified). If the rule must be scheduled on that date, it is loaded by ControlM/Tape and activated. Default.

  • FORCE: Each rule is loaded by ControlM/Tape and activated. Use the FORCE option when you do not want to use ControlM/Tape scheduling options.

For every line in the list, Control‑M/Tape loads the specified rule table from the specified library.

TerminationLink copied to clipboard

Control‑M/Tape must be in operation from system startup to shutdown (that is, all the time), so that it can intercept all removable media management activities. Information about jobs that access removable media is not recorded while Control‑M/Tape is inoperative.

When Control‑M/Tape is terminated, a check is triggered for active jobs that currently access removable media in the system. If such jobs exist, the operator is 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.

New Day ProcedureLink copied to clipboard

The New Day procedure is the primary mechanism used to perform daily maintenance on the Control‑M/Tape Media Database and related files.

The New Day procedure, called CTTDAY, can be activated automatically by a scheduler (for example, Control‑M) at a predefined time each day. The New Day procedure can also be activated manually by submitting a job.

New Day FunctionsLink copied to clipboard

The maintenance operations illustrated and described in this section are performed by the New Day procedure.

New Day ProcessingLink copied to clipboard

The order of processing may be changed in certain situations.

Figure 74 New Day Phases Processing

Table 222 New Day Procedure Phases

Repository StructureLink copied to clipboard

The Control‑M/Tape Repository is composed of the following files:

• media database

• trace file

• stacking database

Control-M/Tape Media and Stacking databases are managed by IOA Access Methods. The following IOA Access Method restrictions exist for the Control-M/Tape database:

• Allocation of new Media Database extensions is not automatically defined. They can only be defined manually, using the IOADBF utility with the EXTEND option.

• Secondary allocations for the index file are not allowed.

• Dual database option is not allowed.

• The data files must be defined with TYPE=F in the IOA Access Method member definition because TYPE=V is not allowed for Control-M/Tape data file.

Media Database StructureLink copied to clipboard

The Control‑M/Tape Media Database consists of the following primary physical files:

Table 223 Control-M/Tape Media Database Files

These files are managed by the IOA Access Method. For more information, see IOA Access Method.

The Data and Index files are allocated by Control‑M/Tape activities using the following DD statements:

Table 224 DD Statements for Allocating the Data and Index Files

Data File ContentsLink copied to clipboard

The Data file contains all the data about any volume or dataset. In Control‑M/Tape, unlike other tape management systems, volume information and dataset information are stored in the same file, but with different record types and formats.

The following table lists the two most common record types in the Control‑M/Tape Data file:

Table 225 Common Data File Record Types

Volume and dataset records are mapped using assembler macros CTTDVL and CTTDDS, respectively. All record types in the Data file have a common header at the beginning of the record. This header contains the following information about the record:

Figure 75 Sample Record in the Data File

Table 226 Fields in the Data File Record

Fields in the Data FileLink copied to clipboard

Some of the more important fields in the volume and dataset records in the Data file are listed in the table below. Each field is assigned an internal name (a symbol in a DSECT that describes the record) and an external name (a logical name used by the user in INCLUDE and EXCLUDE statements). For a comprehensive list of these fields, see Logical Field Names for the Control-M/Tape Repository and the CTTDVL and CTTDDS members in the IOA MAC library.

Table 227 Commonly Referenced Volume Record Fields

Table 228 Commonly Referenced Dataset Record Fields

Index File ContentsLink copied to clipboard

The Index file makes keyed access of records in the Data file possible. The Index file contains records that, in turn, contain index elements. Each index element contains the following fields:

Table 229 Index Element Fields

Key TypesLink copied to clipboard

Each index element contains a particular type of key that is used for accessing records in the data file. The following table describes the full and partial keys of each type:

Table 230 Key Types

Depending on the function being performed when accessing the Index file, you can specify a full key or a partial key. For more information, see Index File Contents.

A partial key is shorter than the full length of the key in the index file. The most common usage of a partial key is the specification of a prefix (for example, dataset name prefix instead of a full dataset name). Partial keys can also be used when all necessary information is not available.

All index elements have the same fixed length, which is determined by the index elements with D‑type keys because the D‑type key is the longest full key (that is, the dataset name).

Index element length exceeds the length of the longest key because index elements contain additional bytes that are used by the Control‑M/Tape Repository-handling mechanisms.

Index elements with V‑type keys are mapped using assembler macro CTTDVX. Index elements with D‑type keys are mapped using assembler macro CTTDDX. Index elements with L‑type keys are mapped using assembler macro CTTDLX.

Volume and Dataset RelationsLink copied to clipboard

The Media Database Data file contains a record for each volume and a record for each dataset. Fields in these records, and indexes of various types, are used to describe the relationships between a volume and its respective datasets. These fields and indexes also describe the relationship between volumes in a multi‑volume chain.

The examples below show the relationship between the relevant fields in the volume records, dataset records, and the index elements that reference these records.

Structure of the Trace FileLink copied to clipboard

The Trace file is used for the following primary purposes:

• to track updates of the Media Database

  This information is used to facilitate recovery of the Media Database when necessary.

• to serve as a queue for requests to be performed by the IOA Functional monitor

The Trace file is automatically maintained by Control‑M/Tape mechanisms that handle the Media Database and the requests to the IOA Functional monitor.

The length of logical records in the Trace file can vary, depending on the type of information in the record.

Logical records in the Trace file are composed of a header (mapped by macro CTTARC) followed by the record data (mapped by the macro relevant for the type of traced action).

The Trace file is processed as a cyclic file. When the file is full new records overwrite the oldest logical records. When the physical end‑of‑file is reached, the next record is written on the first physical record.

Fields in the Trace File

The following table lists some of the more important fields in the Trace file. For a comprehensive list of these fields, see DLogical Field Names for the Control-M/Tape Repository and the IOA MAC library.

Table 231 Fields in the Trace File

Structure of the Stacking DatabaseLink copied to clipboard

The Stacking Database contains statistical information about datasets processed by Control‑M/Tape. This information is gathered from various locations (for example, the Media Database, or the Trace file) by the CTTSTK utility. The information in this file is used by the Dynamic Dataset Stacking facility in the real‑time environment.

The Stacking Database is composed of the following physical files:

Table 232 Stacking Database Files

These files are managed by the IOA Access Method. For more information, see IOA Access Method.

Records in the Data and Index files are mapped by assembler macros CTTSTK and CTTSTX, respectively.

Data File ContentsLink copied to clipboard

The Data file contains statistical information about datasets that have been processed by Control‑M/Tape. A dataset is identified by its name and the name of the job that created the dataset.

All record types in the Data file have a common header at the beginning of the record. This header contains the following information about the record:

Table 233 Header Information in Data File

Each record in the Data file is assigned an RBA that indicates the location of the record in the Data file.

Access to a specific data file record can be performed using its RBA if known, or using the index. Access of a data record using its RBA is known as "non‑keyed access."

Fields in the Data FileLink copied to clipboard

The following table lists some of the more important fields in the Data file. For a comprehensive list of these fields, see the IOA MAC library.

Table 234 Data File Fields

Index File ContentsLink copied to clipboard

The Index file contains index records. These index records enable keyed access to records in the Data file.

Repository MaintenanceLink copied to clipboard

Verifying Data Integrity of Media DatabasesLink copied to clipboard

In the Control‑M/Tape Media Database, data of different types are stored in separate records that are linked using the following mechanisms:

• data fields in data records that reference other data records

  For example, field DDSVOLSR in a dataset record indicates the record of the volume containing the beginning of the dataset.

• index records that link data records (for example, the L-index record)

• counters within data records (for example, field DVLACTD# in a volume record indicates the number of datasets in the volume)

  Media Database integrity is the degree to which the links between data or index records are free of errors. A high level of integrity is necessary to ensure smooth processing by ControlM/Tape. Use the CTTIDB utility to check Media Database logical integrity on a daily basis (for example, as a part of the ControlM/Tape New Day Procedure).

Causes of Media Database Integrity ErrorsLink copied to clipboard

As a rule, normal tape processing by Control‑M/Tape does not cause integrity errors. However, such errors can be caused by external events that interrupt Control‑M/Tape processing, which result, for example, in partially updated records. Some common causes of integrity errors are

• system crash

• cancellation of a job that accesses tapes in the middle of its processing

• interruption of a ControlM/Tape utility that updates records in the Media Database

• processing Control-M/Tape databases or the Trace file by a defragmentation program while Control-M/Tape is running

Examples of Errors Due to Interruption of Control-M/Tape ProcessingLink copied to clipboard

• A volume record points to the next record in a multi-volume chain (using the NEXTVOL field), but that volume does not point back (field PREVVOL).

• A dataset does not span the number of volumes indicated in the record for that dataset.

• An L-index points to a scratch volume.

Integrity errors should not occur often. However, if the CTTIDB utility detects an unusually large number of integrity errors, you should immediately investigate the cause of these errors and fix the problem.

Recovery From Integrity ErrorsLink copied to clipboard

Some integrity errors are automatically resolved by Control‑M/Tape:

L-indexes that point to a scratch volume are removed as soon as the scratch volume is mounted in response to a scratch tape request.

Some utilities (that is, CTTRTM and CTTVTM) have restart capabilities that allow them to continue from the point at which the utility was interrupted.

Integrity errors that are not automatically fixed by Control‑M/Tape must be handled by first studying the nature of the error, and then determining which Media Database updates must be performed to correct the error.

Analyzing an Integrity ErrorLink copied to clipboard

Check the output of the CTTIDB utility every day. If a logical integrity error is detected, you should be able to determine the type of error, and which data or index records are involved, from the output of the utility. Following is a list of the most common logical integrity errors detected using the CTTIDB utility:

• Information in a data record and corresponding information in an index record do not match.

• A counter field in a data record has an incorrect value.

• A group of volumes is chained incorrectly or some volumes in the chain have conflicting attributes (for example, vaulting criteria).

• Data fields linking data records point incorrectly.

• A scratch volume points to, or is pointed to, by an active volume record.

Chose the method used to correct the error based on information in the output of the CTTIDB utility and, optionally, in record data viewed using the Inquire or Update Media Database screen (Screen TI).

Correcting Integrity ErrorsLink copied to clipboard

Logical integrity errors are corrected by updating the data records and/or index records that are in error. For details, see the chapter about verifying media database integrity in the Control‑M/Tape Implementation Guide.

Errors involving data records must be corrected one at a time, using the CTTMUP utility. After fixing each error, it is recommended that you rerun the CTTIDB utility, because fixing one error often eliminates other errors. This can be done automatically by specifying CHECK=YES in the TYPERUN statement of the CTTMUP utility. The output of the CTTIDB utility after it is rerun indicates the integrity errors that remain.

The CTTMUP utility can also be used to fix most index related problems by rebuilding the indexes for a volume, a dataset, or a group of volumes and datasets.

If a large number of index errors are found in the Media Database, consider fixing these errors by rebuilding the index component using the CTTBIX utility.

For a detailed description of the CTTIDB, CTTMUP and CTTBIX utilities, see the INCONTROL for z/OS Utilities Guide.

Manual Update of the Media DatabaseLink copied to clipboard

Manual update of the Media Database is accomplished using the CTTMUP utility. This utility can be used to add new volume or dataset records to the Media Database, or to fix logical integrity errors detected using the CTTIDB utility.

Before using the CTTMUP utility, it is important to understand the structure of the Media Database. For more information, see Media Database Structure. Attempting to fix logical integrity errors without properly understanding the Media Database structure can lead to even more integrity errors.

When updating a volume record, the CTTMUP utility does not always automatically update the corresponding dataset records, and vice versa. When updating data fields that are used to link records, be sure to update all relevant records so that no new logical integrity errors are created. For example, when you add a dataset to a volume, verify that the new number of datasets is recorded in the volume record.

When updating groups of volumes (multivolume chains), use the group statements (prefixed "GRP") to implement the desired change in the records of all the volumes in the group.

After performing the necessary updates, it is highly recommended that you run the CTTIDB utility to verify the results. This can be accomplished by running the utility manually, or by including CHECK=YES in the TYPERUN statement of the CTTMUP utility. For more information about manual update of the Media Database, see the CTTMUP utility in the INCONTROL for z/OS Utilities Guide.

Enlarging the Media DatabaseLink copied to clipboard

Occasionally, it might be necessary to increase the size of the Media Database (MDB). This situation arises if one of the Media Database components (index or data) is almost at maximum capacity, or if extensive additions to the Media Database must be made in the near future.

The user has two options for enlarging the Media Database:

• Reallocate the current extent by increasing the number of blocks or the block size.

• Define a new Media Database extent.

Reallocating the current extentLink copied to clipboard

1. Shut down ControlM/Tape using the operator command

   CopyCopied to clipboard

   SCTTINIT,PARM='MODE=TERM'.

2. Unload the Media Database data component using the IOADUL utility. The output of this utility is loaded to the new and larger Media Database.

3. Rename the production Media DATA and INDEX components. For example, rename the CTT.V900.MDBD.E000 file to CTT.V900.MDBD.E000.OLD. This file is kept as a backup for the Media Database.

4. Using ICE, select Customization. Enter CTT in the Product field, and select Product Customization.

5. Select major step 2, "Customize Control-M/Tape Datasets," and then minor step 1, "Media Database Space Calculation."

6. Calculate the space needed for your Media Database, and update the definitions on the screen. To calculate the amount of space needed, see the ControlM/Tape installation chapter of the INCONTROL for z/OS Installation Guide: Installing.

   The Media Database can be enlarged by increasing the number of blocks, by enlarging the block size, or both.

7. Select minor step 4, "Save parameters into Product Libraries."

8. Select minor step 5, "Create and Init Media Database," and submit the job. This job allocates and formats a new ControlM/Tape Media file.

9. Reload the Media Database data component into the new and larger data component, using the IOADLD utility.

10. Run the CTTBIX utility.

11. Restart ControlM/Tape using the operator command

    CopyCopied to clipboard

    SCTTINIT,PARM='MODE=INIT'.

Defining a new extentLink copied to clipboard

1. Shut down ControlM/Tape using the operator command

   CopyCopied to clipboard

   SCTTINIT,PARM='MODE=TERM'.

2. Create and format a new Media Database data component by running the IOADBF utility with the FUNC parameter set to EXTEND. Use the sample member CTTEMDB in the CTT..JCL library.

3. Restart ControlM/Tape using the operator command

   CopyCopied to clipboard

   SCTTINIT,PARM='MODE=INIT'.

Enlarging the Trace FileLink copied to clipboard

At times, it may be necessary to increase the size of the Control‑M/Tape Trace file. This situation arises if the Trace file often reaches maximum capacity, or if an increase in tape activity at your site is imminent.

To enlarge the Trace file, perform the following steps:

1. Shut down ControlM/Tape using the operator command

   CopyCopied to clipboard

   SCTTINIT,PARM='MODE=TERM'.

2. Back up the active Trace file using the ControlM/Tape CTTACP utility, the IBM IEBGENER utility, or any similar tool.

3. Rename the production Trace file. For example, rename the CTT.V900.TRC file to CTT.V900.TRC.OLD.

4. Using ICE, select Customization. Enter CTT in the Product field, and select Product Customization.

5. Select major step 2, "Customize Control-M/Tape Datasets," and then minor step 3, "Trace File Space Calculation."

6. Calculate the space needed for the new Trace File and update the definitions on the screen. To calculate the space needed, see the planning and space calculation step and the trace file calculation topic in the ControlM/Tape installation chapter of the INCONTROL for z/OS Installation Guide.

   The Trace file can be enlarged either by increasing the number of blocks, by enlarging the block size, or both.

7. Select minor step 4, "Save parameters into Product Libraries."

8. Select minor step 7, "Create and Init Trace File," and submit the job. This job allocates and formats a new Control-M/Tape Trace file.

9. Copy the old Trace file to the new and larger Trace file using the CTTACP utility. Following is an example of CTTACP activation:

   Figure 79 CTTACP Activation Example

   CopyCopied to clipboard

   //name JOB ,IOA,CLASS=A,MSGCLASS=X
   //*
   //*  COPY ONE ControlM/TAPE TRC DATASET TO ANOTHER TRC
   //*
   //TT2ACP EXEC CTTACP,
   //       TRCIN='CTT.V900.TRC.OLD',
   //       TRCOUT='CTT.V900.TRC'
   //SYSIN  DD *
     COPY FROM=TRACE,TO=TRACE
   //

10. Restart ControlM/Tape using the operator command

    CopyCopied to clipboard

     SCTTINIT,PARM='MODE=INIT'.

Enlarging the Stacking DatabaseLink copied to clipboard

At times, it may be necessary to increase the size of the Stacking Database. This situation arises if one of the Stacking Database components (index or data) is almost at maximum capacity, or if extensive additions to the Stacking Database need to be made in the near future.

The user has two options for enlarging the Stacking Database:

• Reallocate the current extent by increasing the number of blocks or the block size.

• Define a new Stacking Database extent.

Reallocating the current extentLink copied to clipboard

1. Shut down ControlM/Tape using the operator command

   CopyCopied to clipboard

   SCTTINIT,PARM='MODE=TERM'

2. Unload the Stacking Database data component using the IOADUL utility. The output of this utility is loaded to the new and larger Stacking Database.

3. Rename the production Stacking DATA and INDEX components. For example, rename the CTT.V900.STKD.E000 file to CTT.V900.STKD.E000.OLD. This file is kept as a backup for the Stacking Database.

4. Using ICE, select Customization. Enter CTT in the Product field, and select Product Customization.

5. Select major step 2, "Customize Control-M/Tape Datasets," and then minor step 2, "Stacking Database Space Calculation."

6. Calculate the space needed for your Stacking Database, and update the definitions on the screen. To calculate the amount of space needed, see the stacking database calculation topic in the ControlM/Tape installation chapter of the INCONTROL for z/OS Installation Guide.

   The Stacking Database can be enlarged by increasing the number of blocks, by enlarging the block size, or both.

7. Select minor step 4, "Save parameters into Product Libraries."

8. Select minor step 6, "Create and Init Stacking Database," and submit the job. This job allocates and formats a new ControlM/Tape Stacking file.

9. Reload the Stacking Database data component into the new and larger data component, using the IOADLD utility.

10. Run the CTTDBIB utility.

11. Restart ControlM/Tape using the operator command

    CopyCopied to clipboard

    SCTTINIT,PARM='MODE=INIT'.

Defining a new extentLink copied to clipboard

1. Shut down ControlM/Tape using the operator command

   CopyCopied to clipboard

   SCTTINIT,PARM='MODE=TERM'.

2. Create and format a new Stacking Database data component by running the IOADBF utility with the FUNC parameter set to EXTEND. Use the sample member CTTEMDB in the CTT..JCL library.

3. Restart Control-M/Tape using the operator command

   CopyCopied to clipboard

   S CTTINIT,PARM='MODE=INIT'.

Repository Backup and RecoveryLink copied to clipboard

Control‑M/Tape has a comprehensive set of utilities that ensure data integrity and provide full recovery in situations caused by system or disk crashes or user error. Two types of recovery are possible: logical and physical. Each type is appropriate in specific situations. Use the following table to determine when to use each recovery method:

Table 235 Comparison of Physical vs. Logical Recovery Methods

The following sections briefly discuss backup procedures, followed by a description of the procedures that the INCONTROL administrator must perform in various situations. For a detailed description of the utilities discussed in the following topics, see the INCONTROL for z/OS Utilities Guide.

Media Database BackupLink copied to clipboard

Control‑M/Tape provides several utilities to facilitate the backup and recovery process. Backups can be performed at any time using batch utilities. At most sites, backups are initiated by the New Day procedure.

Normally, the Media Database is backed up first. It updates the Trace file with the date and time that backup started and completed. The Trace file is backed up as soon as the Media Database backup completes successfully, Therefore, each Media Database backup has a corresponding Trace file backup. All removable media processing can continue during this process.

Media Database RecoveryLink copied to clipboard

If the Media Database or some portion of it must be recovered as follows:

• Restore the latest Media Database backup using the standard site backup utility. Run the CTTRCV utility to apply all updates since that backup from the active Trace file (a RollForward process).

• Based on the current Media Database, the CTTrcv utility can withdraw all updates until a certain point (a Rollback process). It can also remove all updates in a specified time range or generated by a specific job.

• When the restore is complete, the free record chain must be rebuilt by running the IOADIG utility with FUNC=W. All indexes must be rebuilt by running the CTTBIX utility.

Disaster RecoveryLink copied to clipboard

Control‑M/Tape recovery is performed using the most current Trace file and the last Media Database backup in three steps (see the following figure). First, a backup and restore utility (for example, ADDRSSU) is run to restore the Media Database. Then, the CTTrcv utility is run to roll forward all Trace file Updates since the last backup. The IOADIG and CTTBIX utilities are then run to rebuild the file structure and indexes.

Figure 80 Disaster Recovery

Selective RecoveryLink copied to clipboard

This method recovers only a selection of changes that satisfy specified selection criteria. For example, to undo the effects of a bad maintenance job (such as a retention management job that ran with incorrect parameters) all decisions or actions made by this job must be reversed. Only selected portions of the Media Database are recovered. This is a logical, backward recovery using the CTTRCV, IOADIG, and CTTBIX utilities.

Displaying Media Database Information on an OS/390 or z/OS ConsoleLink copied to clipboard

Information obtained from the Media Database volume and dataset records can be displayed on an OS/390 or 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 console is often more readily available than a TSO/E session. For more information on the Inquiry and Update facility, see the online facilities chapter in the Control‑M/Tape User Guide.

Defining ViewsLink copied to clipboard

Media Database information is displayed on an OS/390 or z/OS console in a format called a "view," using one of three display commands. For more information on the display commands, see the Control‑M/Tape User Guide. The types of views displayed are similar to the display types available through the Inquiry and Update facility. The view definitions reside in member VIEWSDEF in the Control‑M/Tape PARM library.

There is a default view for each of the three Media Database display commands. For more information, see Setting Default Views. The INCONTROL administrator can modify these default views, as well as define and modify optional views. A default view member is provided upon installation of Control‑M/Tape.

The syntax for view definition is as follows:

viewtype fieldname, fieldname, …, NAME=viewname

where

• viewtype is the type of view being defined (for example,a dataset view must display dataset-related fields, and a volume view must display volume-related fields). Valid values are

  • VOLVIEW: The view displays volume-related and volume group-related fields.

  • DSVIEW: The view displays dataset-related fields.

• fieldname is any field that must be displayed in the view. Any number of field names can be specified, separated by commas. For a list of ControlM/Tape Media Database field names, see D Logical Field Names for the Control-M/Tape Repository.

• viewname is a user-defined name assigned to the view.

VOLVIEW VOLSER,VOLFLAGS,VAULTS,NAME=
VVOLVIEW VOLSER,VOLSTAT,NAME=S
VOLVIEW VOLSEQ,NEXTVOL,FIRSTVOL,PREVVOL,NAME=G
DSVIEW  DSNAME,DSVOLSER,VOLSNUM,NAME=D

Setting Default ViewsLink copied to clipboard

To set the default views for each view type, add the following parameters in the View section of member CTTPARM in the IOA PARM library:

Table 236 Parameters for Setting Default Views

Loading ViewsLink copied to clipboard

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, which can be used as provided, or modified as needed.

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 the above command has been issued.

Control-M/Restart Support for Control-M/TapeLink copied to clipboard

The CTRX001 exit (Control‑M/Restart Exit 1) is used by Control-R to release tapes which were used by the previous run of the job before the job is restarted.

The exit recognizes the appropriate Control-M/Tape it is working with to support the C-1 concept. The exit interfaces with Control-M/Tape using CTTAPI.

CTRX001 checks the compatibility mode values in IOAPARM for Control‑M/Tape and Control-M/Restart and sets the SSNAME parameter in the CTTAPI call accordingly to one of the following:

• If MODECTR=MODECTT then SSNAME=blank.

• If MODECTR<MODECTT then SSNAME=ABOV.

• If MODECTR>MODECTT then SSNAME=BELW.

CTRX001 (Control‑M/Restart Exit 1) must be defined as an interface between Control‑M/Restart and Control‑M/Tape. This exit must be defined in addition to (not as a replacement for) any previously defined Control‑M/Restart Exit 1 (for example, an interface between Control‑M/Restart and another product such as HSM or CA‑1).

The Control‑M/Restart Driver exit is used to invoke the Control‑M/Tape Interface Exit 1 and any previously defined instances of Exit 1.

When Control-M/Restart Exit 1 is used for the Control-M/Tape interface, it receives dataset DELETE requests and changes the Control-M/Tape controlled dataset status to Scratch. This enables expiration of the specified dataset by the next run of Retention Management the CTTRTM utility. Using customization of this exit, you can cause Control-M/Tape controlled datasets to be scratched immediately (that is, without running the CTTRTM utility).

Control-M/Restart Driver Exit CTRX001GLink copied to clipboard

The Control‑M/Restart Driver exit optionally invokes multiple user exits that provide programming interfaces to various dataset management software packages (for example, HSM or Control‑M/Tape). The Control‑M/Restart Driver exit sequentially invokes all user exits listed in its source text. Any number of single purpose Control‑M/Restart user exits can be listed. For more information, see Exits.

Installing the Control-M/Restart InterfaceLink copied to clipboard

Perform the following steps to install the Control‑M/Restart to Control‑M/Tape interface:

1. Verify that YES is specified for ControlM/Restart installation parameter TAPEMS in member CTRPARM in the IOA PARM library.

2. To compile and link ControlM/Restart Roof Exit CTRX001G and existing ControlM/Restart Exit CTRX001T, use the ICE Automatic Exit Installation tool. For details, see Exits.

3. The ICE Automatic Exit Installation Tool Builds Job UMRX001G in the CUSTEXIT library. Using the Automatic Exit Installation tool, run the job.

For more information about the logic implemented by this exit, see the exit source.

Control-M/Tape Application Programming InterfaceLink copied to clipboard

The Control‑M/Tape Application Programming Interface provides an interface between Control‑M/Tape and user application programs. Control‑M/Tape API requests are performed using Assemb

Control-M/Tape APILink copied to clipboard

The purpose of the Control-M/Tape API is to provide external products an access to the Control-M/Tape Media database. The API provides query commands to obtain information from the Media database, as well as logical updates commands such as scratch a volume or extend a volume.

When the API interface is invoked, it returns information about volumes and their datasets, as they are in the Control-M/Tape Media database. The output of the API is in a fixed format, and the information may contain both data set and volume information.

OperationsLink copied to clipboard

The Control-M/Tape API has the following commands:

1. Initialize the API environment.

2. Close the API environment.

3. Start query for all volumes in the Media database.

4. Get the next record, which found by the last query command.

5. Change a volume or a data-set into scratch.

6. Change the expiration of volume or data set.

Invoking the Control-M/Tape APILink copied to clipboard

The access to the Control-M/Tape API is performed using the CTTAPI macro. The format of the CTTAPI is:

Label     CTTAPI    function-code,
                    RC=rc
                    REASON=reason,
                    URC=utility-rc,
                    REPLY=output-block-addr,
                    REALENV=Y/N,
                    SCRATCH=Y/N,
                    OPTIONS=options,
                    OPENUPD=Y/N,
                    PATH=path,
                    WHERE=where,
                    TRACELVL=trc-level,
                    MF=E/L
                    SSNAME=blank/<ssname>/ABOV/BELW

Table 237 CTTAPI Macro Parameters

DSNSCR - {DEFERRED|IMMEDIATE}

DSNACT - RETENTION={EDM|<number of days>}

Table 238 CTTAPI Function Values

Table 239 CTTAPI Path Values

Return Codes

One of the following return codes is returned to the user in general register 15:

Table 240 CTTAPI Return Codes

Reason Codes

The list of the reason codes, their related return codes, and the source of the ABEND are listed below:

Table 241 CTTAPI Reason Codes

Output Record FormatLink copied to clipboard

The output record from the QUERY command is in a fixed format, regardless of the version of Control-M/Tape. The output record holds both data set and volume information. DSECT CTTOAPI maps the output record.

Sample UsageLink copied to clipboard

**********************************************************************  00000100
*                                                                    *  00000200
*                                                                    *  00000300
*                            CTTAPIEX                                *  00000400
*                                                                    *  00000500
*                                                                    *  00000600
*   FUNCTION: SAMPLE PROGRAM TO DEMONSTRATE ACCESS TO THE Control-T  *  00000700
*             MEDIA DATA BASE (MDB) USING THE CTT API.               *  00000800
*                                                                    *  00000900
*   OUTPUT:   THE SAMPLE PRODUCES A REPORT OF ALL THE ACTIVE VOLUMES *  00001000
*             AND ITS DATASETS. THE DATASETS ORDER IN THE REPORT IS  *  00001100
*             ACCORDING TO THE DATASETS LABEL IN THE CHAIN.          *  00001200
*                                                                    *  00001300
*   LOGIC:    AT FIRST, THE PROGRAM STARTS THE API. THEN IT PERFORMS *  00001400
*             QUERY ON THE DATABASE AND RECEIVES THE FIRST RECORD.   *  00001500
*             AFTERWARD IT PERFORMS QUERYNXT FOR EACH RECORD UNTIL   *  00001600
*             IT RECEIVES RC=4. AT THE END, THE PROGRAM CLOSES THE   *  00001700
*             API.                                                   *  00001800
*                                                                    *  00001900
*   TO COMPILE, LINK AND RUN THE PROGRAM:                            *  00002000
*                                                                    *  00002100
*   //CTTAPIEX JOB ...                                               *  00002200
*   //ASM     EXEC CTTASM                                            *  00002500
*   //C.SYSIN   DD DISP=SHR,DSN=IOA.SAMPLE(CTTAPIEX)<<<----- CHANGE  *  00002600
*   //L.AIOALOAD DD  DISP=SHR,DSN=IOA.AIOALOAD      <<<----- CHANGE  *  00002700
*   //L.SYSLMOD  DD  DISP=SHR,DSN=YOUR.LOAD.LIBRARY <<<----- CHANGE  *  00002800
*   //L.SYSIN   DD *                                                 *  00002900
*     MODE RMODE(24),AMODE(31)                                       *  00003000
*     ENTRY CTTAPIEX                                                 *  00003100
*     NAME CTTAPIEX(R)                                               *  00003200
*   //*                                                              *  00003300
*   //RUN EXEC PGM=CTTAPIEX,COND=(0,NE),REGION=60M                   *  00003400
*   //STEPLIB  DD DISP=SHR,DSN=YOUR.LOAD.LIBRARY    <<<----- CHANGE  *  00003500
*   //         DD DISP=SHR,DSN=IOA.LOAD             <<<----- CHANGE  *  00003600
*   //DAALOCIN DD DISP=SHR,DSN=IOA.PARM(ALCCTT)     <<<----- CHANGE  *  00003700
*   //DARPTOUT DD SYSOUT=*                                           *  00004200
*   //                                                               *  00004400
*                                                                    *  00004500
**********************************************************************  00004600
*------------------------V.9.0.00------------------------------------*  00004700
* WT0761 18.08.02 CTT API                                        -YM-*  00004800
**********************************************************************  00004900
         MACRO                                                          00005000
&NAME    MYPUT &DCB,&REC                                                00005100
&NAME    LA    R15,*+6               ADDRESS FOLLOWING BASSM            00005200
         BASSM R14,R15               CHANGE AMODE                       00005300
         PUT   &DCB,&REC             PUT THE DESIRED RECORD             00005400
         LA    R15,*+10              ENDING ADDRESS                     00005500
         O     R15,=X'80000000'                                         00005600
         BSM   0,R15                                                    00005700
         MEND                                                           00005800
         CTTIAPI               INPUT DSECT PARAMETERS                   00005900
         CTTOAPI               OUTPUT DSECT PARAMETERS                  00006000
CTTAPIEX CSECT                                                          00006100
CTTAPIEX AMODE 31                                                       00006200
CTTAPIEX RMODE 24                                                       00006300
         BEGIN EQUR=YES                                                 00006400
         OPEN  (RPTOUT,OUTPUT)     OPEN VOLUME REPORT OUTPUT FILE       00006600
         LTR   R15,R15             SUCCESSFUL ?                         00006700
         BNZ   OUTERROR            NO - TERMINATE                       00006800
         MYPUT RPTOUT,HEADER1      PRINT REPORT HEADER                  00006900
         MYPUT RPTOUT,HEADER2      PRINT REPORT HEADER                  00007000
*                                                                       00007100
* START THE API ENVIRONMENT.                                            00007200
* THE RELEVANT PARAMETERS FOR START ARE AS THE FOLLOWING:               00007300
* 1) FUNCTION START                                                     00007400
* 2) RC WHICH IS ALSO PROVIDED IN R15                                   00007500
* 3) REASON                                                             00007600
* 4) UTILITY RC WHICH CONTAINS THE RC THAT RETURNED FROM THE            00007700
*    THE CALLED PROGRAM.                                                00007800
* 5) REALENV=(Y/N) - SPECIFY IF API WILL USE THE Control-T              00007900
*    REAL ENVIRONMENT INSTEAD OF OPENING THE MEDIA DATABASE FILES.      00008000
*    DEFAULT: N - ALLOCATE AND OPEN THE MEDIA DATABASE FILES.           00008100
*                                                                       00009400
         CTTAPI START,RC=RC,REASON=REASON,MF=(E,APILIST)                00009500
         LTR   R15,R15        WAS START SUCCESSFUL?                     00009700
         BZ    DOQUERY                                                  00009800
         B     RETURN                                                   00009900
*                                                                       00010000
* PERFORM QUERY REQUEST.                                                00010100
* THE RELEVANT PARAMETERS ARE AS THE FOLLOWING:                         00010200
* 1) FUNCTION=QUERY                                                     00010300
* 2) RC IF REQUIRED. IT IS ALSO RETURN IN R15.                          00010400
* 3) REASON                                                             00010500
* 4) URC - UTILITY RC FROM CALLED PROGRAM.                              00010600
* 5) REPLY - REPLY BUFFER ADDRESS IN CTTOAPI FORMAT.                    00010700
* 6) PATH  - SPECIFIES THE TYPE OF RECORDS TO BE EXTRACTED.             00010800
*            VALID VALUES:                                              00010900
*            VOL - VOLUME RECORDS ARE EXTRACTED                         00011100
*            VOL/FDS - VOLUME RECORDS WITH ONLY THEIR                   00011200
*            FIRST DATASET RECORDS ARE EXTRACTED.                       00011300
*            VOL/ADS - VOLUME RECORDS WITH ALL THEIR                    00011400
*            DATASET RECORDS ARE EXTRACTED. DEFAULT.                    00011500
*            DS - DATASET RECORDS ARE EXTRACTED.                        00011600
*            DS/FVOL - DATASET RECORDS WITH ONLY THEIR                  00011700
*            FIRST VOLUME RECORD ARE EXTRACTED.                         00011800
*            DS/AVOL - DATASET RECORDS WITH ALL THEIR                   00011900
*            VOLUME RECORDS ARE EXTRACTED.                              00012000
* 7) WHERE - SPECIFY INCLUDE AND EXCLUDE STATEMENTS LIKE IN OTHERS      00012100
*            Control-T UTILITIES.                                       00012200
*                                                                       00012300
DOQUERY  EQU   *                                                        00012400
         CTTAPI QUERY,REPLY=BUFREP,RC=RC,REASON=REASON,URC=URC,        *00012500
               PATH=PATH,WHERE=WHERE,MF=(E,APILIST)                     00012600
         LTR   R15,R15                                                  00012700
         BZ    LOOPNEXT                                                 00012800
         B     RETURN                                                   00012900
*                                                                       00013000
* PERFORM QUERYNXT - GET THE NEXT RECORD                                00013100
* THE RELEVANT PARAMETERS FOR THE QUERYNXT ARE AS THE FOLLOWING:        00013200
* 1) FUNCTION QUERYNXT                                                  00013300
* 2) REPLY = REPLY BUFFER ADDRESS FORMATTED AS CTTOAPI                  00013400
* 3) RC                                                                 00013500
* 4) REASON                                                             00013600
* 5) URC                                                                00013700
*                                                                       00013800
LOOPNEXT EQU   *                                                        00013900
         L     R8,BUFREP          GET BUFFER ADDRESS                    00014000
         USING CTTO,R8                                                  00014100
         MVC   PRINTREC(L'CTTVOLSR),CTTVOLSR                            00014200
         MVC   PRINTREC+8(L'CTTDDSN),CTTDDSN                            00014300
         MYPUT RPTOUT,PRINTREC                                          00014400
*                                                                       00014500
         CTTAPI QUERYNXT,REPLY=BUFREP,RC=RC,REASON=REASON,URC=URC,     *00014600
               MF=(E,APILIST)                                           00014700
         LTR   R15,R15                                                  00014800
         BZ    LOOPNEXT                                                 00014900
         C     R15,=F'4'          DID WE FINISH QUERY?                  00015000
         BE    GOEND                                                    00015100
         B     RETURN                                                   00015200
*                                                                       00015300
* PERFORM END - DELETE THE API ENVIRONMENT.                             00015400
* THE RELEVANT PARAMETERS FOR THE END ARE AS THE FOLLOWING:             00015500
* 1) FUNCTION END                                                       00015600
* 2) RC                                                                 00015700
* 3) REASON                                                             00015800
* 4) URC - UTILITY RC                                                   00015900
*                                                                       00016000
GOEND    EQU   *                                                        00016100
         CTTAPI END,REASON=REASON,MF=(E,APILIST)                        00016200
         CLOSE (RPTOUT)                                                 00016300
         B     RETURN                                                   00017000
OUTERROR WTO   'UNABLE TO OPEN OUTPUT FILE'                             00018000
         LA    R15,8                                                    00018100
RETURN   EQU   *                                                        00020000
         BRTRN (15)                                                     00039200
APILIST  CTTAPI MF=L                                                    00039300
BUFREP   DC    A(0)                                                     00039400
RC       DS    H                                                        00039600
REASON   DS    H                                                        00039800
URC      DS    H                                                        00039900
TRCLVL   DC    X'10'                                                    00040000
RPLBUF   DS    (CTTOLEN)X                                               00040100
PATH     DC    CL8'VOL/ADS'                                             00040200
WHERE    DC    H'1'                                                     00040300
         DC    CL80'INCLUDE VOLSTAT=ACTIVE'                             00040400
HEADER1  DC    CL80'VOLUME  DATASET'                                    00040500
HEADER2  DC    CL80'-------------------------------------------------'  00040600
PRINTREC DC    CL80' '                                                  00040700
***                                                                     00040800
* DATA Control BLOCKS                                                   00040900
***                                                                     00041000
RPTOUT   DCB   DDNAME=DARPTOUT,MACRF=PM,LRECL=80,RECFM=FB,             *00041100
               DSORG=PS                                                 00042000
         END                                                            00110000

Legacy APIsLink copied to clipboard

Background InformationLink copied to clipboard

Users must become familiar with the following background information before using the Control‑M/Tape Application Programming Interface.

Control-M/Tape Control Table (TCT)

Control‑M/Tape stores certain basic information (for example, the values specified for Control‑M/Tape installation parameters) in a control block called the Control‑M/Tape Control Table (TCT). User-written APIs require access to the TCT in order to determine certain aspects of the Control‑M/Tape environment.

The TCT is mapped by macro CTTTCT.

The following table describes two types of TCTs that are used by Control‑M/Tape APIs:

Table 242 Types of TCTs Used by Control-M/Tape APIs

Creating a Local TCT

A local TCT must be created for each program that uses the Base-Level API. This task is performed using routine CTTTLD that is called from a user-written program.

Use the following call to invoke routine CTTTLD:

CALL    CTTTLD,(func-addr, tct-addr, 0, 0)

where

• func-addr is the address of an 8character field that describes the function to be performed by routine CTTTLD. Valid values are

  • LOADENV: Create a local TCT.

  • DELETE: Release the storage area used by the LOAD function call. Routine CTTTLD must be called with this function after the userwritten program has finished using the base level API.

• tct-addr is the address of a fullword field in which the routine inserts the address of the newly created local TCT.

Return Codes

Routine CTTTLD returns one of the following return codes in general register 15:

Table 243 Return Codes for Routine CTTTLD

Sample TCT Load Request

The following sample demonstrates a load request call to routine CTTTLD that creates a copy of the local TCT:

Figure 81 Sample TCT Load Request

CALL     CTTTLD,(LOADENV,TCTADDR,0,0) Load the TCT
LTR      R15,R15                      Successful ?
BNZ      TCTFAIL                      No - Terminate
L        R12,TCTADDR
USING    TCT,R12
.
.
TCTFAIL   WTO     ‘TCT LOAD FAILED, PROGRAM TERMINATED’
.
LOADENV   DC      CL8’LOADENV’        Constant for CTTTLD
TCTADDR   DS      A                   Address of TCT
                   .
TCT       DSECT
          COPY    CTTTCT              TCT mapping

Obtaining the Address of the Real-Time TCT

Each invocation of a Rule Search API must include the address of the Real-Time TCT. The address of the Real-Time TCT is obtained using macro CTTGTCT.

Use the following call statement to invoke macro CTTGTCT:

CTTGTCT    TCTADDR=tctaddr,TEST=ACT

where

• tct-addr is the address of a fullword field to contain the address of the Real-Time TCT that is returned by macro CTTGTCT. Optional. If no value is specified for this parameter, the address of the Real-Time TCT is returned in general register 1.

• TEST is an explicit request to check if ControlM/Tape is active. A value of ACT must be specified for this parameter.

Macro CTTGTCT alters the values in general registers 0, 1, and 15. If programs at your site depend on the integrity of values in these registers, it is recommended that you save their values before running macro CTTGTCT and restore them after the macro is completed.

Return Codes

The CTTGTCT macro returns one of the following return codes in general register 15:

Table 244 Return Codes for Macro CTTGTCT

Sample TCT Address Request

The following sample demonstrates how macro CTTGTCT is called to obtain the address of the Real‑Time TCT:

Figure 82 Sample TCT Address Request

          CTTGTCT TCTADDR=ACTVTCT,TEST=ACT          
LTR     R15,R15                                Active TCT obtained ?    
          BNZ     TCTFAIL                                No - Terminate
          L       R12,ACTVTCT
          USING   TCT,R12
 .
          .
TCTFAIL   WTO     ‘TCT NOT FOUND OR NOT ACTIVE, PROGRAM TERMINATED’
          .
          .
          COPY    CTTSSVT                                   | For use by
CVT       CVT     DSECT=YES,PREFIX=YES                      | Macro
          IEFJSCVT                                          | CTTGTCT
          IEFJESCT                                          |
ACTVTCT   DS      A                                         Address of TCT
          .
TCT       DSECT
          COPY    CTTTCT                                    TCT mapping

Control-M/Tape Media Database

The API consists of Assembler macros that facilitate interaction with the Control‑M/Tape Media Database. Therefore, familiarity with the Media Database format is a prerequisite for using the API. For a detailed description of the Media Database see Media Database Structure.

Base Level versus High Level APILink copied to clipboard

A calling program can interface with Control‑M/Tape using either the base level or high level API (Application Programming Interface). The base level API offers versatility with few fixed requirements. The high level API provides more automation but requires an active Control‑M/Tape real-time environment and APF authorization. the following table details the differences between these two types of API access methods.

Table 245 API Access Method Functions

Base Level APILink copied to clipboard

When accessing the Media Database, the base level API can perform the following functions:

Table 246 Base Level API Functions

Record Access by the Base Level API

Records in the database can be accessed by non‑keyed or keyed methods.

• To perform nonkeyed access of database records, the full RBA must be specified.

• To perform keyed access of database records, the value specified depends on the function performed.

  • To perform a READNEXT operation, the entire index record must be specified.

  • To perform a READ operation, it is sufficient to use a partial key. Of course, the full key or even the full index record can be used.

Both READ and READNEXT requests return the full index record to the area pointed to by the KEY parameter.

A READ request is usually used for accessing a specific record. Since a READ request can use a partial key as input, it is also useful when you have only partial data available (for example, a volser without a label number when using the L‑type index).

A READNEXT request is usually used for accessing a series of records. Since, however, a READNEXT request requires specification of a full index value (whereas a READ request can use a partial key as an input value), a sequence of READNEXT requests must be preceded by a READ request.

Macro CTTIOS

Control‑M/Tape APIs use macro CTTIOS to access the Media Database. However, before the base level API can use macro CTTIOS, the Control‑M/Tape Control Table (TCT) must be loaded.

Instructions for loading the TCT are included in the examples for base level API. For more information, see Examples of Macro Access and Base Level API Functions.

Format

Instructions for macro CTTIOS are formatted as follows:

Figure 83 Formats for Macro CTTIOS Instructions

Label    CTTIOS   request‑type,
                  function‑code,
                  RC=reason‑code‑field,
                  [ENV=envir‑id,]
                  [TCT=tst‑address,]
                  [REC=buffer‑address,]
                  [RBA=field,]
                  [DATA=Y/N,]
                  [KEY=key‑field,]
                  [KEYTYPE=key‑type,]
                  [KEYLEN=key‑length,]
                  [MF={L,(E,list-address)}]

Parameters

Table 247 Base Level API Parameters

The CTTIOS macro must be coded in accordance with all standard macro Assembler coding restrictions.

The values in general purpose registers 0, 1, 15 are modified by macro CTTIOS.

The CTTIOS macro accesses a set of variables generated by the CTTDBTP macro. Therefore, the CTTDBTP macro must be included in the source code of the calling program.

Return Codes

The CTTIOS macro returns a return code in general purpose register 15. Do not confuse this code with the reason code returned in parameter RC described in the above table.

Table 248 Return Codes for Macro CTTI

For more information about the return codes and reason codes of the CTTIOS macro, see the CTT200S message in the INCONTROL for z/OS Messages Manual.

Base Level API Access of the Media Database

For sample macro code and exaith a CLOSE request. The CLOSE request automatically closes all the files and performs all other required activities.

Reading Files

As mentioned earlier, Media Database READ requests can be made using either READ and READNEXT function codes. The differences between these requests must be understood if they are to be used effectively. The following topics describe these function codes and the various key-related and RBA-related parameters used with them.

READ Requests

The READ request is used to read a specific data record from the Media Database. The READ request locates the requested data record and retrieves it into the area specified by parameter REC.

Either a keyed or non‑keyed (that is, RBA) access method can be used to specify the record to be read.

When using keyed access to perform a READ from the Media Database, either a full or partial key can be specified. The READ request returns the whole index record (of the data record being read) into the area specified by the KEY parameter. Therefore, even when using a partial key, the KEY parameter must specify an area large enough to contain the whole index record (not just the partial key).

If the requested record is not found, either because there is no record at the specified RBA or because no record exists with the specified full or partial key, the CTTIOS macro returns a return code of 4.

Using the READ request in conjunction with partial keys is useful for reading from the Media Database when you have partial data only.

For example, assume you know a volser and want to find the name of the first dataset on the volser, but you do not know the label number for this dataset (for example, the first label may belong to a file that is already expired). In this case, you can use partial keys as follows:

• Select request type VOL, specify KEYTYPE=L, and set the VOLSER field in the Ltype index to the known volser.

• Instead of specifying the label number, read using a KEYLEN parameter equal to the length of the volser number (without the label number).

The CTTIOS macro then retrieves the first record that matches the volser number, which is the dataset record of the first label number that exists for this volser. The area specified by the key field is updated with the full‑key value of the retrieved record.

READNEXT Requests

The READNEXT request is used to read the next data records from the Media Database. A READNEXT request can be used with either an RBA or a full index record. READNEXT finds and reads the record (matching the request type specified in the CTTIOS macro) that follows the specified RBA or index (that is, the next record), and then updates the KEY field or RBA field with the corresponding value of the record being read.

Because READNEXT requests require specification of an RBA value or a full index record, and because READ requests always store the RBA value or the full index record of the record read, a READ request must always precede a READNEXT request or set of READNEXT requests. The READ request can be specified with either the RBA or KEY parameters and partial keys can be used. The READNEXT request must then be specified without explicitly modifying the value in the KEY or RBA fields, and without specifying the KEYLEN parameter.

Because both READ and READNEXT update the key or RBA value with each invocation, it is possible to follow the READ request with more than one READNEXT request. Each READNEXT request, in its turn, reads the next record and updates the index record (pointed to by the KEY parameter) or the RBA (pointed to by the RBA parameter) to the value corresponding to the record being read.

The READNEXT function is generally used for reading a series of records in the Media Database, such as all records matching a prefix, or all records until the end‑of‑file.

For example, to read all records that match a dataset name prefix, first specify a READ with the partial key (the dataset prefix) followed by one or more READNEXT requests. The first record matching the dataset prefix is read (if one exists), and the READNEXT requests read all subsequent records (datasets) following the first match. If no matching record exists, CTTIOS positions the program for subsequent READNEXT requests according to ordinary key sorting rules.

Sequential Reading of the Entire Media Database—Keyed vs. Non‑Keyed Access

The entire Media Database can be read either by using indexes (for example, reading all volsers by using the V‑type index) or by using RBAs to read through the entire Media Database. Every program that requires sequential access to the entire Media Database must select the appropriate access method. When selecting the access method, consider the following points:

• When reading the Media Database using RBAs, one I/O operation is performed for each block (one block contains a number of records). Thus, the number of I/O operations required for reading the entire Media Database is relatively small. When reading the Media Database sequentially using indexes, each record access results in one access to the index, and one access to the data. This may result in a high I/O count and unsatisfactory performance for the program.

• When reading the Media Database using indexes, records are read in ascending sort order. When reading the Media Database using RBAs, records are read in the order they appear in the data file (not necessarily sorted).

It is much faster to read the Media Database using RBAs instead of indexes. If data items from the Media Database do not have to be sorted, it is highly recommended to use RBA‑based reading of the Media Database.

Even if the data items retrieved from the Media Database must be sorted, it may be more efficient (depending on the environment) to read the Media Database using RBAs, and sort it after you have read it. You can also use sort utilities to merg

Examples of Macro Access and Base Level API Functions

The following topics present several examples of how to perform the various functions described in this chapter. Do not use these examples without appropriate modification. Most of the examples provided do not check the return code from macro CTTIOS. Some examples refer to Assembler symbols that are not included in the example.

Loading the TCT into Storage

The TCT (Control‑M/Tape Control Table) is not a load module and therefore cannot be loaded using the LOAD macro. To load the TCT, use the CTTTLD macro. The example below shows a sample program that uses the CTTTLD macro to load the TCT.

Code Sample for TCT Load Request

             CALL   CTTTLD,(LOADENV,TCTADDR,0,0)   LOAD THE TCT
             LTR    R15,R15                        SUCCESSFUL?
             BNZ    TCTFAIL                        NO - TERMINATE
             .
             .
    TCTFAIL  WTO    'TCT LOAD FAILED, PROGRAM TERMINATED'
             ABEND  8,DUMP ABEND PROGRAM WITH U0008
             .
             .
    LOADENV  DC     CL8'LOADENV'                CONSTANT FOR CTTTLD
    TCTADDR  DS     A                              ADDRESS OF TCT

Code sample for Media Database OPEN Request

            CALL   CTTTLD,(LOADENV,TCTADDR,0,0)   Load the TCT             .
             .
             L      R12,TCTADDR
    OPENMDB  CTTIOS ANY,OPEN,ENV=$ENV,TCT=(R12),               Open the MDB  *
                    RC=RESCODE,MF=(E,IOSLIST)
             .
             .
    IOSLIST  CTTIOS MF=L
    $ENV     DC     CL4'USER'                     Environment specification
    TCTADDR  DS     A                             Address of TCT
    RESCODE  DS     F
    LOADENV  DC     CL8'LOADENV'               Constant for CTTTLD

Code sample for CLOSE Request

    CLOSEMDB        CTTIOS ANY,CLOSE,MF=(E,IOSLIST)
                    .
                    .
    IOSLIST         CTTIOS MF=L

Keyed Reading From the Media Database

Control‑M/Tape base level API provides keyed access to data residing in the Media Database. Keyed access is achieved using the indexes, as explained above.

The example below shows samples for keyed access requests from the Media Database.

Code sample for "Read by Volser" Request

             L      R2,=A(VOLKEY)               Volume key field
             USING  DVX,R2
             XC     VOLKEY,VOLKEY
             MVC    DVXVOLSR,=C'123456'         Prepare vol. key
             LA     R15,=A(L'DVXVOLSR)          Length of volser
    READVOL  CTTIOS VOL,READ,KEY=VOLKEY,RC=RESCODE,REC=VOLREC,  Read from MDB *
                    KEYLEN=(R15),MF=(E,IOSLIST)
             LTR    R15,R15                     Was read OK?
             BNZ    NOTFOUND                    No - treat accordingly
             .
             .
    VOLKEY   DS     XL(DVXLEN)                  Vol. index key
    VOLREC   DS     XL(DVLLEN)                  Vol. record buffer
    RESCODE  DS     F                           CTTIOS reason code
    IOSLIST  CTTIOS MF=L                        CTTIOS list form
             .
             .
    * Control‑M/TAPE MAPPING MACROS
             CTTDVL                             Vol. data record
             CTTDVX                             Vol. index record
             CTTDBTP                            CTTIOS parameters block

Sample "Read by Dataset Name" Request

Since D‑type indexes are non‑unique (that is, more than one dataset can have the same name), the sample shown below reads only the record of the first dataset in the Media Database with the specified name.

Code sample for "Read by Dataset Name" Request

             LA     R2,DSNKEY                   D.S. key field
             USING  DDX,R2
             XC     DSNKEY,DSNKEY
             MVC    DDXDSN,=CL44'CTT.SAMPLE.FILE'    Prepare D.S. key
             LA     R15,=A(L'DDXDSN)
             CTTIOS DS,READ,KEY=DSNKEY,REC=DSNREC,   Read from MDB        *
                    KEYLEN=(R15),ENQ=Y,MF=(E,IOSLIST)
             LTR    R15,R15                     Was read OK?
             BNZ    NOTFOUND                    No - treat accordingly
             .
             .
    DSNKEY   DS     XL(DDXLEN)                  D.S. index key
    DSNREC   DS     XL(DDSLEN)                  D.S. record buffer
    RESCODE  DS     F                           CTTIOS reason code
    IOSLIST  CTTIOS MF=L                        CTTIOS list form
             .
             .
    * Control‑M/TAPE MAPPING MACROS
             CTTDDS                             D.S. data record
             CTTDDX                             D.S. index record
             CTTDBTP                            CTTIOS parameters block

Code sample for "Read by Volser and File Sequence Number" Request

             LA     R2,DLSKEY                   D.S. key field
             USING  DLX,R2
             XC     DLSKEY,DLSKEY
             MVC    DLXVOLSR,=C'123456'         Copy volser
             LA     R3,1                        First D.S. on volser
             STCM   R3,B'0011',DLXLBLNM         Store label number
             LA     R15,=A(L'DLXVOLSR+L'DLXLBLNM)
             CTTIOS DS,READ,KEY=DLSKEY,KEYLEN=(R15),KEYTYPE=L,  Read from MDB   *
                    REC=DSNREC,MF=(E,IOSLIST)
             LTR    R15,R15                     Was read OK?
             BNZ    NOTFOUND                    No - treat accordingly
             .
             .
    DLSKEY   DS     XL(DLXLEN)                  D.S. L‑type key
    DSNREC   DS     XL(DDSLEN)                  D.S. record buffer
    RESCODE  DS     F                           CTTIOS reason code
    IOSLIST  CTTIOS MF=L                        CTTIOS list form
             .
             .
    * Control‑M/TAPE MAPPING MACROS
             CTTDDS                             D.S.data record
             CTTDLX                             D.S.L-type index
             CTTDBTP                            CTTIOS parameters block

Code sample for "Read All Datasets With Specified Prefix Using READNEXT" Request

          LA     R2,DSNKEY                   D.S. key field
         USING  DDX,R2
         L      R3,=A(DSNREC)               Record addressability
         USING  DDS,R3
         XC     DSNKEY,DSNKEY               Clear index
         MVC    DDXDSN(L'DSPRFX),DSPRFX     Dataset's prefix
         LA     R15,=A(L'DSPRFX)            Length of prefix
         CTTIOS DS,READ,KEY=DSNKEY,REC=DSNREC,  Read from MDB            *
                KEYLEN=(R15),MF=(E,IOSLIST)
         .
         .
READNEXT CTTIOS DS,READNEXT,KEY=DSNKEY,     Read next dataset from MDB   *
                REC=DSNREC,MF=(E,IOSLIST)
         LTR   R15,R15                      Successful ?
         BNZ   NOMORE                       No - skip further READNEXTs
         CLC   DDSDSN(L'DSPRFX),DSPRFX      Is it still the same prefix
         BE    READNEXT                     Yes - loop again
NOMORE   EQU                                                              *
         .
         .
DSPRFX   DC    CL15'DATASET.PREFIX.'        Dataset's prefix
DSNKEY   DS    XL(DDXLEN)                   D.S. index key
DSNREC   DS    XL(DDSLEN)                   D.S. record buffer
RESCODE  DS    F                            CTTIOS reason code
IOSLIST  CTTIOS MF=L                        CTTIOS list form
         .
         .
* Control‑M/TAPE MAPPING MACROS
         CTTDDS                             D.S. data record
         CTTDDX                             D.S.index record
         CTTDBTP                            CTTIOS parameters block

Non‑Keyed (RBA‑Based) Reading of the Media Database

Control‑M/Tape Base Level API also provides non‑keyed access to data residing in the Media Database. Non‑keyed access is achieved by using the RBA as the pointer to the desired record in the data file, as explained above.

The example below shows a few sample RBA‑based access requests from the Media Database.

Code sample for "Read a Record" Request

             MVC    RECRBA,=X'000203'           Set the RBA to block 2, record 3
             CTTIOS ANY,READ,RC=RESCODE,REC=AREA,RBA=RECRBA,  Read from MDB    *
                    MF=(E,IOSLIST)
             LTR    R15,R15                     Does record exists ?
             BNZ    NOTFOUND                    No - treat accordingly
             L      R3,=A(AREA)                 R3 points to the record read
             USING  DVL,R3
             CLI    DVLRTYPE,DVLRVL             Is it a volume record ?
             BE     TREATVOL                    Yes - treat accordingly
             CLI    DVLRTYPE,DDSRDS             Is it a dataset record ?
             BE     TREATDS                     Yes - treat accordingly
             B      TREATOTH                    Treat other record types
             .
             .
    AREA     DS     CL(DVLLEN)                  Record buffer (both vol and D.S.)
    RECRBA   DS     XL4                         RBA of record
             .
             .
    * Control‑M/TAPE MAPPING MACROS
             CTTDVL                             Vol. data record
             CTTDDS                             D.S. data record
             CTTDBTP                            CTTIOS parameters block

In this sample

• You do not have to check whether the record being read is free or active, because the CTTIOS macro does that for you. If the record is free (that is, not active), the macro returns a return code of 4 (not found).

• Because the headers of all record types are the same, you can compare the record type FIELD from the volume DSECT against the record type EQUATE from the dataset DSECT.

Code sample for "Read Next Record" Request

    MVC    RECRBA,DVLRBA             Set RBA of current record
    CTTIOS ANY,READNEXT,REC=AREA,    Read the next record from MDB          *
           RBA=RECRBA,RC=RESCODE,MF=(E,IOSLIST)
    LTR    R15,R15
           .
           .

In this sample

• The rest of the sample program can be the same as the one in the above “Read a Record” Request sample .

• When using the READNEXT function code, the CTTIOS macro skips free records and looks for active records to read. A return code of 4 (not found) signals that the endoffile was reached.

Sample Media Database Access Program

This sample access program sequentially reads all the Media Database using RBAs and produces the following reports:

• all volumes with all the datasets for each volume

• all datasets with all the volumes for each dataset

This program provides a working example for a wide variety of requests available through the CTTIOS macro.

Code sample for Media Database Access Program

        ********************************************************************** *                                                                    *
        *                            CTTSAM1                                 *
        *                                                                    *
        *                                                                    *
        *   FUNCTION: SAMPLE PROGRAM TO DEMONSTRATE ACCESS TO THE Control‑M/ *
        *             TAPE MEDIA DATABASE  (MDB)  USING THE BASE LEVEL API.  *
        *             THE PROGRAM READS THE MDB AND PRODUCES TWO REPORTS:    *
        *             1. A VOLUME REPORT CONTAINING ALL VOLUMES IN THE MDB   *
        *                AND ALL DATASETS EXISTING ON EACH VOLUME            *
        *             2. A DATASET REPORT CONTAINING ALL DATASETS IN THE MDB *
        *                AND ALL VOLUMES THAT ARE PART OF EACH DATASET       *
        *                                                                    *
        *   RETURN CODES: 00  ‑  OK                                          *
        *                 04  ‑  MDB EMPTY                                   *
        *                 08  ‑  ERROR DURING PROCESSING                     *
        *                                                                    *
        *   LOGIC: THE PROGRAM READS THE MDB SEQUENTIALLY USING RBAS. VOLUME *
        *          AND DATASET RECORDS ARE PROCESSED, AND OTHER RECORDS ARE  *
        *          DISREGARDED.                                              *
        *          FOR VOLUME RECORDS,  THE DATASETS OF THE VOLUME ARE READ, *
        *          USING THE L‑TYPE INDEX.  A READ REQUEST WITH NO LABEL     *
        *          NUMBER  (VOLSER ONLY)  IS PERFORMED FIRST.  THE READNEXT  *
        *          REQUEST IS THEN USED REPEATEDLY UNTIL ALL DATASETS ON THE *
        *          VOLUME ARE PROCESSED.                                     *
        *          FOR DATASET RECORDS,  THE VOLUMES OF THE DATASET ARE READ *
        *          THE FIRST VOLSER IS TAKEN FROM THE DATASET RECORD,  AND   *
        *          AFTERWARDS,  THE VOLUME RECORDS ARE READ,  AND THE        *
        *          NEXT VOLUME RETRIEVED FROM THEM, UNTIL ALL VOLUMES OF THE *
        *          DATASET HAVE BEEN READ.                                   *
        *                                                                    *
        *   DD CARDS:  DAMDB    ‑ MDB DATA FILE                              *
        *              DAMDI    ‑ MDB INDEX FILE                             *
        *              DATRC    ‑ TRACE FILE                                 *
        *              DARPTVOL ‑ VOLUME REPORT FILE                         *
        *              DARPTDSN ‑ DATASET NAMES REPORT FILE                  *
        *                                                                    *
        *   DISCLAIMER:  THIS SAMPLE PROGRAM IS PROVIDED ON AN ‘AS IS’ BASIS,*
        *                WITHOUT ANY WARRANTY, EITHER EXPRESS OR IMPLIED     *
        *                                                                    *
        *   REGISTERS: R13    ‑ BASE                                         *
        *              R2     ‑ MDB RECORD KEY  (WHERE APPLICABLE)           *
        *              R3     ‑ MDB RECORD BUFFER                            *
        *                                                                    *
        *   ATTRIBUTES: AMODE 31                                             *
        *               RMODE 24                                             *
        *                                                                    *
        *   TO COMPILE, LINK AND RUN THE PROGRAM:                            *
        *                                                                    *
        *   //CTTSAM1 JOB ...                                                *
        *   //        JCLLIB  ORDER=IOA.PROCLIB             <<<----- CHANGE  *
        *   //        INCLUDE MEMBER=IOASET                                  *
        *   //ASM     EXEC IOAASM                                            *
        *   //C.SYSIN   DD DISP=SHR,DSN=&ILPREFA..SAMPLE(CTTSAM1)            *
        *   //L.SYSLMOD DD DISP=SHR,DSN=YOUR.LOAD.LIBRARY   <<<----- CHANGE  *
        *   //L.SYSIN   DD *                                                 *
        *      INCLUDE SYSLIB(CTTTRC)                                        *
        *      INCLUDE SYSLIB(CTTTLD)                                        *
        *     MODE RMODE(24),AMODE(31)                                       *
        *     ENTRY CTTSAM1                                                  *
        *     NAME CTTSAM1(R)                                                *
        *   //*                                                              *
        *   //RUN EXEC PGM=CTTSAM1,COND=(0,NE),REGION=60M                    *
        *   //STEPLIB  DD DISP=SHR,DSN=YOUR.LOAD.LIBRARY    <<<----- CHANGE  *
        *   //         DD DISP=SHR,DSN=&STEPLIB                              *
        *   //DAPARM   DD DISP=SHR,DSN=&ILPREFA..PARM                        *
        *   //         DD DISP=SHR,DSN=&ILPREFA..IOAENV                      *
        *   //DAMDB    DD DISP=SHR,DSN=&DBPREFT..MDBD.E000                   *
        *   //DAMDI    DD DISP=SHR,DSN=&DBPREFT..MDBI.E000                   *
        *   //DATRC    DD DISP=SHR,DSN=&DBPREFT..TRC                         *
        *   //DARPTVOL DD SYSOUT=*                                           *
        *   //DARPTDSN DD SYSOUT=*                                           *
        *   //                                                               *
        *                                                                    *
        **********************************************************************
                 EJECT
                 CTTDDS                    D.S.  DATA RECORD
                 CTTDVL                    VOL.  DATA RECORD
                 CTTDVX                    VOL.  INDEX RECORD
                 CTTDDX                    D.S.  INDEX RECORD
                 CTTDLX                    D.S.  L‑TYPE INDEX
                 CTTDBTP                   CTTIOS PARAMETERS BLOCK
                 EJECT
                 MACRO
        &NAME    MYPUT &DCB,&REC
        &NAME    LA    R15,*+6               ADDRESS FOLLOWING BASSM
                 BASSM R14,R15               CHANGE AMODE
                 PUT   &DCB,&REC             PUT THE DESIRED RECORD
                 LA    R15,*+10              ENDING ADDRESS
                 O     R15,=X'80000000'
                 BSM   0,R15
                 MEND
        **********************************************************************
                 EJECT
        CTTSAM1  AMODE 31
        CTTSAM1  RMODE 24
        CTTSAM1  CSECT
                 BEGIN *,EQUR=YES
                 CTTLEVEL
                 SPACE 3
        ***
        * INITIALIZE PROGRAM ‑ LOAD THE TCT AND OPEN FILES
        ***
                 CALL  CTTTLD,(LOADENV,TCTADDR,0,0)  LOAD THE TCT
                 LTR   R15,R15             SUCCESSFUL ?
                 BNZ   LTCTFAIL            NO ‑ TERMINATE
                 SPACE 3
                 OPEN  (RPTVOL,OUTPUT)     OPEN VOLUME REPORT OUTPUT FILE
                 LTR   R15,R15             SUCCESSFUL ?
                 BNZ   OUTERROR            NO ‑ TERMINATE
                 OPEN  (RPTDSN,OUTPUT)     OPEN DATASET REPORT OUTPUT FILE
                 LTR   R15,R15             SUCCESSFUL ?
                 BNZ   OUTERROR            NO ‑ TERMINATE
                 MYPUT RPTVOL,VOLMSG       PRINT VOLUME REPORT HEADER
                 MYPUT RPTDSN,DSNMSG       PRINT DATASET REPORT HEADER
                 SPACE 3
                 L     R12,TCTADDR
                 MVC   MSGOP,=CL8'OPEN'
                 CTTIOS ANY,OPEN,ENV=$ENV,              OPEN MDB            *
                        TCT=(R12),RC=RESCODE,MF=(E,IOSLIST)
                 LTR   R15,R15             SUCCESSFUL ?
                 BNZ   MDBERROR            NO ‑ TERMINATE
                 SPACE  3
        ***
        * SEQUENTIAL READING OF THE MDB,  BY RBA
        ***
                 MVC   RECRBA,RBA0         START WITH THE FIRST RECORD
                 MVC   MSGOP,=CL8'READ'
                 CTTIOS ANY,READ,RC=RESCODE,REC=AREA,RBA=RECRBA,  *
                       MF=(E,IOSLIST)  READ THE FIRST RECORD
                 LTR   R15,R15             SUCCESSFUL ?
                 BZ    READOK              YES ‑ PROCESS THE NEXT RECORD
                 CH    R15,=H'4'           WAS IT BECAUSE FIRST RECORD IS FREE?
                 BH    MDBERROR            NO ‑ TERMINATE                      *
                                           OTHERWISE TRY TO READ THE NEXT ONE
                 MVC   MSGOP,=CL8'READNEXT'
                 CTTIOS ANY,READNEXT,RC=RESCODE,REC=AREA,  READ NEXT RECORD     *
                       RBA=RECRBA,MF=(E,IOSLIST)
                 LTR   R15,R15             WAS READNEXT SUCCESSFUL ?
                 BZ    READOK              YES ‑ PROCESS THE RECORD
                 CH    R15,=H'4'           E.O.F ?
                 BE    MDBEMPTY            YES ‑ MDB IS EMPTY
                 B     MDBERROR            OTHERWISE ‑ TERMINATE
                 SPACE 3
        ***
        * LOOP ON ALL RECORDS
        ***
        READOK   EQU   *
                 L     R3,=A(AREA)  ESTABLISH ADDRESSABILITY
                 USING DVL,R3              TO THE RECORD BUFFER
                 CLI   DVLRTYPE,DVLRVL     IS THIS A VOLUME RECORD ?
                 BE    TREATVOL            YES ‑ TREAT ACCORDINGLY
                 CLI   DVLRTYPE,DDSRDS     IS THIS A DATASET RECORD ?
                 BE    TREATDS             YES ‑ TREAT ACCORDINGLY
        READNEXT EQU   *
                 MVC   MSGOP,=CL8'READNEXT'
                 CTTIOS ANY,READNEXT,RC=RESCODE,REC=AREA,  READ NEXT RECORD     *
                       RBA=RECRBA,MF=(E,IOSLIST)
                 LTR   R15,R15             WAS READ SUCCESSFUL ?
                 BZ    READOK              YES ‑ PROCCESS THIS RECORD
                 CH    R15,=H'4'           E.O.F ?
                 BE    EODAD               YES ‑ ISSUE MESSAGE
                 B     MDBERROR            OTHERWISE TERMINATE
                 DROP  R3
                 SPACE 3
        ***
        * TREAT ONE VOLUME RECORD ‑ PRINT ALL ITS DATASETS
        ***
        TREATVOL EQU   *
                 USING DVL,R3              ESTABLISH ADDRESSABILITY
                 MVC   VOLUME,DVLVOLSR     MOVE VOLSER TO OUTPUT RECORD
                 MYPUT RPTVOL,OUTVOL
                 TM    DVLSTAT,DVLSSCR     IS IT SCRATCH ?
                 BNO   GETDSNS             NO ‑ GET DATASETS ON THE VOLUME
                 MVC   DSNAME,SCRIND       ELSE ‑ ISSUE SCRATCH MESSAGE
                 MYPUT RPTVOL,OUTDSN       PRINT THE SCRATCH MESSAGE
                 B     ENDVOL              END VOLUME PROCESSING
        GETDSNS  EQU   *
                 LA    R2,DLSKEY           ESTABLISH ADDRESSABILITY
                 USING DLX,R2              TO D.S.  L‑TYPE INDEX
                 XC    DLSKEY,DLSKEY       CLEAR INDEX FIELD
                 MVC   DLXVOLSR,DVLVOLSR   MOVE VOLSER TO KEY FIELD
                 DROP  R3                  VOLUME RECORD NOT NEEDED ANY MORE
                 LA    R15,=A(L'DLXVOLSR)
                 MVC   MSGOP,=CL8'READ'
                 CTTIOS DS,READ,KEY=DLSKEY,  READ FROM MDB                     *
                       RC=RESCODE,                               *RC           *
                       KEYTYPE=L,KEYLEN=(R15),REC=AREA,MF=(E,IOSLIST)
                 CH    R15,=H'4'                                 *NFD
                 BE    ENDVOL                                    *NFD1
                 BH    MDBERROR                                  *NFD
        PRINTDSN EQU   *
                 USING DDS,R3              ADDRESSABILITY  (R3‑>>RECORD BUFFER)
                 MVC   DSNAME,DDSDSN       MOVE DSNAME TO OUTPUT RECORD
                 MYPUT RPTVOL,OUTDSN       PRINT IT
                 MVC   MSGOP,=CL8'READNEXT'
                 CTTIOS DS,READNEXT,KEY=DLSKEY,  READ NEXT RECORD FROM MDB     *
                       RC=RESCODE,                               *RC           *
                       KEYTYPE=L,REC=AREA,MF=(E,IOSLIST)
                 LTR   R15,R15             SUCCESSFUL ?
                 BZ    PROCDSN             YES ‑ PROCESS DSN
                 CH    R15,=H'4'           NO ‑ WAS IT BECAUSE THE END OF MDB ?
                 BH    MDBERROR            NO ‑ ISSUE AN ERROR MESSAGE
                 B     ENDVOL              YES ‑ PROCESS NEXT VOLUME
        PROCDSN  EQU   *
                 CLC   DLXVOLSR,VOLUME     ARE WE STILL IN THE SAME VOLUME ?
                 BE    PRINTDSN            YES ‑ PRINT IT AND PROCESS NEXT DS
        ENDVOL   EQU   *
                 B     READNEXT            GO TO GET NEXT RECORD
                 SPACE 3
        ***
        * TREAT ONE DATASET RECORD ‑ PRINT ALL ITS VOLUMES
        ***
        TREATDS  EQU   *
                 USING DDS,R3              ESTABLISH ADDRESSABILITY
                 MVC   DSNAME,DDSDSN       MOVE DSNAME TO OUTPUT RECORD
                 MYPUT RPTDSN,OUTDSN       PRINT IT
                 MVC   VOLUME,DDSVOLSR     MOVE FIRST VOLSER TO MESSAGE
                 MYPUT RPTDSN,OUTVOL       PRINT MESSAGE
                 LH    R4,DDSVOLS#         NUMBER OF VOLUMES IN DATASET
                 CH    R4,=H'1'            IS THERE ONLY ONE VOL IN DATASET ?
                 BNH   ENDDSN              YES ‑ END PROCESSING OF DATASET
                 DROP  R3                  ADDRESSABILITY NOT NEEDED ANY MORE
                 SPACE 3
        ***
        * FIND ALL VOLUMES OF DATASET
        ***
                 LA    R2,DVXKEY           ESTABLISH ADDRESSABILITY
                 USING DVX,R2              TO VOLUME INDEX FIELD
                 USING DVL,R3              AND TO VOLUME RECORD
                 XC    DVXKEY,DVXKEY       CLEAR VOLUME KEY FIELD
                 BCTR  R4,0                DECREMENT VOL COUNT  (1 PRINTED)
        NEXTVOL  EQU   *
                 MVC   DVXVOLSR,VOLUME
                 LA    R15,=A(L'DVXVOLSR)
                 MVC   MSGOP,=CL8'READ'
                 CTTIOS VOL,READ,KEY=DVXKEY,  READ FROM MDB                    *
                       RC=RESCODE,                                             *
                       REC=AREA,KEYLEN=(R15),MF=(E,IOSLIST)
                 CH    R15,=H'4'
                 BE    ENDDSN
                 BH    MDBERROR
                 MVC   VOLUME,DVLNEXT      NEXT VOLUME  (PREV ALREADY PRINTED)
                 MYPUT RPTDSN,OUTVOL       PRINT THE VOLUME SERIAL
                 BCT   R4,NEXTVOL          AND GO GET NEXT VOLUME  (IF ANY)
        ENDDSN   EQU   *                   END OF DATASET PROCESSING
                 B     READNEXT            GO TO GET NEXT RECORD
                 DROP  R3
                 SPACE 3
        *
        MDBERROR EQU *
                 LR    R5,R15
                 CVD   R5,DOUBLE
                 UNPK  MSGRC(2),DOUBLE+6(2)
                 OI    MSGRC+1,X'F0'
        *
                 L     R5,RESCODE
                 CVD   R5,DOUBLE
                 UNPK  MSGRSN(5),DOUBLE+5(3)
                 OI    MSGRSN+4,X'F0'
        *
                 IOAEDIT 'CTT200S _ FAILED FOR DAMDB DATASET.',(MSGOP,8),      *
                       INTO=MDBERR1+8,REGSAVE=YES,MF=(E,WORKEDIT)
        MDBERR1  WTO   'CTT200S   OPER   FAILED FOR DAMDB DATASET.'
        *
                 IOAEDIT '        RC=_, REASON=_',(MSGRC,2,MSGRSN,5),  ,       *
                       INTO=MDBERR2+8,REGSAVE=YES,MF=(E,WORKEDIT)
        MDBERR2  WTO   '        RC=XX,  REASON=YYYYY'
        *
                 B     RET8
        OUTERROR WTO   'UNABLE TO OPEN OUTPUT FILE'
                 B     RET8
        LTCTFAIL WTO   'TCT LOAD FAILED'
                 B     RET8
        MDBEMPTY WTO   'MDB IS EMPTY'
                 B     RET4
        EODAD    EQU   *
                 MYPUT RPTVOL,EOFMSG
                 MYPUT RPTDSN,EOFMSG
                 CLOSE  (RPTVOL,,RPTDSN)  CLOSE OUTPUT FILES
                 CTTIOS ANY,CLOSE,                                             *
                 RC=RESCODE,                                                   *
                 MF=(E,IOSLIST)
        CALL     CTTTLD,(DELETE,TCTADDR,0,0)   FREE TCT AREA
                 B     RET0
        RET8     LA    R15,8
                 B     ENDPGM
        RET4     LA    R15,4
                 B     ENDPGM
        RET0     SLR   R15,R15
                 B     ENDPGM
        ENDPGM   EQU   *
                 SPACE 3
                 BRTRN  (15)
                 EJECT
        ***
        * CONSTANTS
        ***
        RBA0     DC    XL4'00000100'       RBA OF FIRST RECORD IN DATABASE
        $ENV     DC    CL4'SAM1'
        LOADENV  DC    CL8'LOADENV'
        DELETE   DC    CL8'DELETE'
        PATTERN  DC    X'402120202020'
                 SPACE 3
        ***
        * DATA AREAS
        ***
        AREA     DS    CL(DVLLEN)  RECORD BUFFER  (BOTH VOL AND D.S.)
        RECRBA   DS    XL4                 RBA OF RECORD
        RESCODE  DS    F                   REASON CODE OF PROGRAM
        DLSKEY   DS    XL(DLXLEN)  D.S.  L‑TYPE INDEX KEY
        DVXKEY   DS    XL(DVXLEN)  VOL.  INDEX RECORD
        TCTADDR  DS    A                   ADDRESS OF THE TCT
        DOUBLE   DS    D
        MSGRC    DS    CL6                 RC FROM CTTIOS FOR CTT200S
        MSGRSN   DS    CL6                 REASON CODE FOR CTT200S
        MSGOP    DS    CL8                 OPERATION FOR CTT200S
                 DS    0F
        WORKEDIT DS    CL256               OPERATION FOR CTT200S
                 SPACE 3
        ***
        * OUTPUT MESSAGES
        ***
        OUTDSN   DS    CL80                DATASET OUTPUT RECORD
                 ORG   OUTDSN
                 DC    CL6' DSN= '         RECORD PREFIX
        DSNAME   DS    CL(L'DDSDSN)        DATASET NAME
                 DC    CL(80+OUTDSN‑*)' ' FILLER
                 ORG
        OUTVOL   DS    CL80                VOLUME OUTPUT RECORD
                 ORG   OUTVOL
                 DC    CL6' VOL= '         RECORD PREFIX
        VOLUME   DS    CL(L'DVLVOLSR)      VOLUME SERIAL
                 DC    CL(80+OUTVOL‑*)' ' FILLER
                 ORG
        VOLMSG   DC    CL80' *** VOLUME REPORT ***'
        DSNMSG   DC    CL80' *** DATASET REPORT ***'
        EOFMSG   DC    CL80' *** END OF MDB WAS REACHED *** '
        SCRIND   DC    CL44' *** THIS IS A SCRATCH VOLUME ***'
                 SPACE 3
        ***
        * CTTIOS IN LIST FORM
        ***
        IOSLIST  CTTIOS MF=L
                 SPACE 3
        ***
        * DATA Control BLOCKS
        ***
        RPTVOL   DCB   DDNAME=DARPTVOL,MACRF=PM,LRECL=81,RECFM=FBA,            *
                       DSORG=PS
        RPTDSN   DCB   DDNAME=DARPTDSN,MACRF=PM,LRECL=81,RECFM=FBA,            *
                       DSORG=PS
                 END
        High Level API

Calling programs that access the Control‑M/Tape Media Database using basic level API must load a Control‑M/Tape Control Table and allocate the Media Database components. High Level API performs these actions automatically.

High Level APILink copied to clipboard

High level API uses the real-time environment TCT and the real-time environment’s Media Database components.

As a result

• high level API cannot be used when the Control‑M/Tape real-time environment is not active

• calling programs intended for use with high level API have to be APF-authorized

Control‑M/Tape high level API is implemented by the following Assembler macros:

Table 249 Assembler Macros for Implementing Control-M/Tape High Level APIs

The following functions can be performed by high level API using macro CTTACCDB:

Table 250 High Level API Functions using the CTTACCDB macro

After each run of the CTTACCDB macro, it is highly recommended that you check the completion code of the access to the Media Database using the CTTCHKDB macro. This macro tests the return code from the API and transfers control to an error handling routine that is written by the user as part of the calling program.

The CTTACCDB Macro

High level API access to the Media Database is performed using the CTTACCDB macro.

Format

Instructions for the CTTACCDB macro are formatted as follows:

label     CTTACCDB        function‑code,
                          R  EC=buffer‑address,
                          VOL=volser,
                          PARMS=parm-work-area

Table 251 Parameters

REC   DS (DVLLEN)X

All invocations of the CTTACCDB macro must access the same parameter area. Therefore, you must use the same parm-work-area in all calls to the CTTACCDB macro.

The CTTACCDB macro must be coded in accordance with all standard macro assembler coding restrictions.

Values in general purpose registers 0, 1, 14, and 15 are modified by the CTTACCDB macro.

The CTTACCDB macro accesses a set of variables generated by macro CTTADBP and by the CTTDBTP macro. Therefore, the source of the calling program must include both these macros.

The CTTCHKDB Macro

This macro is used to check return codes resulting from access of the Media Database using the CTTACCDB macro.

Format

Instructions for the CTTCHKDB macro are formatted as follows:

label     CTTCHKDB   ERR=error‑routine,
                     PARMS=work‑area

Table 252 Format for Macro CTTCHKDB Instructions

The CTTCHKDB macro must be coded in accordance with all standard macro Assembler coding restrictions.

Values in general purpose registers 0, 1 and 15 are modified by the CTTCHKDB macro.

Media Database Error Handling Routine

The calling program must supply an error handling routine. This error handling routine is given control whenever the CTTCHKDB macro determines that the last access to the Media Database was unsuccessful (for example, the requested volume was not found).

High level API invokes the CTTIOS macro to access the Media Database. For more information, see Macro CTTIOS.

High level API accesses a set of variables generated by the CTTADBP macro. Some of these variables contain information relevant to the Media Database error handling routine. The variables are located in the area specified using the PARMS parameter to the CTTACCDB macro, and are mapped by the CTTADBP macro. The following table describes these variables:

Table 253 Variables Generated by Macro CTTADBP, Accessible by High Level APIs

Example of Macro Code Usage and JCL for High Level API

This sample access program reads the volume record of volume V00001 from the Media Database using high level API, and issues a message about the status of this volume (that is, SCRATCH, ACTIVE, or NOT FOUND IN MDB). This sample also includes an example for the Media Database error handling routine.

Figure 94 Example of Macro Usage and JCL for High Level API

     **********************************************************************
     *                            CTTSAM2                                 *
     *                                                                    *
     *                                                                    *
     *  FUNCTION:  SAMPLE PROGRAM TO DEMONSTRATE ACCESS TO Control‑M/TAPE *
     *             MEDIA DATABASE  (MDB)  USING THE HIGH LEVEL API.       *
     *             THIS PROGRAM READS THE MDB VOLUME RECORD OF A CERTAIN  *
     *             VOLUME, (IN THIS SAMPLE:  V00001) AND ISSUES A MESSAGE *
     *             ABOUT THE VOLUME'S STATUS:  ACTIVE OR SCRATCH.         *
     *             IN THIS CODE YOU WILL ALSO FIND AN EXAMPLE FOR AN      *
     *             MDB ERROR HANDLING ROUTINE THAT SHOULD BE CALLED BY    *
     *             ANY PROGRAM THAT USES THE HIGH LEVEL API.              *
     *                                                                    *
     *  DD CARDS:  NONE  (THE HIGH LEVEL API USES THE Control‑M/TAPE REAL *
     *                    TIME ENVIRONMENT FILES).                        *
     *                                                                    *
     *   DISCLAIMER:  THIS SAMPLE PROGRAM IS PROVIDED ON AN AS IS BASIS,  *
     *                WITHOUT ANY WARRANTY,  EITHER EXPRESS OR IMPLIED    *
     *                                                                    *
     *   REGISTERS: R13    ‑ BASE                                         *
     *              R4     ‑ MDB VOLUME RECORD  (MAPPED BY CTTDVL)        *
     *              R9     ‑ CTTACCDB PARMS  (MAPPED BY CTTADBP)          *
     *                                                                    *
     *   ATTRIBUTES: AMODE 31                                             *
     *               RMODE 24                                             *
     *                                                                    *
     *   TO COMPILE, LINK AND RUN THE PROGRAM :                           *
     *                                                                    *
     *   //CTTSAM2 JOB ...                                                *
     *   //        JCLLIB  ORDER=IOA.PROCLIB             <<<----- CHANGE  *
     *   //        INCLUDE MEMBER=IOASET                                  *
     *   //ASM     EXEC IOAASM                                            *
     *   //C.SYSIN   DD DISP=SHR,DSN=&ILPREFA..SAMPLE(CTTSAM2)            *
     *   //L.SYSLMOD DD DISP=SHR,DSN=YOUR.LOAD.LIBRARY   <<<----- CHANGE  *
     *   //L.SYSIN   DD *                                                 *
     *     MODE RMODE(24),AMODE(31)                                       *
     *     ENTRY CTTSAM2                                                  *
     *     NAME CTTSAM2(R)                                                *
     *   //*                                                              *
     *   //RUN EXEC PGM=CTTSAM2,COND=(0,NE),REGION=60M                    *
     *   //STEPLIB  DD DISP=SHR,DSN=YOUR.LOAD.LIBRARY    <<<----- CHANGE  *
     *   //         DD DISP=SHR,DSN=&STEPLIB                              *
     *   //DARPTVOL DD SYSOUT=*                                           *
     *   //DARPTDSN DD SYSOUT=*                                           *
     *   //                                                               *
     *                                                                    *
     **********************************************************************
              EJECT ,
     CTTSAM2  AMODE 31
     CTTSAM2  RMODE 24
     CTTSAM2  CSECT                      HIGH LEVEL API SAMPLE
              BEGIN *,EQUR=YES
              SPACE 1
              LA    R9,ADBPARMS          R9‑>> CTTADB PARMS
              USING ADBP,R9
              XC    FLAG,FLAG            INIT INTERNAL FLAG
              SPACE 1
     *********************************************************************
     * PERFORM INITIALIZATION REQUIRED usingusing HIGH LEVEL API: START COMMAND *
     *********************************************************************
              SPACE 1
              CTTACCDB START,PARMS=ADBPARMS         INITIALIZATION
                  CTTCHKDB ERR=ADBERROR,PARMS=ADBPARMS  CHECK START OPERATION
                 SPACE 1
                 OI    FLAG,$OPENED         MARK:  MDB IS OPENED
                 SPACE 1
     *********************************************************************
     *  READ MDB VOLUME RECORD OF VOLUME:  V00001 usingusing READVOL COMMAND    *
     *********************************************************************
              SPACE 1
              MVC   VOL(6),=CL6'V00001'  VOLSER TO READ
              SPACE 1
              CTTACCDB READVOL,REC=VOLREC,VOL=VOL,PARMS=ADBPARMS
              CTTCHKDB ERR=RVOLERR,PARMS=ADBPARMS
              SPACE 1
              NI    FLAG,X'FF'‑$OPENED   MARK:  MDB IS NOT OPENED
              SPACE 1
     *********************************************************************
     *  PERFORM CLEANUP REQUIRED using HIGH LEVEL API:  END COMMAND        *
     *********************************************************************
              SPACE 1
              CTTACCDB END,PARMS=ADBPARMS
              CTTCHKDB ERR=ADBERROR,PARMS=ADBPARMS
              SPACE 1
     *********************************************************************
     *  ISSUE A MESSAGE ACCORDING TO VOLUME'S STATUS:  ACTIVE OR SCRATCH *
     *********************************************************************
              SPACE 1
              LA    R4,VOLREC            R4‑>>MDB VOL RECORD
              USING DVL,R4
              TM    DVLSTAT,DVLSACT      AN ACTIVE VOLUME ?
              BNO   WTOSCR ..N,  GO ISSUE:  SCRATCH
              SPACE 1
              WTO   'VOLUME V00001 IS ACTIVE'  VOLUME IS ACTIVE
              B     EXIT
              SPACE 1
     WTOSCR   DS    0H                   VOLUME IS SCRATCH
              WTO   'VOLUME V00001 IS SCRATCH'
              SPACE 1
              B     EXIT
              DROP  R4                   WAS MDB VOL RECORD
              SPACE 1
     *********************************************************************
     *   MDB ERROR HANDLING ROUTINE ‑ FOR READVOL FUNCTION               *
     *********************************************************************
              SPACE 1
     RVOLERR  DS    0H                   READVOL ERROR
              L     R15,ADBPRC           R15 ‑ CTTADB RC
              C     R15,=F'16'           A CTTIOS FAILURE ?
              BNE   ADBERROR ..N,  GO ISSUE ERROR MSG
              SPACE 1
              L     R15,ADBPIRC          R15 ‑ RC OF CTTIOS
              C     R15,=F'4'            VOLUME NOT FOUND ?
              BNE   ADBERROR ..N,  GO ISSUE ERROR MSG
              SPACE 1
              WTO   'VOLUME V00001 NOT FOUND IN MEDIA DATABASE'
              SPACE 1
              NI    FLAG,X'FF'‑$OPENED
              CTTACCDB END,PARMS=ADBPARMS    TRY TO PERFORM CLEANUP
              CTTCHKDB ERR=ADBERROR,PARMS=ADBPARMS
              SPACE 1
              B     EXIT                NO OTHER UPDATES
              SPACE 1
     *********************************************************************
     *   MDB ERROR HANDLING ROUTINE ‑ FOR START/END FUNCTIONS            *
     *********************************************************************
     ADBERROR DS    0H
              MVC   MSG1FUNC(8),ADBPFUNC    CTTACCDB FUNCTION FOR MESSAGE
              MVC   MSG1VOL(6),=CL6'V00001' VOLSER FOR MESSAGE
              L     R3,ADBPRC               CONVERT
              CVD   R3,DW ..CTTACCDB
              UNPK  MSG1RC(3),DW+6(2) ..RETURN‑CODE
              OI    MSG1RC+2,X'F0' ..FOR MESSAGE
              SPACE 1
              MVC   WTO1+10(MSG1LEN),MSG1   MOVE MESSAGE TO BE WTO'ED
     WTO1     WTO   '                                                       +
                                                          ',ROUTCDE=11
              MVC   MSG2FUNC(8),ADBPIOPR    LAST CTTIOS FUNCTION FOR MSG
              L     R3,ADBPIRC              CONVERT
              CVD   R3,DW ..LAST CTTIOS
              UNPK  MSG2RC(3),DW+6(2) ..    RETURN‑CODE
              OI    MSG2RC+2,X'F0' ..       FOR MESSAGE
              SPACE 1
              L     R3,ADBPIRSN             CONVERT
              CVD   R3,DW ..LAST CTTIOS
              UNPK  MSG2RSN(5),DW+5(3) ..   REASON‑CODE
              OI    MSG2RSN+4,X'F0' ..      FOR MESSAGE
              SPACE 1
              MVC   WTO2+10(MSG2LEN),MSG2   MOVE MESSAGE TO BE WTO'ED
     WTO2     WTO   '                                                       +
                                                          ',ROUTCDE=11
              SPACE 1
              B     EXIT
              SPACE 1
     EXIT     DS    0H
              TM    FLAG,$OPENED            IS MDB STILL OPENED ?
              BNO   SKIPEND ..N,            SKIP END
              SPACE 1
              CTTACCDB END,PARMS=ADBPARMS
              SPACE 1
     SKIPEND  DS    0H
              BRTRN 0
              SPACE 1
     *********************************************************************
     *   WORK AREAS                                                      *
     *********************************************************************
     DW       DS    D                       DOUBLE WORD
     *
     FLAG     DS    X                       INTERNAL FLAG
     $OPENED  EQU   X'80'                   MARK:  MDB IS OPENED
     *
     MSG1     DS    0C                      1ST ERROR MESSAGE
              DC    C'CTTACCDB FUNCTION:  '
     MSG1FUNC DS    CL8
              DC    C' FOR VOLUME:  'MSG1VOL  DS    CL6
              DC    C' FAILED.  RC:  '
     MSG1RC   DS    CL3
     MSG1LEN  EQU   *‑MSG1
     *
     MSG2     DS    0C                      2ND ERROR MESSAGE
              DC    C'LAST CTTIOS FUNCTION:  '
     MSG2FUNC DS    CL8
              DC    C' RC:  '
     MSG2RC   DS    CL3
              DC    C' REASON:  '
     MSG2RSN  DS    CL5
     MSG2LEN  EQU   *‑MSG2
     *
         VOL      DS    CL6                     VOLUME SERIAL NUMEBR TO READ
     VOLREC   DS    (DVLLEN)X               MDB RECORD BUFFER
     *
     ADBPARMS DS    (ADBPLEN)X              CTTACCDB WORK PARMS
     *********************************************************************
     *   MAPPING DSECTS                                                  *
     *********************************************************************
              CTTDBTP ,                     CTTIOS PARMS
              CTTADBP ,                     CTTACCDB PARMS
              CTTDVL ,                      MDB VOLUME RECORD MAP
     END
     Rule Search API

Rule Search APILink copied to clipboard

The Control‑M/Tape Rule Search API is a powerful tool that can be used to determine what actions (DO statements) is triggered when a given set of selection criteria (specified using ON statements) is satisfied.

To use the Control‑M/Tape Rule Search API, perform the following steps:

1. Use the CTTGTCT macro to obtain the address of the ControlM/Tape Control Table (TCT) of the real-time Environment. For additional information, seeObtaining the Address of the Real-Time TCT.

2. Specify desired selection criteria (that is, ON statements) using the RSO block. For more information, see Input.

3. Call the Rule Search API with the necessary arguments specified.

4. Analyze the information returned by the Rule Search API in the RLM and RSI control blocks.

InputLink copied to clipboard

A set of selection criteria are specified for the Rule Search API using an RSO block. This block is passed to the API and is mapped by the CTTRSO dsect. For information on how to set the RSO block, see the CTTRSO dsect in the IOA MACRO library.

Below is an example of how information can be specified in an RSO block.

Figure 95 Information Specified in an RSO Block

             SPACE 1             MVI   MYRSO,C' '
             Clear RSO block
             MVC   MYRSO+1(L'MYRSO-1),MYRSO
             LA    R3,MYRSO
             USING RSO,R3
             MVC   RSODSN,MYDSN           Specify ON DATASET criteria
             MVC   RSOVOL,MYVOL           Specify ON VOLUME criteria
             DROP  R3
             .
             .
    MYRSO    DS    XL(RSOLEN)
    MYDSN    DC    CL44’MY.FILE’
    MYVOL    DC    CL6’VOL001’
             SPACE 1

The Rule Search API scans Control‑M/Tape rules currently in memory, and determines which actions (DO statements) are invoked by the specified selection criteria. The Rule Search API needs the address of the Real‑Time TCT in order to determine the address of the currently loaded rules in memory. The address of the Real‑Time TCT must be included in the CALL statement used to invoke the Rule Search API.

Use the CTTGTCT macro to determine the address of the Real‑Time TCT. For more information, seeObtaining the Address of the Real-Time TCT. 

OutputLink copied to clipboard

The Rule Search API returns information in the following control blocks:

Table 254 Control Blocks with Information from the Rule Search API

The addresses for control blocks RLM and RSI are indicated as parameters in the CALL statement that is used to invoke the Rule Search API. For more information, see Invoking the Rule Search API

RLM Control Block

The RLM control block is mapped by the CTTRLM dsect. Whereas an RLM control block is normally created for each Control‑M/Tape rule in memory, the RLM control block created by the rule search API contains information about all DO statements that are triggered by selection criteria specified in the RSO block. For more information, see Input. 

This control block is composed of the following components:

• a rule header

• This part of the control block normally contains rulespecific information (for example, rule mode).

  • information about DO statements that can be assigned only one set of values (for example, DOSTACK, DOPOOL and DOLABEL)

  • information about DO statements that can be assigned multiple sets of values (for example, DOVAULT or DOSTKGROUP)

  • information about DO statements that perform IOA functions (for example, DOFORCEJOB, DOSHOUT or DOCONDITION)

• Each DO statement describing an IOA function is preceded by a one-byte number describing the length of the DO statement. This number can be used while extracting information from the RLM control block to move from the description of one DO statement to the description of the next DO statement.

For more information about the fields in the RLM control block, see the CTTRLM dsect in the Control‑M/Tape MACRO library.

RSI Control Block

The RSI control block contains information about each of the DO statements described in the RLM control block. For more information, see RLM Control Block

The following information is provided for each DO statement:

• the name of the rule containing the DO statement

• the name of the rule table

• the name of the library from which the rule table was loaded into memory

• the address of the RLM control block that describes the rule from which the information was extracted. This RLM control block is not the one created by the Rule Search API. This RLM block was created as part of the ControlM/Tape rule load process

For more information about the fields in the RSI control block, see the CTTRSI dsect in the IOA MACRO library.

Invoking the Rule Search APILink copied to clipboard

Use the following call statement to invoke the Control‑M/Tape Rule Search API:

CALL   CTTRSR,(func-addr,tct-address,rso-address,expdt,rlm-address,
IOA-trace-header- address,rsi-address)

Table 255 Fields for Invoking the Rule Search API

Sample Call to the Rule Search API

The following lines demonstrate a call to the Control‑M/Tape Rule Search API:

Figure 96 Sample Call to the Rule Search API

          L       R12,TCTADDR
          CALL    CTTRSR,(RSEARCH,(12),RSOBLK,0,RLMADDR,(2),RSIADDR)
          .
          .
          .
TCTADDR   DS      A
RSEARCH   DC      C’R’
RSOBLK    DS      XL(RSOLEN)
RLMADDR   DS      A
RSIADDR   DS      A

For a more detailed example, see Sample Rule Search API. 

Return Codes

The Rule Search API returns one of the following return codes in general register 15:

Table 256 Return Codes for the Rule Search API

Sample Rule Search APILink copied to clipboard

The following sample program demonstrates usage of the Rule Search API. This sample includes commands that print the information in the RLM and RSI control blocks (that is, the DO statements and relevant descriptions).

This sample is located in the CTTSAM3 member in the IOA SAMPLE library.

Figure 97 Sample Rule Search API

        ***********************************************************************  
        *                                                                     *
        *                             CTTSAM3                                 *
        *                   Using Rule Search API - Sample                    *
        *                                                                     *
        * ------------------------------------------------------------------- *
        *  FUNCTION: This sample program demonstrates the Rule Search API.    *
        *            This program obtains a copy of the real-time environment *
        *            TCT, specifies two ON statements and calls the API.      *
        *                                                                     *
        *            Upon return from the API, the program searches the RLM   *
        *            control block created by the API for DO STACK, DO VAULT  *
        *            and DO CONDITION statements which are triggered by the   *
        *            specified ON criteria. The DO statements that are        *
        *            detected are then printed out.                           *
        *                                                                     *
        *  RETURN CODES:                                                      *
        *            00      OK                                               *
        *            04      No matching rules were triggered or found        *
        *            24      SYSPRINT file could not be opened                *
        *            28      TCT could not be obtained. Control‑M/TAPE is     *
        *                    probably not active                              *
        *            Other   Internal error in API (see documentation)        *
        *                                                                     *
        *  LOGIC:    The following steps are performed by this sample program:*
        *                                                                     *
        *            1. Obtain a copy of the real-time environment TCT.       *
        *                                                                     *
        *            2. Specify ON DATASET and ON VOLUME criteria and call    *
        *               the Rule Search API.                                  *
        *                                                                     *
        *            3. Search for DO STACK, DO VAULT and DO CONDITION        *
        *               statements in the RLM control block created by        *
        *               the API, and print information about detected DO      *
        *               statements.                                           *
        *                                                                     *
        *            4. If a DO STACK statement was found in the previous     *
        *               step, print the rule name, the table name, and the    *
        *               library name in which the DO STACK statement was      *
        *               found.                                                *
        *                                                                     *
        * DD CARDS:  SYSPRINT - Output file                                   *
        *                                                                     *
        * DISCLAIMER: This sample is provided on an as-is basis, without any  *
        *             warranty, either expressed or implied.                  *
        *                                                                     *
        * REGISTERS: R13   - Base                                             *
        *            R12   - TCT address                                      *
        *            R2    - SYSPRINT DCB address                             *
        *            R3:R7 - Work registers                                   *
        *                                                                     *
        * ATTRIBUTES: AMODE 31                                                *
        *             RMODE 24                                                *
        *                                                                     *
        * TO COMPILE, LINK AND RUN THE PROGRAM :                              *
        *                                                                     *
        * //CTTSAMP JOB ...                                                   *
        * //ASM  EXEC IOAASM                                                  *
        * //        JCLLIB  ORDER=IOA.PROCLIB             <<<----- CHANGE     *
        * //        INCLUDE MEMBER=IOASET                                     *
        * //C.SYSIN    DD  DISP=SHR,DSN=&ILPREFA..SAMPLE(CTTSAM3)             *
        * //L.SYSLMOD  DD  DISP=SHR,DSN=YOUR.LOAD.LIBRARY <<<----- CHANGE     *
        * //L.AIOALOAD DD  DISP=SHR,DSN=&ILPREFA..AIOALOAD                    *
        * //L.SYSIN    DD *                                                   *
        *   INCLUDE AIOALOAD(CTTRSR)                                          *
        *   INCLUDE AIOALOAD(IOADBG)                                          *
        *   INCLUDE AIOALOAD(IOAMVN)                                          *
        *   INCLUDE AIOALOAD(CTMXAGR)                                         *
        *   MODE AMODE(31),RMODE(24)                                          *
        *   ENTRY CTTSAM3                                                     *
        *   NAME CTTSAM3(R)                                                   *
        * //*                                                                 *
        * //RUN EXEC PGM=CTTSAM3,COND=(0,NE)                                  *
        * //STEPLIB  DD DISP=SHR,DSN=YOUR.LOAD.LIBRARY    <<<----- CHANGE     *
        * //         DD DISP=SHR,DSN=&STEPLIB                                 *
        * //SYSPRINT DD SYSOUT=*                                              *
        * //                                                                  *
        *                                                                     *
        ***********************************************************************
        CTTSAM3  CSECT
        CTTSAM3  AMODE  31
        CTTSAM3  RMODE  24
                 BEGIN  EQUR=YES
                 CTTLEVEL CTTAPI,1.0.0
        *
                 XC    RC,RC                  Clear RC
                 SPACE 1
        ***********************************************************************
        *  GET ADDRESS OF REAL-TIME ENVIRONMENT TCT                           *
        ***********************************************************************
                 SPACE 1
                 CTTGTCT TCTADDR=ACTVTCT,TEST=ACT
                 LTR   R15,R15                TCT loaded ?
                 BNZ   TCTFAIL                N, exit
                 SPACE 1
        ***********************************************************************
        *  BUILD 'ON' COMMANDS BLOCK                                          *
        ***********************************************************************
                 SPACE 1
                 MVI   MYRSO,C' '             Clear RSO block
                 MVC   MYRSO+1(L'MYRSO-1),MYRSO
                 LA    R3,MYRSO
                 USING RSO,R3
                 MVC   RSODSN,MYDSN           Set 'ON DATASET' command
                 MVC   RSOVOL,MYVOL           Set 'ON VOLUME' command
                 DROP  R3
                 SPACE 1
        ***********************************************************************
        *  CALL RULE SEARCH API                                               *
        ***********************************************************************
                 SPACE 1
                 MVI   FUNCTYPE,C'I'          Extract 'DO' commands & rule info
                 L     R12,ACTVTCT            TCT address
                 USING TCT,R12
                 L     R2,TCTMCTA
                 USING MCT,R2
                 LA    R2,MCTTRCHD            IOA trace header
                 DROP  R2,R12                 was MCT, TCT
                 CALL  CTTRSR,(FUNCTYPE,(R12),MYRSO,EXPDT,DOOPT,(R2),STATUS,   X
                       RULEINFO),VL
                 C     R15,=F'4'              Any matching rules found ?
                 BE    NOMATCH                No, exit
                 BH    RSRFAIL                Rule search API failed ?
                 SPACE 1
        ***********************************************************************
        *  OPEN  SYSPRINT FILE                                                *
        ***********************************************************************
                 SPACE 1
                 OPEN  (SYSPRINT,OUTPUT)
                 LA    R2,SYSPRINT
                 USING IHADCB,R2
                 TM    DCBOFLGS,DCBOFOPN      Successfully opened ?
                 DROP  R2
                 BNO   OPENFAIL
                 SPACE 1
        ***********************************************************************
        *  PRINT OUT THE TRIGGERED 'DO' Statements                            *
        ***********************************************************************
                 SPACE 1
                 BAL   R14,PRTDO
                 SPACE 1
        ***********************************************************************
        *  PRINT OUT THE INFORMATION ORIGIN                                   *
        ***********************************************************************
                 SPACE 1
                 BAL   R14,PRTINFO
                 SPACE 1
        ***********************************************************************
        *  CLOSE SYSPRINT FILE                                                *
        ***********************************************************************
                 SPACE 1
                 CLOSE SYSPRINT
                 SPACE 1
        ***********************************************************************
        *  FREE RULE SEARCH API                                               *
        ***********************************************************************
                 SPACE 1
                 MVI   FUNCTYPE,C'F'          Free request
                 CALL  CTTRSR,(FUNCTYPE,(R12),0,0,DOOPT,STATUS,RULEINFO),VL
                 LTR   R15,R15                RLM/RSI freed ?
                 BNZ   RSRFAIL                Rule search API failed ?
                 B     RETURN                 Return
                 SPACE 1
        ***********************************************************************
        *  CHECK SELECTED 'DO' COMMANDS AND PRINT THEM OUT                    *
        ***********************************************************************
                 SPACE 1
        PRTDO    EQU   *
                 LR    R11,R14                Save return address
        ***
        *  Check 'DO' command (in fixed part of RLM)
        ***
                 L     R3,DOOPT               Get address of RLM block
                 USING RLM,R3
                 CLI   RLMDPSTK,RLMDPSBL      'DO STACK' command is blank ?
                 BE    CHKVLT                 Yes, go check 'DO VAULT'
                 MVC   STACKVAL(1),RLMDPSTK
                 IOAMODE 24,R=R8 
                 PUT   SYSPRINT,STACK         PRINT 'DO STACK = X'
                 IOAMODE RESTORE,R=R8 
        ***
        *  Check 'DO' command (in dynamic part of RLM)
        ***
        CHKVLT   EQU   *
                 ICM   R6,15,RLMDV#VL         Any 'DO VAULT' commands ?
                 BZ    CHKMORE                No, go check other 'DO' commands
                 L     R5,RLMDVADR            Yes, get address of vaults block
        VLTLOOP  MVC   VAULTNAM(L'RLMDVNAM),0(R5)
                 IOAMODE 24,R=R8 
                 PUT   SYSPRINT,VAULT         Print 'DO VAULT = <vault-name>'
                 IOAMODE RESTORE,R=R8 
                 LA    R5,RLMDLVLT(R5)        Skip to next vaulting pattern
                 BCT   R6,VLTLOOP
        CHKMORE  EQU   *
                 ICM   R5,15,RLMDOADR         Address of 'DO' block
                 BZ    NOMORE
                 L     R6,RLMD#IOA            No. of 'DO <IOA-cmd>' commands
                 DROP  R3
                 USING RLMRCRDS,R5
                 L     R6,RLMD#IOA            No. of 'DO <IOA-cmd>' commands
                 XR    R7,R7
        MOREDO   MVI   IOACMDV,C' '           Clear output record
                 MVC   IOACMDV+1(L'IOACMDV-1),IOACMDV
                 CLI   RLMDTYPE,RLMDCOND      Is it a 'DO CONDITION' command ?
                 BNE   SKIPNXT                No, skip to next 'DO' command
                 MVC   IOACMDV(L'RLMDCCND),RLMDCCND
                 IOAMODE 24,R=R8
                 PUT   SYSPRINT,IOACMD        Print the 'DO' command
                 IOAMODE RESTORE,R=R8
                 ICM   R7,B'0001',RLMLRCRD    Length of the 'DO' command
        SKIPNXT  AR    R5,R7                  Skip to next command
                 BCT   R6,MOREDO
                 DROP  R5
        NOMORE   EQU   *
                 BR    R11
                 SPACE 1
        ***********************************************************************
        *  PRINT OUT THE INFORMATION ORIGIN                                   *
        ***********************************************************************
                 SPACE 1
        PRTINFO  EQU   *
                 LR    R11,R14                Save return address
                 CLI   STACKVAL,C' '          DO STACK command retrieved ?
                 BE    NOSTACK                No, don't print its origin
        ***
        *  Print information about the origin of the 'DO STACK' command
        ***
                 L     R3,RULEINFO            Get address of RSI block
                 USING RSI,R3
                 MVC   RULENAME(L'RSISRLNM),RSISRLNM
                 LA    R4,RULENAM
                 IOAMODE 24,R=R8
                 PUT   SYSPRINT,(R4)          Print the rule name
                 IOAMODE RESTORE,R=R8
                 MVC   RULETABL(L'RSISTBNM),RSISTBNM
                 LA    R4,RULETAB
                 IOAMODE 24,R=R8
                 PUT   SYSPRINT,(R4)          Print the rule table
                 IOAMODE RESTORE,R=R8
                 MVC   RULELIBR(L'RSISTBLB),RSISTBLB
                 LA    R4,RULELIB
                 IOAMODE 24,R=R8
                 PUT   SYSPRINT,(R4)          Print the rule library
                 IOAMODE RESTORE,R=R8
        NOSTACK  EQU   *
                 BR    R11
                 SPACE 1
        ***********************************************************************
                 SPACE 1
        NOMATCH  EQU   *                      No rule was triggered
                 MVI   FUNCTYPE,C'F'          Free request
                 CALL  CTTRSR,(FUNCTYPE,(R12),0,0,DOOPT,STATUS,RULEINFO),VL
                 LA    R15,RC4
                 ST    R15,RC
                 B     RETURN
        *
        OPENFAIL EQU   *                      SYSPRINT Open failed
                 MVI   FUNCTYPE,C'F'          Free request
                 CALL  CTTRSR,(FUNCTYPE,(R12),0,0,DOOPT,STATUS,RULEINFO),VL
                 LA    R15,RC24
                 ST    R15,RC
                 B     RETURN
        *
        TCTFAIL  EQU   *                      TCT could not be obtained
                 LA    R15,RC28
                 ST    R15,RC
                 B     RETURN
        *
        RSRFAIL  EQU   *                      Rule search API has failed
                 ST    R15,RC
                 B     RETURN
        *
        RETURN   L     R15,RC                 Return to caller
                 BRTRN (15)
        *--------------------------------------------------------------------*
                 LTORG
                 EJECT
        *--------------------------------------------------------------------*
        *  COMMON BLOCK AREA                                                 *
        *--------------------------------------------------------------------*
        COMBLOCK DS    0D
        *
        *  Constants
        *
        RC4      EQU   4
        RC24     EQU   24
        RC28     EQU   28
        *
        RC       DS    F                      Routine's return code
        ACTVTCT  DS    A                      TCT address
        MYDSN    DC    CL44'N89.CHKIN.TRY'
        MYVOL    DC    CL6'CHKIN0'
        DOSTKFND DS    C                      DO STACK command found ? (Y/N)
        *---------------------------------------------------------------------*
        FUNCTYPE DS    C                      Function type
        MYRSO    DS    XL(RSOLEN)             'ON' statements
        DOOPT    DC    A(0)                   Address of RLM block
        RULEINFO DC    A(0)                   Address of RSI block
        EXPDT    DC    F'0'                   JCL expdt
        STATUS   DC    X'00'                  Status flag 
        *---------------------------------------------------------------------*
        SYSPRINT DCB   DDNAME=SYSPRINT,DSORG=PS,MACRF=PM,RECFM=FB,LRECL=121
        *---------------------------------------------------------------------*
        IOACMD   DC    CL14'DO CONDITION: '
        IOACMDV  DS    CL107' '
        STACK    DC    CL11'DO STACK = '
        STACKVAL DS    CL110
        VAULT    DC    CL11'DO VAULT = '
        VAULTNAM DS    CL110
        RULENAM  DC    CL37'DO STACK command taken from rule:    '
        RULENAME DS    CL84
        RULETAB  DC    CL37'                       from table:   '
        RULETABL DS    CL84
        RULELIB  DC    CL37'                       from library: '
        RULELIBR DS    CL84
        *---------------------------------------------------------------------*
                 EJECT
                 IEFJSCVT                     Macros for CTTGTCT
                 IEFJESCT
                 COPY  CTTSSVT
        CVT      CVT   DSECT=YES,PREFIX=YES
        TCT      DSECT
                 COPY  CTTTCT                 TCT  layout
        MCT      DSECT
                 COPY  IOAMCT                 MCT  layout
        *---------------------------------------------------------------------*
                 EJECT
        RSO      DSECT                        'ON' statements
                 COPY  CTTRSO
        RLM      DSECT                        'DO' statements
                 COPY  CTTRLM
        RSI      DSECT                        Rules information
                 COPY  CTTRSI
        RLD      DSECT                        Equates for CTTRLM
                 COPY  CTTRLD
        RLX      DSECT                        Equates for CTTRLM
                 COPY  CTTRLX
                 DCBD  DSORG=PS
        *---------------------------------------------------------------------*
                 END