MainframeMaster

CICS Data Area Management

DATA

CICS provides various mechanisms for storing and sharing data between programs and transactions. Data areas allow applications to persist information across task boundaries and enable communication between different CICS components.

Types of Data Areas

1. Temporary Storage Queue (TSQ)

Temporary Storage Queues are named data areas that can be created, accessed, updated, and deleted by CICS programs. They are ideal for passing data between different transactions or storing intermediate results.

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
WORKING-STORAGE SECTION.
01 TS-QUEUE.
    10 TS-QID PIC X(8) VALUE 'ORDDATA'.
 
PROCEDURE DIVISION.
    * Write to temporary storage
    EXEC CICS WRITEQ TS QUEUE(TS-QID)
        FROM(WS-ORDER-HEADER)
        LENGTH(LENGTH OF WS-ORDER-HEADER)
        RESP(WS-RESPONSE)
    END-EXEC.
    
    IF WS-RESPONSE NOT = DFHRESP(NORMAL)
        PERFORM HANDLE-TS-ERROR
    END-IF.

2. Transient Data Queue (TDQ)

Transient Data Queues are used for sequential data processing and interface with external systems. They can be intrapartition (within CICS) or extrapartition (to JES or other systems).

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
WORKING-STORAGE SECTION.
01 TRANS-DATA-QUEUE PIC X(16) VALUE 'ORDER-QUEUE'.
 
PROCEDURE DIVISION.
    * Write transaction data
    EXEC CICS WRITEQ TD QUEUE(TRANS-DATA-QUEUE)
        FROM(WS-TRANSACTION-RECORD)
        LENGTH(LENGTH OF WS-TRANSACTION-RECORD)
        RESP(WS-RESPONSE)
    END-EXEC.
    
    IF WS-RESPONSE = DFHRESP(NORMAL)
        DISPLAY 'Transaction queued successfully'
    ELSE
        PERFORM HANDLE-QUEUE-ERROR
    END-IF.

3. Shared Data Areas (DATABASE)

Shared data areas provide a way for multiple tasks to access common data with optional locking mechanisms. They are useful for maintaining configuration data, counters, or shared state.

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
EXEC CICS GET DATABASE DB(WS-DB-ID)
        DSNAME('CICSDATA.COUNTER')
        SET(BUFPTR)
        LENGTH(BUFLEN)
        RESP(WS-RESPONSE)
    END-EXEC.
 
    * Update shared counter
    ADD WS-INCREMENT TO COUNTER-VALUE (BUFPTR)
    
    EXEC CICS UPDATE DATABASE DB(WS-DB-ID)
        RESP(WS-RESPONSE)
    END-EXEC.

Temporary Storage Queues (TSQ)

Creating and Writing to TSQ

Write data to a temporary storage queue:

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
* Write a single record
EXEC CICS WRITEQ TS QUEUE(WS-QUEUE-ID)
    FROM(WS-RECORD-DATA)
    LENGTH(WS-RECORD-LENGTH)
    RESP(WS-RESPONSE)
END-EXEC.
 
* Write multiple records
PERFORM VARYING WS-SUB FROM 1 BY 1
    UNTIL WS-SUB > WS-RECORD-COUNT
    EXEC CICS WRITEQ TS QUEUE(WS-QUEUE-ID)
        FROM(WS-TABLE-ENTRY(WS-SUB))
        RESP(WS-RESPONSE)
    END-EXEC
    
    IF WS-RESPONSE NOT = DFHRESP(NORMAL)
        DISPLAY 'TS write failed for record ' WS-SUB
        PERFORM HANDLE-TS-ERROR
    END-IF
END-PERFORM.

Reading from TSQ

Read data from temporary storage queues:

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
* Read all records sequentially
MOVE ZERO TO WS-RECORD-NUMBER.
PERFORM UNTIL WS-TS-END
    EXEC CICS READQ TS QUEUE(WS-QUEUE-ID)
        INTO(WS-RECORD-BUFFER)
        LENGTH(WS-RECORD-LENGTH)
        ITEM(WS-RECORD-NUMBER)
        RESP(WS-RESPONSE)
        RESP2(WS-RESPONSE2)
    END-EXEC.
    
    EVALUATE WS-RESPONSE
        WHEN DFHRESP(NORMAL)
            ADD 1 TO WS-RECORD-NUMBER
            PERFORM PROCESS-RECORD
        WHEN DFHRESP(END)
            SET WS-TS-END TO TRUE
        WHEN DFHRESP(END)
            DISPLAY 'TS read error: ' WS-RESPONSE2
            SET WS-TS-END TO TRUE
    END-EVALUATE
