Record Length

All records contain the record length, a fixed-length portion which must be large enough to contain all the data (including keys) for a record, plus the overhead required to store a record on a data page. The following table shows how many bytes of overhead you must add to the logical record length to obtain a physical record length.


Type of Overhead	Bytes
Record usage count	2 (only for 6.0 and later files)
Linked-duplicatable keys	8 (per key)
Reserved duplicate pointers¹	8 (per pointer)
Variable-length record pointer	4 (if file enables variable-length records)
Blank truncation	2 (if file does not use VATs) 4 (if file uses VATs)
Record length	4 (if file uses VATs) 8 (if file uses system data)

¹Reserved duplicate pointers apply only to linked-duplicatable keys.

Given that the largest page size is 4,096 bytes, the maximum fixed-length record size is 4,088 bytes, unless you use Data Compression (page 4-59).

Note
Btrieve automatically uses Data Compression (page 4-59) on files that use System Data and have a record length greater than 4,076 bytes.

Optionally, the records in a file can contain a variable-length portion. A variable-length record has a fixed-length portion that is the same size in every record and a variable-length portion that can be a different size in each record. When you create a file that uses variablelength records, the fixed-length amount is the minimum length of each record; you do not define the maximum record length.

Theoretically, the maximum length of variable-length records is limited only by Btrieve's file size limit: 64 GB. In reality, the maximum is limited by such factors as the operating system and record access method you choose. If you retrieve, update, or insert whole records, then the data buffer length parameter, because it is a 16-bit unsigned integer, limits the record length to 65,535.

A data buffer is a Btrieve function parameter that you use to transfer various information depending on the operation being performed. A data buffer can contain all or part of a record, a file specification, and so forth. Refer to Table 5-3 in Chapter 5, Designing the Database for more information on data buffers.

Note
NetWare developers: The maximum record length is 57,000 bytes. This limit applies to all NetWare Btrieve clients, including NLM applications making calls to remote NetWare servers.

Windows developers: The total bytes of data plus internal header information cannot exceed 64 KB (0x10000) bytes. Btrieve reserves 1,024 (0x400) bytes for internal purposes, meaning you can have 64,512 (0xFC00) bytes of data.

If your file uses very large records, consider using variable-tail allocation tables (VATs) in the file. A VAT, which is implemented as a linked list, is an array of pointers to the variable-length portion of the record. VATs accelerate random access to portions of very large records. Some examples of very large records are binary large objects (BLOBs) and graphics.

For files that contain very large variable-length records, Btrieve splits the record over many variable pages and connects the pages using a linked list called a variable tail. If an application uses chunk operations to access a part of a record and that part of the record 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 that offset. To limit such seek time, you can specify that the file use VATs. Btrieve stores the VAT on variable pages. In a file containing a VAT, each record that has a variable-length portion has its own VAT.

Btrieve uses VATs not only to accelerate random access, but also to limit the size of the compression buffer used during data compression. If your files use data compression, you may want to use VATs in the file.