CICS File Control: READ, WRITE, REWRITE, and DELETE

EXEC CICS READ UPDATE does not change a record. It retrieves the record and reserves it for a later REWRITE, DELETE, or UNLOCK. A program that treats UPDATE as a separate file command can hold a lock without completing the intended change.

CICS file control gives an application a command-level interface to VSAM and other supported files. The examples below use a KSDS named CUSTFILE and show the command sequence, response checks, and recovery points that matter in a COBOL transaction.

CICS file control commands read, add, change, and remove records while RESP, RESP2, and syncpoint handling protect the transaction.

CICS file control command map

Requirement	CICS command	Main point
Read one record	READ	Identify the record with RIDFLD; add UPDATE only when a change or delete will follow.
Add a record	WRITE	Pass the new record with FROM. A duplicate primary key normally returns DUPREC.
Change a record	READ UPDATE, then REWRITE	Keep the KSDS primary key unchanged and finish the update sequence promptly.
Remove a record	DELETE	Use a full key for a direct delete, or omit RIDFLD after READ UPDATE. ESDS records cannot be deleted.
Read sequentially	STARTBR, READNEXT, ENDBR	A browse must be started before the first READNEXT and ended when it is no longer needed.

If these commands are new to you, keep the CICS tutorial index open for related transaction topics. The VSAM data set selection guide explains when KSDS, ESDS, RRDS, and LDS organizations fit a workload.

Read a KSDS record by key

A direct READ identifies the record with RIDFLD. INTO names the application buffer. For a variable-length file, supply the correct length fields required by the file definition and installed CICS level.

       MOVE CUSTOMER-ID TO WS-CUSTOMER-KEY

       EXEC CICS READ
            FILE('CUSTFILE')
            INTO(CUSTOMER-RECORD)
            RIDFLD(WS-CUSTOMER-KEY)
            RESP(WS-RESP)
            RESP2(WS-RESP2)
       END-EXEC

       EVALUATE WS-RESP
          WHEN DFHRESP(NORMAL)
             CONTINUE
          WHEN DFHRESP(NOTFND)
             PERFORM CUSTOMER-NOT-FOUND
          WHEN OTHER
             PERFORM REPORT-FILE-ERROR
       END-EVALUATE

Use RESP and RESP2 together. RESP names the broad condition; RESP2 can identify the reason that applies to the command and resource definition. Record the file name, key in a safe display form, transaction ID, and both response values.

Write a new record

WRITE adds a record from the area named by FROM. For a KSDS, the record contains the primary key. A pre-read is usually unnecessary and introduces a race: another task can add the key between the read and the write. Issue the write and handle DUPREC.

       EXEC CICS WRITE
            FILE('CUSTFILE')
            FROM(CUSTOMER-RECORD)
            RESP(WS-RESP)
            RESP2(WS-RESP2)
       END-EXEC

       IF WS-RESP = DFHRESP(DUPREC)
          PERFORM CUSTOMER-ALREADY-EXISTS
       ELSE
          IF WS-RESP NOT = DFHRESP(NORMAL)
             PERFORM REPORT-FILE-ERROR
          END-IF
       END-IF

Other responses can include NOSPACE, NOTOPEN, NOTAUTH, IOERR, and LENGERR. The program should not translate all of them into "record not written"; operations staff need the actual condition.

Update with READ UPDATE and REWRITE

To change a record, retrieve it with the UPDATE option, modify the application buffer, and issue REWRITE. IBM documents TOKEN for associating a read-for-update with its later REWRITE, DELETE, or UNLOCK when a task has more than one outstanding update request.

       EXEC CICS READ
            FILE('CUSTFILE')
            INTO(CUSTOMER-RECORD)
            RIDFLD(WS-CUSTOMER-KEY)
            UPDATE
            RESP(WS-RESP)
            RESP2(WS-RESP2)
       END-EXEC

       IF WS-RESP = DFHRESP(NORMAL)
          MOVE WS-NEW-STATUS TO CUSTOMER-STATUS

          EXEC CICS REWRITE
               FILE('CUSTFILE')
               FROM(CUSTOMER-RECORD)
               RESP(WS-RESP)
               RESP2(WS-RESP2)
          END-EXEC
       END-IF

Do not leave a read-for-update outstanding. Complete it with REWRITE, DELETE, or UNLOCK. CICS also releases update state at a syncpoint, but using a syncpoint as routine cleanup hides a broken command sequence.

A KSDS primary key must not be altered during the rewrite. Fixed-length records must retain the defined length. Variable-length files require correct LENGTH handling and cannot exceed the maximum defined to VSAM.

Delete a record safely

