Record Input/Output

You can open a file with the APPEND option of the ENVIRONMENT attribute to add new records to the end of an existing sequential file. This overrides the default action of PL/I, which is to create a new version of an existing file when the existing file is opened for output. For example:

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

This OPEN statement opens the file BIRD_FILE and positions it at its current end-of-file. The WRITE statement adds a new record at the end of the file.

The ENVIRONMENT option SUPERSEDE lets you create a new version of a file each time you write it, simultaneously deleting an existing version. By default, each time a specific file is written, PL/I gives it a new version number and does not replace the existing version. For example:

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

This OPEN statement opens the file CONTROL.DAT;1. If this file already exists, it is deleted.

RMS supports the magnetic tape structure defined by ANSI X3.27-1977, the Magnetic Tape Labels and File Structure for Information Interchange. The tapes are encoded in ASCII format and can be processed on 9-track tape drives only.

The INITIALIZE command writes a label on the tape in the required format. A tape created on an OpenVMS system can be read on another system that supports the same tape label format.

When an existing magnetic tape file is opened, it is by default rewound, if necessary, and positioned at its beginning. This positioning can be overridden in the following ways:

By default, when a file is closed, the tape remains positioned after the last record that was read or written. The ENVIRONMENT option REWIND_ON_CLOSE can override this action and position the tape at its beginning.

While the file is open, the program can call the REWIND built-in subroutine to rewind the tape to its beginning.

For example:

DECLARE TAPEFILE FILE;

OPEN FILE (TAPEFILE) OUTPUT RECORD ENVIRONMENT(APPEND);
WRITE FILE (TAPEFILE) FROM (NEWREC);
⋮
CLOSE FILE(TAPEFILE) ENVIRONMENT (REWIND_ON_CLOSE);
OPEN FILE(TAPEFILE) INPUT RECORD;

In this example, the file TAPEFILE is opened for output with the APPEND option. WRITE statements add new records at the end of the tape file. Then, the CLOSE statement specifies that the tape is to be rewound, and the next OPEN statement opens the file for input. The first READ statement reads the first record in the file.

On a magnetic tape, a block is a unit consisting of an integral number of records. Because of the control information needed to separate records on a tape, operations on a tape can be improved by blocking.

To create a blocked tape file, you must open it with the ENVIRONMENT option BLOCK_SIZE. This option specifies the size of the blocks. RMS automatically performs the blocking necessary. For example:

OPEN FILE(TAPEFILE) ENVIRONMENT(
                     BLOCK_SIZE (2048),
                     MAXIMUM_RECORD_SIZE (512),
                     FIXED_LENGTH_RECORDS);
WRITE FILE(TAPEFILE) FROM (BIG_RECORD);

Following this opening, each WRITE statement writes a single record; the file system buffers the records until it accumulates four records and then transfers them, blocked, to the tape volume.

The BLOCK_SIZE option, if specified, is ignored when the output file is not a magnetic tape device. Thus, if you create and test a program that writes to a magnetic tape, you can test the program's output on a disk device; PL/I ignores the block size.

When a blocked magnetic tape file is read, RMS determines the block size from the tape itself, and deblocks the file as individual records are read.

If a tape file is opened with the ENVIRONMENT option BLOCK_IO, the file can be read or written in terms of blocks. The size of a block is determined by the value of the BLOCK_SIZE option. Each I/O operation transfers the specified number of bytes. For example:

OPEN FILE (TAPEFILE) ENV (BLOCK_IO,BLOCK_SIZE(2048));
READ FILE (TAPEFILE) INTO (READBUF);

These statements open the file TAPEFILE and read a 2048-byte block of data into the program variable READBUF. When a file is opened with the BLOCK_IO option, RMS does not block or deblock records. Your program must perform all necessary blocking and deblocking.

When a file is opened for block I/O, the program can advance the tape or move it backward a specified number of blocks by calling the SPACEBLOCK built-in subroutine. For example:

CALL SPACEBLOCK(TAPEFILE,3);

This call advances the file TAPEFILE forward three blocks. The SPACEBLOCK built-in subroutine is described in Chapter 9, File-Handling Built-In Subroutines.

The ANSI standard X3.27-1977 for magnetic tapes allows any of the following combinations of tape files:

