WRITEQ TS

Write data to a temporary storage queue.

WRITEQ TS

Read syntax diagramSkip visual syntax diagramWRITEQ TSQUEUE( name)QNAME( name)FROM( data-area)LENGTH( data-value)NUMITEMS( data-area)ITEM( data-area)REWRITESYSID( systemname)AUXILIARYMAINNOSUSPEND

Conditions: INVREQ, IOERR, ISCINVREQ, ITEMERR, LENGERR, NOSPACE, NOTAUTH, QIDERR, SYSIDERR

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 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, and the NOSUSPEND option has been specified, or there is an active HANDLE CONDITION for NOSPACE, 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.

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.

MAIN
specifies that the temporary storage queue is in main storage.

This option is ignored for an existing queue.:

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 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.

This does not apply to temporary storage queues in main storage (MAIN option).

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 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 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.
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)
specifies the system name (1–4 characters) identifying the remote system 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
occurs when there is an irrecoverable input/output error.

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.

NOSPACE
occurs when the NOSUSPEND option is specified and there is no space for the data in the auxiliary temporary storage data set.

Also occurs if there is no space and there is an active HANDLE CONDITION for NOSPACE.

Default action: ignore the condition.

NOTAUTH
occurs when a resource security check has failed on QUEUE(name), or QNAME(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

Default action: terminate the task abnormally.

SYSIDERR
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).
  • The link to the remote system is closed.

Default action: terminate the task abnormally.