COBOL file handling

COBOL reads and writes records of named files; the program never sees an operating system handle. A file is tied to the outside world in two places: a SELECT entry in the environment division, and an FD entry with its record layouts in the data division (Data division).

The SELECT entry

       ENVIRONMENT DIVISION.
       INPUT-OUTPUT SECTION.
       FILE-CONTROL.
           SELECT CUSTOMERS ASSIGN TO "customers.dat"
               ORGANIZATION IS INDEXED
               ACCESS MODE IS DYNAMIC
               RECORD KEY IS CUST-ID
               ALTERNATE RECORD KEY IS CUST-NAME WITH DUPLICATES
               FILE STATUS IS WS-STATUS.
           SELECT OPTIONAL REPORT-OUT ASSIGN TO PRINTER
               ORGANIZATION IS LINE SEQUENTIAL.
       I-O-CONTROL.
           SAME RECORD AREA FOR CUSTOMERS.

Clause	Meaning
`SELECT [OPTIONAL] file`	Names the file. `OPTIONAL` lets `OPEN INPUT` succeed on a missing file (status 05) and reads then return end of file.
`ASSIGN TO` name \| literal \| `USING` item \| `DYNAMIC` \| device	Where the file is. On z/OS the name is a DD name (`ASSIGN TO CUSTFILE` or `S-CUSTFILE`) tied by JCL; elsewhere it is a path or an environment variable (GnuCOBOL `DD_CUSTFILE`, `dd_CUSTFILE`, `CUSTFILE`) or a literal path. A mnemonic from `SPECIAL-NAMES` such as `PRINTER`, `SYSIN`, `SYSOUT` names a device.
`ORGANIZATION IS` `SEQUENTIAL` \| `LINE SEQUENTIAL` \| `RELATIVE` \| `INDEXED`	How records are stored; see below. Default: `SEQUENTIAL`. Micro Focus and GnuCOBOL add `BINARY-SEQUENTIAL`; the 2023 standard adds `LINE SEQUENTIAL`.
`ACCESS MODE IS` `SEQUENTIAL` \| `RANDOM` \| `DYNAMIC`	How the program asks for records. Dynamic lets one program switch between random reads and `READ NEXT`.
`RECORD KEY IS` item	The unique primary key of an indexed file (an item in the record, or a split key in 2002 with `SOURCE IS`).
`ALTERNATE RECORD KEY IS` item [`WITH DUPLICATES`]	An extra key; duplicates allowed or not.
`RELATIVE KEY IS` item	The record number of a relative file: an unsigned integer item outside the record.
`FILE STATUS IS` item	A two-character item set after every I/O statement (status codes below). Micro Focus allows a second item for extended status.
`LOCK MODE IS` `MANUAL` \| `AUTOMATIC` [`WITH LOCK ON [MULTIPLE] RECORDS`] and `SHARING WITH` `ALL OTHER` \| `NO OTHER` \| `READ ONLY`	Record locking and file sharing between processes (2002; Micro Focus, GnuCOBOL, Acu earlier).
`RESERVE n AREAS`	Buffers. Ignored by many compilers.
`PADDING CHARACTER`, `RECORD DELIMITER`, `COLLATING SEQUENCE`	Sequential-file details and key order.
`I-O-CONTROL`: `SAME [RECORD \| SORT \| SORT-MERGE] AREA FOR`, `RERUN`, `APPLY WRITE-ONLY`, `MULTIPLE FILE TAPE`	Buffer sharing and checkpoints; mostly historical.

File organizations

Organization	On disk	Access
Sequential	Records one after another. Fixed-length, or variable with a length prefix: on IBM mainframes `RECFM=F`, `FB`, `V`, `VB` (record descriptor word of 4 bytes, block descriptor word), on Unix and Windows compilers a record-length header or a newline.	Read in order, append with `EXTEND`; `REWRITE` replaces the last-read record in place.
Line sequential	Text with a line ending after each record (LF or CRLF); trailing spaces dropped on write and padded on read; some compilers expand tabs and check for control characters.	Sequential only. Added to the standard in 2023; long supported by Micro Focus, GnuCOBOL, Acu, RM/COBOL.
Relative	Fixed slots numbered from 1; an empty slot can exist.	By record number in `RELATIVE KEY`, or in order.
Indexed	An index plus data. IBM: VSAM KSDS. Micro Focus: C-ISAM style `.dat` and `.idx` pairs. GnuCOBOL: Berkeley DB, VBISAM, C-ISAM, LMDB or its own, by build option.	By key, in key order, or from a key onward; alternate keys.
Binary sequential	No record structure: bytes (Micro Focus, GnuCOBOL).	Sequential only.
Report file	A sequential file handed to the Report Writer (`REPORT IS`).	`WRITE` through `GENERATE`.
Sort and merge files	Work files described with `SD`; never opened by the program.	`SORT`, `MERGE`, `RELEASE`, `RETURN`.

The data files are not COBOL source and have no common layout: the same program on two compilers writes two different files. See Dialects and versions for the formats each compiler uses.

I/O statements

