ORGANIZATION, ACCESS MODE, and FILE STATUS for VSAM

ORGANIZATION tells the COBOL run time which VSAM dataset shape you intend to mimic at the language level: indexed keyed files for KSDS, sequential entry order for ESDS, or relative slots for RRDS. ACCESS MODE narrows how your PROCEDURE DIVISION may move the file cursor: purely sequential walks, random jumps by key or RRN, or DYNAMIC mixtures. FILE STATUS is the two-character thermometer you read after each I/O verb to learn whether VSAM accepted the request, reached end of file, or rejected a key lookup. Together these three clauses explain most beginner mysteries that survive compile time and explode at OPEN or first READ. This page compares the organizations, contrasts access modes for KSDS workloads, and lists frequently encountered FILE STATUS values with practical interpretations while reminding you that exact text mapping belongs to your IBM Language Environment message manual for your release.

ORGANIZATION mapped to VSAM types

LDS and other specialized VSAM uses may not appear in classic COBOL FILE-CONTROL examples because applications access them through language extensions or assembler. Mainstream batch COBOL centers on KSDS, ESDS, and RRDS, which align with the three ORGANIZATION keywords above. If someone mentions LINEAR data sets in the same breath as COBOL, expect vendor interfaces or specialized runtimes rather than textbook FILE SECTION material.

ACCESS MODE trade-offs for KSDS

• SEQUENTIAL: VSAM walks keys in order; simplest for reports; use AT END handling on READ.
• RANDOM: each READ uses current RECORD KEY value; ideal for direct lookup by business key.
• DYNAMIC: runtime switches strategies; powerful for programs that sometimes scan and sometimes fetch by key, but harder to reason about in code review.

ACCESS MODE must agree with what verbs you execute. Random READ without populating RECORD KEY first yields predictable confusion. Sequential READ after positioning with START requires understanding of how your shop uses START key comparisons. When in doubt, reproduce the smallest possible reproducer in a sandbox and step through with DISPLAY tracing before modifying production scheduling.

FILE STATUS instrumentation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
       FILE-CONTROL.
           SELECT CUSTFILE ASSIGN TO CUSTDD
               ORGANIZATION IS INDEXED
               ACCESS MODE IS RANDOM
               RECORD KEY IS CUST-KEY
               FILE STATUS IS WS-FS.
       WORKING-STORAGE SECTION.
       01  WS-FS PIC XX.
       PROCEDURE DIVISION.
           OPEN INPUT CUSTFILE
           IF WS-FS NOT = '00'
               DISPLAY 'OPEN FS=' WS-FS
               STOP RUN
           END-IF
           MOVE '0000000123' TO CUST-KEY
           READ CUSTFILE
           IF WS-FS = '23'
               DISPLAY 'NOT FOUND'
           END-IF
           CLOSE CUSTFILE
           STOP RUN.

Treat DISPLAY tracing as temporary scaffolding; replace with structured logging where your platform supports it. The sample shows branching on 23 for not found style flows; confirm the exact code for your environment because installations can map VSAM conditions differently when VSAM returns extended status through file status versus VSAM feedback area in assembler programs.

Common FILE STATUS values to memorize first

Advanced programs sometimes enable VSAM return code areas or use file handlers, but batch maintenance COBOL still lives mostly on FILE STATUS. When a status surprises you, copy the hex or character value into your incident ticket, pull the matching message ID from the LE guide, and cross-check LISTCAT for attribute mismatches. Many “random” VSAM bugs are actually OPEN parameter mismatches that manifest as odd status combinations on the first READ.

RELATIVE KEY usage pattern

For RRDS, declare RELATIVE KEY IS data-name in FILE-CONTROL and move positive integers into that data item before each random READ or WRITE. Sequential processing still updates the relative key as VSAM advances through slots. Empty slots and deleted records have VSAM-specific semantics your design document must spell out so business analysts do not assume array-like compacting behavior that VSAM does not guarantee unless programmed explicitly.

Hands-on exercises

1. Build a tiny KSDS program using ACCESS MODE IS SEQUENTIAL and log FILE STATUS until you see 10 at end of file.
2. Change the same program to RANDOM and force a not-found case; compare the status to your manual description of code 23.
3. For RRDS sample data, chart five RRNs and whether READ returns data or status for empty slots per your test results.

Explain Like I'm Five

ORGANIZATION is the rule book for how the closet of toys is sorted: by secret name tag, by arrival order, or by numbered basket slots. ACCESS MODE is how you are allowed to walk: only in line, only by jumping straight to a name tag, or both if the teacher says dynamic walking is okay today. FILE STATUS is the color light on your chest: green means the step worked, yellow means you reached the end of the line, red means the name tag you shouted is not on any toy.

Test Your Knowledge