CICS WRITEQ TS

The CICS WRITEQ TS statement is utilized to write temporary data into the TSQ as individual items. Each WRITEQ statement can write a single item. If the queue can be recovered and is deleted, the application program should issue a SYNCPOINT command before another WRITEQ TS.

Points to note -

Application programs create the TSQ by issuing a WRITE TSQNAME command.
Item in a TSQ can be modified with the REWRITE option.

Syntax -

EXEC CICS WRITEQ TS
     QUEUE('queue-name')
     FROM(data-area)
     LENGTH(length)
	 [NUMITEMS(items-number)]
     [ITEM(item-number)  REWRITE]
	 [SYSID(system-name)]
     [MAIN|AUXILIARY]
     [RESP(response-field)]
     [RESP2(response-field2)]
     END-EXEC.

QUEUE('queue-name') - Specifies the name of the temporary storage queue where the data will be written.
FROM(data-area) - Defines the data area containing the information to be stored in the queue.
LENGTH(length) - Specifies the length of the data to be written to the queue.
NUMITEMS(items-number) - Stores a number that indicates how many items there are now in the queue, after the WRITEQ TS command is executed.
ITEM(item-number) - Optional. Defines which item number within the queue to store the data. If omitted, data is appended.
REWRITE - Optional. Allows overwriting an existing item in the queue instead of appending new data.
MAIN | AUXILIARY - Optional. Specifies where the TSQ should be stored: MAIN (memory, faster) or AUXILIARY (disk, survives longer).
SYSID(system-name) - Specifies the system name to which the request is directed.
RESP(response-variable) - Optional. It captures the response code of the WRITEQ 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 WRITEQ TS operation when the error occured.

How it works?

The WRITEQ TS command writes data to a named temporary storage queue (TSQ).
If no ITEM number is coded, data is stored in the next available item in the queue.
If REWRITE is used, data replaces an existing item at a specified position.
The TSQ can be later read using READQ TS.
Data remains available until it is explicitly deleted (DELETEQ TS) or CICS is restarted.

Short Examples -

Scenario - Writing a New Item to 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-RESP        PIC S9(4) COMP.

PROCEDURE DIVISION.

    MOVE "0000011111" TO WS-CUST-ID.
    MOVE "John Doe" TO WS-CUST-NAME.
    MOVE "123 Main Street, NY" TO WS-CUST-ADDRESS.
    MOVE "9876543210" TO WS-CUST-PHONE.
	MOVE 12000.35 TO WS-CUST-BAL.

    EXEC CICS WRITEQ TS
         QUEUE(WS-QUEUE-NAME)
         FROM(WS-CUST-RECORD)
         LENGTH(WS-LENGTH)
         RESP(WS-RESP)
         END-EXEC.

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

	...

The queue name TSQTEST is assigned to WS-QUEUE-NAME. The data area (WS-CUST-RECORD) is written to the queue using WRITEQ TS. The response code is checked to confirm whether the write operation was successful.

Error Conditions -

Eror Condition	RESP	RESP2	Reason
INVREQ	16		Queue name specifies consisting of binary zeroes or queue locked and waiting for ISC session recovery or queue created by CICS internal code.
IOERR	17	5	There is an irrecoverable input/output error for a shared queue.
NOSPACE	18		Occurs when NOSUSPEND option specified, no space in the following conditions – Main storage The auxiliary temporary storage data set The temporary storage pool list structure
LENGERR	22		The length of the stored data area is zero or negative or greater than 32763.
ITEMERR	26		The ITEM number provided is out of range or exceeds 32767.
QIDERR	44		Occurs when the queue specified with the REWRITE option cannot be found in Main storage, Auxiliary storage and Temporary storage pool.
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).