Enscribe Programmer's Guide

For audited queue files only, your application can recover from a timeout error by calling the
ABORTTRANSACTION procedure to ensure that any dequeued records are reinserted into the file.
The corresponding transaction must then be restarted.
NOTE: For unaudited queue files, your application should never call
AWAITIO[X]/FILE_AWAITIO64_ with a time limit greater than OD if a
READUPDATELOCK[X]/FILE_READUPDATELOCK64_ is pending. The recovery procedure described
above does not work on unaudited queue files.
Dequeuing From Unaudited Files
If the read operation is not successful because the file is empty or all records are locked, the read
is suspended until one of these events occurs:
• The disk process waits until a FILE_WRITE64_/WRITE[X] operation completes successfully.
• If a special queue file timeout on the read operation expires, the disk process returns an error
162 (operation timed out) to the requesting process.
As with audited files, one exception is the use of exact positioning. If the application requests exact
positioning and the file is empty or the record does not exist, the
FILE_READUPDATELOCK64_/READUPDATELOCK[X] operation receives an error 11 (record not
found) and does not queue the request.
Examining a Record
To read a record without deleting it, use the FILE_READ64_, FILE_READLOCK64_, READ[X] or
READLOCK[X] procedures. These procedures function exactly the same as when used for a
key-sequenced file. Note, however, that FILE_READ64_, FILE_READLOCK64_, READ[X] and
READLOCK[X] differ from FILE_READUPDATELOCK64_/READUPDATELOCK[X] in these ways:
• The disk process does not delete a record after reading it
• If no record is available, the request is not retained and the disk process returns an error 1
(EOF)
• A read operation returns the entire record, including the 8-byte timestamp. To delete the record
after examining it, use exact positioning and then call the
FILE_READUPDATELOCK64_/READUPDATELOCK[X] procedure.
Dequeuing With Positioning
To change the access path and positioning dynamically, you can precede calls to
FILE_READUPDATELOCK64_/READUPDATELOCK[X] with a call to FILE_SETKEY_ or KEYPOSITION.
This method allows an application to move to a random position in the file, establish a subset of
records to be retrieved, and apply other selection rules according to the specified parameters.
The disk process does not dequeue locked records. Locked records which exist within the desired
key range are skipped until an unlocked record is found or the key in a record is outside of the
desired range.
Approximate Positioning
Figure 17 (page 115) illustrates how approximate positioning works for a queue file when the call
to FILE_SETKEY_ (or equivalent call to KEYPOSITION) has these parameters:
key-value = "MA"
positioningmode = 0
comparelength is omitted = 2
The queue file has a key length of 10 bytes, so the user key length is 2 bytes.
114 Queue Files