END-PERFORM.

TSQ Item Operations

Work with specific items on TSQ:

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
* Read last item (most recent)
EXEC CICS READQ TS QUEUE(WS-QUEUE-ID)
    INTO(WS-LAST-RECORD)
    ITEM(0)
    RESP(WS-RESPONSE)
END-EXEC.
 
* Update existing item
EXEC CICS REWRITEQ TS QUEUE(WS-QUEUE-ID)
    FROM(WS-UPDATED-RECORD)
    ITEM(WS-ITEM-NUMBER)
    RESP(WS-RESPONSE)
END-EXEC.
 
* Delete specific item
EXEC CICS READQ TS QUEUE(WS-QUEUE-ID)
    DELETE ITEM(WS-ITEM-NUMBER)
    RESP(WS-RESPONSE)
END-EXEC.
 
* Delete entire queue
EXEC CICS DELETEQ TS QUEUE(WS-QUEUE-ID)
    RESP(WS-RESPONSE)
END-EXEC.

Queue Management Best Practices

1. Use Meaningful Queue Names

Choose queue names that clearly indicate purpose and scope:

  • Include transaction or application prefix
  • Use descriptive suffixes (DATA, TMP, LOG)
  • Consider using user or session identifiers

2. Manage Queue Lifecycle

Always clean up temporary storage:

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
PROCEDURE DIVISION USING WS-TRANS-ID.
    PERFORM INITIALIZE-WORK-AREA
    PERFORM PROCESS-BUSINESS-LOGIC
    PERFORM CLEANUP-AREA
    
CLEANUP-AREA.
    * Clean up any temporary queues created
    EXEC CICS DELETEQ TS QUEUE(WS-TEMP-QUEUE-ID)
        RESP(WS-RESPONSE)
    END-EXEC.
    
    * Ignore errors if queue doesn't exist
    EXEC CICS RETURN END-EXEC.

3. Handle Queue Errors Gracefully

Always check response codes and implement appropriate error handling:

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
EXEC CICS READQ TS QUEUE(WS-QUEUE-ID)
    INTO(WS-RECORD-BUFFER)
    LENGTH(WS-RECORD-LENGTH)
    RESP(WS-RESPONSE)
    RESP2(WS-RESPONSE2)
END-EXEC.
 
EVALUATE WS-RESPONSE
    WHEN DFHRESP(QIDERR)
        DISPLAY 'Queue ' WS-QUEUE-ID ' does not exist'
        PERFORM CREATE-QUEUE-IF-NEEDED
    WHEN DFHRESP(LENGERR)
        DISPLAY 'Data area too small, required length: ' WS-RESPONSE2
        PERFORM ALLOCATE-LARGER-BUFFER
    WHEN DFHRESP(END)
        DISPLAY 'End of data reached'
        SET WS-PROCESSING-COMPLETE TO TRUE
    WHEN DFHRESP(NORMAL)
        PERFORM PROCESS-RECORD
END-EVALUATE.

4. Use Appropriate Data Structures

Design efficient data structures for TSQ usage:

cobol
1
2
3
4
5
6
7
8
WORKING-STORAGE SECTION.
01 WS-TS-RECORD.
    10 WS-RECORD-ID PIC 9(6).
    10 WS-TIMESTAMP PIC X(26).
    10 WS-DATA-FIELD PIC X(200).
    10 WS-FILLER PIC X(10).
 
01 WS-TS-BUFFER PIC X(1000) VALUE SPACES.

Advanced TSQ Features

Main Storage vs Auxiliary Storage

TSQs can use main storage (high-speed) or auxiliary storage (disk):

cobol
1
2
3
4
5
6
7
8
9
10
11
* Create in auxiliary storage (default)
EXEC CICS WRITEQ TS QUEUE(WS-QUEUE-ID)
    FROM(WS-RECORD-DATA)
    AUXILIARY
END-EXEC.
 
* Create in main storage (for small, frequently accessed data)
EXEC CICS WRITEQ TS QUEUE(WS-SMALL-QUEUE-ID)
    FROM(WS-SHORT-DATA)
    MAIN
END-EXEC.

TSQ with RID

Create TSQs that are recoverable across system restarts:

