Using VSAM from a program
From COBOL a KSDS looks like an indexed file: you declare a record key and use READ, WRITE, REWRITE and DELETE. From CICS it looks like a set of file control commands. The concepts match; the syntax differs.
Batch COBOL
FILE-CONTROL.
SELECT ACCT-FILE ASSIGN TO ACCTFILE
ORGANIZATION IS INDEXED
ACCESS MODE IS DYNAMIC
RECORD KEY IS ACCT-ID
ALTERNATE RECORD KEY IS ACCT-SURNAME
WITH DUPLICATES
FILE STATUS IS WS-STATUS.
* random read
MOVE WS-WANTED-ID TO ACCT-ID
READ ACCT-FILE
INVALID KEY PERFORM 9100-NOT-FOUND
END-READ
* start at a key and read forward
MOVE WS-FROM-ID TO ACCT-ID
START ACCT-FILE KEY IS NOT LESS THAN ACCT-ID
INVALID KEY PERFORM 9100-NOT-FOUND
END-START
PERFORM UNTIL END-OF-FILE
READ ACCT-FILE NEXT
AT END SET END-OF-FILE TO TRUE
END-READ
END-PERFORM| ACCESS MODE | Use for |
|---|---|
| SEQUENTIAL | Reading the whole file in key order |
| RANDOM | Direct reads by key only |
| DYNAMIC | Both — required if you use START and READ NEXT |
The file statuses that matter here
| Status | Meaning |
|---|---|
| 00 | OK |
| 02 | Read succeeded on a non-unique alternate key |
| 10 | End of file |
| 21 | Sequence error — writing out of key order in sequential mode |
| 22 | Duplicate key on WRITE |
| 23 | Record not found |
| 24 | No space left — the file cannot extend |
| 35 | File not found at OPEN — check the DD |
| 37 / 39 | Attribute or organisation mismatch |
| 92 | Logic error, e.g. REWRITE without a preceding READ |
From CICS
* read one record EXEC CICS READ FILE('ACCTFILE') INTO(WS-REC) RIDFLD(WS-KEY) RESP(WS-RESP) END-EXEC * read with intent to update — takes a lock EXEC CICS READ FILE('ACCTFILE') INTO(WS-REC) RIDFLD(WS-KEY) UPDATE RESP(WS-RESP) END-EXEC EXEC CICS REWRITE FILE('ACCTFILE') FROM(WS-REC) RESP(WS-RESP) END-EXEC * browse a range, then always end it EXEC CICS STARTBR FILE('ACCTFILE') RIDFLD(WS-KEY) END-EXEC EXEC CICS READNEXT FILE('ACCTFILE') INTO(WS-REC) RIDFLD(WS-KEY) RESP(WS-RESP) END-EXEC EXEC CICS ENDBR FILE('ACCTFILE') END-EXEC
Batch and online at the same time
A VSAM file open for update in CICS normally cannot also be updated by a batch job — which is why batch windows exist. Where both are genuinely needed, sites use VSAM record-level sharing (RLS), which moves locking to a shared facility so CICS regions and batch can share the file safely. If your site uses RLS, the rules change and it is worth asking how.
Common mistakes
Status 92. The read establishes the position and the lock.
Holds a record lock while a human decides. It will block others and may time out.
Browse resources stay held for the life of the task and can exhaust region limits under load.
Usually fails at OPEN. Check the schedule and the file's CICS status before assuming a code problem.
What you will see at work
- 'The file is held by CICS' is a routine overnight message. The fix is usually to close the file in CICS or wait for the batch window.
- Alternate index reads use the PATH name, not the base cluster name, in the JCL.
- Test files are typically built with REPRO COUNT from production, subject to data protection rules at your site.
Key terms
Check your understanding.
Take this lesson's quiz and save your progress. Free.