Queue and Scratch Management Commands › PUT QUEUE

PUT QUEUE

Purpose

Stores a queue record in the data dictionary.

Syntax

►►─── PUT QUEUE ─────┬───────────────┬──────────┬─ LAST ◄ ─┬──────────────────►
                     └─ ID queue-id ─┘          └─ FIRST ──┘

 ►─── FROM queue-data-location-variable ──────────────────────────────────────►

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

 ►──┬────────────────────────────────────────────┬────────────────────────────►
    └─ RETENTION is ──┬─ FOREVER ◄ ──────────────┤
                      └─ queue-retention-period ─┘

 ►──┬─────────────────────────────────────────────────────┬───────────────────►
    └── RETURN RECORD ID into return-queue-id-variable ───┘

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

Parameters

ID queue-id

Stores a record in the queue identified by queue-id.

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.

LAST

Stores a record at the end of the queue.

LAST is the default when you specify neither LAST or FIRST.

FIRST

Stores a record at the beginning of the queue.

FROM queue-data-location-variable

Specifies the location of the data to be stored in the queue record.

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 that contains the queue record data.

End-queue-data-location-variable is the name of a variable data field that contains a data item not associated with the queue record data.

The field specified by end-queue-data-location-variable must immediately follow the last byte of the buffer area that contains the queue record data.

LENGTH queue-data-length

Specifies the length, to be specified in bytes, of the buffer area that contains the data to be stored in the queue record.

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

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

RETENTION

Introduces the number of days, in the range 0 through 255, that the queue is to be retained.

A retention period of 255 is equivalent to FOREVER.

FOREVER

Retains the queue until all queue records associated with the queue are explicitly deleted.

FOREVER is the default when the queue's retention period is not otherwise specified.

queue-retention-period

The name of a variable data field that contains the retention period or the retention period itself, expressed as a numeric constant.

RETURN RECORD ID into return-queue-id-variable

Returns a system-assigned queue record id to the location specified by return-queue-id-variable.

The queue record id is returned as a binary fullword and is converted, as appropriate, when it is moved to return-queue-id-variable

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

Return-queue-id-variable cannot be a doubleword binary field. The system-assigned queue record id can subsequently be used to retrieve or delete the associated queue record.

error-expression

Specifies the status codes that are returned to the dialog.

Usage

Considerations

If autostatus is not in use, a dialog's error-status field indicates the outcome of a PUT QUEUE command:

Example

The following example illustrates the use of the PUT QUEUE command to store the data in CUSTWORK in a queue record associated with queue CUSTQ:

PUT QUEUE ID 'CUSTQ' FROM CUSTWORK LENGTH REC-LENGTH
    RETURN RECORD ID INTO REC-ID.

More information:

Error Handling