When more than one tape volume is required to contain a file or files, the tapes constitute a volume set. The OpenVMS system processes volume sets as follows:

Normally, RMS requests new volumes automatically. However, a PL/I program can request that the next volume in a volume set be mounted, for either an input or an output operation, by calling the NEXT_VOLUME built-in subroutine. The NEXT_VOLUME subroutine is described in Chapter 9, File-Handling Built-In Subroutines.

The physical process of volume switching, whether the switching is performed automatically by RMS or as a result of a call to the NEXT_VOLUME built-in subroutine, is transparent to the PL/I program. As a user, you may wish to function as an operator to receive the volume switching requests and to mount the volumes yourself. For a description of the procedure for handling volume switching, see the OpenVMS DCL Dictionary.

The MAXIMUM_RECORD_NUMBER option specifies the largest relative record number that will be used in the file, and thus specifies the maximum number of cells that the file can have. If you do not specify a maximum record number, PL/I sets the maximum record number to zero. This permits the file to expand to any size.

For example, if a relative file will contain inventory data on 600 parts, and the part number is to be used as the file key, the MAXIMUM_RECORD_NUMBER option can be specified as follows:

DECLARE PARTS FILE ENVIRONMENT (
               MAXIMUM_RECORD_NUMBER (600));

You should realistically allow for future expansion of the file when you specify a maximum record number; the number is a permanent attribute of the file and cannot be changed. PL/I signals the KEY condition when a key value is too large.

When you specify the length of the records in a file, RMS uses the value you specify in the MAXIMUM_RECORD_SIZE option to calculate a cell size. It uses the following formulas to calculate the size:

When you select a record size for a relative file, you should try to specify a size that is no greater than the largest record that will be written. Otherwise, any unused space in each cell will be wasted. If you do not specify a maximum record size for either fixed- or variable-length records, PL/I uses the default length of 480 bytes.

A bucket is the storage unit for data in the file. Records are arranged in buckets, which consist of an integral number of physically contiguous 512-byte disk blocks. Within the bucket, records can cross block boundaries; however, records cannot cross bucket boundaries.

When RMS transfers data from a file, it transfers data a bucket at a time; thus, a large bucket size reduces the number of actual data transfers that are required. When you do not specify a bucket size, RMS uses the cell size rounded to a multiple of 512 bytes. When records are written to the file, RMS places as many records as will fit in each bucket. Excess space is wasted.

You can improve I/O performance by specifying a bucket size that is a multiple of the cell size, and by calculating whether space is being wasted. For example:

DECLARE EMP_FILE OUTPUT RECORD ENVIRONMENT (
               FIXED_LENGTH_RECORDS,
               MAXIMUM_RECORD_SIZE (80)
               BUCKET_SIZE (4) );

The file EMP_FILE will be created with 81-byte cells and buckets that have 2048 bytes (that is, four 512-byte blocks). Each bucket can contain twenty-five 81-byte cells; 23 bytes in each bucket are unused.

When you specify a maximum record size and a bucket size for a relative file, you should consult the description of the BUCKET_SIZE option in Chapter 7, Options of the ENVIRONMENT Attribute. That description contains formulas for calculating the bucket size within the limits required by RMS.

To avoid the processing overhead that occurs when a file is extended beyond an initial default allocation, you can specify the FILE_SIZE option when you create a relative file. If you specify this option, you can preallocate all the space that will ever be required for the cells in the file.

To determine the space requirements of a file, you can use the following formulas. To compute the size of the file in 512-byte blocks: display file_size = (511 + ( number_of_buckets * bytes_per_bucket ) ) / 512

To compute the number of buckets: display number_of_buckets = number_of_records / number_of_cells_per_bucket

You can also specify the CONTIGUOUS or CONTIGUOUS_BEST_TRY options in conjunction with the FILE_SIZE option to attempt to allocate all of the space for the file in contiguous disk blocks.

If you plan to add data to the file, you should specify a reasonable default extension size to reduce the number of times the file is extended. The FDL attribute FILE EXTENSION sets the extension size. The value to be assigned depends on the size of the records in the file and on the number of records that will be added to the file. The EDIT/FDL Utility calculates and assigns the correct extension size. For more information on the EDIT/FDL Utility, see Section 6.7.2, “Defining and Creating an Indexed Sequential File”.

