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 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-EVALUATERESP 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-IFOther 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-IFREWRITE, 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-IFA 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-EXECProduction 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 UPDATEandREWRITEorDELETEshort. - Do not wait for terminal input, an HTTP call, or another slow service while holding an update lock.
- For RLS files, review
NOSUSPEND,RECORDBUSY, andLOCKEDbehavior 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, andENDFILEseparately from infrastructure failures. - Capture
RESPandRESP2without 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.
