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 L‑type 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.

Note: A READNEXT operation does not automatically stop after all records matching the prefix (or any other partial key) are read. The READNEXT request stops reading, and returns a return code of 4, only when the end‑of‑file is reached. Therefore, your application program must check when the READNEXT request results in a record that does not match the partial key, and it must then stop issuing READNEXT requests.

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 merge volume and dataset records retrieved from the Media Database, instead of performing keyed accesses for every volume (or for every dataset).