Function-code

Specifies a function requested from CTTAPI. Mandatory. This parameter must always be the first parameter. Valid values are:

• START
• END
• QUERY and QUERYNXT
• VOLSRC
• VOLACT
• DSNSCR
• DSNACT

See next table, CTTAPI Function Values for more details.

RC

Specifies the return code returned to the caller. This variable must point to an area of two bytes (one half word). Identical to register R15.

REASON

Specifies the reason code returned to the caller. This variable must point to an area of two bytes (one half word).

URC

Specifies utility return code, which is returned to CTTAPI from the invoked utility if that utility failed.

REPLY

Start address of the reply buffer:

• If set to zero, no reply is returned.
• If set to a value other than zero, the API return its replies into this buffer.

This parameter is mandatory for QUERY and QUERYNXT. The reply buffer is mapped according to DSECT CTTOAPI.

SCRATCH

Specifies if the output data includes SCRATCH volumes or not. Valid values are:

• Y - Include SCRATCH volumes. Default.
• N - Do not include SCRATCH volumes

This parameter can be specified just for function code QUERY.

WHERE

This parameter must be specified when using QUERY, VOLSRC, VOLACT, DSNSCR, and DSNACT functions.

Defines requested selection criteria (like the WHERE clause in SQL). The format of this input field is the same as the INCLUDE/EXCLUDE statements, which are used in the CTTRPT report utility. When using this parameter, all fields are available to the selection criteria. The area begins with a half-word counter of a number of lines, proceeded by the required number of lines, each in a field of 80 bytes.

PATH

This parameter can be specified only when using the QUERY function.

Controls the output record from the API. The field can hold one of the values listed in Control-M/Tape Control Table (TCT).

OPTIONS

This parameter must be specified when using VOLSRC, VOLACT, DSNSCR, and DSNACT functions. The syntax of this parameter is:

For VOLSCR:

DSNSCR - {DEFERRED|IMMEDIATE}

If DEFERRED is specified, the volume takes the status of PENDING SCRATCH and is the default value for this function.

For VOLACT:

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

The default value for this function is 0 days.

OPENUPD

Must be set to Y (to open the database for updating) with VOLSCR, VOLACT, DSNSCR, or DSNACT functions.

REALENV

This parameter can be specified only for the START function.

Specifies whether to use the real-time environment or to build a new environment. Valid values are:

• Y - Use the real-time environment. It is valid as long as Control-M/Tape is active. Default.
• N - Load a new Control-M/Tape environment.

TRACELVL

Specifies which Control-M/Tape trace level to turn on.

This variable must point to an area one byte in length. Valid values are according to Control-M/Tape trace level values. In order to turn off the trace level, the area should contain 0. This parameter can be specified only for the START function, which loads the environment, and is applicable when REALENV=N.

MF

Specifies the form of the macro. Valid values are:

• E - Execute form
• L - List form

SSNAME

This parameter can be specified only when using the START function. This parameter is relevant only if the real-time environment is accessed (REALENV=Y).

Specifies the Control-M/Tape. Optional. Valid values are:

• blank

  Use the Control-M tape associated with the API subsystem (same as not specifying this parameter.) Default.

• <ssname>

  Use the Control-M/Tape associated with the subsystem name specified.

• ABOV

  Use one step up from the current subsystem name of the API (use the next Control-M/Tape release).

• BELW

  Use one step down from the current subsystem name of the API (use the preceding Control-M/Tape release).

  Table 238 CTTAPI Function Values

START

Initialize the API environment.

END

Close the API environment

QUERY

Start query based on selection criteria specified in the WHERE parameter from the Media database

QUERYNXT

Get the next record query based on selection criteria specified in the WHERE parameter from the Media database

VOLSCR

Scratch a volume based on a request specified in the OPTION parameter. The volumes to be scratched are specified in the WHERE parameter.

VOLACT

Change the expiration of volume based on a request specified in the OPTION parameter. The volumes to be modified are specified in the WHERE parameter.

DSNSCR

Scratch a data set based on a request specified in the OPTION parameter. The data sets to be scratched are specified in the WHERE parameter.

DSNACT

Change the expiration of a data set based on a request specified in the OPTION parameter. The data sets to be modified are specified in the WHERE parameter.

ALL

Used only by a Resolve SRM for Tape project. The entire Media database is read sequentially. One output record is returned for each data set of each volume.

This was developed in the first phase of the API.

DS

The program read data set records using the data set index. One output record is returned for each dataset record in the Media database. The volume information is not filled in the output record.

DS/FVOL

The program reads data set records using the data set index. One output record is returned for each data set record in the Media database. The output record holds the data set information along with the first volume of the data set.

DS/AVOL

The program reads data set records using the data set index. One output record is returned for each data set of each volume. The output record holds the data set information along with the volume information.

VOL

The program reads volume records using the volume index. One output record is returned for each volume record in the Media database. The data set information is not filled in the output record.

VOL/FDS

The program reads volume records using the volume index. One output record is returned for each volume record in the Media database. The output record holds the volume information along with the first data set that resides on the volume.

VOL/ADS

The program reads volume records using the volume index. One output record is returned for each volume and a data set that resides on the volume. The output record holds the volume information along with the data set information.