Hidden fields

There are three special fields that are automatically included by c-treeDB in the table record definition. c-treeACE 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 table creation modes allowing developers to create c-treeDB tables without any, 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 NULL 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:

• ctdbGetFieldNullFlag() or ctdbIsNullField() verify if a field contains null data.
• Use ctdbSetFieldNullFlag() to set the null flag for a particular field.
• ctdbClearField() and ctdbClearRecord() also clear the null flag.

$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 ctdbGetRowid(), or retrieve the record handle given its ROWID using ctdbFindRowid(). To know if a table has support for ROWID , use ctdbHasRowid().

$ROWID$ is used by c-treeACE SQL as a unique record identifier. For ISAM files or c-treeDB tables created with CTCREATE_NOWROWID 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. Therefore, 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-treeACE ISAM and Low-level APIs will not include these fields by default. c-treeDB does not require the fields to operate, but they allow more advanced capabilities. When creating a new table, disable the inclusion of the hidden fields using the create modes CTCREATE_NONULFLD, CTCREATE_NODELFLD, and CTCREATE_NOROWID.

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