You can also specify the extension size by using the DCL command SET FILE/EXTENSION=n. To determine the value to be assigned to the EXTENSION attribute, multiply the record size by the number of records to be added.

If you do not specify an extension size, RMS allocates the number of blocks needed for each extension.

In Example 6.1, “Creating a Relative File”, the file PARTS is opened with the KEYED and OUTPUT attributes. When this program is executed, the amount of space allocated for the file PARTS depends on the relative record numbers of the records that are written to the file. For example, if the largest record number allowed for any record in the file is 600, but the largest record number specified for a record is 200, then RMS allocates only enough space for 200 records.

When you initially populate a file and you plan to fill the entire file through the maximum record number, you can cause RMS to use either of the following techniques to allocate space for the entire file:

These techniques can optimize the throughput for the subsequent file additions, because RMS will not need to perform repeated extensions to the file as records are added.

To add or modify records in a relative file, open the file with the DIRECT and UPDATE attributes. For example, a procedure that updates the file PARTS when new stock is ordered might contain the following:

ORDER_PARTS: PROCEDURE (ORDERED_AMOUNT,PART_NUMBER);
%INCLUDE PARTLIST;      /* Declaration of PARTLIST */
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;

In this example, the procedure ORDER_PARTS receives as its parameters the order quantity and the part number. It reads the record associated with the part number from the file, adds the order quantity to the existing quantity, and rewrites the record.

You can access a relative file sequentially as well as by key. When you access the file sequentially, each READ statement returns the record in the next cell that contains a record, skipping empty cells. The following example illustrates reading a relative file sequentially:

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;

This procedure outputs the contents of the file PARTS, listing each field in the data records described by PARTLIST. The READ statement specifies the KEYTO option; the procedure outputs the value returned to the variable CHECK_NUM.

When you specify a key, you must specify both its position in the record and its length. The position is specified with respect to the beginning of the record; thus, a key that is positioned beginning in the first byte of the record has a starting position of 0, a key positioned beginning in the 21st byte has a key position of 20, and so on.

If the ENVIRONMENT option SCALARVARYING is in effect, the key size for a CHARACTER VARYING key should be 2 more than your declared maximum size; you specify a key position offset 2 from the variable base offset.

To determine the key positions for fields within a structure, you can examine the storage map in the program listing that defines the structure. The following structure definition illustrates the relationships between key field definitions and the storage map offsets:

    1           FOO: PROCEDURE;
    2    1      DECLARE 1 STATE BASED (STATE_PTR),
    3    1                  2 NAME CHARACTER (20), /*Primary key */ ❶
    4    1                  2 POPULATION FIXED BINARY(31), /*3rd alternate key */❹
    5    1                  2 CAPITAL,
    6    1                      3 NAME CHARACTER(20),
    7    1                      3 POPULATION FIXED BINARY(31),
    8    1                  2 LARGEST_CITIES(2),
    9    1                      3 NAME CHARACTER(30),
   10    1                      3 POPULATION FIXED BINARY(31),
   11    1                  2 SYMBOLS,
   12    1                      3 FLOWER CHARACTER(30), /*1st alternate key*/ ❷
   13    1                      3 BIRD CHARACTER(30); /*2nd alternate key*/ ❸
   14    1
   15    1      END FOO;

The resultant storage map shows the following:

The storage map is:

                                +-------------+
                                | Storage Map |
                                +-------------+


External Entry Points and Variables Declared Outside Procedures
---------------------------------------------------------------

 Identifier Name                 Storage     Size     Line  Attributes
 ---------- ----                 -------     ----     ----  ----------


 FOO                                                  1     ENTRY, EXTERNAL


