CICS File Management

CICS file management covers how transactions read and update records in files (typically VSAM and BDAM) and how temporary data is stored in temporary storage queues. Programs use File Control commands—READ, WRITE, REWRITE, DELETE—and each file must be defined in the File Control Table (FCT). This page explains these commands, the role of the FCT, and how temporary storage fits in.

Explain Like I'm Five: What Is File Management in CICS?

Imagine CICS as a librarian. The library has filing cabinets (files). Before you can look at or change a folder, the librarian must know which cabinet you mean and whether you are allowed to read or change it. File management is the set of rules and commands: "read this folder," "add a new folder," "change this folder," "remove this folder." There is also a scratch pad (temporary storage) where you can jot things down during your visit. The librarian (CICS) keeps track of who has which folder open so two people do not change it at once.

File Control and the File Control Table (FCT)

File Control is the CICS component that handles file I/O. Every file a CICS region can access must be defined in the File Control Table (FCT). An FCT entry specifies the logical file name used in programs, the physical dataset name (e.g. VSAM cluster name), the file type (KSDS, ESDS, RRDS, etc.), and which operations are allowed: read, update (REWRITE/DELETE), add (WRITE), browse (sequential read with STARTBR/READNEXT/ENDBR), and delete. The program uses the logical file name in EXEC CICS READ FILE(name) etc.; CICS translates it to the dataset and enforces the allowed operations. If the FCT does not allow update, a REWRITE or DELETE will fail.

Reading Records: READ

EXEC CICS READ retrieves one record from a file. For keyed files (e.g. VSAM KSDS), you set the key in the RIDFLD (record identifier field) and optionally specify KEYLENGTH. The record is returned INTO a data area (or you use SET for a pointer). If you intend to update or delete the record later, you must use READ with the UPDATE option so CICS locks the record; otherwise another task could change it before you REWRITE or DELETE. The response code indicates success (NORMAL) or conditions such as NOTFND (record not found), and for optional files you can get a specific response when the file is not open. Always check the response after READ.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
       EXEC CICS READ
           FILE('ACCTFILE')
           RIDFLD(WS-ACCT-KEY)
           INTO(WS-ACCT-REC)
           UPDATE
           RESP(WS-RESP)
           RESP2(WS-RESP2)
       END-EXEC
       IF WS-RESP NOT = DFHRESP(NORMAL)
           IF WS-RESP = DFHRESP(NOTFND)
               PERFORM RECORD-NOT-FOUND
           ELSE
               PERFORM FILE-ERROR
           END-IF
       END-IF.

RIDFLD must be at least as long as the key (or the full RID for RRDS). For READ UPDATE, the same RIDFLD is used in the subsequent REWRITE or DELETE so CICS knows which record to update or remove.

Adding Records: WRITE

EXEC CICS WRITE adds a new record to the file. You supply the record content in the FROM (or INTO) area and the key (or RID) in RIDFLD. For a KSDS, the key must be unique; if a record with that key already exists, CICS typically returns DUPREC (duplicate record). For ESDS you do not supply a key; CICS may use RIDFLD to return the RBA of the new record. LENGTH and KEYLENGTH can be specified if needed. The FCT must allow add (write) for the file. After a successful WRITE, the record is in the file and can be read or updated by the same or another task according to the file type and locking rules.

Updating Records: REWRITE

REWRITE replaces an existing record. You must have read that record earlier with READ UPDATE. You then modify the data in your buffer (the INTO area from the READ) and issue EXEC CICS REWRITE FILE(name) FROM(updated-area) (and optionally LENGTH). The value in RIDFLD must not change between the READ and the REWRITE—it identifies the same record. If the record was deleted by another task after your READ, or if you did not do a READ UPDATE, REWRITE can fail (e.g. NOTFND or invalid state). REWRITE does not change the key in keyed files; to change the key you typically delete the old record and write a new one with the new key.

Removing Records: DELETE

EXEC CICS DELETE removes a record from the file. For keyed files you must have read the record with READ UPDATE first; then issue DELETE FILE(name) RIDFLD(same-key). The record is removed from the file. The FCT must allow delete for that file. After DELETE, the record is gone; any subsequent READ with that key will return NOTFND.

Browse Operations

For sequential access (e.g. "read all records in key order") you use STARTBR to position at a key or RBA, then READNEXT (or READPREV) repeatedly until you get NOTFND or reach the end. ENDBR releases the browse. RIDFLD is updated after each READNEXT/READPREV so you know the current position. Browse does not lock records for update; use READ UPDATE for a single record if you need to REWRITE or DELETE.

Temporary Storage (TS) and TS Queues

Besides files, CICS provides temporary storage: named queues (TSQs) that can hold data for a task or across tasks. You WRITEQ TS to add items to a queue and READQ TS to read them. Queues can be task-private or shared (same queue name from different tasks). Data can be recoverable (logged) or not. Main temporary storage holds queues in memory; auxiliary temporary storage uses a backing dataset (e.g. VSAM DFHTEMP). Main is faster but limited in size and lost on region failure unless recoverable; auxiliary can hold more and survive restarts when recoverable. Use TS for work areas, lists built during a transaction, or passing data between related transactions.

Response Codes and Error Handling

Every File Control command returns a response. Use RESP and optionally RESP2 in the EXEC CICS command to capture the code; then check it. NORMAL means success. NOTFND means the record was not found (READ, REWRITE, DELETE). DUPREC means duplicate key on WRITE. Other codes indicate I/O errors, invalid state (e.g. REWRITE without READ UPDATE), or file not open. Always handle NOTFND and duplicate key where applicable and log or handle permanent errors so transactions do not leave data inconsistent.

Step-by-Step: Reading and Updating a VSAM Record

1. Set the key of the record you want in the RIDFLD area. Issue EXEC CICS READ FILE(name) RIDFLD(...) INTO(...) UPDATE RESP(...).
2. Check RESP. If NORMAL, you have the record and it is locked. If NOTFND, the record does not exist—handle (e.g. create new or return error).
3. Modify the data in the INTO area as needed. Do not change the key portion if it is part of the record.
4. Issue EXEC CICS REWRITE FILE(name) FROM(updated-area) (and RIDFLD if required). Check RESP again.
5. If you do not need to update, you can omit UPDATE on the READ or issue ENDBR if you were browsing; that releases the lock.

Step-by-Step: Writing to Temporary Storage

1. Choose a queue name (e.g. a constant or a name that includes transaction or user id for uniqueness).
2. Use EXEC CICS WRITEQ TS QUEUE(name) FROM(data) LENGTH(length) (and MAIN or AUXILIARY, and optionally REWRITE for overwriting an item).
3. To read back, use EXEC CICS READQ TS QUEUE(name) INTO(data) LENGTH(length). You can read the same queue from the same or another task if the queue is shared.
4. Optionally delete the queue with DELETEQ TS when no longer needed, or let it expire if an expiry interval is set.

Best Practices

• Always check RESP (and RESP2) after every File Control command and handle NOTFND, DUPREC, and errors explicitly.
• Use READ UPDATE only when you intend to REWRITE or DELETE; otherwise use READ without UPDATE to avoid holding locks.
• Keep the FCT in sync with the actual datasets and restrict operations (e.g. read-only) where updates are not needed.
• Use temporary storage for transient data; use files for persistent data. Prefer main TS for small, short-lived data; auxiliary for large or recoverable queues.
• Document which files and queues a transaction uses and in what order to avoid deadlocks and simplify problem determination.

Test Your Knowledge