Enscribe Programmer's Guide

• FILE_WRITE64_, WRITE[X]
• FILE_GETINFO_, FILE_GETINFOLIST_, FILE_GETINFOBYNAME_, FILE_GETINFOLISTBYNAME_
Types of Access
Like key-sequenced files, queue files can be accessed by applications either sequentially or randomly.
Queue File Structure
Queue files are physically organized as one or more bit-map blocks and a B-tree structure of index
and data blocks. Organization is the same as for key-sequenced files, described in “Key-Sequenced
Files” (page 68). Queue files are distinguished from other key-sequenced files by having item 48
of the FILE_GETINFOLIST_procedure set to 1. The superseded FILEINFO procedure has bit 9 set in
the file-type word if the file is a queue file.
Primary Keys
Each record in a queue file consists of a primary key and data. At a minimum, the primary key
consists of an 8–byte timestamp generated by the disk process when a record is inserted in the
file. In addition, you can define a user key that precedes the timestamp within the primary key.
The disk process maintains the timestamp as part of each record. This ensures that each record
has a unique key and it eliminates the need to use an application-defined key for insertion or
deletion of records. When you read a record from a queue file, the timestamp is part of the returned
data. When you write a record, the disk process places the timestamp in the low-order eight bytes
of the key, overwriting any information stored in those bytes.
Although you do not need to maintain or use the timestamp portion of the key, you do not need
to specify the eight bytes when you create the file. Thus, all key lengths must be defined as at least
eight bytes long. If you do not define a user key, the data begins at the eighth byte. If you do
supply a user key, it precedes the timestamp. The data begins at the length of your key plus eight
bytes. (For more information, see “Creating Queue Files” (page 108)
Figure 15 (page 108) shows the format of each physical record.
Figure 15 Queue File Record Format
User key
(optional)
Timestamp
(8 bytes)
Data
Creating Queue Files
To create a queue file, use the File Utility Program (FUP) or call the FILE_CREATE_ or
FILE_CREATELIST_ procedure. You cannot define partitions or alternate keys for queue files.
When you create a queue file, be sure to leave room for the 8–byte timestamp in the key. If you
do not need a user-defined key, specify a key length of eight bytes for the file. Otherwise, specify
the length of your key plus eight bytes. In addition, leave room for the 8–byte key in your record
length definition.
The key offset value must equal zero. You can omit the key specifier designation; however, if you
set it, it must equal zero.
When you create an Enscribe queue file, you can specify the size of the primary and secondary
extends. Format 1 files can have from 1 through 65,535 pages (where a page is 2048 bytes).
Format 2 files can have from 1 through 536,870,912 pages.
108 Queue Files