Procedure FOO on line 1
-----------------------

 Identifier Name                 Storage     Size     Line  Attributes
 ---------- ----                 -------     ----     ----  ----------


 BIRD                                        30 BY    13    OFFSET FROM BASE IS 146 BY,
                                                            MEMBER OF STRUCTURE SYMBOLS,
                                                            CHARACTER(30) UNALIGNED, NONVARYING ❸

 CAPITAL                                     24 BY    5     OFFSET FROM BASE IS 24 BY,
                                                            MEMBER OF STRUCTURE STATE, STRUCTURE

 FLOWER                                      30 BY    12    OFFSET FROM BASE IS 116 BY,
                                                            MEMBER OF STRUCTURE SYMBOLS,
                                                            CHARACTER(30) UNALIGNED, NONVARYING ❷

 LARGEST_CITIES                              68 BY    8     OFFSET FROM BASE IS 48 BY,
                                                            MEMBER OF STRUCTURE STATE, STRUCTURE
                                                            DIMENSION

 NAME                                        30 BY    9     OFFSET FROM BASE IS 48 BY, MEMBER OF
                                                            STRUCTURE LARGEST_CITIES
                                                            CHARACTER(30), UNALIGNED, NONVARYING

 NAME                                        20 BY    6     OFFSET FROM BASE IS 24 BY, MEMBER OF
                                                            STRUCTURE CAPITAL, CHARACTER(20)
                                                            UNALIGNED, NONVARYING

 NAME                                        20 BY    3     OFFSET FROM BASE IS 0 BY, MEMBER OF
                                                            STRUCTURE STATE, CHARACTER(20)
                                                            UNALIGNED, NONVARYING ❶

 POPULATION                                  4 BY     10    OFFSET FROM BASE IS 78 BY, MEMBER OF
                                                            STRUCTURE LARGEST_CITIES
                                                            FIXED BIN(31,0), ALIGNED, PRECISION

 POPULATION                                  4 BY     7     OFFSET FROM BASE IS 44 BY, MEMBER OF
                                                            STRUCTURE CAPITAL, FIXED BIN(31,0)
                                                            ALIGNED, PRECISION

 POPULATION                                  4 BY     4     OFFSET FROM BASE IS 20 BY, MEMBER OF
                                                            STRUCTURE STATE, FIXED BIN(31,0)
                                                            ALIGNED, PRECISION
❹

 STATE                           based       176 BY   2     STRUCTURE

 SYMBOLS                                     60 BY    11    OFFSET FROM BASE IS 116 BY, MEMBER OF
                                                            STRUCTURE STATE, STRUCTURE

⋮

After you enter the EDIT/FDL command, you can specify the keys to FDL as follows:

        Enter Desired Primary        (Keyword)[-]   : KEY 0


                - Legal KEY 0 Secondary Attributes -

CHANGES                 yes/no    LEVEL1_INDEX_AREA   number
DATA_AREA               number    NAME                string
DATA_FILL               number    NULL_KEY            yes/no
DATA_KEY_COMPRESSION    yes/no    NULL_VALUE          char/num
DATA_RECORD_COMPRESSION yes/no    POSITION            number
DUPLICATES              yes/no    PROLOGUE            number
INDEX_AREA              number    TYPE                keyword
INDEX_COMPRESSION       yes/no    SEGn_LENGTH         number
INDEX_FILL              number    SEGn_POSITION       number
LENGTH                  number

   Enter KEY 0 Attribute       (Keyword)[-]   :POSITIONReturn


KEY 0
        SEG0_POSITION

Enter value for this Secondary  (0-16299)[-]   :0Return

                        - Resulting Primary Section -

KEY 0
        SEG0_POSITION          0

Continue with this Same Primary (Yes/No)[No]   :YESReturn

At this point, the menu Secondary Attributes reappears on your screen:

Enter KEY 0 Attribute        (Keyword)[-]   :LENGTHReturn

KEY 0
         SEG0_LENGTH
Enter value for this Secondary  (0-255)[-]  :20Return


                        - Resulting Primary Section -

KEY 0
         SEG0_LENGTH           20
         SEG0_POSITION         0

Continue with this Same Primary (Yes/No)[No]  :Return

At this point, you return to the first menu. To establish the keys necessary for ADDRESS.DAT, you need to step through the entire process again. In response to the prompt after the first menu, type ADD; in response to the prompt after the second menu, type KEY 1. Give KEY 1 (for example) a position of 116 and a length of 30.

Establish the third and last key the same way. Give KEY 2 a position of 146 and a length of 30. Then go back to the first menu and type VIEW in response to the prompt. A summary appears as follows:

