COBOL File Organization

File organization in COBOL defines how records are stored and how you can access them: in order only (sequential), by a key (indexed), or by relative record number (relative). This page explains each type, how they map to mainframe VSAM, and when to use them.

Explain Like I'm Five: What Is File Organization?

Imagine a stack of papers. If you can only take the top sheet each time and add new sheets on top, that’s like sequential: you go in one order. If every sheet has a number and you have an index that says "sheet 42 is in this drawer," you can jump straight to 42—that’s indexed. If the papers are in slots 1, 2, 3, and you can say "give me slot 5," that’s relative. The organization is the rule that says how the file is arranged and how you’re allowed to ask for records.

Organization Types and Access

COBOL supports three main organization types: SEQUENTIAL, INDEXED, and RELATIVE. The ORGANIZATION clause in the SELECT statement determines what access modes are allowed and how the runtime (and on z/OS, VSAM) stores the data.

Sequential Organization

With ORGANIZATION IS SEQUENTIAL, records are stored in the order they are written. You can only access them in that same order: READ gets the next record, WRITE adds to the end. There is no "read record 10" or "read by key." Sequential files are simple and efficient for batch jobs that process an entire file from start to finish—reading an input file or writing a report file. On the mainframe, sequential files are often implemented as physical sequential (PS) or QSAM; they can also be backed by VSAM ESDS (Entry-Sequenced Data Set), which keeps records in entry order.

1
2
3
4
5
6
7
8
9
10
11
12
13
       FILE-CONTROL.
           SELECT TRANSACTION-FILE
               ASSIGN TO TRANFILE
               ORGANIZATION IS SEQUENTIAL
               ACCESS MODE IS SEQUENTIAL
               FILE STATUS IS WS-STATUS.
 
       DATA DIVISION.
       FD TRANSACTION-FILE.
       01 TRANSACTION-RECORD.
           05 TRAN-ID    PIC 9(8).
           05 TRAN-AMT   PIC 9(9)V99.
           05 TRAN-DATE  PIC 9(8).

ACCESS MODE IS SEQUENTIAL is the only option for sequential organization. You OPEN INPUT or OUTPUT (or EXTEND), then READ or WRITE in order. REWRITE and DELETE are not used for standard sequential files.

Indexed Organization

With ORGANIZATION IS INDEXED, each record has a primary key. The system (or VSAM) maintains an index so records can be retrieved by key or processed in key order. You can use ACCESS MODE SEQUENTIAL (next record in key order), RANDOM (read by key), or DYNAMIC (mix of both). RECORD KEY identifies the primary key; ALTERNATE RECORD KEY can define alternate indexes for different orderings. On the mainframe, indexed files are typically VSAM KSDS (Key-Sequenced Data Set).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
       FILE-CONTROL.
           SELECT CUSTOMER-FILE
               ASSIGN TO CUSTFILE
               ORGANIZATION IS INDEXED
               ACCESS MODE IS RANDOM
               RECORD KEY IS CUST-ID
               ALTERNATE RECORD KEY IS CUST-NAME
               FILE STATUS IS WS-STATUS.
 
       FD CUSTOMER-FILE.
       01 CUSTOMER-RECORD.
           05 CUST-ID    PIC 9(6).
           05 CUST-NAME  PIC X(30).
           05 CUST-BAL   PIC 9(9)V99.

RECORD KEY must match a field in the record; it is usually unique. With ACCESS MODE RANDOM you set the key in the record buffer and issue READ to get that record. With SEQUENTIAL you READ next in key order. With DYNAMIC you can START at a key, then READ NEXT, or READ by key. REWRITE updates the last record read; DELETE deletes it. You cannot change the primary key between READ and REWRITE.

Relative Organization

