request‑type

Type of request from the CTTIOS macro. Mandatory. This parameter must always be the first parameter in the macro instructions. Valid values are:

• VOL - Volume data requests.
• DS - Dataset data requests.
• ANY - Both volume and dataset data requests.

function‑code

Function requested from the CTTIOS macro. Mandatory. This parameter must always be the second parameter in the macro instructions. Valid values are:

• Base Level API Access of the Media Databasepen the Media Database (to establish access to the Media Database).
• CLOSE - Close the Media Database (to terminate access to the Media Database).
• READ - Read data from the Media Database.
• READNEXT - Read the next data item from the Media Database.

These functions are described in more detail in Base Level API Access of the Media Database.

RC

Points to a 4‑byte area into which the CTTIOS macro places the reason code. Mandatory for all request types and function codes.

Reason codes are extremely useful when analyzing the reasons a request failed, and must be kept for debugging and error handling purposes. For explanations of reason codes, see the CTT200S message in the INCONTROL for z/OS Messages Manual.

Note: Do not confuse the reason code with the return code located in register 15.

ENV

Points to a four‑byte field that identifies the environment under which the Media Database is opened. Mandatory for Media Database OPEN requests.

The value specified in the ENV parameter is passed to user exits and is recorded in the Trace file when Media Database updates are performed.

TCT

Address of the TCT returned by the CTTTLD macro. Mandatory for Media Database OPEN requests.

REC

The buffer into which the CTTIOS macro puts data retrieved from the Media Database. Mandatory for READ requests. REC must point to an area large enough to hold the data record retrieved from the database.

RBA

Record location identifier, used to determine which record must be retrieved from the Data file.

For READ requests, this field must specify the RBA of the record to be read (or X'000100' for the first record). For READNEXT requests, the field must specify the RBA of the record preceding the record to be read (that is, the RBA returned by the previous READ/READNEXT request).

DATA

Determines whether the Data record of the specified dataset or volume must be read. Valid only when the READ or READNEXT function code (see the RBA parameter in this table) is specified. Valid values:

• Y (Yes) - Read the Data record of the specified dataset or volume.
• N (No) - Do not read the Data record.

KEY

Points to a valid index record (mapped by the CTTDVX, CTTDDX, or CTTDLX macro—Note: The index records are saved by the IOA Access Method in the file as compressed.) that serves as the key (or partial key) by which the CTTIOS macro retrieves the data record from the Media Database. Valid for READ requests. This parameter is related to parameters KEYTYPE and KEYLEN.

For READ requests, this field must specify the key (or partial key) of the record to be read. For READNEXT requests, this field must specify the key of the record preceding the record to be read (that is, the key returned by the previous READ/READNEXT request).

KEYTYPE

Type of index being used. Valid when accessing data records that may be pointed to by more than one index type (that is, dataset records).

Because volume records are indexed by only one key type (the V‑type index), do not specify this parameter when performing keyed access of volume records.

When performing keyed access dataset records, valid values are

• D—when using the D‑type key (mapped by DSECT CTTDDX). Default.
• L—when using the L‑type key (mapped by DSECT CTTDLX).

KEYLEN

Points to a four‑byte field that specifies the length of the key to be searched. The record length of the Index file is identical for all index types; therefore, this parameter is useful when using an index value shorter than the maximum index length of the file, or when using a partial key.

The KELEN parameter must be used with both full keys and partial keys. Set all necessary fields in the key area (pointed to by parameter KEY) and specify a KEYLEN parameter that includes only the desired fields. When the full key is specified, set parameter KEYLEN to the full length of the key field. This is demonstrated in the examples provided in this chapter.

The CTTIOS macro reads the entire index record into the area specified by parameter KEY. Therefore, when using this parameter, be sure to allocate sufficient storage for the entire index record, or storage overlays may occur.

MF

Macro invocation form. Valid values are:

• L (List Form)—generate all required data areas.
• E (Execute Form)—perform the request specified by the macro parameters using the data areas generated by the List form of the macro. When the Execute form of the macro is used, it must be accompanied by a pointer to the List form of the macro.

This same list form address must be used for all subsequent accesses of the Media Database using the CTTIOS macro until the Media Database is closed.

All invocations of the CTTIOS macro must access the same parameter area. It is therefore preferable to specify the combined Execute and List forms of the macro.

0

Successful execution of the request.

4

Requested record not found (READ requests) End‑of‑File (READNEXT requests).

Greater than 4

Unsuccessful execution of the request; the reason code indicates additional information about why the request failed.