What is a CICS Temporary Storage queue?

A CICS Temporary Storage (TS) queue is a named, ordered collection of data items stored temporarily in CICS-managed memory (MAIN) or on an auxiliary VSAM dataset (AUXILIARY). Programs write items with WRITEQ TS, read items by item number or sequentially with READQ TS, overwrite specific items with WRITEQ TS REWRITE, and delete the entire queue with DELETEQ TS. TS queues are used for session state that exceeds COMMAREA limits, paged report buffers, and inter-task communication.

What is the naming convention for CICS TS queue names?

TS queue names are 1-8 characters. The classic convention for user session queues is TRANSID (4 chars) + TERMID (4 chars), which creates a unique 8-character name for each user's transaction session — e.g., queue name 'EMPIA001' for transaction EMPI on terminal A001. This ensures no two users' queues clash. For shared queues (visible to multiple tasks or transactions), use a meaningful fixed name. Queue names are case-sensitive in CICS TS 3.2 and later.

What is the difference between MAIN and AUXILIARY temporary storage?

MAIN storage holds TS queue items in the CICS region's virtual memory (the TS pool in CICS DSA). It is faster but limited by available memory and is lost if the CICS region fails. AUXILIARY storage holds items in a VSAM dataset (the CICS auxiliary TS dataset, usually DFHTEMP). It is slower but persistent across CICS warm starts. Specify AUXILIARY on WRITEQ TS for data that must survive CICS restarts or for large queues that would exhaust main storage. Default is MAIN.

When should I use TS queues instead of COMMAREA for state management?

Use TS queues instead of COMMAREA when: the state data exceeds 32 KB (COMMAREA maximum); the state includes a variable number of items (browse results, shopping cart lines); the state needs to be shared between multiple different transactions; or you need to build a multi-page report buffer. Store only the TS queue name (8 chars) in the COMMAREA, and read/write the actual data from the TS queue.

CICS Temporary Storage Queues: WRITEQ TS, READQ TS, DELETEQ TS — Complete Guide

Introduction: Temporary Storage Queues in CICS

The CICS COMMAREA is limited to 32,767 bytes and is tightly coupled to one transaction and one terminal session. Many real-world CICS applications need more: a browse results set with 200 employee records, a multi-page report spanning 50 screens, or a shopping cart that accumulates items across multiple screen interactions. The CICS mechanism for all of these is the Temporary Storage (TS) queue.

A TS queue is a named, numbered collection of data items that any CICS program can write to, read from, or delete. Items are retained until explicitly deleted or until the CICS region performs a cold start. TS queues are flexible, efficient, and are one of the most commonly used CICS features in real enterprise applications.

EXEC CICS WRITEQ TS: Writing Items to a Queue

WRITEQ TS adds an item to a named TS queue. Each call to WRITEQ TS adds a new item to the end of the queue and returns the item number of the new item:

cobol

WORKING-STORAGE SECTION.
01  WS-TS-QUEUE      PIC X(8).
01  WS-TS-ITEM-NUM   PIC S9(4) COMP VALUE ZERO.
01  WS-EMP-RECORD.
    05  WS-EMP-NO    PIC X(6).
    05  WS-EMP-NAME  PIC X(30).
    05  WS-EMP-SAL   PIC S9(7)V99 COMP-3.
01  WS-EMP-LEN       PIC S9(4) COMP.
01  WS-RESP          PIC S9(8) COMP VALUE ZERO.

PROCEDURE DIVISION.
BUILD-TS-QUEUE-NAME.
    STRING EIBTRNID DELIMITED SIZE
           EIBTRMID DELIMITED SIZE
           INTO WS-TS-QUEUE.

WRITE-TO-TS.
    MOVE LENGTH OF WS-EMP-RECORD TO WS-EMP-LEN

    EXEC CICS WRITEQ TS
              QUEUE(WS-TS-QUEUE)
              FROM(WS-EMP-RECORD)
              LENGTH(WS-EMP-LEN)
              ITEM(WS-TS-ITEM-NUM)
              RESP(WS-RESP)
              RESP2(WS-RESP2)
    END-EXEC

    EVALUATE WS-RESP
        WHEN DFHRESP(NORMAL)
            *> WS-TS-ITEM-NUM now contains the item number assigned
            CONTINUE
        WHEN DFHRESP(NOSPACE)
            MOVE 'TS STORAGE FULL.' TO WS-ERR-MSG
            PERFORM LOG-ERROR
        WHEN OTHER
            PERFORM HANDLE-TS-ERROR
    END-EVALUATE.

WRITEQ TS Options

Option	Purpose
QUEUE	TS queue name (1-8 chars)
FROM	Data area to write
LENGTH	Length of data to write
ITEM	Halfword field to receive item number of new item
MAIN	Store in CICS main memory (default)
AUXILIARY	Store in VSAM auxiliary TS dataset
REWRITE	Overwrite an existing item (must specify ITEM)
NOSUSPEND	Return NOSPACE instead of waiting if storage is full
RESP	Capture response code

