Reads data from a transient data queue.

Sintaxe:

Descrição:

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) (see the TXSeries for Multiplatforms Application Programming Guide for introductory information about ATI), 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.

Opções:

INTO(data-area)
• Specifies the user data area into which the data that is read from the transient data queue is to be placed.
• See INTO and SET for more information about using this option.

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.
• See INTO and SET for more information about using this option.

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.

Condições:

DISABLED
• Occurs when the queue has been disabled.
• Ação pré-definida: 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.
• See Processing the IOERR condition for information about handling the IOERR condition.
• IOERR can occur for recoverable intrapartition TD queues if the file server has been restarted while CICS is still running.
• Ação pré-definida: Terminates the task abnormally.

ISCINVREQ
• Occurs if the remote system indicates a failure that does not correspond to a known condition.
• Ação pré-definida: 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.
• Ação pré-definida: 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.
• Ação pré-definida: Terminates the task abnormally.

NOTOPEN
• Occurs if the destination is closed.
• This condition applies only to extrapartition queues.
• Ação pré-definida: 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.
• Ação pré-definida: 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.
• Ação pré-definida: Terminates the task abnormally.

QZERO
• Occurs if the destination (queue) is empty or the end of the queue has been reached.
• Ação pré-definida: 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.

Informações relacionadas:

• Processing the IOERR condition
• HANDLE CONDITION
• READQ TS
• TXSeries for Multiplatforms Application Programming Guide
• TXSeries for Multiplatforms Administration Reference
• TXSeries for Multiplatforms Intercommunication Guide