COBOL Indexed File Organization: RECORD KEY and READ Examples

A customer inquiry screen usually cannot read a file from the first record until it finds account 000417. The program needs to place a key value in a field, issue a keyed read, and get the matching record. That is the job of COBOL indexed file organization.

Key lookup plus ordered reads.

What is a COBOL indexed file?

An indexed file stores records with one or more key fields inside the record. The prime key identifies the record, and the index gives COBOL a logical path to the data. On z/OS, this is commonly coded for a VSAM key-sequenced data set, or KSDS.

IBM documents indexed organization as a file type where each record has embedded keys and each key is associated with an index. The prime key must be unique, and COBOL uses the RECORD KEY clause in FILE-CONTROL to name that field.

When indexed organization fits

Use an indexed file when the program needs direct lookup by key and also needs to process records in key order. A batch job can read the file from the lowest customer number to the highest, while an online or inquiry-style program can read one customer directly by account number.

Need	Indexed file fit
Read one employee by employee number	Good fit because the prime key points to one record.
Print all accounts in account number order	Good fit because sequential access follows key order.
Read by department as a second path	Possible with an alternate record key when the file design supports it.
Read every record once with no key lookup	A plain sequential file may be simpler.

FILE-CONTROL for an indexed file

The indexed file definition belongs in the FILE-CONTROL paragraph. The important parts are ORGANIZATION IS INDEXED, an access mode, a RECORD KEY, and a file status field.

ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
    SELECT CUSTOMER-FILE
        ASSIGN TO CUSTKSDS
        ORGANIZATION IS INDEXED
        ACCESS MODE IS DYNAMIC
        RECORD KEY IS CUSTOMER-ID
        ALTERNATE RECORD KEY IS CUSTOMER-ZIP
            WITH DUPLICATES
        FILE STATUS IS WS-CUST-STATUS.

ACCESS MODE IS DYNAMIC lets the program switch between keyed lookup and ordered reading. Use RANDOM when the program only reads by key. Use SEQUENTIAL when the program only walks the file in key order.

Record layout example

The key field named in RECORD KEY must be part of the record description. In this example, CUSTOMER-ID is the prime key. CUSTOMER-ZIP is an alternate key that can return more than one record when duplicates are allowed.

DATA DIVISION.
FILE SECTION.
FD  CUSTOMER-FILE.
01  CUSTOMER-RECORD.
    05 CUSTOMER-ID        PIC X(10).
    05 CUSTOMER-NAME      PIC X(30).
    05 CUSTOMER-ZIP       PIC X(05).
    05 CUSTOMER-BALANCE   PIC S9(7)V99 COMP-3.
    05 FILLER             PIC X(40).

Random READ by prime key

For a direct lookup, move the wanted key value into the record key field before the READ. A status of 00 means the record was found. A status of 23 commonly means the key was not found for indexed and relative files.

MOVE '0000000417' TO CUSTOMER-ID

READ CUSTOMER-FILE
    INVALID KEY
        DISPLAY 'CUSTOMER NOT FOUND: ' CUSTOMER-ID
    NOT INVALID KEY
        PERFORM DISPLAY-CUSTOMER
END-READ

START and READ NEXT

START positions the indexed file at a key. READ NEXT then reads forward from that point. This pattern is useful for range processing, such as all customers from account 000400 upward or all keys in a department sequence.

MOVE '0000000400' TO CUSTOMER-ID

START CUSTOMER-FILE
    KEY IS GREATER THAN OR EQUAL TO CUSTOMER-ID
    INVALID KEY
        MOVE 'Y' TO WS-END-OF-FILE
END-START

PERFORM UNTIL WS-END-OF-FILE = 'Y'
    READ CUSTOMER-FILE NEXT RECORD
        AT END
            MOVE 'Y' TO WS-END-OF-FILE
        NOT AT END
            PERFORM PROCESS-CUSTOMER
    END-READ
END-PERFORM

Alternate record keys

An alternate key gives the program a second path into the same indexed file. For example, the prime key may be employee number, while an alternate key may be department. IBM notes that alternate keys can be used to access records in a sequence other than the prime-key sequence.

Alternate keys can be unique or can allow duplicates. If duplicates are allowed, the program must be written to handle more than one matching record. Do not add alternate indexes casually; each insert, delete, or key-changing update has more index work to maintain.

File status checks

Indexed files need clear file status handling because a failed keyed read is not always a program failure. A missing customer record may be a normal business case, while an open error or duplicate prime key on write should usually stop the job or return a controlled error.

Status	Meaning in common indexed-file logic
00	Successful operation.
02	Successful operation with a duplicate alternate key condition.
10	End-of-file during sequential reading.
22	Duplicate key on write or rewrite.
23	Record not found for a keyed operation.

Indexed vs sequential vs relative files

A sequential file is best when the program reads records in stored order and does not need direct lookup. A relative file is best when the record number itself is the access path. An indexed file is the normal COBOL choice when the business key matters.

Read COBOL Sequential File Organization and COBOL Relative Organization for the nearby file organization choices.

Common mistakes

Changing the prime key during REWRITE

The prime key identifies the record. Do not design update logic that changes the prime key inside a rewrite path. Delete and recreate only when the application design and recovery rules allow it.

Using random access for range work

Random access is right for one key. For a range, use START and READ NEXT. That keeps the program in key order and avoids repeated single-record calls when a sequential pass would be cleaner.

Ignoring alternate-key duplicates

If the alternate key allows duplicates, one key value can represent several records. Code the loop and stop condition carefully, especially for department, location, state, or date fields.

Related mainframe topics

For more COBOL file handling, read COBOL File Operation, COBOL File I/O Modes, COBOL File Status, COBOL Fixed and Variable Records, VSAM IDCAMS Program, and when to use VSAM KSDS, ESDS, RRDS, and LDS.

External references

Technical notes in this refresh were checked against IBM COBOL file organization documentation, IBM access mode rules, IBM VSAM indexed file coding, and IBM alternate key guidance.

FAQ

What is indexed file organization in COBOL?

It is a file organization where records contain key fields and an index provides the path to retrieve records by key or read them in key order.

What is RECORD KEY in COBOL?

RECORD KEY names the prime key field for an indexed file. The program uses that key field for direct access and ordered processing.

Can indexed files be read sequentially?

Yes. Indexed files can use sequential, random, or dynamic access. Sequential access reads records in key order.

When should I use START in COBOL?

Use START when the program needs to position an indexed file at a key before reading the next records in sequence.