READQ TD

Reads data from a transient data queue.

Syntax

READQ TD

Read syntax diagramSkip visual syntax diagramREADQ TDQUEUE( name)INTO( data-area)SET( ptr-ref)LENGTH( data-area)SYSID( name)NOSUSPEND

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

 

Description

READQ TD reads transient data from a predefined symbolic source. To read from an extrapartition queue, the IOMode attribute that is in the Transient Data Definitions (TDD) must be set to input to be able to read the queue.

For intrapartition queues, each record can be read only once and CICS® logically deletes the record from the queue. For extrapartition queues, it is possible to reread the queue by changing and reopening it.

For COBOL programs, if you are using Automatic Transaction Initiation (ATI) (for introductory information about ATI, see Triggered transaction initiation ), the HANDLE CONDITION QZERO command should be included in your application to ensure that termination of an automatically initiated task occurs only when the queue is empty. This does not apply to C or C++ applications.

The following example shows how to read a record from an extrapartition queue that has fixed-length records 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. It is assumed that the record length is known. 
EXEC CICS READQ TD
          QUEUE(EX1)
          SET(PREF)

Options

INTO(data-area)
Specifies the user data area into which the data that is read from the transient data queue is to be placed. For more information about using this option, see INTO and SET.
LENGTH(data-area)
Specifies, as a 16-bit binary value, the length of the data. You must specify LENGTH if you are using the INTO option for an intrapartition queue or for an extrapartition queue that does not contain fixed-length records. However, you can omit LENGTH for remote queues and for extrapartition queues that contain fixed-length records.

For extrapartition queues that contain fixed-length records, any LENGTH that is specified should match the value that is given in the Transient Data Definitions (TDD) for the queue.

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 length that is specified is too long, the record is read into the first part of the specified area; the contents of the remainder of the area are not defined. 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.

NOSUSPEND
Specifies that the application program is not to be suspended if the QBUSY condition occurs.

This option applies only to intrapartition queues.

QUEUE(name)
Specifies the symbolic name of the queue that is to be read from. The name can be up to four characters long. If the SYSID option is not used to specify a remote SYSID, this queue must have an entry in the Transient Data Definitions (TDD).
SET(ptr-ref)
Specifies a pointer reference that is to be set to the address of the data that is read from the queue. CICS acquires an area that is large enough to hold the record, and sets the pointer reference to the address of that area. The area is valid only until another transient data command 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, refer to SYSID.

If the SYSID option is not specified, it defaults to the value that is in the RemoteSysId attribute of the TDD entry for the queue that is requested in the QUEUE option.

Conditions

DISABLED
Occurs when the queue has been disabled.

Default action: Terminates the task abnormally.

IOERR
Occurs if an I/O error occurs during the transient data operation.

This condition occurs only if the queue can be read; that is, the queue contains records; the QZERO condition occurs if the queue cannot be read; that is, either the queue is empty, or the end of queue has been reached.

For information about handling the IOERR condition, see IOERR condition processing.

IOERR can occur for recoverable intrapartition TD queues if the file server has been restarted while CICS is still running.

Default action: Terminates the task abnormally.

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

Default action: Terminates the task abnormally.

LENGERR
Occurs for the following conditions:
  • The LENGTH option is omitted for a READQ TD INTO operation that involves an intrapartition queue or an extrapartition queue that does not contain fixed-length records.
  • The record that is read from a queue is longer than the LENGTH that is specified for the input area; the record is truncated and the data area that is supplied in the LENGTH option is set to the actual record size.
  • An incorrect length is specified for a READQ TD INTO operation that involves fixed-length records.

Default action: Terminates the task abnormally.

NOTAUTH
Occurs for the following conditions:
  • When a resource security check is unsuccessful on QUEUE(name)
  • When SYSID is specified for a transaction that is defined with the RSLCheck attribute set to either internal or external.

Default action: Terminates the task abnormally.

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

Default action: Terminates the task abnormally.

QBUSY
Occurs if a 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 no more committed records are available. This condition applies only to intrapartition queues.

Default action: The task issuing the READQ TD command waits until the queue is no longer being used for output. (This default action can be overridden by the NOSUSPEND option.)

QIDERR
Occurs if the symbolic destination that is to be used with a READQ TD command cannot be found.

Default action: Terminates the task abnormally.

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

Default action: Terminates the task abnormally.

SYSIDERR
Occurs if a problem with the communications configuration prevents the READQ from proceeding. For example:
  • The connection that is named in the SYSID option is not the name of a Communications Definition (CD) entry.
  • The SYSID option references a CD entry that is incorrectly configured.
  • The SYSID option references a CD entry that is marked as out of service.

It can also occur if the connection to the remote system is closed. This could be because the remote system is not available.

Default action: Terminates the task abnormally.