Product Documentation

c-treeDB API API for C

Previous Topic

Next Topic


Add a new field to table


CTHANDLE ctdbAddField(CTHANDLE Handle, pTEXT FieldName,

CTDBTYPE FieldType, VRLEN FieldLength)


ctdbAddField() adds a new field to the end of a table. Fields added with this function are sequentially-numbered, starting with field number zero. If the table has no fields, the first field added will be field number zero. If the table has five fields already (numbered zero to four), the next field added by this function will be field number five.

Use ctdbInsField() and ctdbInsFieldByName() to insert a field in a table in a specified position. Use ctdbDelField() and ctdbDelFieldByName() to delete fields from the table. Note that ctdbAddField() does the field handle allocation, so no explicit "alloc" calls need to be made on the field handles. Field handle deallocation is automatically handled by ctdbCloseTable() and ctdbCloseAll(). After the segments, indexes, and fields have been defined, the table can be created or altered with ctdbCreateTable() or ctdbAlterTable().

  • pTable [in] - The table handle.
  • FieldName [in] - The field name.
  • FieldType [in] - The field type. Available types are listed in the left-hand column ("c-treeDB Field Type") of the "Field Types" table in in c-treeDB definitions.
  • FieldLength [in] - The maximum length of CHAR, VARCHAR, BINARY, and VARBINARY fields (64K bytes max). The maximum length of LVARCHAR, LVARBINARY fields (2GB max, or set to 0 for "2GB"). This parameter is ignored for all other field types (the non-array-like types).

    Note that FieldLength [in] must account for the underlying data type. For example, for a string field allowing up to 256 bytes of application data, the following field length needs to be specified:

    CT_FSTRING (fixed length string) length = 256
    CT_STRING (null terminated string) length = 257
    CT_2STRING (2 byte length prefix) length = 258
    CT_4STRING (4 byte length prefix) length = 260


ctdbAddField returns a newly-allocated field handle on success, or NULL on failure.


pMyTable = ctdbAllocTable(pMyDatabase);

pMyField0 = ctdbAddField(pMyTable, "Name", CT_FSTRING, 32); /* Field #0 */

pMyField1 = ctdbAddField(pMyTable, "Balance", CT_SFLOAT, 4); /* Field #1 */

pMyIndex = ctdbAddIndex(pMyTable, "iName", CTINDEX_FIXED, NO, NO);

pMyIseg = ctdbAddSegment(pMyIndex, pMyField0, 2);

RetVal = ctdbCreateTable(pMyTable,"Table1",CTCREATE_NORMAL);

See also

ctdbAllocTable(), ctdbInsField(), ctdbInsFieldByName(), ctdbDelField(), ctdbDelFieldByName(), ctdbMoveField(), ctdbCreateTable(), ctdbAlterTable()