dequeue record(1) — Commands
Digital
NAME
DEQUEUE RECORD − statement in a task that reads a record from a local queue and deletes the record
SYNOPSIS
[<label-name>:] DEQUEUE
{ FIRST RECORD |
RECORD BY KEY <workspace-field> VALUE <key-value> |
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 use in flow control operations.
•workspace-field
A uniquely qualified field within the data type definition associated with the workspace name. The workspace field identifies a key field within the record queue specification. The data type of the workspace field must match the data type of the field specified by key-value.
•key-value
A workspace field, string literal, integer literal, or a decimal literal to compare to the value of the workspace field specified with RECORD BY KEY. ACMSxp software returns the record queue entry in which the value of the workspace field equals the value specified in the key value.
The 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.
•identifier-field-1
An array workspace field of 16 octets (ARRAY SIZE 16 OF OCTET). An identifier uniquely identifies each item in a specific record queue. When you enqueue a record, ACMSxp software can return the unique identifier of that record.
The field identifier-field-1 allows you to dequeue a specific record by the unique identifier.
•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 allows you to store the identifier of any record being dequeued. Use the identifier-field-2 to specify a workspace field into which ACMSxp software writes the unique identifier of the dequeued record. The field cannot be a variable length array.
•record-queue-name
An operating system name identifying the record queue from which the record is dequeued.
•workspace-name
An identifier specifying the name of workspace that is to contain the information that ACMSxp software returns on the dequeue operation. You must specify the workspace name in the workspace declaration of the task definition that contains the DEQUEUE RECORD. The record layout used in the record queue specified in FROM must match the record layout associated with the workspace specified in INTO.
The STDL compiler generates an error if the size of the record layout associated with the record queue specified in FROM does not equal the size of the workspace specified in INTO.
DESCRIPTION
If the DEQUEUE statement is used in a noncomposable task, it must be inside a transaction block.
DEQUEUE default operation is WITH NO WAIT. If you specify WITH NO WAIT and the record queue is empty, a NO-OUTPUT-ERROR exception is generated.
WITH WAIT causes the dequeue operation to wait for an item to become available if the record queue is empty. If DEQUEUE 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. Specify the time limit for the wait operation with environment information for each task.
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.
The DEQUEUE operation accesses the record queue specified with FROM and returns the record to the workspace specified with INTO. Items in a record queue are ordered by time of insertion. After an item is dequeued, it is deleted from the record queue.
With FIRST RECORD, ACMSxp software dequeues the first available record from the head of the queue. Items are retrieved using first-in/first-out (FIFO) order.
With RECORD BY KEY, ACMSxp software dequeues the first available record from the head of the queue where the value of the workspace field equals the value specified in the key value. Duplicate key values are allowed. The data type of the key value must match the data type of the workspace field. Define record queue keys using the record queue specification. Record queue keys have no effect on the order of items in a queue.
With RECORD BY IDENTIFIER, ACMSxp software dequeues a specific, unique record identified by identifier-field-1. This identifier originates when the record is written to the queue by ENQUEUE RECORD and is guaranteed to be unique for any one queue.
If the dequeue operation removes the record to which the queue cursor points, the ACMSxp software adjusts the cursor to point to the record immediately preceding the deleted record. If the queue cursor is not pointing at the record being deleted, the ACMSxp software does not adjust the queue cursor.
The normal execution for DEQUEUE is:
1.Dequeue the record, storing the data in the workspace identified by INTO workspace-name.
2.When you specify IDENTIFIER identifier-field-2, ACMSxp software stores in identifier-field-2 the unique identifier of the dequeued record.
Deviations from the normal execution flow occur when one of the conditions listed under the Exceptions section occurs. The DEQUEUE 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 identifier-field-2 is undefined.
EXCEPTIONS
The DEQUEUE statement can generate the exception classes described in the following sections.
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 one 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 the 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 layout 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.
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 dequeuing 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 RECORD BY KEY is not defined in the record queue specified.
NO-OUTPUT-ERROR
The NO-OUTPUT-ERROR exception class indicates that WITH NO WAIT is in effect and the record queue is empty. 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: data_type_definition(1), enqueue_record(1), exception_handler(1), queue_specification(1), read_queue(1), task_definition(1), workspace(1)