Digital

NAME

READ QUEUE − statement that returns to a workspace one record from a record queue without deleting the item. Contrast with the dequeue operation. 
 

SYNOPSIS

 [<label-name>:] READ QUEUE
            { FIRST RECORD [ BY KEY <workspace-field> VALUE <key-value> ] |
              NEXT RECORD [ BY KEY ] |
              RECORD BY { ID | IDENTIFIER } <identifier-field-1>
            }
            [ WITH [ NO ] WAIT ]
            [ { ID | IDENTIFIER } <identifier-field-2> ]
            FROM <record-queue-name>
            INTO <workspace-name> ;

PARAMETERS

       •label-name
 
An internal unqualified identifier associated with the statement, for flow control operations.

       •workspace-field
 
The name of a field within the data type definition associated with the workspace name. The workspace field identifies the key field within the data type definition. The workspace field must be a uniquely qualified field and cannot specify a variable-length array. The data type of workspace-field must match the data type of the field specified by key-value.
 
The workspace field must be the same field as specified by the key field name that you defined in the record queue specification.

       •key-value
 
A workspace field, string literal, integer literal, or decimal literal to compare to the value of the workspace field specified with BY KEY. ACMSxp software returns the record in which the value of the workspace field equals the value specified in the key value. A workspace field specified in key-value cannot specify a variable-length array. The data type of key-value must match the data type of the field specified in BY KEY workspace-field.
 
Duplicate key values are allowed. Define record queue keys using the record queue specification. Record queue keys have no effect on the order of items in the queue.

       •identifier-field-1
 
An array workspace field of 16 octets (ARRAY SIZE 16 OF OCTET). An identifier uniquely identifies each item in a record queue. In id-workspace field format, identifier- field-1 indicates the identifier of the record that ACMSxp software is to read.

       •record-queue-name
 
An operating system name identifying the record queue from which the record is read.

       •identifier-field-2
 
An array workspace field of 16 octets (ARRAY SIZE 16 OF OCTET). An identifier uniquely identifies each item in a record queue. The field identifier-field-2 specifies the field in id-workspace field format into which ACMSxp software is to write the unique identifier of the record that the system returned to the application.

       •workspace-name
 
An unqualified identifier specifying the name of a workspace that contains the record that ACMSxp software returns on the read queue operation. Declare the workspace name in the workspace declaration of the task definition that contains the READ QUEUE statement.
 
The STDL compiler generates an error, if the size of the workspace specified by the workspace name does not match the size of the data type definition associated with the record queue specified by the record queue name.
 

DESCRIPTION

 
If READ QUEUE is used in a noncomposable task, it must be inside a transaction block.
 
The WITH WAIT, IDENTIFIER, and FROM clauses can be specified in any order.
 
Items in a record queue are ordered by time of insertion. By default, items in a record queue are retrieved using first-in/first-out (FIFO) order.
 
WITH WAIT specifies that the read operation waits for an item to become available if the record queue is empty. If READ QUEUE is the first statement in the transaction block of a noncomposable task, you can specify WITH WAIT. You cannot specify WITH WAIT in a composable task. READ QUEUE default operation is WITH NO WAIT.
 
If WITH NO WAIT is in effect and the record queue is empty, a NO-OUTPUT-ERROR exception is generated. If you specify WITH WAIT and the record queue is empty, the operation stalls until either a record is available or the time limit expires. If the time limit expires, ACMSxp software returns the REQUEST-TIMEOUT-ERROR exception. If the TPsystem is shutdown during the wait time, ACMSxp software returns the SYSTEM-SHUTDOWN-FAULT exception.
 
             _________ What is the Task Environment Info? _________
 
             Specify the time limit for the wait operation with
             environment information for each task.
 
             ______________________________________________________
 
Record queue context (the queue cursor) consists of information needed for a NEXT RECORD, a NEXT RECORD BY KEY, or a RECORD BY IDENTIFIER operation. Because of context, follow these rules to access a queue with READ QUEUE.

oUse either FIRST RECORD or FIRST RECORD BY KEY to access the first record in a transaction. This operation establishes the queue cursor. 
 
You cannot use RECORD BY IDENTIFIER to establish the queue cursor.
 

oIf the cursor is established, use NEXT RECORD, NEXT RECORD BY KEY, or RECORD BY IDENTIFIER to access an available record on the queue. 

-If NEXT RECORD or NEXT RECORD BY KEY is used, the queue cursor is set to point to the next available position in the the queue (context is maintained). 
 

-If RECORD BY IDENTIFIER is used, the queue cursor is undefined (context is lost) after the operation. 
 

-At any point, FIRST RECORD or FIRST RECORD BY KEY sets the queue cursor to point to the first available record on the queue (context is restored). 

oIf no record is found on the queue by any criterion specified, the ACMSxp system returns a nontransaction exception, and the queue cursor is undefined (context is lost). 

