WRITEQ TS
Write data to a temporary storage queue.
Conditions: INVREQ, IOERR, ISCINVREQ, ITEMERR, LENGERR, LOCKED, NOSPACE, NOTAUTH, QIDERR, SYSIDERR
This command is threadsafe when it is used with a queue in main storage or auxiliary storage, either in a local CICS® region, or function shipped to a remote CICS region over an IPIC connection. It is also threadsafe when it is used with a queue in a shared temporary storage pool in a z/OS® coupling facility that is managed by a temporary storage data sharing server (TS server). The command is non-threadsafe when it is function shipped to a remote CICS region over another type of connection other than IPIC.
Description
WRITEQ TS stores temporary data records in a temporary storage queue in main or auxiliary storage.
If a queue is defined as recoverable, the program must not issue a WRITEQ TS command if a DELETEQ TS command has previously been issued in the same logical unit of work. That is, following a DELETEQ TS command, a WRITEQ TS command must not be issued until after a sync point occurs.
If there is insufficient space available in the temporary storage data set or main storage to satisfy the WRITEQ TS request, the task is suspended until space does become available. (Other tasks in the system might release space.) If space is not available and you specified the NOSUSPEND option, the NOSPACE condition is raised, and you can decide whether to stop the transaction with an abend, or wait.
Options
- AUXILIARY
- Specifies
that the temporary storage queue is on a direct access storage device
in auxiliary storage. This is the default value for the first write.
This option is ignored in the following situations:
- For an existing queue
- If a TSMODEL resource definition with a matching prefix is installed in the system
- If the AUXILIARY option is specified for a temporary storage data queue that resides in a temporary storage pool.
- FROM(data-area)
- Specifies the data to be written to temporary storage.
- ITEM(data-area)
- Specifies,
as a halfword binary value, the item number of the logical record
to be replaced in the queue (REWRITE option also specified).
ITEM can be both an input and output field to CICS. Therefore, programmers must ensure that the ITEM field is not defined in protected storage when issuing a WRITEQ command. If the ITEM value was a literal (for example), command checking (CMDPROT=YES) would result in an AEYD abend occurring.
Note: In earlier releases, ITEM on a WRITEQ TS without REWRITE would perform a similar function to NUMITEMS. This function is retained for compatibility. - LENGTH(data-value)
- Specifies
the length, as a halfword binary value, of the data to be written.
You must specify this option if you are using SYSID.
The maximum length is 32763. For a description of a safe upper limit, see LENGTH options in CICS commands.
- MAIN
- Specifies
that the temporary storage queue is in main storage. This option is ignored in the following situations:
- For an existing queue
- If a TSMODEL resource definition with a matching prefix is installed in the system
- If the MAIN option is specified for a temporary storage data sharing queue that resides in a temporary storage pool.
If you use the MAIN option to write data to a temporary storage queue on a remote system, the data is stored in main storage if the remote system is accessed by the CICS multiregion operation (MRO) facility or IPIC connectivity. If these conditions are not met, the data is stored in auxiliary storage.
If the system is MRO and MAIN is specified, the queue is not recoverable and SYNCPOINT ROLLBACK does not function.
- NOSUSPEND
- Specifies
that if there is insufficient space in the temporary storage data
set or in main storage to satisfy the WRITEQ TS request, the application
program is not suspended. The NOSPACE condition is raised instead.
However, if a HANDLE CONDITION command for NOSPACE is active when the command is executed, this condition also overrides the default action, and control is passed to the user label supplied in the HANDLE CONDITION command. This condition takes precedence over the NOSUSPEND option but is, of course, negated by either NOHANDLE or RESP.
- NUMITEMS(data-area)
- Specifies
a halfword binary field where CICS stores
a number that indicates how many items there are now in the queue,
after the WRITEQ TS command is executed.
If the record starts a new queue, the item number assigned is 1; subsequent item numbers follow on sequentially. NUMITEMS is not valid if REWRITE is specified.
- QNAME(name)
- An alternative to QUEUE, QNAME specifies the symbolic name (1 - 16 characters) of the queue to be written to. If the name has less than 16 characters, you must still use a 16-character field, padded with blanks if necessary. If the queue is defined to CICS as remote, the request is shipped to a remote system. Do not use X'FA' through X'FF', or **, or $$, or DF, as the first character of the name; these characters are reserved for CICS use. The name cannot consist solely of binary zeros.
- QUEUE(name)
- Specifies the symbolic name (1 - 8 characters) of the queue to be written to. If the name has less than 8 characters, you must still use an 8-character field, padded with blanks if necessary. If the queue is defined to CICS as remote, the request is shipped to a remote system. Do not use X'FA' through X'FF', or **, or $$, or DF, as the first character of the name; these characters are reserved for CICS use. The name cannot consist solely of binary zeros.
- REWRITE
- Specifies that the existing record in the queue is to be overwritten with the data provided. If the REWRITE option is specified, the ITEM option must also be specified. If the specified queue does not exist, the QIDERR condition occurs. If the correct item within an existing queue cannot be found, the ITEMERR condition occurs and the data is not stored.
- SYSID(systemname)
- (Remote and shared queues only) Specifies the system name (1 - 4 characters) identifying the remote system or shared queue pool to which the request is directed. Note that TSMODEL resource definitions do not support specifying a SYSID for a queue that resides in a temporary storage data sharing pool. Use the QUEUE or QNAME option instead. Using an explicit SYSID for a shared queue pool requires the support of a temporary storage table (TST).
Conditions
- 16 INVREQ
- Occurs
in any of the following situations:
- A WRITEQ TS command specifies a queue name that consists solely of binary zeros.
- A WRITEQ TS command specifies a queue that is locked and awaiting ISC session recovery.
- The queue was created by CICS internal code.
Default action: terminate the task abnormally.
- 17 IOERR
- RESP2
values:
Default action: terminate the task abnormally.
- 54 ISCINVREQ
- Occurs
when the remote system indicates a failure that does not correspond
to a known condition.
Default action: terminate the task abnormally.
- 26 ITEMERR
- Occurs
in any of the following situations:
- The item number specified in a WRITEQ TS command with the REWRITE option, is not valid (that is, it is outside the range of entry numbers assigned for the queue).
- The maximum number of items (32767) is exceeded.
Default action: terminate the task abnormally.
- 22 LENGERR
- Occurs
in any of the following situations:
- The length of the stored data is zero or negative.
- The length of the stored data is greater than 32763.
Default action: terminate the task abnormally.
- 100 LOCKED
- RESP2
values:
Default action: terminate the task abnormally.
- 18 NOSPACE
- Occurs
when the NOSUSPEND option is specified and there is no space for the
data in the following:
- Main storage
- The auxiliary temporary storage data set
- The temporary storage pool list structure
This condition also occurs if there is no space and there is an active HANDLE CONDITION for NOSPACE.
Default action: ignore the condition.
- 70 NOTAUTH
- RESP2
values:
Default action: terminate the task abnormally.
- 44 QIDERR
- Occurs
when the queue specified by a WRITEQ TS command with the REWRITE option
cannot be found in any of the following:
- Main storage
- Auxiliary storage
- Temporary storage pool
Default action: terminate the task abnormally.
- 53 SYSIDERR
- RESP2
values:
Default action: terminate the task abnormally.