A record represents a set of logically associated data items in a Btrieve file. Generally, a record is the unit transferred between an application and Btrieve in a single operation.
No inherent restrictions apply to the number of records allowed in a Btrieve file. A record can consist entirely of a fixed-length portion (a fixed-length record), or it can consist of a fixed-length portion followed by a variable-length portion (a variable-length record). All the keys defined for the file must be located within the fixed-length portion of the record.
In a file that uses fixed-length records, the length of each record in that file must be the same. The maximum length of a fixed-length record depends on the physical page size and the number of duplicate keys you define for the file.
Btrieve allows a fixed-length record to contain up to 4,088 bytes (4,096 minus 6 bytes for page overhead information, and 2 bytes for the record usage count). Therefore, the largest possible fixed-length record is 4,088 bytes.
Variable-length records store data of indeterminate length. When you create a Btrieve file, you can specify that you want the file to use variable-length records.
A variable-length record has a fixed-length portion and a variable-length portion. While the fixed-length portion of all variable-length records in a file must be the same size, the variable-length portion can vary. This means that the overall length of each variable-length record in the file can vary.
When you create a Btrieve file that uses variable-length records, you specify the length in bytes of the fixed-length portion of each record. This length is the minimum length of each record. You do not define the maximum record length.
When you insert or update a record, the application uses the data buffer length parameter to specify the length of the record to Btrieve. If the data buffer length you specify is less than the defined fixed-length portion of the record, Btrieve returns a status code and does not insert or update the record.
If the data buffer length is equal to the length of the fixed-length portion of the record, Btrieve will store none of the variable-length portion of the data.
When you attempt to read a record longer than the length specified in your data buffer length parameter, Btrieve returns as much of the record as possible, based on the data buffer length you specified. Btrieve then returns Status Code 22 (The data buffer parameter is too short) to inform you that it did not read the entire record.
If you specify a data buffer length longer than the record you want to retrieve, Btrieve returns only the number of bytes in the actual record. In all cases, Btrieve informs the application of the number of bytes it returned by setting the data buffer length parameter to that value.
In a Btrieve file, each page is the same size, and the maximum length of a page is 4,096 bytes. Btrieve splits the variable-length portion of a record between as many variable pages as necessary to accommodate the record's length.
Accordingly, for a file with a page size of 4,096 bytes and a variable-length portion that is 409,600 bytes long, Btrieve would split the record between at least 100 variable pages (409,600/4,096). Btrieve connects these pages (or more precisely, the parts of these pages devoted to the record) as a linked list. This linked list is called a variable tail.
If an application uses chunk operations to access part of a record, and that part begins at an offset well beyond the beginning of the record itself, Btrieve may spend considerable time reading the variable-tail linked list to seek to that offset.
To limit such seek time in nonsequential access to very large records, Btrieve 6.1 introduced a new file structure called the Variable-tail Allocation Table (VAT). Btrieve stores the VAT on variable pages. In a file containing VATs, each record that has a variable-length portion has its own VAT.
Using a record's VAT, Btrieve can divide the variable-length portion of that record into smaller portions and then store those portions in any number of variable tails. Btrieve stores an equal amount of the record's data in each of the record's variable tails (except the final variable tail).
Btrieve can use the VAT to accelerate a seek to a large offset in a record because the VAT allows it to skip reading the variable tails containing the record's lower-offset bytes.
Btrieve maintains the Free Space List for variable pages. The Free Space List indicates which variable pages contain the same or more free space than that specified by the Free Space Threshold file specification.
The Free Space Threshold file specification (discussed in Free Space Threshold in Appendix B) is a value you can specify when you create a file. This value, expressed as a percentage, tells Btrieve how much free space must remain on a variable page in order for that page to appear on the Free Space List.
When Btrieve adds new variable-length records to the file, it uses pages in the Free Space List before using new variable pages. After each insert, update, or delete operation, Btrieve rechecks the remaining space on the affected variable page to see if it is still above the threshold to qualify for the Free Space List.
The free space threshold feature provides a means of reducing the fragmentation of variable-length records across several pages. A higher free space threshold reduces fragmentation at the cost of requiring more disk space for the file.
If you specify the Data Compression option (discussed in Data Compression) when you create a Btrieve file, Btrieve compresses the file's records before inserting or updating them and uncompresses the records when it retrieves them.
The length of a record after compression depends on its contents. Even records whose lengths are equal before compression are likely to have different lengths after compression. For this reason, Btrieve stores compressed records on variable pages, even if during the create operation the file was specified as not allowing variable-length records.
A compressed fixed-length-record file differs from a compressed variable-length-record file only in that Btrieve prevents insert and update operations from producing a record longer than a compressed fixed-length-record file's specified record length.
Compressed record files do, however, have data pages. A record's entry on its data page establishes an address for the record so that the Btrieve Step and Get Direct/Record operations can find the record. (See Accessing Records by Physical Location.)
The data page entry can also provide links to other records sharing a duplicate key value, and it provides a pointer to the record's contents, which are compressed and stored on variable pages.