CA IDMS Reference 19.0

PDF
English

GET QUEUE (COBOL)

The GET QUEUE statement retrieves a queue record and places it in a storage area that is associated with the issuing program. If the queue record is larger than the designated storage area, the record is truncated. The retrieved record is automatically deleted from the queue unless the GET QUEUE statement explicitly requests to keep the record in the queue.
idmscu
The GET QUEUE statement retrieves a queue record and places it in a storage area that is associated with the issuing program. If the queue record is larger than the designated storage area, the record is truncated. The retrieved record is automatically deleted from the queue unless the GET QUEUE statement explicitly requests to keep the record in the queue.
Syntax

►►─── GET QUEUE ─┬───────────────┬─┬─────────────────────────────────┬────────►
                 └─ ID 
queue-id
 ─┘ └─┬─ NEXT ◄ ────────────────────┬─┘
                                     ├─ FIRST ─────────────────────┤
                                     ├─ LAST ──────────────────────┤
                                     ├─ PRIOR ─────────────────────┤
                                     ├─ 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
 ─┘
Parameters
  • ID 
    queue-id
    Specifies the queue that is associated with the record to retrieve. Specify the symbolic name of a user-defined field that contains the ID, or the ID itself enclosed in quotation marks. If the queue ID is not specified, a null ID of 16 blanks is assumed.
  • NEXT
    Retrieves the next record in the queue. This value is the default. If currency has not been established, NEXT is equivalent to FIRST.
  • FIRST
    Retrieves the first record in the queue.
  • LAST
    Retrieves the last record in the queue.
  • PRIOR
    Retrieves the prior record in the queue. If currency has not been established, PRIOR is equivalent to LAST.
  • SEQUENCE 
    number
    Retrieves the specified queue record. Specify 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.
  • RECORD ID 
    queue-record-id
     
    Retrieves the specified record. Specify the symbolic name of the PIC S9(8) COMP (fullword) field containing the queue record ID that the PUT QUEUE function returned.
  • DELETE
    Deletes the record from the queue. This value is the default. If DELETE is specified and the record has been truncated, the truncated data is lost.
  • KEEP
    Keeps the record in the queue.
  • LOCK|NOLOCK
    These parameters have been nonfunctional since CA IDMS Release 12.0, and are included only for release compatibility. Queue record locking is now performed as part of the standard database locking routines.
  • WAIT
    Suspends task execution until the requested queue exists.
  • NOWAIT
    Continues task execution when a queue is nonexistent. This value is the default.
  • INTO 
    return-queue-data-location
    Specifies the WORKING-STORAGE SECTION or LINKAGE SECTION entry of the data area that is reserved for the requested queue record. Specify the symbolic name of a user-defined field.
  • TO 
    end-queue-data-location
    Specifies the end of the WORKING-STORAGE SECTION or LINKAGE SECTION entry that is reserved for the requested queue record. Specify the symbolic name of a user-defined dummy byte field or a field with a data item that is not associated with the requested queue record.
  • MAX LENGTH 
    queue-data-max-length
    Explicitly defines the length of the data area that is reserved for the requested queue record. Specify the symbolic name of the user-defined field that contains the length of the queue records data, or the length itself expressed as a numeric constant.
  • RETURN LENGTH INTO 
    queue-data-actual-length
    Specifies where to return the actual length of the retrieved queue record. Specify the symbolic name of a user-defined 4-byte field. If the record has been truncated, the returned value is the actual length of the queue record before truncation.
Example
The following example retrieves the first record in the RES-Q queue, returns it to the PEND-RES field, and keeps the record in the queue:

GET QUEUE
  ID 'RES-Q'
  FIRST
  KEEP
  INTO PEND-RES MAX LENGTH 125.
Status Codes
After completion of the GET QUEUE function, the ERROR-STATUS field of the IDMS-DC communications block indicates the outcome:
Status code
Meaning
0000
The request has been serviced successfully.
4404
The requested queue header record cannot be found.
4405
The requested queue record cannot be found.
4407
A database error occurred during queue processing. A DBKEY deadlock is a common cause. For a PUT QUEUE operation, this code can also mean that the queue upper limit has been reached.
If a database error has occurred, the CA-IDMS/DC/UCF log usually includes other messages indicating a problem encountered in RHDCRUAL, the internal Run Unit Manager. If a deadlock has occurred, messages DC001000 and DC001002 are also produced.
4419
The program storage area that was specified for return of the queue record is too small. The returned record has been truncated to fit the available space. In a DC-BATCH environment, the size of the queue record may exceed the MAX LENGTH value specified in the BIND TASK statement. This problem can also happen when the record size that is specified in the GET QUEUE statement is large enough for the queue record, but larger than the maximum that is specified in the BIND TASK statement. The record size is always truncated to the maximum length that is specified in the BIND TASK statement.
4431
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.
4432
The derived length of the queue record data area is negative.