Write data to a temporary storage queue.
WRITEQ TS
.-TS-.
>>-WRITEQ-+----+--+-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 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.
Note for dynamic transaction routing: Using
this command might create inter-transaction affinities that adversely
affect the use of dynamic transaction routing. For more information
about transaction affinities, see
Affinity.
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:
- 5
- There is an irrecoverable input/output error for a shared queue.
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:
- 0
- The request cannot be performed because use of the queue has been
restricted owing to a unit of work failing indoubt.
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:
- 101
- A resource security check has failed on QUEUE(name).
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:
- 4
- Occurs in any of the following situations:
Default action: terminate the task abnormally.