READQ TS

Read data from a temporary storage queue.

READQ TS

Read syntax diagramSkip visual syntax diagramREADQTSQUEUE( name)QNAME( name)INTO( data-area)SET( ptr-ref)LENGTH( data-area)NUMITEMS( data-area)NEXTITEM( 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 that is 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 that is read from the queue.

If you specify the SET option, the LENGTH must be specified.

For more information about when LENGTH must be specified, see LENGTH options in CICS commands.

NEXT
Specifies retrieval for the next sequential logical record following the last record that was 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 that indicates how many items there are in the queue. This occurs only 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 fewer 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 fewer 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 that is returned is in a user-key. If TASKDATAKEY(CICS) is specified and storage protection is active, the data that is 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 that is specified consists solely of binary zeros.

Default action: terminate the task abnormally.

17 IOERR
RESP2 values:
5
There is an unrecoverable 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 that is specified is invalid (that is, outside the range of item numbers that are written to the queue).
  • An attempt is made to read beyond the end of the queue by 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 applies only 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:
  • 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 that manages 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.

Examples

The following example shows how to read the first (or only) record from a temporary storage queue into a data area that is 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 that is provided by CICS. The pointer reference that is specified by the SET option is set to the address of the storage area that is 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