Read data from the transient data queue.
READQ TD >>-READQ TD--QUEUE(name)--+-INTO(data-area)-+-------------------> '-SET(ptr-ref)----' >--+-------------------+--+-------------------+-----------------> '-LENGTH(data-area)-' '-SYSID(systemname)-' >--+-----------+----------------------------------------------->< '-NOSUSPEND-'
Conditions: DISABLED, INVREQ, IOERR, ISCINVREQ, LENGERR, LOCKED, NOTAUTH, NOTOPEN, QBUSY, QIDERR, QZERO, SYSIDERR
READQ TD reads transient data from a queue (after which the record is no longer available).
If you are using automatic transaction initiation (ATI) (see the section on ATI in the CICS® Application Programming Guide for introductory information) your application should test for the QZERO condition to ensure that termination of an automatically initiated task occurs only when the queue is empty.
If the READQ TD command attempts to access a record in a logically recoverable intrapartition queue that is being written to, or deleted by, another task, and there are no more committed records, the command waits until the queue is no longer being used for output. If, however, the NOSUSPEND option has been specified, or there is an active HANDLE CONDITION for QBUSY, the QBUSY condition is raised.
If you specify the INTO option, LENGTH specifies 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 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.
Note, however, that if a HANDLE CONDITION for QBUSY is active when the command is executed, this also overrides the default action, and control is passed to the user label supplied in the HANDLE CONDITION. This takes precedence over the NOSUSPEND option but is, of course, negated by either NOHANDLE or RESP.
This option only applies to intrapartition queues.
If SYSID is specified, the queue is assumed to be on a remote system whether or not it is defined as remote. Otherwise the transient data queue definition is used to find out whether the data set is on a local or a remote system.
If DATALOCATION(ANY) is associated with the application program, the address of the data can be above or below the 16MB line.
If DATALOCATION(BELOW) is associated with the application program, and the data resides above the 16MB line, the data is copied below the 16MB line, and the address of this copy is returned.
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.
Default action: terminate the task abnormally.
Default action: terminate the task abnormally.
This condition occurs as long as the queue can be read; a QZERO condition occurs when the queue cannot be read.
This condition can also occur if the FREE=CLOSE operand has been used in the data set definition for an extrapartition queue, and the queue has been closed and reopened.
Default action: terminate the task abnormally.
Default action: terminate the task abnormally.
Default action: terminate the task abnormally.
Specify WAIT(YES) and WAITACTION(QUEUE) in the TDQUEUE resource definition if you want the transaction to wait.
Default action: terminate the task abnormally.
Default action: terminate the task abnormally.
Default action: terminate the task abnormally.
The NOSUSPEND option must be specified, or a HANDLE for the condition must be active, for this condition to be raised.
This condition applies only to intrapartition queues.
Default action: ignore the condition.
Default action: terminate the task abnormally.
Default action: terminate the task abnormally.
Default action: terminate the task abnormally.
EXEC CICS READQ TD
QUEUE('CSML')
INTO(DATA)
LENGTH(LDATA)
EXEC CICS READQ TD
QUEUE(EX1)
SET(PREF)