Write data to a temporary storage queue.

WRITEQ TS
>>-WRITEQ TS--+-QUEUE(name)-+--FROM(data-area)------------------>
'-QNAME(name)-'
>--+--------------------+--+------------------------------+----->
'-LENGTH(data-value)-' +-NUMITEMS(data-area)----------+
'-ITEM(data-area)--+---------+-'
'-REWRITE-'
.-AUXILIARY-.
>--+-------------------+--+-----------+--+-----------+---------><
'-SYSID(systemname)-' '-MAIN------' '-NOSUSPEND-'
Conditions: INVREQ, IOERR, ISCINVREQ, ITEMERR, LENGERR, LOCKED,
NOSPACE, NOTAUTH, QIDERR, SYSIDERR
This command is threadsafe.
Note for dynamic transaction routing: Using this command could
create inter-transaction affinities that adversely affect the use of dynamic
transaction routing. See the CICS® Application
Programming Guide for more information about transaction affinities.
Description
WRITEQ TS stores temporary data (records)
in a temporary storage queue in main or auxiliary storage.
If a queue
has been defined as recoverable, the program must not issue a WRITEQ TS if
a DELETEQ TS has previously been issued within the same logical unit of work.
In other words, following a DELETEQ TS, no WRITEQ TS can be issued until after
a syncpoint has occurred.
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. (Space may be released by other tasks in
the system.) If, however, space is not available in the temporary storage
data set or main storage, and the NOSUSPEND option has been specified, the
NOSPACE condition is raised.
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:
- 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. As such, programmers should ensure that the ITEM
field is not defined within protected storage when issuing a WRITEQ command.
If the ITEM value were 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:
- 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. 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 the application program is not to be suspended if there is insufficient
space in the temporary storage data set or in main storage to satisfy the
WRITEQ TS request. Instead, the NOSPACE condition is raised. Note, however,
that if a HANDLE CONDITION for NOSPACE is active when the command
is executed, this also overrides the default action, and control is passed
to the user label supplied in the HANDLE CONDITION. This takes precedence
over the NOSUSPEND option but is, of course, negated by either NOHANDLE or
RESP.

- NUMITEMS(data-area)
- specifies
a halfword binary field into which CICS stores a number indicating 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.
- 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 name appears in the TST, and
the entry is marked as remote, the request is shipped to a remote system.
The name must be unique within the CICS 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.
- 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 name appears in the TST, and the entry is marked as remote, or if the
QNAME is described by a TSMODEL resource definition which identifies a remote
system, the request is shipped to a remote system. The name must be unique
within the CICS 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.
Conditions
- 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.
- IOERR
- RESP2
values:
- 5
- There is an irrecoverable input/output error for a shared queue.
Default action: terminate the task abnormally.
- ISCINVREQ
- occurs
when the remote system indicates a failure that does not correspond to a known
condition.
Default action: terminate the task abnormally.
- 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 (32 767) is exceeded.
Default action: terminate the task abnormally.
- 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.
- LOCKED
- RESP2
values:
- 0
- The request cannot be performed because use of the queue has been restricted
owing to a unit of work failing in-doubt.
Default action: terminate the task abnormally.
- NOSPACE
- occurs
when the NOSUSPEND option is specified and there is no space for the data
in:
- The auxiliary temporary storage data set
- The temporary storage pool list structure
Also occurs if there is no space and there is an active HANDLE CONDITION
for NOSPACE.
Default action: ignore the condition.
- NOTAUTH
- RESP2
values:
- 101
- A resource security check has failed on QUEUE(name).
Default action: terminate the task abnormally.
- QIDERR
- occurs
when the queue specified by a WRITEQ TS command with the REWRITE option cannot
be found, either in:
- Main storage
- Auxiliary storage
- Temporary storage pool
Default action: terminate the task abnormally.
- SYSIDERR
- RESP2
values:
- 4
- The CICS region in which the temporary storage command is executed fails
to connect to the TS server managing the TS pool that supports the referenced
temporary storage queue. (For example, this can happen if the CICS region
is not authorized to access the temporary storage server).
SYSIDERR can
also occur if the temporary storage server has not been started, or because
the server has failed (or been stopped) while CICS continues executing. Also
occurs in any of the following situations:
- When the SYSID option specifies a name that is neither the local system
nor a remote system (made known to CICS by defining a CONNECTION).
- When the link to the remote system is closed.
Default action: terminate the task abnormally.