Read data from temporary storage queue.

READQ TS
>>-READQ TS--+-QUEUE(name)-+--+-INTO(data-area)-+--------------->
'-QNAME(name)-' '-SET(ptr-ref)----'
>--+-------------------+--+---------------------+--------------->
'-LENGTH(data-area)-' '-NUMITEMS(data-area)-'
.-NEXT-------------.
>--+------------------+--+-------------------+-----------------><
'-ITEM(data-value)-' '-SYSID(systemname)-'
Conditions: INVREQ, IOERR, ISCINVREQ, ITEMERR, LENGERR, 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
READQ TS retrieves data from a temporary
storage queue in main or auxiliary storage.
Options
- INTO(data-area)
- specifies
the data area into which the data is to be written. The data area can be any
variable, array, or structure.
- ITEM(data-value)
- provides
a halfword binary value that specifies the item number of the logical record
to be retrieved from the queue.
- LENGTH(data-area)
- specifies
the length, as a halfword binary value, of the record to be read.
If you
specify the INTO option, LENGTH need not be specified if the length can be
generated by the compiler from the INTO variable.
See LENGTH options in CICS commands for
more information about when LENGTH must be specified.
If you specify
INTO, LENGTH defines the maximum length of data that the program accepts.
If the value specified is less than zero, zero is assumed. If the length of
the data exceeds the value specified, the data is truncated to that value
and the LENGERR condition occurs.
On completion of the retrieval operation,
the data area is set to the original length of the data record read from the
queue.
If you specify the SET option, the LENGTH must be specified.
- NEXT
- specifies
retrieval for the next sequential logical record following the last record
retrieved (by any task), or the first record if no previous record has been
retrieved.
- NUMITEMS(data-area)
- specifies
a halfword binary field into which CICS stores a number indicating how many
items there are in the queue. This only occurs if the command completes normally.
- QUEUE(name)
- specifies
the symbolic name (1–8 characters) of the queue to be read from. If the name
has less than 8 characters, you must still use an 8-character field, padded
with blanks if necessary.
- QNAME(name)
- an
alternative to QUEUE, QNAME specifies the symbolic name (1–16 characters)
of the queue to be read from. If the name has less than 16 characters, you
must still use a 16-character field, padded with blanks if necessary.
- SET(ptr-ref)
- specifies
the pointer reference that is set to the address of the retrieved data. The
pointer reference, unless changed by other commands or statements, is valid
until the next READQ TS command or the end of task.
If the application
program is defined with DATALOCATION(ANY), the address of the data can be
above or below the 16MB line. If the application program is defined with DATALOCATION(BELOW),
the address of the data is below the 16MB line.
If TASKDATAKEY(USER)
is specified for the running task, and storage protection is active, the data
returned is in a user-key. If TASKDATAKEY(CICS) is specified and storage protection
is active, the data returned is in a CICS-key.
- 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 either of the following situations:
- the queue was created by CICS internal code.
- the queue name specified consists solely of binary zeroes.
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 is invalid (that is, outside the range of item
numbers written to the queue).
- An attempt is made to read beyond the end of the queue using the NEXT
(default) option.
Default action: terminate the task abnormally.
- LENGERR
- occurs
when the length of the stored data is greater than the value specified by
the LENGTH option.
This condition only applies to the INTO option and
cannot occur with SET.
Default action: terminate the task abnormally.
- 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 cannot be found, either in main or in auxiliary storage.
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.
Examples
The following example shows how to read
the first (or only) record from a temporary storage queue into a data area
specified in the request; the LENGTH data area is given the value of the length
of the record.
EXEC CICS READQ TS
ITEM(1)
QUEUE(UNIQNAME)
INTO(DATA)
LENGTH(LDATA)
The following example shows how to read the next record from
a temporary storage queue into a data area provided by CICS; the pointer reference
specified by the SET option is set to the address of the storage area reserved
for the data record, and the LENGTH data area is given the value of the length
of the record.
EXEC CICS READQ TS
QUEUE(DESCRQ )
SET(PREF)
LENGTH(LENG)
NEXT