VSAM KSDS Update

Updating a record in a VSAM Key Sequenced Data Set (KSDS) means changing the contents of an existing record without changing its key or position. You read the record (by key or sequentially), modify the data in the record area—without changing the primary key—and then issue REWRITE. The record is replaced in place in the same control interval; the key remains the same. You cannot change the primary key with REWRITE; to "change" a key you would delete the old record and write a new one with the new key. This page explains how REWRITE works, the read-then-rewrite pattern, and how update differs from insert (WRITE) and delete (DELETE).

What Is an Update (REWRITE)?

REWRITE replaces the record that was last read. So the sequence is: READ the record (so that it is "current"), change whichever fields you need in the record area (the key field must stay the same), then REWRITE record-name. VSAM writes the contents of the record area back to the same logical record position. The record length can usually stay the same (or within the same RECORDSIZE min-max); the key cannot change. So "update" here means in-place modification of the non-key data. This is efficient because the record stays in the same CI and no index structure change is needed (the key is unchanged).

The file must be open I-O. You cannot REWRITE when the file is open INPUT only. After a successful REWRITE, the record on disk (and in any buffers) is the new version; a subsequent READ by key returns the updated record.

Read-Then-REWRITE Pattern

For random update: READ the record by key (move key to RECORD KEY, READ file-name). If the read is successful, modify the record area, then REWRITE record-name. For sequential update: READ NEXT (or READ PREV) to get a record, modify it, then REWRITE record-name. In both cases the REWRITE applies to the record you just read. If you issue REWRITE without having done a successful READ (or after a READ that failed), you get a logic error. So the pattern is always: successful READ, modify record, REWRITE.

COBOL: Random Read and REWRITE

Example: read a customer by key, change the balance, then REWRITE.

1
2
3
4
5
6
7
8
9
10
11
12
13
       MOVE 'CUST000042' TO CUST-ID.
       READ CUSTFILE
           INVALID KEY
               DISPLAY 'Customer not found'
           NOT INVALID KEY
               ADD AMOUNT TO CUST-BAL
               REWRITE CUST-REC
                   INVALID KEY
                       DISPLAY 'REWRITE failed'
                   NOT INVALID KEY
                       DISPLAY 'Updated balance: ' CUST-BAL
               END-REWRITE
       END-READ.

The key (CUST-ID) is not changed; only CUST-BAL (or other non-key fields) are updated. REWRITE writes the record back. INVALID KEY on REWRITE is rare for a KSDS if you did not change the key; it might indicate an I/O or logic error.

Why the Key Cannot Change

In a KSDS, records are stored in key order. The index maps keys to control intervals. If you could change the key with REWRITE, the record would belong in a different position in the key sequence—possibly in a different CI. VSAM does not support "move" a record to a new key position via REWRITE. So REWRITE is defined to replace the record in place; the key in the record must match the key of the record you read. If you need to change the key (e.g. customer ID change), you must DELETE the old record and WRITE a new record with the new key. That is two operations and may affect alternate indexes or external references that use the old key.

Record Length and REWRITE

VSAM KSDS typically allows variable-length records within a range (RECORDSIZE(min max)). When you REWRITE, the record length (if variable) should be within that range. Shrinking or growing the record within the same CI is usually supported; if the new record is too long for the CI, VSAM may need to move it (e.g. use spanned records or split). In practice, keeping the record length the same on REWRITE avoids such issues. Check your RECORDSIZE definition and ensure the record you REWRITE does not exceed the maximum.

Update vs Insert vs Delete

Use READ then REWRITE to update an existing record in place. Use WRITE to insert a new record (key must not exist). Use DELETE to remove a record (by key for random, or after READ for sequential). So: READ + REWRITE = update; WRITE = insert; DELETE = remove. All of these require the file to be open I-O (except WRITE can also be used after OPEN OUTPUT for initial load).

Key Takeaways

• REWRITE replaces the last record read; you must READ first (random or sequential), then modify and REWRITE.
• The primary key must not change on REWRITE; to change a key, DELETE the old record and WRITE a new one.
• File must be open I-O. Only non-key fields should be changed in the record area before REWRITE.
• WRITE = insert, REWRITE = update in place, DELETE = remove.

Explain Like I'm Five

Updating is like changing what's inside a box without moving the box. You find the box (READ), take out the stuff and put in new stuff (change the record), then put the box back in the same spot (REWRITE). The box number (key) stays the same. If you want a new number on the box, you have to take the old box away (DELETE) and add a new box with the new number (WRITE).

Test Your Knowledge