Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

Fixed versus Variable-length Records

The following file modes are related to fixed and variable-length records:

  • ctFIXED

When creating a data file, filmod specifies whether the data records are fixed-length or variable-length. Once a data file is created, its record-length characteristics cannot be changed (i.e. ctFIXED or ctVLENGTH file mode and fixed-length size). The remaining variable-length portions of the record are truly dynamic. Because variable-length records require a little more processing and some extra code, it is advisable to use fixed-length records unless variable-length records are actually necessary.

The file modes are ctFIXED and ctVLENGTH, which can be used with the other file mode constants. The ctVLENGTH file mode should not be applied to index files.

Fixed length data files can be created with record lengths in the range from 5 bytes to 65,535 bytes. Variable-length data files are created with a defined minimum record length. The minimum record length specifies the smallest data record that will be added to the file. Conceptually, this minimum record length corresponds to the fixed-length fields that may be part of your record structure. The minimum fixed-length portion may be set to zero, indicating all fields for this particular record are in the variable-length portion. FairCom recommends placing fields of a constant length, including all numeric fields, (e.g., LONG, COUNT), in the fixed-length portion. The standard ISAM-level retrieval functions, e.g., GetRecord(), NextRecord(), etc., retrieve only the fixed-length portion of variable-length records. ReReadVRecord() is called to retrieve the variable-length portion. This way, the typically small fixed-length portion can be quickly read, without the overhead of reading the variable-length portion. Variable-length ISAM-level retrieval functions, e.g., GetVRecord(), NextVRecord(), etc., retrieve the entire variable-length record.

With variable-length records, all of the fields in the variable-length portion are themselves variable-length fields terminated with a delimiter. This delimiter is typically the NULL character, unless you have changed the value of the delimiter with the SetVariableBytes() function. The following figure demonstrates the recommended method for creating variable-length field buffers. The delimiter is shown as a null byte, but it can be set to any delimiter.

Once the data is packed into the buffer as illustrated in the previous schematic, the record buffer and buffer length can be passed to AddVRecord() for insertion into the variable-length data file.

The maximum fixed-length portion is 65522. The total length of a variable-length record is 2GB, as long as the application has buffer space to hold the record this large. c-tree capacity limits are available in FairCom DB Capacity Planning.

If you are not going to use a field in the variable-length portion of the record to build an ISAM key you can put any type of field there that you wish. c-tree treats the variable-length portion as a contiguous string of bytes. However, if you are going to build an ISAM key with a variable-length field you have to be careful. You can, however, place any type of field in the variable-length portion of the record if you use a Record Schema, (see Record Schemas). However, even with a Record Schema the application is still responsible for packing and unpacking the variable-length record. All fields in the variable-length portion must be packed as opposed to aligned. No padding bytes are allowed between fields.