FairCom DB API for C

ctdbInsFieldByName

Insert a new field into a table before the field named by FieldIndex.

Declaration

CTHANDLE ctdbInsFieldByName(CTHANDLE Handle, pTEXT FieldIndex, pTEXT

FieldName, CTDBTYPE FieldType, VRLEN FieldLength)

Description

ctdbInsFieldByName() inserts a new field into a table before the field given by the FieldIndex parameter, which specifies the name of an existing field in the table. This is implemented as follows: the existing field with the name FieldIndex, and any fields "above" it (with higher field numbers than that field) will be shifted upwards (have one added to their field numbers). This frees up the position previously occupied by the named field, 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 ctdbInsField() to insert a field in a table in a position specified by a number. Use ctdbAddField() to add a field to the end of the table. Use ctdbDelField() and ctdbDelFieldByName() to delete fields from a table.

ctdbInsFieldByName() 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.
FieldIndex [in] the name of the existing field - notice that the new field will go into the table at this field's current location.
FieldName [in] the new field name.
FieldType [in] the field type. Available types are listed in the left-hand column ("FairCom DB API Field Type") of the table 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).

Returns

ctdbInsFieldByName() 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 "SecondField" */

ctdbInsFieldByName(hTable, "SecondField", "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".