Writes data to a temporary storage queue.
Syntax
WRITEQ TS
>>-WRITEQ TS--+-QUEUE(name)-+--FROM(data-area)------------------>
'-QNAME(name)-'
>--+--------------------+--+------------------------------+----->
'-LENGTH(data-value)-' '-ITEM(data-area)--+---------+-'
'-REWRITE-'
.-AUXILIARY-.
>--+-------------+--+-----------+--+-----------+---------------><
'-SYSID(name)-' '-+------+--' '-NOSUSPEND-'
'-MAIN-'
Conditions: INVREQ, IOERR, ISCINVREQ, ITEMERR, LENGERR, NOSPACE, NOTAUTH, QIDERR,
SYSIDERR
Note: The LENGTH option is required with C or C++ programs when FROM is used.
Description
WRITEQ TS stores temporary data (records) in a temporary storage queue that is in either main or
auxiliary storage. In the latter case, the queue can reside on a remote system.
Examples
The following example shows how to write a record to a temporary storage queue that is in
auxiliary storage:
EXEC CICS WRITEQ TS
QUEUE(UNIQNAME)
FROM(MESSAGE)
LENGTH(LENGTH)
ITEM(DREF)
The following example shows how to update a record in a temporary storage queue that is in main
storage:
EXEC CICS WRITEQ TS
QUEUE('TEMPQ1')
FROM(DATAFLD)
LENGTH(40)
ITEM(ITEMFLD)
REWRITE
MAIN
Options
- AUXILIARY
- Specifies that
the temporary storage queue is on a direct access storage device in auxiliary storage.
- FROM(data-area)
- Specifies the data
that is to be written to temporary storage.
- ITEM(data-area)
- Specifies a 16-bit
binary field to be used for the item number that is assigned to the logical record in the queue. If
the REWRITE option is not specified, the data area receives the item (record) number that is
assigned to this record in the queue. If the record starts a new queue, the item number assigned is
1; subsequent item numbers follow on sequentially. If the REWRITE option is specified, the data area
specifies the item that is to be replaced in the queue.
- LENGTH(data-value)
- Specifies, as a
16-bit binary value, the length of the data that is to be written. For more information about using
this option, see LENGTH.
- MAIN
- Specifies that the
temporary storage queue is in main storage.
- NOSUSPEND
- Specifies that
the application program is not to be suspended if the NOSPACE condition occurs.
- 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.
- 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.
For
a description of how queue names are found by pattern matching, see Temporary Storage Definitions
(TSD) .
Note: - If the queue name appears in the Temporary Storage Definitions (TSD), and the entry is marked as
remote, the request is shipped to a remote system. The name of the remote queue is taken from the
TSD.
- Do not use X'FA' through X'FF' as the first character of the name; these characters are reserved
for CICS use.
- If a non-local SYSID is specified, the queue is assumed to reside on a remote system
irrespective of whether the name exists in the local TSD. Otherwise, the TSD is used to determine
whether the queue is on a local or a remote system.
- REWRITE
- Specifies that the
existing record in the queue is to be overwritten with the data that is 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(name)
- Specifies on which
CICS® region the
WRITEQ is to run. The SYSID name has one through four characters. For a full description of the
SYSID option, see SYSID.
If the SYSID option is not specified, it
defaults to the value that is in the RemoteSysId attribute of the TSD entry that is matched
with the queue name that is requested in the QUEUE or QNAME option.
Conditions
- INVREQ
-
- Occurs if the specified queue is in doubt (that is, locked upon restart and awaiting
transaction resolution).
Default action: Terminates the task abnormally.
- IOERR
- Occurs if an I/O
error occurs during the temporary storage operation.
(For information about handling the IOERR
condition, see IOERR condition processing.)
IOERR can occur for recoverable auxiliary intrapartition TS queues if the file server has been
restarted while CICS
is still running.
Default action: Terminates the task abnormally.
- ISCINVREQ
- Occurs if the
remote system indicates a failure that does not correspond to a known condition.
Default action:
Terminates the task abnormally.
- ITEMERR
- Occurs for the
following conditions:
- The item number that is specified or implied by a WRITEQ TS command with the REWRITE option is
not valid (that is, outside the range of entry numbers that are assigned for the queue).
- The maximum number of items (32767) is exceeded.
Default action: Terminates the task abnormally.
- LENGERR
- Occurs if the
LENGTH option specifies a negative or zero value for the length of the data that is to be written.
Default action: Terminates the task abnormally.
- NOSPACE
- Occurs if not
enough space is available in temporary storage to contain the data.
Default action: Suspend the
task until space becomes available as it is released by other tasks; then return normally. (This
default action can be overridden by the NOSUSPEND option.)
- NOTAUTH
- Occurs for the
following conditions:
- When a resource security check is unsuccessful on QUEUE (name) or QNAME
(name).
- When SYSID is specified by a transaction that is defined with the RSLCheck attribute set
to either internal or external.
Default action: Terminates the task abnormally.
- QIDERR
- Occurs if the
queue that is specified by a WRITEQ TS command with the REWRITE option cannot be found in either
main or auxiliary storage.
Default action: Terminates the task abnormally.
- SYSIDERR
- Occurs if a
problem with the communications configuration prevents the WRITEQ from proceeding. For example:
- The connection that is named in the SYSID option is not the name of a Communications Definition
(CD) entry.
- The SYSID option references a CD entry that is incorrectly configured.
- The SYSID option references a CD entry that is marked as out of service.
It can also occur if the connection to the remote system is closed. This could be because the
remote system is not available.
Default action: Terminates the task abnormally.