File Organizations and Input/Output

You can use sequential access with any type of file organization except stream access to a variable length record file. When you access a file sequentially, each read or write operation reads or writes the next record in the file. As you process a file sequentially, PL/I keeps track of the current record (that is, the record just read or written) and the next record (the record that follows the record just read or written).

When you access a relative file sequentially, the records are read or written in order by relative record number. In a file in which not all cells contain records, sequential input operations involve only cells that contain data records.

When you access a file randomly by key, each I/O request must contain the KEY or KEYFROM option. For a relative file, the key is the relative record number of the record to be accessed.

By default, a READ statement accesses a record based on an exact match of the key specified. In PL/I, you have the option of requesting that the READ statement match any record with an equal or greater key value, or any record with a greater key value.

When you access a file for random and sequential access, you can read records sequentially or randomly. For example, you can use a keyed READ statement to position the file at a specified record and then read or process records sequentially from that position.

You can use a record identification to access records in any type of disk file (except stream files with variable length records) that is opened for any type of access. To access records by record identification:

For example:

DECLARE LIBFILE FILE ENVIRONMENT(RECORD_ID_ACCESS),
               SAVED_ID(2) FIXED BINARY(31);
OPEN FILE(LIBFILE) DIRECT;
READ FILE(LIBFILE) KEY(MODULE_NAME) INTO(INREC)
               OPTIONS(RECORD_ID_TO(SAVED_ID));

The READ statement in this example returns the value of the record identification associated with the record whose key is indicated by the variable MODULE_NAME. The value of SAVED_ID may subsequently be used in a REWRITE or DELETE statement to modify the record.

In a file containing fixed-length records, all records have the same length. Thus, when you create a file with fixed-length records, you must specify the length of each record in the file; this size cannot be changed after the file is created.

To create a file with fixed-length records in a PL/I program, use the FIXED_LENGTH_RECORDS option of the ENVIRONMENT attribute. The MAXIMUM_RECORD_SIZE option specifies the size of each record. For example:

DECLARE FIXED_FILE FILE RECORD KEYED OUTPUT
       ENVIRONMENT(FIXED_LENGTH_RECORDS,
       MAXIMUM_RECORD_SIZE(80));

When the file FIXED_FILE is opened, its record format is established as having fixed-length 80-character records.

When a file that has fixed-length records is processed by READ and WRITE statements, the file system checks the length of the variable specified in the INTO or FROM option to see if it is the same as the length of the records in the file. If not, the ERROR condition is signaled.

PL/I supports only record I/O on variable-length record files with relative file organizations. In a file containing variable-length records, each record can have a different size. PL/I places a count field at the beginning of each record to indicate its size; however, this count field is not considered a part of the data record, nor is the length of the count field included in the size of the record.

Variable length is the default record format for PL/I files. Use the MAXIMUM_RECORD_SIZE option to specify the maximum length that any record can have. For example:

DECLARE VAR_FILE FILE RECORD OUTPUT
       ENVIRONMENT(MAXIMUM_RECORD_SIZE(80));

This declaration indicates that the file VAR_FILE has variable-length records, each with a maximum length of 80 characters.

When a file that has variable-length records is processed by READ statements, the file system checks the length of the variable specified in the INTO option to see if it is large enough to hold the record being read. If not, the ERROR condition is signaled.

Stream input and output are performed by the statements GET and PUT, respectively. Both statements can perform either list-directed or edit-directed operations.

A file has the STREAM attribute if it meets any of the following conditions:

Files declared with the STREAM attribute have the following characteristics:

Stream files contain only ASCII data. The ASCII format used to represent program data in a stream output file differs depending on the attributes given to the file. For example, the representation of character strings differs depending on the presence or absence of the PRINT attribute in the file declaration.

Unlike VAX VMS, an existing stream file cannot be reopened and accessed by the READ and WRITE statements. Stream files are true byte streams on UNIX. If READ and WRITE open a file implicitly, the attributes RECORD INPUT SEQUENTIAL and RECORD OUTPUT SEQUENTIAL are implied, respectively. These attributes are not compatible with an existing disk file created with the STREAM and OUTPUT attributes, and these operations will produce unpredictable results.

Whenever a PL/I program opens a file with the SEQUENTIAL OUTPUT attributes, PL/I creates a new stream file. By default, records are 510-byte, variable-length records. If record I/O is done on this file, you must specify the FIXED_LENGTH_RECORDS attribute (or the IBM dialect equivalent attribute).^[1]

OPEN FILE (BIRD_FILE) OUTPUT SEQUENTIAL
       TITLE ('BIRDS.DAT')
       ENVIRONMENT (APPEND, FIXED_LENGTH_RECORDS);
WRITE FILE (BIRD_FILE) FROM (NEWDATA);

OPEN FILE(CONTROL) OUTPUT RECORD TITLE('CONTROL.DAT')
       ENVIRONMENT(SUPERSEDE);

The relative file organization is suitable for files with data that can be arranged serially and be uniquely identified by an integer value, for example, a part number or an employee identification number. Within the file, records are written into cells that are numbered; there is a one-to-one correspondence between the cell number and the integer value associated with the data in the record. This number, called the relative record number, is the key by which records are accessed.

Figure 4.1, “Relative File” illustrates a relative file in which not all cells contain records. The first record written to the file was relative record number 1 (which may have been data for a part numbered 1 or an employee whose number is 1, for example). The second record written was relative record number 2. The third record written was relative record number 4; thus cell number 3 does not contain a record.