EXEC CICS READQ TS: Reading Items from a Queue

READQ TS retrieves a specific item from a TS queue by item number, or reads the next item sequentially:

cobol

*── Read item 1 (the first item) ────────────────────────────────
READ-TS-ITEM-ONE.
    MOVE 1 TO WS-TS-ITEM-NUM
    MOVE LENGTH OF WS-EMP-RECORD TO WS-EMP-LEN

    EXEC CICS READQ TS
              QUEUE(WS-TS-QUEUE)
              INTO(WS-EMP-RECORD)
              LENGTH(WS-EMP-LEN)
              ITEM(WS-TS-ITEM-NUM)
              RESP(WS-RESP)
    END-EXEC.

*── Read the next item (sequential read) ─────────────────────────
READ-TS-NEXT.
    EXEC CICS READQ TS
              QUEUE(WS-TS-QUEUE)
              INTO(WS-EMP-RECORD)
              LENGTH(WS-EMP-LEN)
              NEXT
              RESP(WS-RESP)
    END-EXEC

    IF WS-RESP = DFHRESP(ITEMERR)
        *> No more items — end of queue
        MOVE 'Y' TO WS-EOF-FLAG
    END-IF.

READQ TS responses to check:

DFHRESP Constant	Meaning
NORMAL	Item retrieved successfully
QIDERR	Queue name does not exist
ITEMERR	Item number does not exist or sequential read past end
LENGERR	INTO area smaller than the stored item

When using NEXT, CICS maintains an internal browse cursor per queue per task. Each READQ TS NEXT advances the cursor by one item.

Overwriting a Queue Item: REWRITE

The REWRITE option overwrites an existing item in place rather than adding a new one. This is essential for updating a header record or status item in the queue without deleting and rebuilding the whole queue:

cobol

*── Update item 1 (queue header) with current page info ─────────
UPDATE-QUEUE-HEADER.
    MOVE 1 TO WS-HEADER-ITEM-NUM
    MOVE WS-CURRENT-PAGE TO WS-HEADER-CURRENT-PAGE
    MOVE WS-TOTAL-PAGES  TO WS-HEADER-TOTAL-PAGES
    MOVE LENGTH OF WS-QUEUE-HEADER TO WS-HEADER-LEN

    EXEC CICS WRITEQ TS
              QUEUE(WS-TS-QUEUE)
              FROM(WS-QUEUE-HEADER)
              LENGTH(WS-HEADER-LEN)
              ITEM(WS-HEADER-ITEM-NUM)
              REWRITE
              RESP(WS-RESP)
    END-EXEC.

The REWRITE item must exist. If you specify an item number that does not exist, CICS returns ITEMERR.

EXEC CICS DELETEQ TS: Deleting a Queue

DELETEQ TS removes the entire queue (all items) from CICS storage. Individual items cannot be deleted — only the whole queue. Always delete TS queues when they are no longer needed to free storage:

cobol

DELETE-SESSION-QUEUE.
    EXEC CICS DELETEQ TS
              QUEUE(WS-TS-QUEUE)
              RESP(WS-RESP)
    END-EXEC

    *── QIDERR is acceptable — queue may already be deleted ──────
    IF WS-RESP NOT = DFHRESP(NORMAL)
    AND WS-RESP NOT = DFHRESP(QIDERR)
        PERFORM LOG-DELETEQ-ERROR
    END-IF.

Practical Pattern 1: Session State Beyond 32 KB

When a transaction's state data is too large for a COMMAREA, store it in a TS queue and keep only the queue name in the COMMAREA:

cobol

*── COMMAREA (small — just the queue name) ───────────────────────
01  WS-COMMAREA.
    05  WS-CA-TS-QUEUE   PIC X(8).
    05  WS-CA-CURRENT-PG PIC 9(4).
    05  WS-CA-TOTAL-PGS  PIC 9(4).

*── Large session state stored in TS queue ───────────────────────
01  WS-SESSION-STATE.
    05  WS-SS-USER-ID    PIC X(8).
    05  WS-SS-FILTER     PIC X(40).
    05  WS-SS-SORT-KEY   PIC X(4).
    05  WS-SS-RESULTS OCCURS 500 TIMES.
        10  WS-SS-EMP-NO   PIC X(6).
        10  WS-SS-EMP-NAME PIC X(30).

