The GET QUEUE statement retrieves a queue record and places it in a storage area associated with the issuing program. If the queue record is larger than the designated storage area, the record is truncated. The system automatically deletes the retrieved record from the queue unless the GET QUEUE statement explicitly keeps the record in the queue.
►►─── GET QUEUE ─┬─────────────────┬─┬───────────────────────────────┬────────► └─ ID (queue-id) ─┘ ├─ NEXT ◄ ──────────────────────┤ ├─ FIRST ───────────────────────┤ ├─ LAST ────────────────────────┤ ├─ PRIOR ───────────────────────┤ ├─ SEQUENCE (sequence-number) ──┤ └─ RECORD ID (queue-record-id) ─┘ ►─┬────────────┬─┬──────────┬─┬────────────┬─────────────────────────────────► ├─ DELETE ◄ ─┤ ├─ LOCK ◄ ─┤ ├─ WAIT ─────┤ └─ KEEP ─────┘ └─ NOLOCK ─┘ └─ NOWAIT ◄ ─┘ ►─── INTO (return-queue-data-location) ──────────────────────────────────────► ►─┬─ TO (end-queue-data-location) ───────┬───────────────────────────────────► └─ MAX LENGTH (queue-data-max-length) ─┘ ►─┬─────────────────────────────────────────────────┬─ ; ────────────────────►◄ └─ RETURN LENGTH INTO (queue-data-actual-length) ─┘
Specifies the 1- to 16-character ID of the queue associated with the record to be retrieved. Queue-id is either the symbolic name of a user-defined field that contains the ID, or the ID itself enclosed in single quotation marks. If the queue ID is not specified, a null ID of 16 blanks is assumed.
Specifies the queue record to be retrieved:
Retrieves the next record in the queue. If currency has not been established, NEXT is equivalent to FIRST. NEXT is the default.
Retrieves the first record in the queue.
Retrieves the last record in the queue.
Retrieves the prior record in the queue. If currency has not been established, PRIOR is equivalent to LAST.
Retrieves the queue record identified by sequence. Sequence is either the symbolic name of a user-defined field that contains the sequence number of the record, or the sequence number itself expressed as a numeric constant.
Retrieves the record identified by queue-record-id. Queue-record-id is the symbolic name of the FIXED BINARY(31) field that contains the queue record ID returned by the PUT QUEUE function.
Specifies whether the queue record will be deleted from the queue after it is passed to the requesting program:
Deletes the record from the queue. Note that if DELETE is specified and the record has been truncated, the truncated data is lost. DELETE is the default.
Keeps the record in the queue.
These parameters have been non-functional since CA IDMS Release 12.0. They are included as parameters for release compatibility. Queue record locking is performed as part of the standard database locking routines since CA IDMS Release 12.0.
Specifies whether the issuing task is to suspend execution if the requested record cannot be found in the queue:
Suspends task execution until the requested queue exists.
Continues task execution in the event of a nonexistent queue. An ERROR_STATUS value of 4405 indicates that the requested queue record cannot be found. NOWAIT is the default.
Indicates the program variable-storage entry of the data area reserved for the requested queue record. Return-queue-data-location is the symbolic name of a user-defined field. The length of the data area is determined by one of the following specifications:
Indicates the end of the program variable-storage entry reserved for the requested queue record and is specified following the last data-item entry in return-queue-data-location. End-queue-data-location is the symbolic name of either a user-defined dummy byte field or a field that contains a data item not associated with the requested queue record.
Explicitly defines the length of the data area reserved for the requested queue record. Queue-data-max-length is either the symbolic name of the user-defined field that contains the length of the queue record's data, or the length itself expressed as a numeric constant.
Specifies the location to which the system will return the actual length of the retrieved queue record. Queue-data-actual-length is the symbolic name of a user-defined 4-byte field. If the record has been truncated, the value returned to this field is the actual length of the queue record before truncation.
The following example retrieves the first record in the RES_Q queue, return it to the PEND_RES field, and keep the record in the queue:
GET QUEUE
ID ('RES_Q')
FIRST
KEEP
INTO (PEND_RES) MAX LENGTH (125);
Upon completion of the GET QUEUE function, the ERROR_STATUS field of the IDMS DC communications block indicates the outcome of the operation:
The request has been serviced successfully.
The requested queue header record cannot be found.
The requested queue record cannot be found.
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.
The program storage area specified for return of the queue record is too small; the returned record has been truncated as appropriate to fit the available space.
The parameter list is invalid. In DC_BATCH, this code signifies that the specified record length has exceeded the maximum length based on the packet size.
The derived length of the queue record data area is negative.
|
Copyright © 2014 CA.
All rights reserved.
|
|