Queue and Scratch Management Commands › GET QUEUE

GET QUEUE

Purpose

Transfers the contents of a queue record to a specified location in a dialog's record buffers.

Syntax

►►─── GET QUEUE ───────┬───────────────┬──────────────────────────────────────►
                       └─ ID queue-id ─┘

 ►───┬─ DELETE ◄ ─┬────────────────┬─ NOWAIT ◄ ─┬─────────────────────────────►
     └─ KEEP ─────┘                └─ WAIT ─────┘

 ►───── INTO return-queue-data-location-variable ─────────────────────────────►

 ►───┬────────────────────────────────────────┬───────────────────────────────►
     ├─ TO end-queue-data-location-variable ──┤
     └─ MAX LENGTH queue-data-max-length ─────┘

 ►───┬─ FIRST ───────────────────────┬────────────────────────────────────────►
     ├─ LAST ────────────────────────┤
     ├─ NEXT ◄ ──────────────────────┤
     ├─ PRIOR ───────────────────────┤
     ├─ SEQUENCE sequence-number ────┤
     └─ RECORD ID queue-record-id ───┘

 ►───┬───────────────────────────────────────────────────────────┬────────────►
     └── RETURN LENGTH into queue-data-actual-length-variable ───┘

 ►───┬────────────────────┬────── . ──────────────────────────────────────────►◄
     └─ error-expression ─┘

Parameters

ID queue-id

Specifies the queue-id to be retrieved.

Queue-id is either the name of a variable data field that contains a queue id or the 1- to 16-character queue id itself, enclosed in single quotation marks.

If queue-id is not specified, a null queue id (that is, 16 blanks) is assumed.

DELETE

Deletes the record from the queue after it is passed to the requesting task. If the record is truncated, the truncated data may be lost permanently.

DELETE is the default when you specify neither DELETE or KEEP.

KEEP

Retains the record in the queue after it is passed to the requesting task.

NOWAIT

Continues task execution in the event of a nonexistent queue. NOWAIT is the default when you specify neither NOWAIT or WAIT.

WAIT

Suspends task execution until the requested queue exists.

INTO return-queue-data-location-variable

Specifies the location to which the requested queue record is transferred.

Return-queue-data-location-variable is the name of a variable data field in the dialog's record buffers.

TO end-queue-data-location-variable

Specifies the end of the buffer area allocated for the requested queue record.

End-queue-location-variable is either the name of a dummy byte field or the name of a variable data field that contains a data item not associated with the requested queue record. The field specified by end-queue-data-location must immediately follow the last byte of the buffer area allocated for the requested queue record.

MAX LENGTH queue-data-max-length

Specifies the length of the buffer area allocated for the requested queue record.

Queue-data-max-length is either the name of a variable data field that contains the length of the buffer area allocated for the requested queue record or the length itself, expressed as a numeric constant.

If neither TO end-queue-data-location-variable nor MAX LENGTH queue-data-max-length is specified, the length of the location is the length of return-queue-data-location-variable.

FIRST

Obtains the first record in the queue that is specified by queue-id.

LAST

Obtains the last record in the queue that is specified by queue-id.

NEXT

Obtains the record that follows the current record of the queue specified by queue-id.

NEXT is the default when you specify no other queue record to be obtained.

If currency is not established, NEXT is equivalent to FIRST.

PRIOR

Obtains the record that precedes the current record in the queue specified by queue-id.

If currency is not established, PRIOR is equivalent to LAST.

SEQUENCE sequence-number

Obtains the nth record in the queue specified by queue-id.

Sequence-number is either the name of a variable data field that contains the sequence number or the sequence number itself, expressed as a numeric constant.

RECORD ID queue-record-id

Obtains the record identified by queue-record-id.

Queue-record-id is either the name of a numeric variable data field that contains the system-assigned queue record id or the queue record id itself, expressed as a numeric constant.

Queue-record-id cannot be a doubleword binary field. The runtime system converts the queue record id to a binary fullword for internal storage.

RETURN LENGTH into queue-data-actual-length-variable

Returns the untruncated length of the obtained queue record to the location specified by queue-data-actual-length-variable.

Queue-data-actual-length-variable is the name of a numeric field in the dialog's record buffers.

error-expression

Specifies the status codes that are returned to the dialog.

Usage

Considerations

• If the queue record is larger than the allocated buffer area, the record is truncated as necessary. Deletion of the record from the queue after the transfer is complete can be specified.
• If autostatus is not in use, a dialog's error-status field indicates the outcome of a GET QUEUE command:

Example

The following example illustrates the use of the GET QUEUE command. The data in the last record in queue CUSTQ is transferred to the location in the dialog's record buffers identified by CUSTWORK. The record is deleted from the queue:

GET QUEUE ID 'CUSTQ' INTO CUSTWORK MAX LENGTH REC-LENGTH LAST.

More information:

Error Handling