*── On first entry: build results, write to TS ───────────────────
FIRST-ENTRY.
    PERFORM BUILD-RESULTS-IN-WS-SESSION-STATE
    STRING EIBTRNID DELIMITED SIZE
           EIBTRMID DELIMITED SIZE
           INTO WS-CA-TS-QUEUE
    EXEC CICS WRITEQ TS
              QUEUE(WS-CA-TS-QUEUE)
              FROM(WS-SESSION-STATE)
              LENGTH(LENGTH OF WS-SESSION-STATE)
              ITEM(WS-TS-ITEM)
    END-EXEC
    MOVE 1 TO WS-CA-CURRENT-PG
    EXEC CICS RETURN TRANSID(EIBTRNID)
                     COMMAREA(WS-COMMAREA)
                     LENGTH(LENGTH OF WS-COMMAREA)
    END-EXEC.

*── On re-entry: read state from TS, display requested page ──────
RE-ENTRY.
    MOVE DFHCOMMAREA TO WS-COMMAREA
    EXEC CICS READQ TS
              QUEUE(WS-CA-TS-QUEUE)
              INTO(WS-SESSION-STATE)
              LENGTH(LENGTH OF WS-SESSION-STATE)
              ITEM(1)
    END-EXEC
    PERFORM DISPLAY-CURRENT-PAGE.

Practical Pattern 2: Building a Paged Browse List

The classic CICS browse-and-page pattern uses a TS queue to hold all browse results, then displays one page at a time:

cobol

BUILD-BROWSE-LIST.
    *── Browse VSAM file and write all matching records to TS ────
    EXEC CICS STARTBR FILE('EMPFILE')
                      RIDFLD(WS-START-KEY) GTEQ RESP(WS-RESP)
    END-EXEC

    MOVE 0 TO WS-ITEM-COUNT
    PERFORM UNTIL WS-EOF

        EXEC CICS READNEXT FILE('EMPFILE')
                           INTO(WS-EMP-REC) RIDFLD(WS-BROWSE-KEY)
                           LENGTH(WS-EMP-LEN) RESP(WS-RESP)
        END-EXEC

        EVALUATE WS-RESP
            WHEN DFHRESP(NORMAL)
                ADD 1 TO WS-ITEM-COUNT
                EXEC CICS WRITEQ TS
                          QUEUE(WS-TS-QUEUE)
                          FROM(WS-EMP-REC)
                          LENGTH(WS-EMP-LEN)
                          ITEM(WS-TS-ITEM)
                END-EXEC
            WHEN DFHRESP(ENDFILE)
                MOVE 'Y' TO WS-EOF-FLAG
            WHEN OTHER
                MOVE 'Y' TO WS-EOF-FLAG
        END-EVALUATE

    END-PERFORM

    EXEC CICS ENDBR FILE('EMPFILE') END-EXEC
    MOVE WS-ITEM-COUNT TO WS-CA-TOTAL-ITEMS.

DISPLAY-PAGE.
    *── Calculate which items are on the current page ────────────
    COMPUTE WS-FIRST-ITEM = (WS-CA-CURRENT-PG - 1) * 12 + 1
    PERFORM VARYING WS-ROW FROM 1 BY 1 UNTIL WS-ROW > 12
        COMPUTE WS-TS-ITEM = WS-FIRST-ITEM + WS-ROW - 1
        IF WS-TS-ITEM > WS-CA-TOTAL-ITEMS
            EXIT PERFORM
        END-IF
        EXEC CICS READQ TS
                  QUEUE(WS-TS-QUEUE)
                  INTO(WS-EMP-REC)
                  LENGTH(WS-EMP-LEN)
                  ITEM(WS-TS-ITEM)
        END-EXEC
        PERFORM POPULATE-MAP-ROW
    END-PERFORM.

TS Queue Housekeeping

TS queues persist until explicitly deleted or CICS cold start. Orphaned queues (from tasks that ABENDed without running DELETEQ TS) accumulate and waste storage. Best practices:

Always include a DELETEQ TS in your transaction's exit logic (PF3 / cancel processing). Use EXEC CICS HANDLE ABEND to issue DELETEQ TS even when the task ABENDs. In CICS TS 4.1+, define TS models in the CSD to set automatic expiry times for queues.

cobol

ABEND-CLEANUP.
    *── Clean up TS queue even when ABENDing ─────────────────────
    EXEC CICS DELETEQ TS
              QUEUE(WS-TS-QUEUE)
              RESP(WS-RESP)
    END-EXEC
    EXEC CICS RETURN END-EXEC.

Key Takeaways

CICS Temporary Storage queues are the standard mechanism for storing state that exceeds COMMAREA limits, building paged browse displays, and passing large data sets between task invocations. The core command set — WRITEQ TS (add or overwrite), READQ TS (read by item or sequentially), DELETEQ TS (delete queue) — is simple. The key discipline is always deleting queues when finished and always using the transid+termid naming convention for user session queues to prevent naming collisions.

For the sequential delivery queue mechanism — Transient Data queues — continue with CICS Transient Data Queues. For the complete CICS course, visit the CICS Mastery Course.