READQ TD

Read data from the transient data queue.

READQ TD

Conditions: DISABLED, INVREQ, IOERR, ISCINVREQ, LENGERR, LOCKED, NOTAUTH, NOTOPEN, QBUSY, QIDERR, QZERO, SYSIDERR

This command is threadsafe when it is used with a queue in a local CICS® region, or function shipped to a remote CICS region over an IPIC connection. It is non-threadsafe when it is function shipped to a remote CICS region over another type of connection.

Description

READQ TD reads transient data from a queue (after which the record is no longer available).

If you are using automatic transaction initiation (ATI), your application should test for the QZERO condition to ensure that termination of an automatically initiated task occurs only when the queue is empty. For introductory information about ATI, see Automatic transaction initiation (ATI).

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.

Options

INTO(data-area)

Specifies the user data area into which the data read from the transient data queue is to be placed.

LENGTH(data-area)

Specifies the length, as a halfword binary value, of the record to be read.

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 a LENGERR condition will be raised and the queue will not be read. If the value specified is zero a LENGERR condition will be raised and the queue will be read. 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.

NOSUSPEND

Specifies that if the application program attempts to read from a queue that is already being used for output, the task is not suspended until the queue becomes available. Instead, the QBUSY condition is raised.

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.

QUEUE(name)

Specifies the symbolic name (1 - 4 alphanumeric characters) of the queue to be read from. The named queue must have been defined to CICS.

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.

SET(ptr-ref)

Specifies a pointer reference that is to be set to the address of the data read from the queue. CICS acquires an area large enough to hold the record and sets the pointer reference to the address of that area. The area is retained until another transient data command is executed. The pointer reference, unless changed by other commands or statements, is valid until the next READQ TD command or the end of task.

If DATALOCATION(ANY) is associated with the application program, the address of the data can be above or below the 16 MB line.

If DATALOCATION(BELOW) is associated with the application program, and the data resides above the 16 MB line, the data is copied below the 16 MB 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.

SYSID(systemname)

(remote systems only) Specifies the name (1 - 4 characters) of the system to which the request is directed.

Conditions

84 DISABLED

occurs when the queue has been disabled.

Default action: terminate the task abnormally.

16 INVREQ

Occurs if READQ names an extrapartition queue that has been opened for output. This condition cannot occur for intrapartition queues.

Default action: terminate the task abnormally.

17 IOERR

Occurs when an input/output error occurs and the data record in error is skipped.

This condition occurs if the queue can be read; when the queue cannot be read, a QZERO condition occurs in this situation.

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.

54 ISCINVREQ

Occurs when the remote system indicates a failure that does not correspond to a known condition.

Default action: terminate the task abnormally.

22 LENGERR

Occurs if READQ names an INTO area that cannot hold all the data that is to be returned to the application or an invalid length has been supplied. The check is made after the XTDIN exit has been invoked.

Default action: terminate the task abnormally.

100 LOCKED

Occurs when the request cannot be performed because use of the queue has been restricted owing to a unit of work failing indoubt. This can happen on any request for a logically-recoverable queue defined with WAIT(YES) and WAITACTION(REJECT) in the TDQUEUE resource definition.

Specify WAIT(YES) and WAITACTION(QUEUE) in the TDQUEUE resource definition if you want the transaction to wait.

Default action: terminate the task abnormally.

70 NOTAUTH

Occurs when a resource security check has failed on QUEUE(name).

Default action: terminate the task abnormally.

19 NOTOPEN

Occurs if the destination is closed. This condition applies to extrapartition queues only.

Default action: terminate the task abnormally.

25 QBUSY

Occurs if a READQ TD command attempts to access a record in a logically recoverable intrapartition queue that is being written to or is being deleted by another task, and there are no more committed records.

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.

44 QIDERR

Occurs if the symbolic destination to be used with READQ TD cannot be found.

Default action: terminate the task abnormally.

23 QZERO

Occurs when the destination (queue) is empty or the end of the queue has been reached.

Default action: terminate the task abnormally.

53 SYSIDERR

Occurs when the SYSID option specifies a name that is neither the local system nor a remote system (made known to CICS by defining a CONNECTION or an IPCONN). SYSIDERR also occurs when the link to the remote system is closed.

Default action: terminate the task abnormally.

Examples

The following example shows how to read a record from an intrapartition data set (queue), which in this case is the control system message log (CSML), into a data area specified in the request:

EXEC CICS READQ TD
     QUEUE('CSML')
     INTO(DATA)
     LENGTH(LDATA)

The following example shows how to read a record from an extrapartition data set (queue) that has 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)