With ORGANIZATION IS RELATIVE, each record is identified by relative record number (1, 2, 3, ...). You can READ, WRITE, or REWRITE a specific record by setting the relative key and issuing the appropriate verb. ACCESS MODE can be SEQUENTIAL (next by position), RANDOM (by relative record number), or DYNAMIC. On the mainframe, relative files are typically VSAM RRDS (Relative-Record Data Set).

1
2
3
4
5
6
7
8
9
10
11
12
13
       FILE-CONTROL.
           SELECT LOOKUP-TABLE
               ASSIGN TO LOOKUP
               ORGANIZATION IS RELATIVE
               ACCESS MODE IS RANDOM
               RELATIVE KEY IS WS-REL-KEY
               FILE STATUS IS WS-STATUS.
 
       WORKING-STORAGE SECTION.
       01 WS-REL-KEY PIC 9(8).
 
       FD LOOKUP-TABLE.
       01 LOOKUP-RECORD PIC X(80).

RELATIVE KEY is a working-storage (or linkage) item that holds the relative record number. For READ you set RELATIVE KEY to the desired record number and issue READ; the record is returned. For WRITE you set RELATIVE KEY to where you want to put the record. Empty slots can exist; the exact behavior depends on the implementation and VSAM type.

Access Modes Compared

SEQUENTIAL: You only get the "next" record (or write the next). No positioning by key or number. Used with ORGANIZATION SEQUENTIAL, or with INDEXED/RELATIVE when you want to scan in order.

RANDOM: You specify which record (by RECORD KEY for indexed, or RELATIVE KEY for relative) and the system retrieves or updates that record. Used for lookups and direct updates.

DYNAMIC: You can do both—e.g. START at a key, READ NEXT for a while, then READ by a different key. Gives flexibility when the program sometimes scans and sometimes jumps.

VSAM and Mainframe Mapping

On IBM z/OS, files are often implemented with VSAM. COBOL organization maps as follows: ORGANIZATION SEQUENTIAL usually to physical sequential (PS) or QSAM, or to VSAM ESDS. ORGANIZATION INDEXED maps to VSAM KSDS (key-sequenced). ORGANIZATION RELATIVE maps to VSAM RRDS. The JCL DD statement points the logical file name to the actual dataset (e.g. a VSAM cluster). The COBOL program does not change; only the ASSIGN and dataset type change.

• ESDS (Entry-Sequenced Data Set): Records in the order they were written. Sequential access. No key; no direct access by key.
• KSDS (Key-Sequenced Data Set): Indexed by a unique key. Supports sequential, random, and dynamic access. Alternate indexes possible.
• RRDS (Relative-Record Data Set): Fixed-length slots by relative record number. Sequential, random, or dynamic access by that number.

Line-Sequential

LINE SEQUENTIAL is a variant of sequential organization used on systems with a hierarchical file system (e.g. Unix, Windows). Records are variable-length lines ending with a newline. Only sequential access is allowed. Use it when the file is a text file (one line per record) rather than fixed-length blocks. On the mainframe, standard sequential or ESDS is more common.

Step-by-Step: Choosing an Organization

1. If you only read or write in order from start to end, use ORGANIZATION IS SEQUENTIAL and ACCESS MODE IS SEQUENTIAL.
2. If you need to find or update records by a unique key, use ORGANIZATION IS INDEXED, define RECORD KEY, and choose RANDOM or DYNAMIC.
3. If you need to access by position (record 1, 2, 3, ...), use ORGANIZATION IS RELATIVE and RELATIVE KEY.
4. Create the underlying dataset (e.g. VSAM cluster) to match: sequential/ESDS, indexed/KSDS, or relative/RRDS.

Best Practices

• Match the organization to the access pattern: sequential for batch streams, indexed for keyed lookups, relative when position is the natural key.
• Always specify FILE STATUS and check it after every file I/O.
• For indexed files, keep the primary key stable; use alternate keys for other orderings if needed.
• Document whether the file is backed by VSAM and which type (ESDS/KSDS/RRDS) for operations and performance tuning.

Test Your Knowledge