Although the cells in a relative file have the same length, the records need not be fixed-length records. However, when a record is smaller than the length of a cell, the unused space is wasted.

In PL/I, relative file organization is the default organization for files that are opened with the KEYED attribute. Thus, when a WRITE statement is directed to a file with the KEYED and OUTPUT attributes, PL/I creates a relative file.

When you initially create a relative file in a PL/I program, consider using the ENVIRONMENT option MAXIMUM_RECORD_SIZE (or the IBM dialect RECSIZE option) to maximize the efficiency of I/O operations on the file.

You can create a relative file from any existing file that is suitable for relative file organization. Example 4.1, “Creating a Relative File” illustrates copying a sequential file with fixed-length records into a relative file.

COPY_TO_RELATIVE: PROCEDURE OPTIONS(MAIN);

       %INCLUDE PARTLIST; ❶ /* Declaration of PARTLIST */
       DECLARE OLDFILE FILE INPUT RECORD SEQUENTIAL ENVIRONMENT(
               FIXED_LENGTH_RECORDS,
               MAXIMUM_RECORD_SIZE(36));
       DECLARE RECORD_NUMBER FIXED BINARY(15);
       DECLARE
               PARTS FILE OUTPUT KEYED RECORD ENVIRONMENT(
                       FIXED_LENGTH_RECORDS,  ❷
                       MAXIMUM_RECORD_SIZE(36));

       ON ENDFILE(OLDFILE) BEGIN;  ❸
               CLOSE FILE(OLDFILE), FILE(PARTS);
               STOP;
               END;

       OPEN FILE(OLDFILE), FILE(PARTS);

       DO WHILE('1'B);
               READ FILE(OLDFILE) INTO(PARTLIST);  ❹
               RECORD_NUMBER = PARTLIST.NUMBER;
               WRITE FILE(PARTS) FROM(PARTLIST) KEYFROM(RECORD_NUMBER); ❺
               END;
       END COPY_TO_RELATIVE;

The following notes are keyed to Example 4.1, “Creating a Relative File”:

Records in this file can subsequently be accessed either sequentially or by part number. To access a record by part number, you specify the number as a key. For example:

GET LIST(INPUT_NUMBER) OPTIONS(PROMPT('Part? '));
READ FILE(PARTS) INTO(PARTLIST) KEY(INPUT_NUMBER);

Here, the value entered in response to the GET statement is used as a key value to access a record in the file.

ORDER_PARTS: PROCEDURE(ORDERED_AMOUNT,PART_NUMBER);
%INCLUDE PARTLIST;                                             /* Declaration of PART.LIST */
DECLARE (ORDERED_AMOUNT,PART_NUMBER) FIXED BIN(15);
DECLARE PARTS FILE RECORD DIRECT UPDATE;

       OPEN FILE(PARTS);
       READ FILE(PARTS)                                INTO(PARTLIST)
                                       KEY(PART_NUMBER);
       PARTLIST.ON_ORDER =                                     PARTLIST.ON_ORDER +
                                               ORDERED_AMOUNT;
       REWRITE FILE(PARTS) FROM(PARTLIST);
       CLOSE FILE(PARTS);
END;

PRINT_PART: PROCEDURE OPTIONS(MAIN);
%INCLUDE PARTLIST;                                     /* Declaration of PARTLIST */

DECLARE PARTS FILE,
       CHECK_NUM FIXED;

DECLARE EOF BIT(1) ALIGNED INIT('0'B);

       OPEN FILE(PARTS) INPUT SEQUENTIAL RECORD KEYED;
       ON ENDFILE(PARTS) EOF = '1'B;
       READ FILE(PARTS) INTO(PARTLIST) KEYTO(CHECK_NUM);
       DO WHILE(^EOF);
               PUT SKIP EDIT(PARTLIST.NAME, /* Output data */
                               UNIT_PRICE,
                               IN_STOCK,
                               ON_ORDER)
                       (A,X,A,X,A,X,A);
               PUT SKIP EDIT('Relative record number',CHECK_NUM,
                       'Part number:',PARTLIST.NUMBER)
                       (X(10),A,X,F(5),A,X,A);         /* Output
                               verification */
               READ FILE(PARTS) INTO(PARTLIST) KEYTO(CHECK_NUM);
END;

PL/I signals the KEY condition when errors occur during the processing of record numbers for relative files. For example, it signals the KEY condition when the number of a record that already exists is specified in a KEYFROM option in a WRITE statement.

The following sample ON-unit shows how to detect whether a record already exists in a relative file.

ON KEY(PARTS) BEGIN;
       %INCLUDE $RMSDEF;
       /* Check for duplicate records */
       IF ONCODE() = RMS$_REX                                                          /* If duplicate */
       THEN DO;
               PUT SKIP EDIT('Part number',
                       PARTLIST.NUMBER,'exists. Reenter')
                       (A,X,A,X,A);
               GET LIST(PARTLIST.NUMBER);                                                      /* Get new value */
               GOTO GET_DATA;                                                  /* Go get other data */
               END;
       END;
GET_DATA:

In this example, the ON-unit gets symbolic names for a specific status value returned by ONCODE, from RMSDEF, a system include file provided for compatibility with VAX PL/I. The value RMS$_REX indicates that a record already exists.

In an ON-unit for the KEY condition for a relative file, ONCODE can also return the values associated with the following status codes:

The symbolic names for these status codes are included from the system include file rmsdef.in, from /usr/lib/pl1/include.