The CICS READQ TS statement is used to retrieve data stored in a Temporary Storage Queue (TSQ). It is stored on either main or auxiliary storage.

Points to note -

• Each TSQ can hold multiple items, which can be accessed by their assigned item numbers (e.g., 1st item, 2nd item, 3rd item, etc.).
• TSQ can read either sequentially or directly by their item number (ITEM option). Read is not destructive.

Syntax -

EXEC CICS READQ TS
     QUEUE('queue-name')
     INTO(data-area)
     LENGTH(length)
	 [NUMITEMS(number)]
     [ITEM(item-number)]
     [NEXT]
	 [SYSID(system-name)]
     [RESP(response-field)]
     [RESP2(response-field2)]
     END-EXEC.

• QUEUE('queue-name') - Specifies the name of the temporary storage queue to be read.
• INTO(data-area) - Defines the data area where the retrieved information will be stored.
• LENGTH(length) - Specifies the maximum length of data to be read from the queue.
• NUMITEMS(items-number) - Stores a number that indicates how many items there are now in the queue, after the READQ TS command is executed.
• ITEM(item-number) - Optional. Defines which item number within the queue to retrieve. If omitted, NEXT must be used.
• NEXT - Optional. Specifies that the next available item in the queue should be read sequentially.
• SYSID(system-name) - Specifies the system name to which the request is directed.
• RESP(response-variable) - Optional. It captures the response code of the READQ TS operation and used to check if the command executed successfully or encountered an error.
• RESP2(response2-variable) - Optional. It captures the response2 code of the READQ TS operation when the error occured.

How it works?

• The READQ TS command retrieves data from a specified TSQ.
• If an ITEM number is provided, that specific item is read.
• If the NEXT option is used, the next available item in the queue is retrieved.
• The retrieved data is stored in the specified data area (INTO).
• The data remains in the TSQ until explicitly deleted using DELETEQ TS.

Short Examples -

Scenario - Reading a Specific Item from a Temporary Storage Queue

...
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-QUEUE-NAME  PIC X(8)  VALUE 'TSQTEST'.
01 WS-CUST-RECORD.
   05 WS-CUST-ID        PIC X(10).
   05 WS-CUST-NAME      PIC X(30).
   05 WS-CUST-ADDRESS   PIC X(50).
   05 WS-CUST-PHONE     PIC X(15).
   05 WS-CUST-BAL       PIC 9(15).   
01 WS-LENGTH      PIC S9(4) COMP VALUE 120.
01 WS-ITEM-NO     PIC S9(4) COMP.
01 WS-RESP        PIC S9(4) COMP.

PROCEDURE DIVISION.

    MOVE 5 TO WS-ITEM-NO.

    EXEC CICS READQ TS
         QUEUE(WS-QUEUE-NAME)
         INTO(WS-CUST-RECORD)
         LENGTH(WS-LENGTH)
         ITEM(WS-ITEM-NO)
         RESP(WS-RESP)
         END-EXEC.

    IF WS-RESP = DFHRESP(NORMAL) THEN
       ...
	ELSE
	   ...
	END-IF.

	...

The queue name TSQTEST is specified. The first item in the TSQ (ITEM 5) is read into WS-DATA. The response code (RESP) is checked to confirm whether the read operation was successful.

Error Conditions -

Eror Condition	RESP	RESP2	Reason
INVREQ	16		Queue name specifies consisting of binary zeroes or queue created by CICS internal code.
IOERR	17	5	There is an irrecoverable input/output error for a shared queue.
LENGERR	22		The retrieved data area length is more than the specified length in LENGTH. This only happens for INTO not to SET.
ITEMERR	26		The ITEM number provided is out of range or attempt made to read beyond the end of queue using NEXT.
QIDERR	44		Occurs when the queue specified cannot be found in Main storage, Auxiliary storage.
SYSIDERR	53	4	Occurs in any of the following situations: The specified SYSID name is not the local system or a remote system. The link to the remote system is closed. The CICS region specified fails to connect to the TS server supports the referenced temporary storage queue.
NOTAUTH	70		A resource security check has failed on QUEUE (name).

---