Using FIRST RECORD

 
With FIRST RECORD, ACMSxp software returns the first available record in the queue. The operation accesses the record queue specified with FROM and returns the record to the workspace specified with INTO. The operation establishes record queue context for either NEXT RECORD or RECORD BY IDENTIFIER.
 

Using FIRST RECORD BY KEY

 
With FIRST RECORD BY KEY, ACMSxp software returns the first available record where the value of the workspace field equals the value specified in the key value. The data type of the key value must match the data type of the workspace field. The operation establishes record queue context for either NEXT RECORD BY KEY or RECORD BY IDENTIFIER.
 

Using NEXT RECORD

 
With NEXT RECORD, ACMSxp software returns the next available record in the record queue. Within a task group context and a transaction context for a record queue, the previous operation for a NEXT RECORD must be a FIRST RECORD or a NEXT RECORD operation.
 

Using NEXT RECORD BY KEY

 
With NEXT RECORD BY KEY, ACMSxp software returns the next available record in the record queue with the same key value specified in the previous FIRST RECORD BY KEY operation. The previous READ QUEUE operation for a NEXT RECORD BY KEY operation must be a FIRST RECORD BY KEY or NEXT RECORD BY KEY operation.
 

Using RECORD BY IDENTIFIER

 
With RECORD BY IDENTIFIER, ACMSxp software returns a specific record identified by identifier-field-1. After the RECORD BY IDENTIFIER operation completes, the queue cursor is undefined. To use another RECORD BY IDENTIFIER, first re-establish the cursor with either a FIRST RECORD or FIRST RECORD BY KEY operation.
 

Normal Execution Flow

 
The normal execution for READ QUEUE is:

oReturn the record, storing the data in the workspace identified by INTO workspace-name. 
 

oWhen you specify IDENTIFIER identifier-field-2, ACMSxp software stores in the workspace field identifier-field-2 the unique identifier of the returned record. 

 
Deviations from the normal execution flow occur when one of the conditions listed under the Exceptions section occurs. The READ QUEUE statement completes with the exception class associated with the condition. The value of workspace-name is undefined, and if an identifier-field-2 is specified, the value of the field is undefined.
 

EXCEPTIONS

 
The READ QUEUE statement can generate the exception classes described in the following sections. The sections describe the conditions leading to the exception class and suggest actions to take.
 

AP-EXECUTION-FAULT

 
The AP-EXECUTION-FAULT exception class indicates one of the following error conditions:

oThe subscript used to refer to an element in a fixed-length array is invalid (referring to A(n) where n is less than 1 or greater than the maximum size of array). 
 

oThe subscript used to refer to an element in a variable-length array is invalid (referring to A(n) where n is less than one or greater than the value of the DEPENDING ON field). 
 

oThe value of the DEPENDING ON field used when referring to an element of a variable-length array is invalid (the value of the DEPENDING ON field is less than the minimum size of the array or the value of the DEPENDING ON field is greater than the maximum size of array). 
 

oThe size of the workspace specified by the workspace name does not match the size of the target data type definition associated with the record queue. For a workspace that contains a variable-length array, the size of the workspace or record is determined by the DEPENDING ON field for the array. 
 

oThe value of the DEPENDING ON field was invalid when referring to a workspace name or workspace field containing a variable-length array. 
 

oA NEXT RECORD operation is unable to complete successfully because the previous operation was neither a FIRST RECORD nor a NEXT RECORD operation. 
 

oA NEXT RECORD BY KEY operation is unable to complete successfully because the previous operation was neither a FIRST RECORD BY KEY nor a NEXT RECORD BY KEY operation. 

ENV-EXECUTION-FAULT

 
The ENV-EXECUTION-FAULT exception class indicates that the record queue server in the TPsystem in which the task is executing encountered a problem reading a record from the record queue specified by the value of the record queue name in FROM.
 

ENV-INVOCATION-FAULT

 
The ENV-INVOCATION-FAULT exception class indicates one of the following conditions:

oThe record queue specified by the value of the record queue name in FROM is not defined within the environment information of the TPsystem in which the task is executing. 
 

oThe key specified by the workspace field in FIRST RECORD BY KEY is not defined within the environment information of the TPsystem in which the task is executing. 

NO-OUTPUT-ERROR

 
The NO-OUTPUT-ERROR exception class indicates that the record queue is empty or no record is found and WAIT is not specified. No data is returned.
 

REQUEST-TIMEOUT-ERROR

 
The REQUEST-TIMEOUT-ERROR exception class indicates that the record queue is empty and the time limit expired. If you specify WITH WAIT and the time limit expires, ACMSxp software returns this class.
 

SYSTEM-SHUTDOWN-FAULT

 
The SYSTEM-SHUTDOWN-FAULT exception class indicates that the TPsystem stopped and the queue operation was waiting for a record (WITH WAIT is in effect).
 

RELATED INFORMATION

 
Syntax: dequeue_record(1), enqueue_record(1), queue_specification(1), statement(1), transaction_block(1) acmsxp_introduction(1)