EXEC CICS READ, WRITE, REWRITE, DELETE for VSAM

Data-oriented EXEC CICS commands are how online programs manipulate VSAM records: READ retrieves rows, WRITE inserts new rows, REWRITE replaces rows previously read for update, and DELETE removes rows held for update. Each command accepts parameters that must agree with the CICS file definition and the underlying DEFINE CLUSTER attributes. This page explains the most common parameters—FILE, INTO, FROM, LENGTH, RIDFLD, KEYLENGTH, UPDATE—and the RESP discipline beginners adopt after their first production NOTFOUND incident. Examples show COBol-shaped pseudocode; adjust names to your copybooks and standards. Always cross-check optional keywords such as TOKEN, SYSID, or data set positioning clauses with the Application Programming Reference for your CICS release because enterprises enable different subsets.

Verb responsibilities

READ for a keyed row

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
           MOVE CUST-ID-IN TO WS-CUST-KEY
           EXEC CICS READ
                FILE('CUSTMAS')
                INTO(WS-CUST-REC)
                LENGTH(WS-LEN)
                RIDFLD(WS-CUST-KEY)
                KEYLENGTH(10)
                RESP(WS-RESP)
           END-EXEC
           IF WS-RESP = 0
               PERFORM USE-CUSTOMER
           ELSE
               IF WS-RESP = 13
                   PERFORM NO-CUSTOMER
               ELSE
                   PERFORM READ-ERROR
               END-IF
           END-IF

Compare RESP to symbolic constants from your copybooks when available; numeric examples in training slides (such as 13 for NOTFOUND on many levels) must be verified against your CICS documentation because values are not portable trivia. LENGTH is often a fullword working storage item set to the maximum buffer size before the call and updated to the actual length returned when the command supports that pattern. If your program intentionally reads partial records, document the business meaning; otherwise set LENGTH to the full maximum to avoid truncation bugs.

READ UPDATE then REWRITE

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
           EXEC CICS READ
                FILE('CUSTMAS')
                INTO(WS-CUST-REC)
                LENGTH(WS-LEN)
                RIDFLD(WS-CUST-KEY)
                KEYLENGTH(10)
                UPDATE
                RESP(WS-RESP)
           END-EXEC
           ... validate ...
           MOVE NEW-EMAIL TO EMAIL-FIELD OF WS-CUST-REC
           EXEC CICS REWRITE
                FILE('CUSTMAS')
                FROM(WS-CUST-REC)
                LENGTH(WS-LEN)
                RESP(WS-RESP)
           END-EXEC

If the transaction ends without REWRITE or DELETE after READ UPDATE, you may hold locks longer than users tolerate. Design short units of work with SYNCPOINT boundaries consistent with your persistence story. When SYNCPOINT rolls back, the REWRITE never persisted; training materials should show both happy and rollback paths so new developers do not assume success from lack of abend messages alone.

WRITE insert

Populate RIDFLD with the new key, FROM with the record image, LENGTH with send length, then EXEC CICS WRITE. Handle duplicate key RESP by branching to an update flow or rejection message. For variable-length records, LENGTH must reflect the actual bytes you intend VSAM to store subject to maximum. Heavy insert hotspots still stress CI splits just like batch; capacity belongs in architecture reviews, not only in post-mortems.

DELETE record

DELETE follows READ UPDATE for the row you intend to remove. Some patterns read without update when business rules allow; follow your manual and standards rather than improvising. After DELETE, subsequent READs for the same key should return NOTFOUND unless duplicates exist and your program walks remaining duplicates by design.

RESP discipline patterns

• Centralize RESP mapping in a copybook or paragraph to reduce magic numbers.
• Log RESP and RESP2 together for service calls; RESP2 refines NOTFOUND versus other states in some cases.
• Map user-facing messages from RESP values with tables maintained by analysts so wording stays consistent.

HANDLE CONDITION versus explicit RESP

Legacy programs sometimes use HANDLE CONDITION to branch on ERROR or NOTFOUND globally. Modern mixed-language applications often prefer explicit RESP on each command for clarity. Your shop standard wins over personal taste. Mixing both styles in one program is difficult to debug because flow jumps to labels far from the failing EXEC block. Refactoring HANDLE programs is a modernization task worth scheduling explicitly rather than pretending it will happen accidentally during small fixes.

Token and function shipping (advanced awareness)

Some architectures ship file requests to remote regions using SYSID or token parameters. Beginners should recognize keywords when reading code even if they do not implement them yet. Misconfigured function shipping can yield NOTAUTH style responses that look like VSAM corruption until someone traces the request to the wrong region. Keep architecture phone numbers handy when those tickets appear.

Length and partial record policies

Some services intentionally read only a prefix of large rows for summary displays. If you adopt partial reads, document maximum LENGTH per API version and update mobile clients when that maximum grows. Otherwise you will ship silent truncation that compliance teams classify as a data integrity defect even though RESP stayed NORMAL.

Hands-on exercises

1. Trace one production READ UPDATE REWRITE chain on paper with arrows for SYNCPOINT.
2. Build a sandbox transaction that forces duplicate WRITE and capture RESP numerically.
3. List five RESP values your team documents as retryable for READ paths.

Explain Like I'm Five

READ is peeking at one card in a box. READ UPDATE is holding that card in your hand so nobody else can change it until you put it back or throw it away. REWRITE is putting the card back with new crayon marks. DELETE is tossing the card in recycling. WRITE is slipping a brand new card into the sorted deck in the right place. RESP is the sticker on your hand that says whether the librarian let you do it.

Test Your Knowledge