Statement	For	Condition phrases
`OPEN INPUT \| OUTPUT \| I-O \| EXTEND`	All organizations (`I-O` not for line sequential on some compilers)	none (check the status)
`READ f [NEXT \| PREVIOUS] [INTO x] [KEY IS k]`	All; `KEY` for indexed	`AT END`, `INVALID KEY`
`WRITE rec [FROM x]`	All; `ADVANCING` for printer files	`INVALID KEY` (duplicate key, full file), `AT END-OF-PAGE`
`REWRITE rec [FROM x]`	Replace the last record read	`INVALID KEY`
`DELETE f RECORD`	Relative, indexed	`INVALID KEY`
`START f KEY IS = \| > \| >= \| < \| <= k`	Relative, indexed with sequential or dynamic access	`INVALID KEY`
`CLOSE f`	All	none
`UNLOCK f`	Locked files	none
`SORT`, `MERGE`, `RELEASE`, `RETURN`	Sort-merge files	`AT END` on `RETURN`

           OPEN INPUT CUSTOMERS
           IF WS-STATUS NOT = "00"
               DISPLAY "OPEN FAILED " WS-STATUS
               STOP RUN
           END-IF
           MOVE "C1001" TO CUST-ID
           READ CUSTOMERS KEY IS CUST-ID
               INVALID KEY DISPLAY "NOT FOUND"
               NOT INVALID KEY DISPLAY CUST-NAME
           END-READ
           CLOSE CUSTOMERS

File status codes

The two characters are set after every statement on the file. The first digit is the class: 0 successful, 1 at end, 2 invalid key, 3 permanent error, 4 logic error, 5 (2002) record or file conflict, 9 implementor-defined. The second digit refines it.

Status	Meaning
`00`	Successful
`02`	Successful; a duplicate alternate key was written or read (`WITH DUPLICATES`)
`04`	Successful; record length does not match the file (sequential)
`05`	Successful; `OPTIONAL` file not present on open
`07`	Successful; `NO REWIND` or `REEL` used on a file that is not a tape
`10`	End of file (no next record)
`14`	Relative record number too big for the relative key item
`21`	Key sequence error (prime key changed on `REWRITE` or out-of-order write)
`22`	Duplicate key (write or rewrite, primary or alternate without duplicates)
`23`	Record not found (`READ` by key, `START`, `DELETE`, `REWRITE`)
`24`	Boundary violation: relative file full or a record number out of range (also sequential file full)
`30`	Permanent error with no further information
`31`	Inconsistent filename (2002)
`34`	Boundary violation on a sequential file (disk full)
`35`	File not found on `OPEN INPUT`, `I-O` or `EXTEND` (not `OPTIONAL`)
`37`	Permission denied, or the open mode is not allowed for the device
`38`	File was closed with `LOCK`
`39`	Conflict between the file’s attributes and the program’s description (record length, keys, organization)
`41`	File already open
`42`	File not open (on `CLOSE`)
`43`	`REWRITE` or `DELETE` without a preceding successful `READ` (sequential access)
`44`	Record size out of the allowed range on `WRITE` or `REWRITE`
`46`	`READ` after the end was reached, or after a failed `START` or `READ`
`47`	`READ` or `START` on a file not opened `INPUT` or `I-O`
`48`	`WRITE` on a file not opened `OUTPUT`, `I-O`, or `EXTEND`
`49`	`DELETE` or `REWRITE` on a file not opened `I-O`
`51`	Record locked by another process (2002)
`52`	End of page reached (`LINAGE`) (2002)
`57`	Bad `LINAGE` specification (2002)
`61`	File sharing failure (2002)
`91`	File not available (implementor-defined; IBM VSAM and Micro Focus use the `9x` class for run-time and system errors)

Micro Focus returns 9/n extended codes (a first digit 9 and a binary second byte) and IBM VSAM returns 9x codes with a VSAM return and feedback code; the full lists are in each vendor’s manual and are not covered here. Without a FILE STATUS item, a failing statement with no condition phrase and no declarative ends the program with a run-time error.

Declaratives and error handling

       PROCEDURE DIVISION.
       DECLARATIVES.
       CUST-ERR SECTION.
           USE AFTER STANDARD EXCEPTION PROCEDURE ON CUSTOMERS.
       CUST-ERR-1.
           DISPLAY "I/O ERROR ON CUSTOMERS: " WS-STATUS.
       END DECLARATIVES.

A declarative runs when an I/O statement on that file fails and the statement has no phrase for it, or has AT END and the error is not an end-of-file. USE AFTER ERROR, USE AFTER EXCEPTION and USE AFTER STANDARD ERROR are the same. The Report Writer uses USE BEFORE REPORTING.

Printer files and LINAGE

WRITE rec AFTER ADVANCING 2 LINES or BEFORE ADVANCING PAGE controls spacing. LINAGE IS n LINES on the FD makes the runtime count lines and sets LINAGE-COUNTER; AT END-OF-PAGE fires when the footing area is reached. Carriage-control characters (RECORDING MODE, ADV on IBM) are an operating-system convention, not part of the language.