READQ TS

Reads data from a temporary storage queue.

Syntax


READQ TS

>>-READQ TS--+-QUEUE(name)-+--+-INTO(data-area)-+--------------->
             '-QNAME(name)-'  '-SET(ptr-ref)----'   

>--+-------------------+--+----------------------+-------------->
   '-LENGTH(data-area)-'  '-NUMITEMS(data-value)-'   

   .-NEXT-------------.                    
>--+------------------+--+-------------+-----------------------><
   '-ITEM(data-value)-'  '-SYSID(name)-'

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

Note: LENGTH is required with INTO for C or C++ programs.

Description

READQ TS retrieves data from a temporary storage queue that is in either main or auxiliary storage. In the latter case, the queue can reside on a remote system.

The following example shows how to read a specific record from a temporary storage queue into a data area that is specified in the request:

EXEC CICS READQ TS
          QUEUE(UNIQNAME)
          INTO(DATA)
          LENGTH(LDATA)
          ITEM(IDATA)

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.

EXEC CICS READQ TS
          QUEUE(DESCRQ)
          SET(PREF)
          LENGTH(LENG)

Options

INTO(data-area)

Specifies the user data area into which the data that is read from the temporary storage queue is to be placed.

LENGTH is required with INTO for C or C++ programs. For more information about using this option, see INTO and SET.

ITEM(data-value)

Specifies, as a 16-bit binary value, the item number of the logical record that is to be retrieved from the queue. The item number is the relative number of the logical record that is to be retrieved. It can be the number of any item that has been written to the temporary storage queue.

LENGTH(data-area)

Specifies, as a 16-bit binary value, the length of the data.

If you specify the INTO option, the LENGTH argument must specify the maximum length of data that the program accepts. If the value that is specified is less than zero, zero is assumed. If the retrieved record exceeds the specified length, the data is truncated to that length and the LENGERR condition occurs. On completion of the retrieval operation, the LENGTH argument is set to the original length of the record (before any truncation).

If you specify the SET option, the LENGTH option need not be specified. On completion of the retrieval operation, any specified LENGTH argument is set to the length of the data. See LENGTH for more information about using this option.

NEXT

Specifies that the next sequential logical record that follows the last record retrieved (by any task) is to be retrieved.

NUMITEMS(data-value)

Specifies a 16-bit binary field that is to receive a number that indicates how many items are in the queue.

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.

For a description of how queue names are found by pattern matching, see Temporary Storage Definitions (TSD) .

Note:

If the queue name appears in the Temporary Storage Definitions (TSD), and the entry is marked as remote, the request is shipped to a remote system. The name of the remote queue is taken from the TSD.
Do not use X'FA' through X'FF' as the first character of the name, as these characters are reserved for CICS use.
If a non-local SYSID is specified, the queue is assumed to reside on a remote system irrespective of whether the name exists in the local TSD. Otherwise, the TSD is used to determine whether the queue is on a local or a remote system.

SET(ptr-ref)

Specifies a pointer reference that is to be set to the address of the retrieved data. CICS acquires an area that is large enough to hold the record and sets the pointer reference to the address of the record. The area is valid only until another temporary storage command, on any temporary storage queue, is executed. For more information about using this option, see INTO and SET.

SYSID(name)

Specifies on which CICS region the READQ is to run. The SYSID name has one through four characters. For a full description of the SYSID option, see SYSID.

If the SYSID option is not specified, it defaults to the value that is in the RemoteSysId attribute of the TSD entry that is matched with the queue name that is requested in the QUEUE or QNAME option.