|
|
|
FairCom DB allows variable-length records which are useful for storing data that is, well, variable in length. XML and JSON information are typical text examples and images, PDFs are frequent types of binary documents stored in variable-length files. Any type of data that is not of a predetermined fixed size can be stored in the variable fields of a record. Variable-length records are limited to 2 GB, with a length (represented by the signed 4-byte varlen parameter). Adding and retrieving data is somewhat different in variable-length records as described in "Fixed versus Variable-length Records".
Note that variable-length records can still entertain a fixed-length portion. Specific variable-length API calls are used with variable-length records, and are denoted with a V in the name to distinguish from corresponding fixed record functions. For example, AddRecord() for fixed records, and AddVRecord() for variable-length. However, fixed length API calls can be used with variable-length records and only the fixed length portion is returned in this case. This is a useful technique for performance, as fixed handling, in general, is more efficient than variable-length handling. Simply re-read the record if needing to access the variable-length portion. The opposite is not true and calling a variable-length function on a fixed length file results in a FMOD_ERR (48, data file is not a variable-length file.)
Hint: The ReWritePartialRecord() API call is useful to avoid writing the entire variable-length portion of the record.
Each variable-length record is proceeded by a 10-byte variable-length record header consisting of the following portions:
The record mark is 0xFAFA for an active variable-length record. Deleted variable-length records are marked 0xFDFD.
The total length is the space used by the header, the actual data image, plus any extra space not currently used by the record. The utilized length is the length of the actual data not including the header or any extra space. In a properly configured file, moving from the first byte of the record header by the total length should place you on the first byte of the next record in the file.
Variable-length records are enabled with a filmod value of ctVLENGTH (0x0004) when creating a file. Index files CANNOT be created with a ctVLENGTH mode.
Deleted Space Management
Deleted space management is different in variable-length files compared to fixed length files. In variable-length files a space management index is embedded into the file and used to keep track of deleted space. With the FairCom DB server technology, a separate thread is used within the server to maintain this index.
A RECBYT index can improve the usage of this special index. Note that the space management index is invalidated under specific conditions should the file be rebuilt, and the old index will consume file space. If this is a problem for larger files, consider compacting the file.
FYI - Resources are specialized types of variable-length records, beginning with 0xFEFE as the 2-byte record mark.