KEY 0
        SEG0_LENGTH           20
        SEG0_POSITION         0


KEY 1
        SEG0_LENGTH           30
        SEG0_POSITION         116


KEY 2
        SEG0_LENGTH           30
        SEG0_POSITION         146

Use FDL to change information if necessary.

Table 6.2, “Key Data Types” summarizes the valid data types for keys in RMS indexed sequential files, lists the corresponding PL/I data type declaration, and shows how to specify the key data type and length to the FDL Facility.

When you define the keys in an indexed sequential file, you must assign an index number to each alternate key. The index number of the primary key is always 0; subsequent alternate key indexes are numbered 1, 2, and so on. When you create a file with the FDL Facility, you must define the keys in index number order.

When you want to access a record in an indexed sequential file by an alternate key, you specify the index number. You can specify the index number either in the INDEX_NUMBER option of ENVIRONMENT or in the INDEX_NUMBER option of a record I/O statement.

For example, to access the record for a state whose flower is MAGNOLIA in the indexed file STATE_FILE, when the current index is not 1, you must specify the index number 1, as in the following example:

READ FILE(STATE_FILE)
INTO(STATE) KEY('MAGNOLIA')
         OPTIONS(INDEX_NUMBER(1));

This READ statement reads the first record whose key in the first alternate index is MAGNOLIA and sets the current index number to 1.

When you define alternate indexes for an indexed sequential file, you can specify the following information:

These options are described in the OpenVMS File Definition Language Facility Reference Manual.

There are two techniques for optimizing the initial population (loading) of an indexed sequential file:

For details on specifying fill numbers for the FDL Facility, see the OpenVMS File Definition Language Facility Reference Manual.

To read records in an indexed sequential file in collating order by key value, open the file with the INPUT and SEQUENTIAL attributes. The following example illustrates reading the file STATE_FILE in sequential order using the primary key, that is, using the STATE.NAME field. This procedure uses the SET option of the READ statement; thus, no space is required in the records.

DECLARE STATE_PTR POINTER,
        STATE_FILE FILE,
        EOF BIT(1) INITIAL ('0'B);
DECLARE 1 STATE BASED (STATE_PTR),
          2 NAME CHARACTER(20),
          ⋮
ON ENDFILE(STATE_FILE) EOF = '1'B;

OPEN FILE(STATE_FILE) INPUT SEQUENTIAL;
READ FILE(STATE_FILE) SET(STATE_PTR);
DO WHILE (^EOF);
    PUT SKIP(2) LIST('State:',STATE.NAME);
    PUT SKIP(2) EDIT('Population:',STATE.POPULATION)
                        (A,P'ZZ,ZZZ,ZZZ');
      ⋮
    READ FILE(STATE_FILE) SET(STATE_PTR);
    END;

In this example, the procedure reads the records in the file STATE_FILE beginning with the first record in its primary index, the NAME field.

To use an alternate key to read a record in an indexed sequential file, specify the INDEX_NUMBER option on the READ statement.

For example, if a file containing data about states has as its primary key the state name, it might have alternate keys for state flowers, birds, and so on. Assuming that a field called FLOWER is the first alternate key, you could access the record for a state whose flower is MAGNOLIA by writing the following statements:

OPEN FILE(STATE_FILE) KEYED INPUT;
READ FILE(STATE_FILE) SET(STATE_PTR) KEY('MAGNOLIA')
      OPTIONS(INDEX_NUMBER(1));

The INDEX_NUMBER option followed by 1 specifies the first alternate index, the FLOWER field. The INDEX_NUMBER option is also valid on the REWRITE and DELETE statements.

You can access a file starting with an alternate index by opening the file with the INDEX_NUMBER option of the ENVIRONMENT attribute as in the following example:

OPEN FILE(STATE_FILE) SEQUENTIAL INPUT ENV(
              INDEX_NUMBER(2));
READ FILE(STATE_FILE) SET(STATE_PTR);
DO WHILE (^EOF);
    PUT SKIP EDIT(STATE.BIRD,'is the bird of',STATE.NAME)
                 (A,X,A,X,A);
    READ FILE(STATE_FILE) SET(STATE_PTR);
    END;

