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.

VSAM IDCAMS Commands: DEFINE, REPRO, LISTCAT, DELETE

A VSAM cluster usually enters a batch job through IDCAMS. One job step can define the cluster, load sorted records with REPRO, print catalog details with LISTCAT, or delete a test cluster before the next run.

Check before change.

What is IDCAMS?

IDCAMS is the z/OS program name for Access Method Services. It is commonly used to define and manage VSAM data sets and integrated catalog facility catalog entries. IBM lists tasks such as defining VSAM data sets, building alternate indexes, copying data sets, printing content, deleting data sets, listing catalog information, diagnosing catalog errors, and recovering from catalog problems.

For a developer, the most common use is simple: run EXEC PGM=IDCAMS, place commands in SYSIN, and review messages in SYSPRINT.

Where IDCAMS fits with VSAM

VSAM stores records on DASD and organizes them as KSDS, ESDS, RRDS, or LDS data sets. IBM describes VSAM records as being arranged by key, relative byte address, or relative record number, depending on the data set type. IDCAMS is the usual batch utility used to create and maintain those cataloged VSAM objects.

Basic IDCAMS JCL

//STEPIDC  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  LISTCAT ENTRIES(PROD.CUST.KSDS) ALL
/*

SYSPRINT is where you read IDCAMS messages, command echo, return codes, and catalog details. Do not skip it when a VSAM job fails. The message text usually tells you whether the issue is catalog, allocation, duplicate key, security, or record format.

IDCAMS command quick reference

Command	Use it for	Common check
DEFINE CLUSTER	Create a VSAM cluster and catalog entry.	Name, space, record size, key length, key offset, volume or SMS class.
REPRO	Load or copy data between VSAM and non-VSAM data sets.	Input sorted by key for a KSDS initial load.
LISTCAT	List catalog information for a cluster, data component, index, path, or AIX.	High-used RBA, allocation, component names, index details.
DELETE	Delete a cataloged VSAM object.	Correct cluster name and environment.
ALTER	Change selected catalog attributes.	Whether the target attribute can be changed for that object.
BLDINDEX	Build an alternate index after defining it.	Base cluster, alternate key definition, path, and upgrade behavior.
EXPORT and IMPORT	Move VSAM data and related catalog information through a portable data set.	Target catalog and naming rules.
VERIFY	Correct catalog high-used information after a VSAM data set was not closed normally.	Whether an abended update job left the cluster in an uncertain state.
DIAGNOSE	Check catalog structures such as BCS and VVDS entries.	Catalog consistency errors.

DEFINE CLUSTER example for KSDS

A KSDS uses a key field inside the record. For a customer file, the key might be a ten-byte customer number starting at byte 1. IDCAMS uses zero-based key offset on KEYS(length offset), so a key that starts at the first byte uses offset 0.

//DEFKSDS  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DEFINE CLUSTER (NAME(PROD.CUST.KSDS) -
          INDEXED -
          KEYS(10 0) -
          RECORDSIZE(100 200) -
          CYLINDERS(5 2) -
          FREESPACE(10 10) -
          CISZ(4096)) -
     DATA  (NAME(PROD.CUST.KSDS.DATA)) -
     INDEX (NAME(PROD.CUST.KSDS.INDEX))
/*

IBM notes that DEFINE CLUSTER creates the catalog entry without moving data. The load happens later, often through REPRO.

REPRO example to load a KSDS

REPRO copies records into the new VSAM cluster. For a first load into a KSDS, make sure the input records are already sorted in key order and do not contain duplicate keys.

//LOADKSDS EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//INFILE   DD DSN=PROD.CUST.SORTED,DISP=SHR
//SYSIN    DD *
  REPRO INFILE(INFILE) OUTDATASET(PROD.CUST.KSDS)
/*

If the load stops, read SYSPRINT. Duplicate keys, wrong record length, security failure, or a missing catalog entry all leave different message trails.

LISTCAT example for a cluster

LISTCAT is the safest first command when you are unsure what exists. It shows catalog information and can confirm the cluster name before a delete, copy, or application test.

//CATINFO  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  LISTCAT ENTRIES(PROD.CUST.KSDS) ALL
/*

Use it before changing a production object. The output can show whether you are looking at the cluster, data component, index component, alternate index, or path.

DELETE example for a test cluster

DELETE removes a VSAM object from the catalog. In test jobs, it is common to delete a cluster and create it again before loading fresh data. In production, use site change controls and confirm the data set name before running it.

//DELKSDS  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DELETE TEST.CUST.KSDS CLUSTER
  IF LASTCC > 8 THEN SET MAXCC = 8
/*

The IF LASTCC pattern is sometimes used in test setup so a missing old test cluster does not fail the whole job. Do not copy that pattern into production deletes without review.

VSAM data set types

Type	Access pattern	Typical use
KSDS	By key and sequential key order.	Customer, account, employee, policy, and part-master files.
ESDS	By relative byte address or entry sequence.	Append-style logs and files read in arrival order.
RRDS	By relative record number.	Fixed slot lookup by numeric record number.
LDS	Byte-addressable linear storage.	Specialized system and application use where records are not the normal unit.

Alternate index commands

When a base KSDS needs another lookup path, define an alternate index and path, then build the index with BLDINDEX. IBM notes that alternate indexes can support access by another fixed-position key, such as employee name or department code, when the base key is employee number.

//BLDAIX   EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  BLDINDEX INDATASET(PROD.CUST.KSDS) -
           OUTDATASET(PROD.CUST.NAME.AIX)
/*

Check whether the alternate index is in the upgrade set. If it is not, updates made through the base cluster may not maintain the alternate index the way the application expects.

Return-code checks

IDCAMS supports conditional processing with values such as LASTCC and MAXCC. A common test job deletes an old cluster, tolerates the missing-cluster condition, then defines a new one.

  DELETE TEST.CUST.KSDS CLUSTER
  IF LASTCC = 8 THEN SET MAXCC = 0

  DEFINE CLUSTER (NAME(TEST.CUST.KSDS) -
          INDEXED KEYS(10 0) RECORDSIZE(100 200) -
          CYLINDERS(1 1))

Use return-code handling to make setup jobs repeatable, but keep the logic narrow. A delete failure caused by security or catalog damage should not be treated the same as a harmless missing test cluster.

Common mistakes

Using the wrong key offset

KEYS(10 0) means a ten-byte key beginning at offset 0, which is the first byte of the record. Many file layouts count fields from position 1, so convert carefully.

Loading an unsorted KSDS

A KSDS initial load expects records in key order. Sort the input first and check duplicate keys before running REPRO.

Deleting by memory instead of LISTCAT

Run LISTCAT before a risky change. Similar names such as TEST.CUST.KSDS and PROD.CUST.KSDS are not mistakes you want to find after DELETE.

Forgetting the data and index components

A KSDS cluster has a data component and an index component. When you inspect catalog output, make sure you understand which entry you are reading.

Related VSAM and JCL guides

For nearby topics, read VSAM concepts, when to use KSDS, ESDS, RRDS, and LDS, DEFINE CLUSTER examples, VSAM control interval, COBOL indexed file organization, and JCL utilities.

External references

Technical notes in this refresh were checked against IBM IDCAMS catalog utility guidance, IBM Access Method Services command list, IBM defining VSAM files with DEFINE CLUSTER, and IBM VSAM data set organization notes.

FAQ

What is IDCAMS used for in VSAM?

IDCAMS is used to define, load, copy, list, alter, delete, and check VSAM data sets and catalog entries.

Which IDCAMS command creates a VSAM cluster?

DEFINE CLUSTER creates the VSAM cluster and catalog entry. For a KSDS, include key length and key offset with KEYS.

Which IDCAMS command loads records into a VSAM file?

REPRO loads or copies records. For a KSDS first load, the input should be sorted in key order.

How do I check a VSAM cluster before changing it?

Run LISTCAT ENTRIES(cluster-name) ALL and review SYSPRINT before running commands such as DELETE, ALTER, or REPRO.