CICS supports a direct keyed delete for a KSDS or RRDS. When business validation must occur first, read the record with UPDATE and then issue DELETE without RIDFLD. A record cannot be deleted from an ESDS.

       EXEC CICS READ
            FILE('CUSTFILE')
            INTO(CUSTOMER-RECORD)
            RIDFLD(WS-CUSTOMER-KEY)
            UPDATE
            RESP(WS-RESP)
            RESP2(WS-RESP2)
       END-EXEC

       IF WS-RESP = DFHRESP(NORMAL)
          AND CUSTOMER-STATUS = 'CLOSED'
          EXEC CICS DELETE
               FILE('CUSTFILE')
               RESP(WS-RESP)
               RESP2(WS-RESP2)
          END-EXEC
       ELSE
          IF WS-RESP = DFHRESP(NORMAL)
             EXEC CICS UNLOCK FILE('CUSTFILE') END-EXEC
          END-IF
       END-IF

A direct delete can name the full key in RIDFLD. When a non-unique alternate index is used, review IBM's documented DUPKEY behavior before assuming that every record with that alternate key was removed.

Browse records with STARTBR and READNEXT

READ NEXT is not the CICS syntax. A sequential browse uses STARTBR, one or more READNEXT or READPREV commands, and ENDBR. STARTBR positions the browse; it does not return the first record.

       EXEC CICS STARTBR
            FILE('CUSTFILE')
            RIDFLD(WS-CUSTOMER-KEY)
            RESP(WS-RESP)
            RESP2(WS-RESP2)
       END-EXEC

       PERFORM UNTIL WS-RESP = DFHRESP(ENDFILE)
          EXEC CICS READNEXT
               FILE('CUSTFILE')
               INTO(CUSTOMER-RECORD)
               RIDFLD(WS-CUSTOMER-KEY)
               RESP(WS-RESP)
               RESP2(WS-RESP2)
          END-EXEC

          IF WS-RESP = DFHRESP(NORMAL)
             PERFORM PROCESS-CUSTOMER
          END-IF
       END-PERFORM

       EXEC CICS ENDBR
            FILE('CUSTFILE')
       END-EXEC

Production code should distinguish ENDFILE from unexpected responses and should end an active browse on every exit path. Use REQID when one task needs multiple browses on the same file.

Record locking, recovery, and syncpoints

For a recoverable file, the unit of work determines whether changes are committed or backed out. A successful command is not the same as a durable commit. If the transaction later abends before syncpoint, CICS recovery can back out the file change.

• Keep the interval between READ UPDATE and REWRITE or DELETE short.
• Do not wait for terminal input, an HTTP call, or another slow service while holding an update lock.
• For RLS files, review NOSUSPEND, RECORDBUSY, and LOCKED behavior for the installed release.
• Use syncpoints according to the transaction's recovery design, not after every individual file command.

The broader CICS transactions guide explains how a transaction fits into online processing. File organization remains a VSAM concern; use the VSAM interview and operations reference for related record-access questions.

Common CICS file-control errors

Response	Typical meaning	Check
NOTFND	The requested record was not found.	Key value, key length, alternate path, and file contents.
DUPREC	A write attempted to add an existing key.	Business duplicate handling; do not retry the same write unchanged.
NOTOPEN	The file is not available in the required state.	CICS file resource status and associated VSAM data set.
LENGERR	The supplied or returned length is invalid for the file or buffer.	Fixed versus variable record definition, application buffer, and RESP2.
INVREQ	The option combination or file state is not valid for the request.	Command options, data set organization, browse state, and RESP2.

Production checklist

• Confirm the CICS file resource name, VSAM organization, key length, and record length.
• Handle expected conditions such as NOTFND, DUPREC, and ENDFILE separately from infrastructure failures.
• Capture RESP and RESP2 without exposing sensitive record data.
• End every browse and every read-for-update sequence on all branches.
• Test normal, missing-key, duplicate-key, file-closed, length-error, lock-contention, abend, and rollback paths.
• Verify that the transaction's syncpoint boundary matches the business unit of work.

Frequently asked questions

Is UPDATE a CICS file-control command?

No. UPDATE is an option on a read command. The program changes the returned data and then issues REWRITE.

Must DELETE always follow READ UPDATE?

No. A KSDS or RRDS record can be deleted directly with a full key. Use READ UPDATE first when the program must validate the current record or associate the delete with a token.

Can CICS delete an ESDS record?

No. IBM documents that ESDS records cannot be deleted. Choose another business technique, such as a logical status flag, when the design uses an ESDS.

What ends a CICS browse?

ENDBR explicitly ends the browse. A syncpoint or rollback can also end it, but the program should issue ENDBR when normal browse processing is complete.

IBM references

• IBM: Using CICS commands to update records
• IBM: Using CICS commands to delete records
• IBM: Sequential reading and browsing
• IBM: File-control response values

The safest update path is short and explicit: READ UPDATE, change the buffer, issue REWRITE, and inspect both response fields before the transaction reaches its syncpoint.