These statements, executed until the end-of-file is reached, access the records in the file STATE_FILE on the basis of its second alternate index, the BIRD field.

You can modify records in an indexed sequential file by opening the file with the UPDATE attribute, and using the REWRITE and DELETE statements to modify or delete records from the file.

The following example shows the correction of an invalid field in a record in the file STATE_FILE:

DECLARE (STATENAME,NEWFLOWER) CHARACTER(30) VARYING;
       ⋮
    OPEN FILE(STATE_FILE) KEYED SEQUENTIAL UPDATE;
    GET SKIP LIST(STATENAME)
                 OPTIONS (PROMPT('State: '));
    READ FILE(STATE_FILE) SET(STATE_PTR)
             KEY(STATENAME);
    GET SKIP LIST(NEWFLOWER) OPTIONS(
                 PROMPT('New state flower name: '));
    STATE.FLOWER = NEWFLOWER;
    REWRITE FILE(STATE_FILE);

The REWRITE statement rewrites the current record in the file, that is, the record that was just read with the READ SET statement.

RMS allows generic key matching; that is, it can locate a record in an indexed sequential file whose key is greater than a specified key value, or whose key is greater than or equal to a specified key value. In PL/I, you can access records by generic key using the MATCH_NEXT and MATCH_NEXT_EQUAL options on a record I/O statement.

For example, the file STATE_FILE's third alternate key is the state's population. To list all states whose populations are greater than a specified size, you could open and read the file as follows:

DECLARE EOF BIT(1) STATIC INIT('0'B),
        SIZE FIXED BIN(31);

        OPEN FILE(STATE_FILE) KEYED SEQUENTIAL ENV(
                INDEX_NUMBER(3));
        GET LIST(SIZE) OPTIONS(PROMPT('Starting population: '));
        READ FILE(STATE_FILE) SET (STATE_PTR) KEY(SIZE)
                        OPTIONS(MATCH_NEXT_EQUAL);
        DO WHILE (^EOF);
            PUT SKIP EDIT(STATE.NAME,'Population is ',
                                STATE.POPULATION)
                        (A,A,P'ZZ,ZZZ,ZZZ');
            READ FILE(STATE_FILE) SET (STATE_PTR);
            END;

In this example, the size is obtained by a GET statement. The procedure opens the file, specifying the third alternate index, the POPULATION field, in the INDEX_NUMBER option. After accessing a record by matching the first key in this index that equals or exceeds the size entered, the procedure reads the file sequentially to the end-of-file, using that index.

PL/I supports the RMS segmented key concept. Segmented keys are used when a single key cannot be made in contiguous fields of the record. The key's parts are split up over the record, or reordered within a contiguous part of the record. Segmenting the key has the advantage of using only one key to represent several fields that are always defined and sorted as a conceptual unit.

When there is a KEYFROM clause with a segmented key, PL/I takes its usual action of copying the key value into the record variable and then writing the variable directly to disk through RMS.

PL/I copies the one contiguous value to the position or positions specified by the RMS definition for the segmented key. This means it must break up the value into subfields or segments. Those fields are determined by the RMS segment sizes for the key. Thus, for a 4-segment key of 8 bytes and individual sizes of 1, 1, 4, and 2, respectively, it would break up the one contiguous key value ABCDEFGH as follows:

Then it copies each segment into its correct position in the record-the positions as specified by RMS, not your record variable structure declaration.

When RMS orders the records by the key, it reconstructs the original key value as one piece and sorts it that way. Thus the relative ordering of the segments within the record has no bearing on how the original value is sorted.

These actions are the same for nonsegmented keys in PL/I. They are treated as keys of one segment only, of the appropriate RMS-determined data type.

If you need to use segmented keys, be aware of the following considerations and constraints:

PL/I signals the KEY condition when errors occur while keys for indexed sequential files are being processed. For example, if a key value specified on a READ statement specifies a key that does not exist, or if a WRITE statement attempts to write a record using a primary key value that already exists, the KEY condition is signaled.

You can write an ON-unit to detect and correct some of the more common key errors. For an example of an ON-unit that detects whether a record with a given key value was not found or whether an attempt was made to write a record whose key duplicates the value of an existing key, see Chapter 4, The File System.