Examples
The following example shows how to read a record from an intrapartition queue into a data area specified in the request:
EXEC CICS READQ TD
QUEUE(’ABCD’)
INTO(DATA)
The following example shows how to read a record from an extrapartition queue of fixed-length records 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. It is assumed that the record length is known.
EXEC CICS READQ TD
QUEUE(EX1)
SET(PREF)
END-EXEC.
READQ TS
(
Retrieve data from a temporary storage queue.
name
)
SET (
(
data-area ptr-ref
)
)
LENGTH (
data-area
)
NEXT
NUMITEMS (
data-area
) ITEM (
data-value
) SYSID (
name
)
Conditions:
INVREQ, IOERR, ISCINVREQ, ITEMERR, LENGERR, NOTAUTH, QIDERR, SYSIDERR
Description
The queue may be in main or auxiliary storage.
See Chapter 24, “Temporary storage control,” on page 219 for more information.
Options
INTO(
data-area
)
specifies the data area into which the data is to be written. The data area may be any variable, array, or structure.
ITEM(
data-value
)
specifies as a halfword binary value the item number of the logical record to be retrieved from the queue. The specified value is to be taken as the relative number of the logical record to be retrieved. This number may be the number of any item that has been written to the temporary storage queue.
An internal CICS pointer is set so that subsequent READQ TS NEXT commands continue from this point.
Chapter 32. Application programming commands - reference
407
LENGTH(
data-area
)
specifies as a halfword binary value the length of the data. For a description of
a safe upper limit, see “LENGTH options” on page 312.
If you specify the INTO option, the LENGTH argument must specify the maximum length of data that the program accepts. If the value specified is less than zero, zero is assumed. If the length of 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.
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.
NEXT
specifies that the next sequential logical record following the last record to be retrieved (by any task) is to be retrieved, or the first record, if no previous record has been retrieved.
NUMITEMS(
data-area
)
specifies a halfword binary field to receive a number indicating how many items there are in the queue.
QUEUE(
name
)
specifies the symbolic name (1–8 characters) of the queue to be read from. If the queue name appears in the temporary storage table (TST), and the entry is marked as remote, the request is shipped to a remote system.
The name must be alphanumeric and unique within the CICS system. Do not use X'FA' through X'FF' as the first character of the name; these characters are reserved for CICS use. The name cannot consist solely of binary zeros.
SET(
ptr-ref
)
specifies a pointer reference to be set to the address of the retrieved data. CICS acquires an area large enough to hold the record and sets the pointer reference to the address of the record. The area is retained until another READQ TS command, on any TS queue, is executed. The pointer reference, unless changed by other commands or statements, is valid until the next READQ TS command or the end of task.
SYSID(
name
)
specifies the name of the system to which the request is directed. The name can be up to 4 characters long.
Exception Conditions
INVREQ
occurs if the queue was created by CICS internal code.
Default action: Terminate the task abnormally.
IOERR
occurs if there is an unrecoverable input/output error.
Default action: Terminate the task abnormally.
ISCINVREQ
occurs if the remote system indicates a failure that does not correspond to a known condition.
Default action: Terminate the task abnormally.
408
CICS for iSeries Application Programming Guide V5
ITEMERR
occurs in any of the following situations: v
The specified item number is not valid (that is, it is outside the range of item numbers written to the queue). v
An attempt is made to read beyond the end of the queue using the (default)
NEXT option.
Default action: Terminate the task abnormally.
LENGERR
occurs if the length of the stored data is greater than the value specified by the
LENGTH option. This condition can only occur when the INTO option is specified.
Default action: Terminate the task abnormally.
NOTAUTH
occurs if a resource security check has failed on QUEUE(
name
).
Default action: Terminate the task abnormally.
QIDERR
occurs if the queue specified cannot be found.
Default action: Terminate the task abnormally.
SYSIDERR
occurs if the SYSID option specifies either a name that is not defined in the terminal control system table (TCS), or a system to which the link 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:
EXEC CICS READQ TS
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:
EXEC CICS READQ TS
QUEUE(DESCRQ)
SET(PREF)
LENGTH(LENG)
Chapter 32. Application programming commands - reference
409
