Product Documentation

FairCom DB API for C

Previous Topic

Next Topic

Hidden fields

Three special fields are automatically included by FairCom DB 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 FairCom DB API and can't be handled directly by the field-handling functions of the FairCom DB 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 FairCom DB API will operate correctly with tables that do not possess them. There are also table creation modes allowing developers to create FairCom DB 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 FairCom DB 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 FairCom DB 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, FairCom DB API creates these three hidden fields. Tables created with the FairCom DB ISAM and Low-level APIs will not include these fields by default. FairCom DB 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