Product Documentation

c-treeDB API for C++ - Developers Guide

Previous Topic

Next Topic

Hidden fields

There are three special fields that are automatically included by c-treeDB in the table record definition. FairCom DB SQL makes extensive use of the null flag and ROWID fields:

  • the delete flag ($DELFLD$)
  • the null flag ($NULFLD$)
  • the ROWID fields ($ROWID$)

These fields are transparently and automatically handled by the c-treeDB API and can’t be handled directly by the field handling functions of the c-treeDB API. There are specific functions that will, in some cases, retrieve data and status information kept by the hidden fields. These fields are also optional and c-treeDB will operate correctly with tables that do not possess them. There are also create table modes that allow the developer creating c-treeDB tables without any one, or all, of the hidden fields.

The delete flag field is for internal deletion purposes and should not be modified. $DELFLD$ is a CT_ARRAY field of four bytes. The only purpose of this field is to keep a place at the beginning of the record to hold a c-tree delete flag byte when the record is deleted. Four bytes are used instead of just one byte due to alignment requirements. This is an internal c-treeDB requirement, and should not be modified or touched by the user.

$NULFLD$ is a CT_ARRAY field with the size based on the number of user defined fields for the table. For each user defined field, one bit is reserved in $NULFLD$. The $NULFLD$ field keeps the NUL flag information for each user defined field. If a user field is null, the corresponding bit in $NULFLD$ will be set. When data is written to the field, the corresponding bit is cleared. The user should never modify or verify this field directly, but should use the appropriate API functions:

  • Use CTRecord::IsNullField() or CTField::GetNullFlag() to verify the if a field contains null data or not.
  • Use CTField::SetNullFlag() to set the null flag for a particular field.
  • Other functions that clear the null flag are CTRecord::ClearField() and CTRecord::Clear().

$ROWID$ is a CT_INT8 (64-bit integer) field holding the auto increment value generated by c-tree every time a new record is added to the table. This field is a read-only field that acts as a unique record identifier. Retrieve the ROWID using CTRecord::GetRowid(), or locate a record given its rowid using CTRecord::FindRowid(). To find out if a table has support for rowid, use CTTable::HasRowid().

$ROWID$ is used by FairCom DB SQL as a unique record identifier. For ISAM files or c-treeDB tables created with CTCREATE_NOROWID flag the $ROWID$ field will not exist. In this case the RECBYT offset will be used instead.

Note: Record offsets may change for a given variable-length record when a record is updated to a larger record size than the original record. Thus the RECBYT index cannot be used as a unique record identifier.

By default, c-treeDB creates the three hidden fields. Tables created with the c-tree Plus ISAM or low-level API will not include these fields by default. c-treeDB does not require the hidden fields to operate, but they allow more advanced capabilities. When creating a new table, users may disable the inclusion of the hidden fields by using the create modes CTCREATE_NONULFLD, CTCREATE_NODELFLD, and CTCREATE_NOROWID.

The default the table layout is presented below. Note that the first field added by the user is always field 0.

$DELFLD$

$NULFLD$

$ROWID$

user field 0

user field 1

...

user field n

TOCIndex