WRITEQ TS

Write data to a temporary storage queue.

WRITEQ TS

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

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:
  • The SYSID option specifies a name that is not the local system or a remote system (made known to CICS by defining a CONNECTION or an IPCONN).
  • When IPIC connectivity is used, the local system, the remote system, or both, are not CICS TS 4.2 or later regions.
  • The link to the remote system is closed.
  • 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 situation can occur if the CICS region is not authorized to access the temporary storage server.

    This condition can also occur if the temporary storage server is not started, or because the server has failed (or been stopped) while CICS continues to run.

Default action: terminate the task abnormally.