Data Manipulation Language Statements › PUT QUEUE (DC/UCF)

PUT QUEUE (DC/UCF)

The PUT QUEUE statement stores a queue record in either the DDLDCRUN or the DDLDCQUE area of the data dictionary. The DC/UCF system assigns an ID to the queue record and places it at the beginning or end of its associated queue.

Syntax

►►─── PUT QUEUE ─┬─────────────────┬─┬──────────┬─────────────────────────────►
                 └─ ID (queue-id) ─┘ ├─ FIRST  ─┤
                                     └─ LAST ◄ ─┘

 ►─── FROM (queue-data-location) ─┬─ TO (end-queue-data-location) ─┬──────────►
                                  └─ LENGTH (queue-data-length) ───┘

 ►─┬──────────────────────────────────────────────────┬───────────────────────►
   └─ RETURN RECORD ID INTO (return-queue-record-id) ─┘

 ►─┬──────────────────────────────────────┬─ ; ───────────────────────────────►◄
   └─ RETENTION (queue-retention-period) ─┘

Parameters

ID (queue-id)

Directs the queue record to a previously defined queue. Queue-id is either the symbolic name of a user-defined alphanumeric field that contains the 1- to 16-character ID, or the ID itself enclosed in single quotation marks. If a queue ID is not specified, a null ID of 16 blanks is assumed.

FIRST/LAST

Specifies whether the queue record is to be placed at the beginning or end of the queue. The default is LAST.

FROM (queue-data-location)

Specifies the program variable-storage entry associated with the data to be stored in the queue record. Queue-data-location is the symbolic name of a user-defined field.

TO (end-queue-data-location)

Indicates the end of the program variable-storage entry that contains the data to be stored in the queue and is specified following the last data-item entry in queue-data-location. End-queue-data-location is the symbolic name of a user-defined dummy byte field or a field that contains a data item not associated with the queue record.

LENGTH (queue-data-length)

Explicitly defines the length, in bytes, of the area that contains the data to be stored in the queue record. Queue-data-length is either the symbolic name of a user-defined field that contains the length or the length itself expressed as a numeric constant.

RETURN RECORD ID INTO (return-queue-record-id)

Specifies the location in the program to which the system will return the system assigned ID of the queue record. Return-queue-record-id is the symbolic name of a user-defined FIXED BINARY(31) field. The returned ID is used to reference the queue record in subsequent GET QUEUE and DELETE QUEUE statements.

RETENTION (queue-retention-period)

Specifies the time, in days, that the system will retain the queue in the data dictionary. At system startup, queues having expired retention periods are deleted automatically by the system. The retention period begins when the first record is stored in the queue.

Queue-retention-period is either the symbolic name of a user-defined fixed binary field that contains the retention period or the retention period itself expressed as a numeric constant in the range 0 through 255. A retention period of 255 indicates that the queue is never to be deleted automatically by the system. The specified retention period takes precedence over retention periods associated with previously defined queues. The RETENTION parameter is ignored if the record being allocated is not the first record in the queue.

Note: If RETENTION is omitted, the default retention period for dynamic queues is taken. For more information on the default retention period for dynamic queues, see the CA IDMS System Generation guide.

Example

The following Example allocates a queue record in the beginning of the RES_Q queue, return the ID of the record to the Q_REC_ID field, and retain the queue for 45 days:

PUT QUEUE
  ID ('RES-Q')
  FIRST
  FROM (NEW_RES) TO (END_NEW_RES)
  RETURN RECORD ID INTO (Q_REC_ID)
  RETENTION (45);

Status Codes

Upon completion of the PUT QUEUE function, the ERROR_STATUS field in the IDMS DC communications block indicates the outcome of the operation:

0000

The request has been serviced successfully.

4407

A database error occurred during queue processing. A common cause is a DBKEY deadlock. For a PUT QUEUE operation, this code can also mean that the queue upper limit has been reached.

If a database error has occurred, there are usually be other messages in the CA-IDMS/DC/UCF log indicating a problem encountered in RHDCRUAL, the internal Run Unit Manager. If a deadlock has occurred, messages DC001000 and DC001002 are also produced.

4431

The parameter list is invalid; under DC-BATCH, this status indicates that the specified record length exceeds the maximum length based on the packet size.

4432

The derived length of the specified queue record is either zero or negative.