Product Documentation

c-treeDB API API for C

Previous Topic

Next Topic

Hidden fields

Three special fields are automatically included by c-treeDB API 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 field ($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 API will operate correctly with tables that do not possess them. There are also table creation modes allowing developers to create c-treeDB API 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 API 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; always use the appropriate API functions:

  • ctdbIsNullField() returns a field's NULL flag. This is for a single field in a single record/row.
  • ctdbClearField() and ctdbClearRecord() set the NULL flag of a single field / entire record, respectively.
  • To clear the NULL flag of a single field or entire record, write to that field / record.
  • Do not use ctdbGetFieldNullFlag() and ctdbSetFieldNullFlag() to interact with the NULL flag discussed here. These two functions are for a column's SQL "NOT NULL" property in the SQL layer.

$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 FairCom DB SQL as a unique record identifier. For ISAM files or c-treeDB API 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 API creates these three hidden fields. Tables created with the FairCom DB ISAM and Low-level APIs will not include these fields by default. c-treeDB API 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.

$DELFLD$

$NULFLD$

$ROWID$

user field 0

user field 1

...

user field n

TOCIndex