cobol
1
2
3
4
5
6
7
8
9
EXEC CICS WRITEQ TS QUEUE(WS-QUEUE-ID)
    FROM(WS-RECORD-DATA)
    RID(WS-RID-AREA)
    RESP(WS-RESPONSE)
END-EXEC.
 
IF WS-RESPONSE = DFHRESP(NORMAL)
    * RID provides restart recovery capability
END-IF.

Transient Data Queues

Intrapartition TDQ

Process data within the same CICS region:

cobol
1
2
3
4
5
EXEC CICS WRITEQ TD QUEUE('INPROC')
    FROM(WS-TRANS-RECORD)
    LENGTH(LENGTH OF WS-TRANS-RECORD)
    RESP(WS-RESPONSE)
END-EXEC.

Extrapartition TDQ

Send data to JES for external processing:

cobol
1
2
3
4
5
EXEC CICS WRITEQ TD QUEUE('OUTPROC')
    FROM(WS-EXTRNL-RECORD)
    LENGTH(LENGTH OF WS-EXTRNL-RECORD)
    RESP(WS-RESPONSE)
END-EXEC.

TDQ Configuration

TDQs must be defined in CSD before use:

cobol
1
2
3
4
CEDA DEFINE TDQUEUE(ORDER-Q) GROUP(PROD-GROUP)
IN(INTRA)
OUT(EXTRA)
* In = intrapartition, Out = extrapartition

Shared Data Areas

Creating and Using Shared Data

Work with shared data areas:

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
* Get exclusive access to shared data
EXEC CICS GET DATABASE DB(WS-DB-ID)
    DSNAME('SHARED.CONFIG')
    SET(BUFPTR)
    LENGTH(BUFLEN)
    RESP(WS-RESPONSE)
END-EXEC.
 
* Update the shared configuration
IF WS-RESPONSE = DFHRESP(NORMAL)
    MOVE 'UPDATED' TO CONFIG-STATUS (BUFPTR)
    
    EXEC CICS UPDATE DATABASE DB(WS-DB-ID)
        RESP(WS-RESPONSE)
    END-EXEC.
END-IF
 
* Release the shared data
EXEC CICS FREE DATABASE DB(WS-DB-ID)
    RESP(WS-RESPONSE)
END-EXEC.

Error Handling

Common Data Area Errors

QIDERR

Queue ID error - the queue doesn't exist or name is invalid:

cobol
1
2
3
4
IF WS-RESPONSE = DFHRESP(QIDERR)
    DISPLAY 'Queue ' WS-QUEUE-ID ' not found'
    PERFORM CREATE-DEFAULT-QUEUE
END-IF.

QZERR

Queue zero error - trying to access item 0 when queue is empty:

cobol
1
2
3
4
IF WS-RESPONSE = DFHRESP(QZERR)
    DISPLAY 'Queue is empty or item does not exist'
    PERFORM HANDLE-EMPTY-QUEUE
END-IF.

LENGERR

Data length error - target area too small or source too large:

cobol
1
2
3
4
IF WS-RESPONSE = DFHRESP(LENGERR)
    DISPLAY 'Length error: RESP2=' WS-RESPONSE2
    PERFORM ALLOCATE-PROPER-SIZE-BUFFER
END-IF.

Performance Considerations

Queue Size Optimization

Optimize performance based on usage patterns:

  • Use MAIN storage for small, frequently accessed queues
  • Use AUXILIARY storage for large datasets
  • Consider reducing queue depth for high-volume applications
  • Review TSQ initialization parameters

Storage Pool Management

Monitor available storage pool sizes:

cobol
1
2
CEMT INQUIRE STORAGE POOL
* Shows current usage and available space

Monitoring and Administration

CICS Explorer Queue View

Use CICS Explorer to monitor queues:

  • TS Queue List - View all temporary storage queues
  • Queue Browser - Examine queue contents
  • Transaction Data Queue View - Monitor TDQ usage

CEMT Queue Commands

Use CEMT for queue administration:

cobol
1
2
3
4
CEMT INQUIRE TSQUEUE(*) STATUS(DISABLED)
CEMT INQUIRE TSQUEUE(MYQUEUE)
CEMT DISCARD TSQUEUE(TEMP-QUEUE)
CEMT DISCARD TSQUEUE(ALL-DEFINED)

RS Queue Quick Reference

RS Queue CICS commands

CICS Storage Management

Managing CICS storage pools

CICS Error Handling

Handling CICS errors

CICS Commands

EXEC CICS command reference