Read data from a temporary storage queue.
READQ TS
.-TS-.
>>-READQ-+----+--+-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 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
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.
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.
See LENGTH options in CICS commands for more information
about when 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.
Attention: It is possible
for two tasks to interleave if they lose control during the browse operation. For example,
task 1 might retrieve items 1, 3, and 6 while task 2 retrieves items 2, 4, and 5. Using the
READQ TS command with NEXT from a threadsafe program
increases the likelihood of tasks interleaving, because they are running in parallel on their
own TCBs. If the order of retrieval of items is important, add serialization logic to the
application in order to single thread the browse of the queue, especially if the application
is to be defined with CONCURRENCY(THREADSAFE) or
CONCURRENCY(REQUIRED).
- 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.
- 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.
- 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.
- 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 16 MB line. If the
application program is defined with DATALOCATION(BELOW), the address
of the data is below the 16 MB 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. 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 either of the following situations:
- The queue was created by CICS internal
code.
- The queue name specified consists solely of binary zeros.
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 either 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.
- 22 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.
- 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 cannot be found, either in main or in auxiliary
storage.
Default action: terminate the task abnormally.
- 53 SYSIDERR
- RESP2
values:
- 4
- Occurs in any of the following situations:
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