Enscribe Programmer's Guide

Specifying Sync-Depth
When you open a queue file, you can specify a sync depth for the file. A non zero sync depth is
supported for all operations except for dequeuing; the sync depth for dequeuing operation must
equal zero.
If you specify a sync depth that I snot equal to zero for any operation other than dequeuing, the
file system attempts to recover from path-related errors (200, 201, 210, and 211). If you specify
a sync depth of zero, no path-related recovery is done and the application is responsible for
responding to path-related error conditions.
Because of the protection a nonzero sync depth provides, it is generally recommended that a sync
depth of one be used for all operations except dequeuing. This implies that multiple opens need
to be done for a queue file that is used simultaneously by the same process for enqueuing and
dequeuing operations if nonzero sync depth protection is desired. For more information about
recovery of retryable errors on queue files, see Communication Path Errors “Communication Path
Errors” (page 121).
Queuing a Record
To queue a record, call the FILE_WRITE64_/WRITE[X] procedure to write the record to the file.
The disk process sets the timestamp field in the key, which causes the record to be positioned after
other existing records that have the same high-order user key.
If the file is audited, the new record is available for read operations when the transaction associated
with the write operation commits. If the transaction aborts, the record is never available to read
operations.
If the file is not audited, the record is available as soon as the write operation completes successfully.
Unlike other key-sequenced files, a write operation to a queue file will never encounter an error
10 (Duplicate record). This is because all queue file records have unique keys generated for them.
Special “Dummy” Record
When the first record is written to a queue file, the disk process inserts a special dummy record
containing all zeros at the front of the file. This record ensures that the file never becomes empty,
avoiding the overhead of collapsing the file and then expanding it whenever the last record is
dequeued.
The dummy record is never dequeued through FILE_READUPDATELOCK64_/READUPDATELOCK[X].
However, the record is visible under these circumstances:
• A FILE_READ64_, FILE_READLOCK64_, READ[X] or READLOCK[X] operation returns the dummy
record.
• The command FUP INFO filename, STAT indicates that the record exists.
• The command FUP COPY filename, newlife causes the dummy record to become a record
that can be dequeued by FILE_READUPDATELOCK64_/READUPDATELOCK[X]. Consequently,
you should be careful using the FUP COPY command on queue files.
Dequeuing a Record
To dequeue a record, call the FILE_READUPDATELOCK64_/READUPDATELOCK[X] procedure. If
the read operation is successful, the disk process deletes the record from the file. If the disk process
cannot return a record because the file is empty or there are no unlocked records which meet the
selection criteria, the disk process retains the request until the file contains a record that fits the
request.
Accessing Queue Files 111