FairCom DB API for C

ctdbInsField

Insert a new field into a table before the field number given by Index.

Declaration

CTHANDLE ctdbInsField(CTHANDLE Handle, NINT Index, pTEXT FieldName,

CTDBTYPE FieldType, VRLEN FieldLength)

Description

ctdbInsField() inserts a new field into a table before the field number given by the Index parameter. This is implemented as follows: the field that is currently at position Index, and any fields "above" it (with higher field numbers than Index) will be shifted upwards (have one added to their field numbers). This frees up position Index, which will then be occupied by the new field. See the code below for an example. This function handles the field handle allocation. Field handle deallocation is automatically handled by ctdbCloseTable() and ctdbCloseAll(). Use ctdbInsFieldByName() to insert a field in a table in a position specified by name. Use ctdbAddField() to add a field to the end of the table. Use ctdbDelField() and ctdbDelFieldByName() to delete fields from a table. ctdbInsField() does the field handle allocation. After the segments, indexes, and fields have been defined, the table can be created or altered with ctdbCreateTable() or ctdbAlterTable().

Handle [in] the Table handle.
Index [in] the field number - notice that the new field will have this field number.
FieldName [in] the field name.
FieldType [in] the field type. Available types are listed in the left-hand column ("FairCom DB API Field Type") in Field Types.
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

Returns

ctdbInsField() returns a field handle on success, or NULL on failure.

Example

/* allocate a new table handle */

CTHANDLE hTable = ctdbAllocTable(hDatabase);

/* add two fields to the table record definition */

ctdbAddField(hTable, "FirstField", CT_INTEGER, 4); /* This is field #0 */

ctdbAddField(hTable, "SecondField", CT_CHAR, 30); /* This is field #1 (for now!) */

/* insert a field into the location previously occupied by field #1 ("SecondField") */

ctdbInsField(hTable, 1, "ThirdField", CT_BOOL, 1);

/* create the table */

ctdbCreateTable(hTable, "MyTable", CTCREATE_NORMAL);

The fields in the table are now as follows: Field #0="FirstField". Field #1="ThirdField". Field #2="SecondField".