Reads data from a temporary storage queue.

Sintaxe:

Nota:

LENGTH is required with INTO for C or C++ programs.

Descrição:

READQ TS retrieves data from a temporary storage queue that is in either main or auxiliary storage.
In the latter case, the queue can reside on a remote system.

Opções:

INTO(data-area)
• Specifies the user data area into which the data that is read from the temporary storage queue is to be placed. LENGTH is required with INTO for C or C++ programs.
• See INTO and SET for more information about using this option.

ITEM(data-value)
• Specifies, as a 16-bit binary value, the item number of the logical record that is to be retrieved from the queue.
• The item number is the relative number of the logical record that is to be retrieved.
• It can be the number of any item that has been written to the temporary storage queue.

LENGTH(data-area)
• Specifies, as a 16-bit binary value, the length of the data.
• 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 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.

NEXT
• Specifies that the next sequential logical record that follows the last record to be retrieved (by any task) is to be retrieved.

NUMITEMS(data-value)
• Specifies a 16-bit binary field that is to receive a number that indicates how many items are in the queue.

QUEUE(name)
• Specifies the symbolic name of the queue that is to be read from.
• If the queue name appears in the Temporary Storage Definitions (TSD) (TSD), and the entry is marked as remote, the request is shipped to a remote system.
• The name of the remote queue is taken from the TSD.
• For a description of how queue names are found by pattern matching, see the TXSeries for Multiplatforms Administration Reference.
• When writing applications in COBOL, the name can be up to eight characters long, each of which can contain any bit pattern; and it must be 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 same rules apply when using C or C++, except that the name must be a full eight characters in length.
• Names that are less than eight characters should not be used.
• The same rules apply when using PL/I, except that the name must be a full eight characters in length.
• Names that are less than eight characters should not be used.
• If a non-local SYSID is specified, the queue is assumed to reside on a remote system irrespective of whether the name exists in the local TSD.
• Otherwise, the TSD is used to determine whether the queue 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 retrieved data.
• CICS acquires an area that is large enough to hold the record and sets the pointer reference to the address of the record.
• The area is valid only until another temporary storage command, on anytemporary storage queue, 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 TSD entry that is matched with the queue name that is requested in the QUEUE option.

Condições:

INVREQ
• Occurs if the specified queue is remote and has been created by CICS internal code.
• Ação pré-definida: Terminates the task abnormally.

IOERR
• Occurs if an I/O error occurs during the temporary storage operation.
• See Processing the IOERR condition for information about handling the IOERR condition.
• IOERR can occur for recoverable auxiliary intrapartition TS 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.

ITEMERR
• Occurs under three conditions:
  • If the item number that is specified or implied by a READQ TS command is not valid (that is, it is outside the range of entry numbers assigned for the queue)
  • If an end of file marker is encountered on a READQ TS NEXT command
  • If this is the first time the queue has been read on a READQ TS NEXT command
• Ação pré-definida: Terminates the task abnormally.

LENGERR
• Occurs if the length of the stored data is greater than the value that is specified in the LENGTH option when the INTO option is also specified.
• 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 by a transaction that is defined with the RSLCheck attribute set to either internal or external
• Ação pré-definida: Terminates the task abnormally.

QIDERR
• Occurs if the specified queue cannot be found in either main or auxiliary storage.
• 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.
• Ação pré-definida: Terminates the task abnormally.

Informações relacionadas:

• Processing the IOERR condition
• TXSeries for Multiplatforms Administration Reference
• TXSeries for Multiplatforms Intercommunication Guide