ctdbAddDatabase

Add an existing database to a session.

Declaration

CTDBRET ctdbAddDatabase(CTHANDLE Handle, pTEXT Name, pTEXT Path)

Description

ctdbAddDatabase() adds an existing database to the present session dictionary. Use the Path parameter to specify where the database dictionary file is on disk. If Path is left empty, FairCom DB API will attempt to locate the file in the Server directory (client/server) or in the execution directory (standalone).

Handle [in] the session handle.
Name [in] the database name.
Path [in] the database path.

Returns

ctdbAddDatabase() returns CTDBRET_OK on success, or a FairCom DB API error code on failure.

Example

eRet = ctdbAddDatabase(hSession, "my_database", "");

if (eRet != CTDBRET_OK)

{

if (eRet == CTDBRET_NOTFOUND)

{

printf("\n\nTable not found at the path.\n");

}

else

{

printf("ctdbAddDatabase returned error code %d\n", eRet);

}

See also

ctdbAddTable(), ctdbDropDatabase(), ctdbDropTable()

ctdbAddField

Add a new field to table

Declaration

CTHANDLE ctdbAddField(CTHANDLE Handle, pTEXT FieldName,

CTDBTYPE FieldType, VRLEN FieldLength)

Description

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 ("FairCom DB API Field Type") of the "Field Types" table in in FairCom DB API 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

Returns

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

Example

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()

ctdbAddIndex

Add a new index to a table.

Declaration

CTHANDLE ctdbAddIndex(CTHANDLE Handle, cpTEXT name, CTDBKEY key_type,

CTBOOL AllowDuplicates, CTBOOL NullFlag)

Description

ctdbAddIndex() adds a new index to a table. An index makes record seeking faster and more efficient, and provides a convenient way to sort a table. Since an index file resides in the same folder as its table, it is not necessary to specify a path when adding an index to a table. After adding an index to a table with this function, add one or more segments to the index, using the ctdbAddSegment___() functions.

Use ctdbDelIndex() to delete indexes from a table.

Use ctdbGetIndexKeyType() to retrieve the key type of an index. ctdbAddIndex() does the allocation of the index handle. Index 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 by calling ctdbCreateTable() or ctdbAlterTable().

Handle [in] the table handle.
name [in] the name of the new index.
key_type [in] the index key type. Allowed index key types are listed in Index Key Types.
AllowDuplicates [in] the indication if the index allows duplicate keys (YES or NO are the valid values).
NullFlag [in] the indication if the index allows null keys (YES or NO are the valid values).

Background Load on Index Creation

Background key loading can improve performance when adding new indexes. A new background loading mode can be OR-d in with an existing key mode from a ctdbAddIndex (ctdbAddIndex, ctdbAddIndex)() call indicating initial index loading must be done in the background.

Once ctdbAddIndex() is called, ctdbAlterTable() initiates the changes to the file and begins the load once the new index is successfully created.

Check the status of index loading with the new ctdbCheckIndexBackgroundLoad() (ctdbCheckIndexBackgroundLoad, ctdbCheckIndexBackgroundLoad) API, useful for monitoring index loading on tables.

Example

This example demonstrates using a background index load option.

ctdbAddIndex(hTable, "test541_i1", CTINDEX_FIXED| CTINDEX_BCKLOAD, YES, NO)

ctdbAlterTable() will fail if a CTINDEX_BCKLOAD is added and it does not have a filename associated (i.e. ctdbSetIndexFilename() has not been called on the index) or ctdbAlterTable() needs to perform any operation other than adding new CTINDEX_BCKLOAD indexes. If the preconditions are met, ctdbAlterTable() is executed without opening the file in exclusive mode and the background load is immediately started.

The new ctdbCheckIndexBackgroundLoad() (ctdbCheckIndexBackgroundLoad, ctdbCheckIndexBackgroundLoad) function can be used to monitor the status of the index loading on tables.

Example

pMyField0 = ctdbAddField(pMyTable, "Name" , CT_FSTRING,32);

pMyField1 = ctdbAddField(pMyTable, "Balance", CT_SFLOAT, 4);

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

pMyIseg = ctdbAddSegment(pMyIndex, pMyField0, 2);

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

Returns

ctdbAddIndex() returns the index handle on success, or NULL on failure.

See also

ctdbAllocTable(), ctdbDelIndex(), ctdbGetIndexKeyType(), ctdbCreateTable(), ctdbAlterTable(), ctdbSetIndexName()

NAV (FairCom DB API) API Variable Length Keys with Compression

ctdbAddSegment

Add a new index segment to an index (given the index handle and a field handle).

Declaration

CTHANDLE ctdbAddSegment(CTHANDLE Handle, CTHANDLE FieldHandle,

CTSEG_MODE SegMode)

Description

ctdbAddSegment() adds a new index segment to an index, specifying both the field and the index by giving their handles. The operation of adding a segment to the index links the specified index with the specified field in its table. When a segment is added with this function, the segment is defined based on an individual full field of a table, using what is known as a record schema. In other words, instead of using a byte offset into the record structure and a length, all you need to provide is a handle to the field of interest. See the FairCom DB documentation for further information on record schemas.

Use ctdbAddSegmentByName() or ctdbAddSegmentByNbr() to add a segment given the index number. Use ctdbAddSegmentEx() to add a new extended index segment, that may use just part of the field as the index segment. Use ctdbInsSegment() to insert a segment in a specified position. Use ctdbDelSegment() to delete a segment from an index.

ctdbAddSegment() does the allocation of the index segment handle. After the segments, indexes, and fields have been defined, the table can be created or altered with ctdbCreateTable() or ctdbAlterTable(). Index segment handle deallocation is automatically handled by ctdbCloseTable() and ctdbCloseAll().

Handle [in] - the handle specifying the index which will receive the new segment.
FieldHandle [in] - the handle of the table field that will be used to build this segment.
SegMode [in] - the Index segment mode. The valid values for the segment modes are: CTSEG_SCHSEG, CTSEG_USCHSEG, CTSEG_VSCHSEG, CTSEG_UVSCHSEG, CTSEG_SCHSRL, described in FairCom DB API definitions. If used with a different segment mode, this call will return error 4047, meaning invalid segment mode. ctdbAddSegmentEx() accepts any segment mode.

Returns

ctdbAddSegment returns the segment handle on success, or NULL on failure.

When used on JSON fields, this function returns an error code of CTDBRET_NOTSUPPORTED.

Example

pMyField0 = ctdbAddField(pMyTable, "Name", CT_FSTRING,32);

pMyField1 = ctdbAddField(pMyTable, "Balance", CT_SFLOAT, 4);

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

pMyIseg = ctdbAddSegment(pMyIndex, pMyField0, CTSEG_USCHSEG);

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

See also

ctdbAllocSegment(), ctdbAddSegmentByName(), ctdbAddSegmentByNbr(), ctdbAddSegmentEx(), ctdbInsSegment(), ctdbCreateTable(), ctdbAlterTable()

ctdbAddJSONSegment

Add a new index segment on a JSON field.

Declaration

CTHANDLE ctdbAddJSONSegment(CTHANDLE Handle, CTHANDLE FieldHandle, pTEXT key, CTDBTYPE type, VRLEN size);

Description

Handle [IN] - Index handle
FieldHandle [IN] - Index segment field handle (JSON field)
key [IN] - JSON key name that is being indexed
type [IN] - c-tree data type of key value
size [IN] - key segment length

Returns

Return the segment handle on success or NULL on failure.

Limitations to JSON Key Segments

A CT_JSON key segment does not support the DSCSEG, ALTSEG, or ENDSEG key segment modes. Attempting to create an index that contains a CT_JSON key segment that includes any of these key segment modes fails with error NSUP_ERR.
CT_JSON key segments that use CT_STRING as the c-tree data type are always padded with null (0x0) bytes. We don't support setting a different key segment padding character on JSON key segments.
A CT_JSON key segment can specify any of the following c-tree data types: CT_BOOL, CT_CHAR, CT_CHARU, CT_INT2, CT_INT2U, CT_INT4, CT_INT4U, CT_INT8, CT_DFLOAT, CT_STRING. Note that CT_INT8U is not supported, because JSON only supports a signed 8-byte integer data type.
Remember that the JSON field indexing behaves as follows: if the JSON data type of the value that is being indexed is not compatible with the underlying c-tree data type specified in the key segment definition, that value is treated as NULL and is not indexed. Some examples:
- If the value is a string and the c-tree data type is an integer, the value is not indexed.
- If the value is an integer and the c-tree data type is CT_INT2 but the value is out of range for a signed two-byte integer, the value is not indexed.

ctdbAddSegmentByName

Add a new index segment to an index (given the table handle, field name, and index number).

Declaration

CTHANDLE ctdbAddSegmentByName(CTHANDLE Handle, NINT IndexNbr,

pTEXT FieldName, CTSEG_MODE SegMode)

Description

ctdbAddSegmentByName() adds a new index segment to an index, specifying the field by giving the table handle and the field name and specifying the index by giving its number. The operation of adding a segment to the index links the specified index with the specified field in the specified table. When a segment is added with this function, the segment is defined based on an individual full field of a table, using what is known as a record schema. In other words, instead of using a byte offset into the record structure and a length, all you need to do is specify the field of interest and what table it’s in. See the FairCom DB documentation for further information on record schemas.

Use ctdbAddSegmentByNbr() to add a new index segment given the field and index number. Use ctdbAddSegment() to add a new index segment given the index handle. Use ctdbAddSegmentEx() to add a new extended index segment.

ctdbAddSegmentByName() does the segment handle allocation. After the segments, indexes, and fields have been defined, the table can be created or altered with ctdbCreateTable() or ctdbAlterTable(). Segment handle deallocation is automatically handled by ctdbCloseTable() and ctdbCloseAll().

Handle [in] the table handle.
IndexNbr [in] the index number. The first index is number 0.
FieldName [in] the field name.
SegMode [in] the Index segment mode. The valid values for the segment modes are: CTSEG_SCHSEG, CTSEG_USCHSEG, CTSEG_VSCHSEG, CTSEG_UVSCHSEG, CTSEG_SCHSRL, described in FairCom DB API definitions. If used with a different segment mode, this call will return error 4047, meaning invalid segment mode. ctdbAddSegmentEx() accepts any segment mode.

Returns

ctdbAddSegmentByName() returns the segment handle on success, or NULL on failure

Example

ctdbAddField(pMyTable, "Name", CT_FSTRING, 32);

ctdbAddField(pMyTable, "Balance", CT_SFLOAT, 4);

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

ctdbAddSegmentByName(pMyTable, 0, "Name", CTSEG_USCHSEG);

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

See also

ctdbAddSegmentEx(), ctdbAddSegmentByNbr(), ctdbAddSegment()

ctdbAddSegmentByNbr

Add a new index segment to an index (given the table handle, field number, and index number).

Declaration

CTHANDLE ctdbAddSegmentByNbr(CTHANDLE Handle, NINT IndexNbr,

NINT FieldNbr, CTSEG_MODE SegMode)

Description

ctdbAddSegmentByNbr() adds a new index segment to an index, specifying the field by giving the table handle and the field number, and specifying the index by giving the index number.

The operation of adding a segment to an index links the specified index with the specified field in the specified table. When a segment is added with this function, the segment is defined based on an individual full field of a table, using what is known as a record schema. In other words, instead of using a byte offset into the record structure and a length, all you need to do is specify the field of interest and what table it’s in. See the FairCom DB documentation for further information on record schemas.

Use ctdbAddSegmentByName() to add a new index segment given its name. Use ctdbAddSegment() to add a new index segment given the index handle. Use ctdbAddSegmentEx() to add a new extended index segment.

ctdbAddSegmentByNbr() does the segment handle allocation. After the segments, indexes, and fields have been defined, the table can be created or altered with ctdbCreateTable() or ctdbAlterTable(). Segment handle deallocation is automatically handled by ctdbCloseTable() and ctdbCloseAll().

Handle [in] the table handle.
IndexNbr [in] the index number. The first index is number 0.
FieldNbr [in] the field number. The first field is number 0.
SegMode [in] the Index segment mode. The valid values for the segment modes are: CTSEG_SCHSEG, CTSEG_USCHSEG, CTSEG_VSCHSEG, CTSEG_UVSCHSEG, CTSEG_SCHSRL, described in FairCom DB API definitions. If used with a different segment mode, this call returns error 4047, invalid segment mode. ctdbAddSegmentEx() accepts any segment mode.

Returns

ctdbAddSegmentByNbr returns the segment handle on success, or NULL on failure

Example

ctdbAddField(pMyTable, "Name", CT_FSTRING, 32);

ctdbAddField(pMyTable, "Balance", CT_SFLOAT, 4);

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

ctdbAddSegmentByNbr(pMyTable, 0, 0, CTSEG_USCHSEG);

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

See also

ctdbAddSegment(), ctdbAddSegmentEx(), ctdbAddSegmentByName()

ctdbAddSegmentEx

Add a new extended index segment to an index, using a byte offset into the record structure and a length.

Declaration

CTHANDLE ctdbAddSegmentEx(CTHANDLE Handle, NINT offset, NINT length,

CTSEG_MODE SegMode)

Description

ctdbAddSegmentEx() adds a new extended index segment given the index handle and the segment offset. A segment is extended if it is based on the segment offset. The operation of adding a segment links the index with the field in the table. To add a segment with this function, the segment may be defined based on partial individual fields, using offsets to indicate the segment beginning and extension.

Note: The offset should account for the fields that are created automatically (unless disabled): $DELFLD$ (4 bytes to account for a deleted record), $NULFLD$ (for each user defined field, FairCom DB API uses 1 bit to indicate if a null value in the field is valid - the size will be adjusted to the next byte), and $ROWID$ (8 bytes to account for the automatic auto-increment record - see the discussion on ROWID in Hidden fields). This variation makes it difficult to predict the correct offset of each user defined offset. FairCom strongly recommends the use of the regular functions (ctdbAddSegment(), ctdbAddSegmentByName() or ctdbAddSegmentByNbr()). The use of the extended segments may even prevent the use of advanced FairCom DB API functions like ctdbAlterTable(). If, for any reason, it is mandatory to use this function, try to follow the example below.

ctdbAddSegmentEx() does the segment handle allocation. After the segments, indexes, and fields have been defined, the table can be created or altered with ctdbCreateTable() or ctdbAlterTable(). Segment handle deallocation is automatically handled by ctdbCloseTable() and ctdbCloseAll().

Use ctdbIsExtSegment() to verify if the segment mode is one of the extended modes.

Handle [in] - the index handle.
offset [in] - the absolute byte offset.
length [in] - the segment length in bytes.
SegMode [in] - the Index segment mode. The valid values for the segment modes are listed in FairCom DB API definitions. Notice that ctdbAddSegmentEx() does work with Absolute byte offset segments.

Returns

ctdbAddSegmentEx() returns the segment handle on success, or NULL on failure

Example

pMyField0 = ctdbAddField(pMyTable, "Name", CT_FSTRING,32);

pMyField1 = ctdbAddField(pMyTable, "Balance", CT_SFLOAT, 4);

ctdbCreateTable(pMyTable,"Table1",CTCREATE_NORMAL);

ctdbOpenTable(pMyTable1, "MyTable3", CTOPEN_EXCLUSIVE);

pMyRec1 = ctdbAllocRecord(pMyTable1);

ctdbFirstRecord(pMyRec1);

fld_offset = ctdbGetFieldOffset(pMyRec1, 0);

pMyIndex = ctdbAddIndex(pMyTable1, "MyTable2", 0, 1, 1);

pMyIseg = ctdbAddSegmentEx(pMyIndex, fld_offset, 32, CTSEG_UREGSEG);

ctdbAlterTable(pMyTable1, 0);

See also

ctdbAllocSegment(), ctdbAddSegment(), ctdbInsSegmentEx(), ctdbAddSegmentByName(), ctdbAddSegmentByNbr(), ctdbGetFieldOffset(), ctdbIsExtSegment()

ctdbAddTable

Add an existing table to a database.

Declaration

CTDBRET ctdbAddTable(CTHANDLE Handle, pTEXT Name, pTEXT Path)

Description

ctdbAddTable() adds an existing table to a database. Use the Path parameter to specify where the table files are on disk. If Path is left empty, FairCom DB API will attempt to locate the files in the Server directory (client/server) or in the execution directory (standalone).

Handle [in] - the database handle.
Name [in] - the name of the table be added, including the file extension, usually .dat.
Path [in] - the table path.

A mirrored table can be added to a FairCom DB API database dictionary by calling the ctdbAddTable() function and specifying the table name and path using the appropriate mirror naming convention:

if (ctdbAddTable(hDatabase, "customer|mirror", "primary_path|mirror_path"))

printf("ctdbAddTable failed\n");

If a table is created originally without mirroring, it can subsequently be mirrored as follows:

Copy the original table to the mirror location.
Change the ctdbOpenTable() function to use the mirror naming convention.

Returns

ctdbAddTable() returns CTDBRET_OK on success, or the c-tree error code on failure.

Example

CTHANDLE hTable;

eRet = ctdbAddTable(hTable, "custmast", "");

ctdbAddTableXtd

Add an existing table to a database with additional physical file information.

Declaration

ctdbAddTableXtd( CTHANDLE Handle, pTEXT Name, pTEXT PhysicalName, pTEXT Path )

Description

ctdbAddTableXtd() adds an existing table to a database. Use the Path parameter to specify where the table files are on disk. If Path is left empty, FairCom DB API will attempt to locate the files in the Server directory (client/server) or in the execution directory (standalone).

Handle [in] the database handle. As of V12 Handle can be a table handle. If it is a table handle, the database handle is derived from it, and any dictionary mark setting in the table handle is used when adding the table to the dictionary. See ctdbSetTableDictionaryMark() (ctdbSetTableDictionaryMark, ctdbSetTableDictionaryMark)
Name [in] the logical name of the table to be added as referenced in the FairCom DB API database.
PhysicalName [in] the physical name of the file on disk, including the file extension, usually .dat.
Path [in] the table path.

This extended function allows adding a table to a FairCom DB API database specified with a logical and physical table name (the physical table name is the name on disk without extension and path), the logical table name is the one associated with file operations such as ctdbOpenTable().

Note: While multiple files with the same physical names can be added to a FairCom DB API database dictionary, they logical names must still be unique.

A mirrored table can be added to a FairCom DB API database dictionary by calling ctdbAddTable() function and specifying the table name and path using the appropriate mirror naming convention:

if (ctdbAddTable(hDatabase, "customer|mirror", "primary_path|mirror_path"))

printf("ctdbAddTable failed\n");

If a table is created originally without mirroring, it can subsequently be mirrored as follows:

Copy the original table to the mirror location.
Change the ctdbOpenTable() function to use the mirror naming convention.

Returns

ctdbAddTable() returns CTDBRET_OK on success, or the c-tree error code on failure.

Example

CTHANDLE hTable;

eRet = ctdbAddTable(hTable, "custmast1", "customer.dat" "c:\company1");

eRet = ctdbAddTable(hTable, "custmast2", "customer.dat" "c:\company2");

ctdbAllocDatabase

Allocate and initialize a new database handle.

Declaration

CTHANDLE ctdbAllocDatabase(CTHANDLE Handle)

Description

ctdbAllocDatabase() allocates memory and initializes a new database handle and associates the handle with the session specified by Handle. Before any operations on a database can take place, the application must allocate a database handle.

Handle [in] - the session handle.

The next step in operating on a database is to connect the database handle returned by this function to the desired database (which has been previously added to the session specified by Handle) by calling ctdbConnect(). The database handle is released by calling ctdbFreeDatabase(). Do not release the database handle by calling the C runtime library function free().

Returns

ctdbAllocDatabase returns the database handle on success or NULL on failure.

Example

CTHANDLE hDatabase = ctdbAllocDatabase(hSession);

See also

ctdbFreeDatabase(), ctdbAllocSession(), ctdbAllocTable()

ctdbAllocRecord

Allocate a new FairCom DB API C API record handle.

Declaration

CTHANDLE ctdbAllocRecord(CTHANDLE Handle)

Description

ctdbAllocRecord() allocates memory and initialize a new record handle. Before any operation on records can take place, the application must allocate a record handle.

Handle [in] the table handle.

The record handle is released by calling ctdbFreeRecord(). Do not release the record handle by calling the C runtime library function free.

Returns

ctdbAllocRecord() returns the new allocated handle on success, or NULL on failure.

See also

ctdbAllocTable(), ctdbFreeRecord(), ctdbGetRecordHandle()

ctdbAllocSession

Allocate a new session handle and set the default attributes.

Declaration

CTHANDLE ctdbAllocSession(CTSESSION_TYPE SessionType)

Description

ctdbAllocSession() allocates memory and initializes a new session handle, setting the default attributes. Before any operations on a session can take place, the application must allocate a session handle. This function takes one parameter, the session type, and returns the new session handle, or NULL if there is not enough memory to allocate the new handle.

SessionType [in] the session type. There are three different session types – see Allocating a Session Handle for a more complete description:
- CTSESSION_CTREE: For existing ISAM applications that need access to some of the FairCom DB API functionality. This mode allocates a new session for logon to the server only. No session or database dictionary files will be used. Use the session handle to allocate table handles.
- CTSESSION_CTDB: allocate a new session using FairCom DB API session and database dictionaries. Table and index creation and modification is significantly easier than CTREE mode.
- CTSESSION_SQL: allocate a new session using FairCom DB API session and database dictionaries. Once logged on a server, if the server is SQL then database creation creates a SQL database. Once connected to a database, if the database is a SQL database and the table is associated with the database, then table and index creation, deletion, and modifications are reflected in SQL system tables.

The session handle is released by calling ctdbFreeSession(). Do not release the session handle by calling the C runtime library function free().

Returns

Return the session handle on success or NULL on failure.

Example

CTSESSION_TYPE ctdbsess=CTSESSION_CTDB;

CTHANDLE handle = ctdbAllocSession(ctdbsess); // FairCom DB API session

See also

ctdbAllocDataBase(), ctdbFreeSession()

ctdbAllocTable

Allocate a new table handle.

Declaration

CTHANDLE ctdbAllocTable(CTHANDLE Handle)

Description

ctdbAllocTable() allocates memory and initializes a new table handle and associates that handle with the database specified by Handle. Before any operation on a table can take place, the application must allocate a table handle.

Handle [in] the database handle, previously allocated by calling ctdbAllocDatabase(). Note that this handle does not need to be connected to a database when ctdbAllocTable() is called.

The next step after calling this function is generally to call ctdbOpenTable(). The table handle is released by calling ctdbFreeTable(). Do not release the table handle by calling the C runtime library function free().

Returns

ctdbAllocTable() returns the table handle on success or NULL on failure.

Example

CTSESSION_TYPE ctdbsess=CTSESSION_CTDB;

CTHANDLE hSession = ctdbAllocSession(ctdbsess);

CTHANDLE hDatabase = ctdbAllocDatabase(hSession);

CTHANDLE hTable = ctdbAllocTable(hDatabase);

See also

ctdbAllocDatabase(), ctdbFreeTable()

ctdbAlterTable

Rebuild existing table based on field, index, and segment changes.

Declaration

CTDBRET ctdbAlterTable(CTHANDLE Handle, NINT Action)

Description

ctdbAlterTable() rebuilds an existing table based on field, index and segment changes.

Handle [in] the table handle.
Action [in] the alter table action. One or more of the following actions can be selected:
- CTDB_ALTER_NORMAL: Check for changes before altering.
- CTDB_ALTER_INDEX: Force rebuild of all indexes.
- CTDB_ALTER_FULL: Force full table rebuild.
- CTDB_ALTER_TRUNCATE: Quickly remove all records.
- CTDB_ALTER_PURGEDUP: OR in with any of the other modes to deal with cases where an alter table is performed on data files with duplicated index information.
- CTDB_ALTER_KEEPTRAN: Allow tables with different TRANDEP modes (e.g. transaction capable, however, transaction control disabled for performance) to undergo ALTER TABLE. (This is generally an internal FairCom operation for certain table types.)
- CTDB_ALTER_V8DELFLD: (Supported in V10.3 and later) The table (if re-created) must have the old $DELFLD$ size (CTDB_ALTER_V8DELFLD forces CTCREATE_V8DELFLD during "alter table").
- CTDB_ALTER_HOT: (Supported in V11.5 and later) A Hot Alter Table will be performed if possible (which requires the file to use the FLEXREC feature and for the changes to the schema to be possible to accomplish using Hot Alter Table). If a Hot Alter Table cannot be performed, ctdbAlterTable() returns error CTDBRET_NOTSUPPORTED.

Unix Note: Due to the non-exclusive nature of Unix, this function can be successfully executed on a file that was opened by several other applications in shared mode. However, although the function succeeds, it may cause havoc for the other applications. This can be prevented by enforcing exclusivity with locks, however, this is not the default mode.

Mirrored Files: The FairCom DB API alter table function will not operate on mirrored tables. If ctdbAlterTable() is called for a mirrored table, nothing is done and it returns error CTDBRET_NOTSUPPORTED.

Existing Indexes: For updating the conditional expression of existing indexes, use ctdbAlterTable() with mode CTDB_ALTER_INDEX.

Returns

ctdbAlterTable() returns CTDBRET_OK if successful, or the c-tree error code on failure.

See also

ctdbCreateTable()

ctdbAttachTable

Attaches a FairCom DB ISAM datno object to a FairCom DB API table handle.

DECLARATION

CTDBRET ctdbAttachTable(CTHANDLE Handle, NINT datno);

DESCRIPTION

ctdbAttachTable() attaches a FairCom DB ISAM datno object to a FairCom DB API table handle. This function is useful if you have opened a data and index file using one of c- tree’s ISAM open functions and need to attach it to a table handle to use some of the advanced FairCom DB API features such as alter table or the record handler. Handle is a table handle and datno is data file number opened with one of the c-tree ISAM open functions.

RETURN

Value	Symbolic Constant	Explanation
0	NO_ERROR	No error occurred.

See Appendix A for a complete listing of valid c-tree Plus error values.

EXAMPLE

CTHANDLE hSession = ctdbAllocSession(CTSESSION_CTREE);

CTHANDLE hTable = ctdbAllocTable(hSession);

CTHANDLE hRecord = ctdbAllocRecord(hTable);

NINT datno, count = 0;

/* logon to c-tree */

ctdbLogon(hSession, SERVER, USER, PASSWD);

/* open the file using c-tree ISAM */

datno = (NINT)OPNRFILX((COUNT) -1, "test309.dat", (COUNT)0, NULL);

/* attach to table */

ctdbAttachTable(hTable, datno);

/* read the records */

if (ctdbFirstRecord(hRecord) == CTDBRET_OK)

{

count++;

}

while (ctdbNextRecord(hRecord) == CTDBRET_OK);

/* cleanup */

ctdbDetachtable(hTable);

ctdbFreeRecord(hRecord);

ctdbFreeTable(hTable);

ctdbLogout(hSession);

ctdbFreeSession(hSession);

ctdbAttachTableXtd

Attaches a FairCom DB ISAM datno object to a FairCom DB API table handle allowing a DODA and IFIL to be specified.

DECLARATION

CTDBRET ctdbAttachTableXtd(CTHANDLE Handle, NINT datno, NINT nbrfields, pDATOBJ dodaptr, pIFIL ifilptr)

DESCRIPTION

ctdbAttachTableXtd() attaches a FairCom DB ISAM datno object to a FairCom DB API table handle. This function is useful if you have opened a data and index file using one of c-tree’s ISAM open functions and need to attach it to a table handle to use some of the advanced FairCom DB API features such as alter table or the record handler. This extended version allows the user to specify the DODA and IFIL for the table, enabling tables without DODA and/or IFIL to be attached to FairCom DB API.

Handle is a table handle and datno is the data file number. nbrfields is the number of fields described by dodaptr. If nbrfields is zero, it is assumed that the DODA is not supplied and a DODA resource will be read from the table itself. dodaptr pointer to DODA entries for each field in table. If dodaptr is NULL, it is assumed that the DODA is not supplied and a DODA resource will be read from the table itself. ifilptr is a pointer to IFIL structure describing indexes of table. If ifilptr is NULL it is assumed that an IFIL is not supplied and an IFIL resource will be read from the table itself.

RETURN

Value	Symbolic Constant	Explanation
0	NO_ERROR	No error occurred.

See Appendix A for a complete listing of valid c-tree Plus error values.

EXAMPLE

/* DODA */

static DATOBJ doda[] =

{

{"f1", (pTEXT)0, CT_INT4, 4},

{"f2", (pTEXT)4, CT_FSTRING, 10}

};

/* IFIL */

static ISEG iseg = {0, 4, 12};

static IIDX iidx = {4, 0, 0, 0, 0, 1, &iseg, "i311x1", NULL, NULL, NULL};

static IFIL ifil = {"test310", -1, 14, 0, 0, 1, 0, 0, &iidx, "f1", "f2", 0};

CTHANDLE hSession = ctdbAllocSession(CTSESSION_CTREE);

CTHANDLE hTable = ctdbAllocTable(hSession);

CTHANDLE hRecord = ctdbAllocRecord(hTable);

NINT datno, count = 0;

/* logon to c-tree */

ctdbLogon(hSession, SERVER, USER, PASSWD);

/* open the file using c-tree ISAM */

datno = (NINT)OPNRFILX((COUNT) -1, "test309.dat", (COUNT)0, NULL);

/* attach to table */

ctdbAttachTableXtd(hTable, datno, doda, &ifil);

/* read the records */

if (ctdbFirstRecord(hRecord) == CTDBRET_OK)

{

count++;

}

while (ctdbNextRecord(hRecord) == CTDBRET_OK);

/* cleanup */

ctdbDetachtable(hTable);

ctdbFreeRecord(hRecord);

ctdbFreeTable(hTable);

ctdbLogout(hSession);

ctdbFreeSession(hSession);

See also

ctdbBlobFree()

ctdbBlobFree

Release all resources associated with a blob.

Declaration

void ctdbBlobFree(pCTBLOB pBlob)

Description

ctdbBlobFree releases all resources associated with a blob. ctdbBlobClear clears the blob data.

pBlob [in] the blob pointer

Returns

None.

See also

ctdbBlobAlloc(), ctdbBlobClear()

ctdbCloneTable

Creates a new clone based on an existing table.

Declaration

CTDBRET ctdbCloneTable( CTHANDLE tarTableHandle, pTEXT tarTableName, CTHANDLE srcTableHandle )

Description

ctdbCloneTable() creates a new table with the attributes from an existing source table. This does NOT create a duplicate table -- records are not copied.

Note: This function is only for a CTSESSION_CTREE session or for cloning tables from/into different databases.

tarTableHandle [in] - The new table handle
tarTableName [in] - The new table name
srcTableHandle [out] - The source table handle

Returns

ctdbCloneTable() returns CTDBRET_OK on success, or FairCom DB API error code on failure. Typical ctdbCreateTable() errors are possible.

Example

CTHANDLE hSession = ctdbAllocSession(CTSESSION_CTREE);

CTHANDLE custmast = ctdbAllocTable( hSession );

CTHANDLE custmast_clone = ctdbAllocTable( hSession );

ctdbOpenTable( custmast, "custmast", CTOPEN_NORMAL );

ctdbCloneTable( custmast_clone, "custmast_clone", custmast );

See also

ctdbCreateTable()

ctdbCreateTable

Create a new table.

Declaration

CTDBRET ctdbCreateTable(CTHANDLE Handle, pTEXT TableName,

CTCREATE_MODE CreateMode)

Description

ctdbCreateTable() creates a new table.

To give the new table a password, call ctdbSetTablePassword() with Handle before calling this function.

To create a session, use ctdbCreateSession().

To create a database, use ctdbCreateDatabase().

To retrieve the table create mode, use ctdbGetTableCreateMode().

To open an existing table, use ctdbOpenTable().

The default directory for the table creation is the server directory (client/server applications) or the execution directory (standalone applications). To change the directory, call ctdbSetTablePath() to set the new directory before creating the table. In order to create the table, its fields, indexes and segments must be created first using, for instance, ctdbAddField(), ctdbAddIndex(), ctdbAddSegment().

Note that the create table process does not leave the table open after the table is created. The new table must be explicitly opened before it is used; see ctdbOpenTable().

Care should be exercised when selecting the table create mode. For example, if you wish to use transaction processing (the ctdbBegin(), ctdbCommit(), and ctdbAbort() functions) to ensure atomicity, then it is important to create the table using the CTCREATE_PREIMG or the CTCREATE_TRNLOG mode, and not the CTCREATE_NORMAL mode. See the Transactions section in Data Integrity for more details.

Handle [in] the table handle.
TableName [in] the table name.
CreateMode [in] the table create mode. The valid values for the table create mode are listed in FairCom DB API Table Create Modes.

Mirrored Files

The FairCom mirroring feature makes it possible to store important files on different drive volumes, partitions or physical drives. If the primary storage location is damaged or lost, the mirroring logic will automatically detect the situation and switch to the secondary or "mirrored" storage area.

The mirrored file is easily specified by appending a vertical bar ( | ) after the table name followed by the table mirror name. For example, to mirror a table named "customer" to "mirror", specify the table name as "customer|mirror". If no path is specified for the mirrored table, both tables will be located in the same directory. If the primary table and the mirrored table are to be located in different directories, then the path names must be specified the same way as the table names: "primary-path|mirrored-path".To create a mirrored table, use the ctdbCreateTable() function passing as the table name a proper mirrored naming convention:

if (ctdbCreateTable(hTable, "customer|mirror", CTCREATE_TRNLOG) )

printf("Create table failed\n");

If you need to specify different locations for the mirrored tables, use ctdbSetTablePath() to specify the mirrored paths:

if (ctdbSetTablePath(hTable, "primary_path|mirrored_path"))

printf("ctdbSetTablePath failed\n");

Under c-tree Server operation, all mirroring can be suspended by adding the following entry to the server configuration file (ctsrvr.cfg):

MIRRORS NO

This may be useful when the mirroring hardware is not operational and the use of the primary data is necessary. By default, read and write operations on mirrored tables will continue without returning an error if either one of the files fail, but the other succeeds. When this happens, the failed file is shut down and subsequent I/O operations continue only with the remaining "good" file. If mirroring is used in the client/server model, the SystemMonitor() function receives an event when one of the files succeed and the other fails.

Note: The FairCom DB API alter table function will not operate on mirrored tables. If ctdbAlterTable() is called for a mirrored table, nothing is done and it returns error CTDBRET_NOTSUPPORTED.

Mirroring is supplied for c-tree Server and single-user operations. It applies to all c-tree file modes including transaction processing. Once a table is created and opened with mirroring, all subsequent table opens must be mirrored (ctdbOpenTable() called with two table names separated by the vertical bar ( | )), except when the table is opened in exclusive mode (ctdbOpenTable()’s third parameter).

Returns

ctdbCreateTable() returns CTDBRET_OK on success or the FairCom DB API error code on failure.

Example

pMyTable = ctdbAllocTable(pMySession);

pMyField = ctdbAddField(pMyTable, "Name", CT_FSTRING,32);

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

pMyIseg = ctdbAddSegment(pMyIndex, pMyField, 2);

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

See also

ctdbCreateSession(), ctdbCreateSession(), ctdbCreateDatabase(), ctdbGetTableCreateMode(), ctdbOpenTable(), ctdbSetTablePath(), ctdbAddField(), ctdbAddIndex(), ctdbAddSegment(), ctdbSetIndexFilename(), ctdbGetIndexFileName()

ctdbDeleteTable

Drop a table from a database and delete its data and index files from disk.

Declaration

CTDBRET ctdbDeleteTable(CTHANDLE Handle, pTEXT TableName, pTEXT Password)

Description

ctdbDeleteTable() drops the table from the database and deletes the table data and index files from disk. This function should be used with care, since it will remove from disk the data and index file(s) associated with the specified table. Note that active/open tables must be closed before they can be deleted with this function (see ctdbCloseTable()).

Handle [in] the handle of the database that contains the table to be deleted.
TableName [in] the name of the table to be deleted.
Password [in] the table password. NULL if the table was created w/o a password.

Use ctdbAddTable() to add a table to a database. Use ctdbDropTable() to drop the table from the database but not delete the table files from disk.

Note: ctdbDeleteTable() is for use within a CTDB or SQL session. For a CTREE session, you must use ctdbRemoveTable(). See also Allocating a Session Handle.

Returns

ctdbDeleteTable() returns CTDBRET_OK on success, or the c-tree error code on failure.

Example

eRet=ctdbConnect(hDatabase, database_name);

eRet = ctdbDeleteTable(hDatabase, table_name, NULL);

See also

ctdbAddTable(), ctdbDropTable(), ctdbAllocDatabase()

ctdbDelField

Delete the field indicated by the field number index from a table.

Declaration

CTDBRET ctdbDelField(CTHANDLE Handle, NINT Index)

Description

ctdbDelField() deletes the field indicated by the field number Index from a table. Note that any fields with higher field numbers than the one you deleted will have one subtracted from their field numbers in order to fill the gap left by the field you deleted. Use ctdbDelFieldByName() to delete a field by name. Use ctdbAddField(), ctdbInsField() and ctdbInsFieldByName() to add fields to a table.

Handle [in] the Table handle.
Index [in] the field number to be deleted.

Returns

ctdbDelField() returns CTDBRET_OK on success or FairCom DB API error code on failure.

See also

ctdbAllocTable(), ctdbAddField(), ctdbInsField(), ctdbInsFieldByName(), ctdbDelFieldByName(), ctdbMoveField()

ctdbDelField

Delete the field indicated by the field number index from a table.

Declaration

CTDBRET ctdbDelField(CTHANDLE Handle, NINT Index)

Description

ctdbDelField() deletes the field indicated by the field number Index from a table. Note that any fields with higher field numbers than the one you deleted will have one subtracted from their field numbers in order to fill the gap left by the field you deleted. Use ctdbDelFieldByName() to delete a field by name. Use ctdbAddField(), ctdbInsField() and ctdbInsFieldByName() to add fields to a table.

Handle [in] the Table handle.
Index [in] the field number to be deleted.

Returns

ctdbDelField() returns CTDBRET_OK on success or FairCom DB API error code on failure.

See also

ctdbAllocTable(), ctdbAddField(), ctdbInsField(), ctdbInsFieldByName(), ctdbDelFieldByName(), ctdbMoveField()

ctdbDelFieldByName

Delete the field indicated by the field name from a table.

Declaration

CTDBRET ctdbDelFieldByName(CTHANDLE Handle, pTEXT FieldName)

Description

ctdbDelFieldByName() deletes the field indicated by the field name from a table. Note that any fields with higher field numbers than the one you deleted will have one subtracted from their field numbers to fill the gap left by the field you deleted. Use ctdbDelField() to delete a field by number. Use ctdbAddField(), ctdbInsField() and ctdbInsFieldByName() to add fields to a table.

Handle [in] the Table handle.
FieldName [in] the name of the field to be deleted.

Returns

ctdbDelFieldByName() returns CTDBRET_OK on success or FairCom DB API error code on failure.

See also

ctdbAllocTable(), ctdbAddField(), ctdbInsField(), ctdbInsFieldByName(), ctdbDelField(), ctdbMoveField()

ctdbDelIndex

Delete an index from a table.

Declaration

CTDBRET ctdbDelIndex(CTHANDLE Handle, NINT IndexNumber)

Description

ctdbDelIndex() deletes an index from a table. Use ctdbAddIndex() to add indexes in a table.

Handle [in] - the table handle.
IndexNumber [in] - the number of the index in the table.

Returns

ctdbDelIndex() returns CTDBRET_OK on success, or FairCom DB API error code on failure.

See also

ctdbAllocTable(), ctdbAddIndex()

ctdbDelSegment

Delete segment indicated by SegNumber.

Declaration

CTDBRET ctdbDelSegment(CTHANDLE Handle, NINT SegNumber)

Description

ctdbDelSegment() deletes a segment from an index. The segment to be deleted is indicated by SegNumber. Use ctdbAddSegment() and ctdbInsSegment() to add new index segments.

Handle [in] the index handle.
SegNumber [in] the index segment number to be deleted.

Returns

ctdbDelSegment() returns CTDBRET_OK on success, or FairCom DB API error code on failure.

See also

ctdbAllocIndex(), ctdbAddSegment(), ctdbInsSegment()

ctdbDelSegmentEx

Delete extended segment.

Declaration

CTDBRET ctdbDelSegmentEx(CTHANDLE Handle)

Description

ctdbDelSegmentEx() deletes an extended segment from an index.

Handle [in] the segment handle.

Returns

ctdbDelSegmentEx() returns CTDBRET_OK on success, or FairCom DB API error code on failure.

See also

ctdbDelSegment()

ctdbDetachTable

Detaches a FairCom DB API table handle from a c-tree data and index files.

DECLARATION

CTDBRET ctdbDetachTable(CTHANDLE Handle);

DESCRIPTION

ctdbDetachTable() detaches a FairCom DB API table handle from a c-tree data and index files. The table is not closed but the FairCom DB API table handle resources are released and the handle re-initialized. Handle is a FairCom DB API table handle allocated by ctdbAllocTable().

RETURN

Value	Symbolic Constant	Explanation
0	NO_ERROR	No error occurred.

See Appendix A for a complete listing of valid c-tree Plus error values.

EXAMPLE

CTHANDLE hSession = ctdbAllocSession(CTSESSION_CTREE);

CTHANDLE hTable = ctdbAllocTable(hSession);

CTHANDLE hRecord = ctdbAllocRecord(hTable);

NINT datno, count = 0;

/* logon to c-tree */

ctdbLogon(hSession, SERVER, USER, PASSWD);

/* open the file using c-tree ISAM */

datno = (NINT)OPNRFILX((COUNT) -1, "test309.dat", (COUNT)0, NULL);)

/* attach to table */

ctdbAttachTable(hTable, datno);

/* read the records */

if (ctdbFirstRecord(hRecord) == CTDBRET_OK)

{

count++;

}

while (ctdbNextRecord(hRecord) == CTDBRET_OK);

/* cleanup */

ctdbDetachtable(hTable);

ctdbFreeRecord(hRecord);

ctdbFreeTable(hTable);

ctdbLogout(hSession);

ctdbFreeSession(hSession);

See also

ctdbAllocDatabase(), ctdbConnect(), ctdbDisconnectAll(), ctdbCreateDatabase()

ctdbDropTable

Drop the table from the database.

Declaration

CTDBRET ctdbDropTable(CTHANDLE Handle, pTEXT TableName)

Description

ctdbDropTable() drops the table from the database, but does not delete the table or index files from disk. When a table is dropped, the allocated records, fields, index and segments are freed from memory.

Handle [in] the handle of the database that contains the table to be dropped.
TableName [in] the name of the table to be dropped.

Note the different syntax from SQL: A SQL Drop Table operation deletes the files from disk, while this function does not. If you wish to delete the files as well, use the ctdbDeleteTable() function. Use ctdbAddTable() to add a table to a database.

Returns

ctdbDropTable() returns CTDBRET_OK on success, or the c-tree error code on failure.

Example

eRet = ctdbConnect(hDatabase, database_name);

eRet = ctdbDropTable(hDatabase, table_name);

See also

ctdbDeleteTable(), ctdbAddTable(), ctdbAllocDatabase()

ctdbFindActiveTable

Get the handle of an active table by name.

Declaration

CTHANDLE ctdbFindActiveTable(CTHANDLE Handle, pTEXT Name)

where:

Handle [in] - the handle of the database dictionary to search.
Name [in] - the string with the table name to lookup in the database dictionary.

Description

ctdbFindActiveTable() retrieves the table handle of an active/open table in the given database dictionary by name.

To get the handle of an active table by the Unique Identifier, use ctdbFindActiveTableByUID().

To retrieve the table handle of the first active table in the database dictionary, use ctdbGetFirstActiveTable().

To get the path of any table in the database dictionary by name, use ctdbFindTable().

Returns

ctdbFindActiveTable() returns the table handle or NULL if the table is not in the database dictionary or if the table is not active/open.

See also

ctdbFindActiveDatabaseByUID(), ctdbFindTable(), ctdbGetFirstActiveTable()

ctdbFindActiveTableByUID

Get the handle of an active/open table by its unique identifier.

Declaration

CTHANDLE ctdbFindActiveTableByUID(CTHANDLE Handle, ULONG uid)

Description

ctdbFindActiveTableByUID() retrieves the handle of an active/open a table in a database dictionary by the table’s unique identifier.

Use ctdbFindActiveTable() to get the handle of an active/open table by name.

Use ctdbFindTableByUID() to get the name and path of any table in the database dictionary by its Unique identifier.

Handle [in] - the handle of the database to be searched.
uid [in] - the unique table identifier, used to locate the table. It is set automatically when the table is created.

Returns

ctdbFindActiveTableByUID() returns the table handle or NULL if the specified table is not in the database dictionary or is not active/open.

See also

ctdbFindTableByUID(), ctdbFindActiveTable(), ctdbGetDatabaseUID()

ctdbFindTable

Get the path of a table in a database dictionary.

Declaration

CTDBRET ctdbFindTable(CTHANDLE Handle, pTEXT Name, pTEXT Path,

VRLEN PathSize)

Description

ctdbFindTable() retrieves the path of a table in a database dictionary by name. Use ctdbFindTableByUID() to get the name and path of a table by its unique identifier. Use ctdbFindActiveTable() to get the handle of an active/connected table by name.

Handle [in] the handle of the database to search.
Name [in] the string with the table name to lookup in the database dictionary.
Path [out] receives the table path.
PathSize [in] the path size in bytes.

ctdbFirstTable() and ctdbNextTable() may be used to obtain the names and paths of all the tables in this database dictionary.

Returns

ctdbFindTable() returns CTDBRET_OK on success, or INOT_ERR (101) if the table cannot be found in the database dictionary, or a c-tree error code on failure.

Example

eRet=ctdbFindTable(hDbase, tb_name, tb_path, sizeof (tb_path));

See also

ctdbAllocDatabase(), ctdbFindTableByUID(), ctdbFirstTable(), ctdbNextTable()

ctdbFindTableByUID

Get the name and path of a table in a database dictionary by its unique identifier.

Declaration

CTDBRET ctdbFindTableByUID(CTHANDLE Handle, ULONG uid, pTEXT Name,

VRLEN NameSize, pTEXT Path, VRLEN PathSize)

Description

ctdbFindTableByUID() retrieves the name and path of a table in a database dictionary by its unique identifier. Use ctdbFindTable() to get the path of a table in the database dictionary by name. Use ctdbGetTableUID() to retrieve the table UID.

Handle [in] the handle of the database to be searched.
uid [in] the unique table identifier, used to find the table.
Name [out] the string with the table name.
NameSize [in] the name size in bytes. If Name is not large enough to receive the table name, ctdbFindTableByUID() will return CTDBRET_ARGSMALL (4006).
Path [out] the path of the table, if the table is located, and it is large enough to hold the path. The path includes drive, directory, name and extension.
PathSize [in] the path size in bytes. If Path is not large enough to receive the table path, ctdbFindTableByUID() will return CTDBRET_ARGSMALL (4006).

Returns

ctdbFindTableByUID() returns CTDBRET_OK on success, or INOT_ERR (101) if the table cannot be found in the database dictionary, or a c-tree error code on failure.

See also

ctdbFindTable(), ctdbFirstTable(), ctdbNextTable(), ctdbGetTableUID()

ctdbFirstTable

Get the name and path of the first table in a database dictionary.

Declaration

CTDBRET ctdbFirstTable(CTHANDLE Handle, pTEXT Name, VRLEN NameSize,

pTEXT Path, VRLEN PathSize)

Description

ctdbFirstTable() gets the name and path of the first table in a database dictionary.

Handle [in] the database handle.
Name [out] receives the table name.
NameSize [in] the Name size in bytes.
Path [out] receives the table path.
PathSize [in] the Path size in bytes.

ctdbFirstTable(), in conjunction with ctdbNextTable(), may be used to obtain the names and paths of all the tables in this database dictionary. ctdbGetTableCount() may be used to retrieve the total number of tables in the database dictionary.

Returns

ctdbFirstTable() returns CTDBRET_OK on success, or INOT_ERR (101) if there are no tables in the database dictionary, or a c-tree error code on failure.

Example

ctdbFirstTable(hDB, t_name, sizeof(t_name), t_path, sizeof (t_path));

{ printf("\ntable name: %s", t_name); }

while (ctdbNextTable(hDB, t_name, sizeof(t_name), t_path,

sizeof(t_path)) == CTDBRET_OK);

See also

ctdbFirstDatabase(), ctdbNextTable(), ctdbFindTable(), ctdbGetTableCount()

ctdbFreeRecord

Release resources allocated for the record handle.

Declaration

void ctdbFreeRecord(CTHANDLE Handle)

Description

ctdbFreeRecord() releases resources allocated for the record handle. Any record handle allocated with ctdbAllocRecord() should be released with a call to ctdbFreeRecord(). After a call to ctdbFreeRecord(), the record handle cannot be used for other operations.

Handle [in] the record handle.

Returns

None.

See also

ctdbAllocRecord(), ctdbFreeTable()

ctdbFreeTable

Release resources allocated for the table handle.

Declaration

void ctdbFreeTable(CTHANDLE Handle)

Description

ctdbFreeTable() releases all resources associated with a table handle. After a call to ctdbFreeTable(), the table handle cannot be used for other operations. Note that if you release an active table’s handle (the handle of a table that is open), ctdbFreeTable() automatically closes the table and resets all record buffers associated with the table.

Handle [in] the Table Handle.

Returns

None.

Example

ctdbClose(hTable);

ctdbFreeTable(hTable);

See also

ctdbAllocTable(), ctdbFreeDatabase()

ctdbGetActiveTableByUID

Retrieve the active table handle given its UID.

Declaration

CTHANDLE ctdbGetActiveTableByUID(CTHANDLE Handle, ULONG uid)

Description

ctdbGetActiveTableByUID() retrieves the active table handle given its UID. Use ctdbGetActiveTableUID() to retrieve the table UID, given the table Handle.

Handle [in] the Table Handle.
uid [in] the table unique identifier number.

Returns

ctdbGetActiveTableByUID() returns the table Handle on success, or NULL on failure.

See also

ctdbGetActiveTableUID()

ctdbGetActiveTableUID

Retrieve the tableUID, given a table handle.

Declaration

CTDBRET ctdbGetActiveTableUID(CTHANDLE Handle, pULONG puid)

Description

ctdbGetActiveTableUID() retrieves the tableUID, given the Table Handle. Use ctdbGetTableUID() to retrieve the tableUID, given the table name. Use ctdbFindTableByUID() to locate a table in a database by its unique identifier.

Handle [in] the Table Handle.
puid [out] the table unique identifier.

Returns

ctdbGetActiveTableUID() returns CTDBRET_OK on success, or FairCom DB API error on failure.

See also

ctdbAllocTable(), ctdbFindTableByUID(), ctdbGetTableUID()

ctdbGetDefaultIndex

Return the current default index.

Declaration

NINT ctdbGetDefaultIndex(CTHANDLE Handle)

Description

ctdbGetDefaultIndex() returns the current default index number. When the record handle is initialized for the first time, the default index is set to zero. To retrieve the index name, use ctdbGetDefaultIndexName(). Use ctdbSetDefaultIndex() to set the default index for the table.

Handle [in] the record handle.

Returns

ctdbGetDefaultIndex() returns the table default index, or -1 on error.

CTDB_DATA_IDXNO: indicates a physical data table traversal without using any indexes.

See also

ctdbAllocRecord(), ctdbGetTableIndexCount(), ctdbSetDefaultIndex(), ctdbGetDefaultIndexName()

ctdbGetDefaultIndexName

Return the default index name.

Declaration

pTEXT ctdbGetDefaultIndexName(CTHANDLE Handle)

Description

ctdbGetDefaultIndexName() retrieves the current default index name. When the record handle is initialized for the first time, the default index is set to zero.

Handle [the] record handle.

Records

ctdbGetDefaultIndexName() returns the current default index name.

ctdbGetFieldDefaultValue

Retrieves the current field default value.

DECLARATION

pTEXT ctdbGetFieldDefaultValue(CTHANDLE Handle, pVRLEN pLength);

DESCRIPTION

If no default value is set ctdbGetFieldDefaultValue() returns NULL and no value is set to pLength. You can use ctdbIsFieldDefaultValueSet() function to check if a field default value is set or not. Handle must be a field handle. If pLength is not NULL, returns the length of the default value string.

RETURN

Returns the current field default value or NULL if no default value was set for the field.

EXAMPLE

/* check if default field value is 'USA' */

hField = ctdbGetField(hTable, 5);

if (hField)

{

VRLEN len;

pTEXT value = ctdbGetFieldDefaultValue(hField, &len);

if (value)

{

if (strcmp(value, "USA") == 0)

printf("Default value is 'USA'\n");

else

printf("Default value is not 'USA'\n");

}

else

printf("No default value set\n");

}

SEE ALSO

ctdbSetFieldDefaultValue(), ctdbGetFieldDefaultValue(), ctdbClearFieldDefaultValue(), ctdbIsFieldDefaultValueSet(), ctdbClearAllFieldDefaultValue(), ctdbSetFieldDefaultDateTimeType(), ctdbGetFieldDefaultTimeType()

ctdbGetFieldName

Retrieve the field name

Declaration

pTEXT ctdbGetFieldName(CTHANDLE Handle)

Description

ctdbGetFieldName() retrieves the field name, given a field handle. Use ctdbGetFieldNumber() to retrieve the field number given the field name.

Handle [in] the Field Handle.

Returns

ctdbGetFieldName() returns the field name, or NULL on failure

See also

ctdbAllocField(), ctdbGetFieldNumber(), ctdbGetFieldNumberByName(), ctdbGetFieldNbr(), ctdbGetFieldLength(), ctdbSetFieldName()

ctdbGetFieldNbr

Retrieve the field number in the table fields list

Declaration

NINT ctdbGetFieldNbr(CTHANDLE Handle)

Description

ctdbGetFieldNbr() retrieves the field number in the table fields list, given a field handle. Use ctdbGetFieldNumber() to retrieve the field number given the field name. Use ctdbGetFieldNumberByName() to retrieve the field number given the record handle.

Handle [in] the Field Handle.

Returns

ctdbGetFieldNbr() returns the field number, or -1 on failure

See also

ctdbAllocField(), ctdbSetFieldProperties(), ctdbGetFieldNumber(), ctdbGetFieldNumberByName(), ctdbGetFieldLength(), ctdbGetFieldName()

ctdbGetFieldNullFlag

Read the SQL null flag for this field's column. This flag indicates whether the SQL layer allows NULL values to be written to the fields of this column or not.

Declaration

CTBOOL ctdbGetFieldNullFlag(CTHANDLE Handle)

Description

ctdbGetFieldNullFlag() retrieves the field null flag.

Handle [in] the Field Handle.

The FairCom DB API null flag controls the NOT NULL property of a column in the SQL layer. If the flag is TRUE, it means the SQL “NOT NULL” property of the column is enabled, which means that that column is not allowed to have NULL values. If the flag is FALSE, it means the SQL “NOT NULL” property of the column is disabled, which means that that column is allowed to have NULL values. Setting this column has no effect on individual record null values: it is NOT enforced at the FairCom DB API layer. It is useful to set this flag in c-tree data files before SQL import such that the property is maintained.

Note: This function has no direct relation to ctdbIsNullField(), which returns if the NULL bit is set for one field in one record.

Returns

ctdbGetFieldNullFlag() returns the field NULL flag.

See also

ctdbGetField(), ctdbGetFieldNbr(), ctdbGetFieldLength(), ctdbGetFieldName(), ctdbSetFieldNullFlag(), ctdbIsNullField()

ctdbGetFieldNumber

Given the field Name and the table handle, returns the field number.

Declaration

NINT ctdbGetFieldNumber(CTHANDLE Handle, pTEXT FieldName)

Description

ctdbGetFieldNumber() returns the field number given the field name. Use ctdbGetFieldNbr() to retrieve the field number given a field handle. Use ctdbGetFieldNumberByName() to retrieve the field number given the name and record handle.

Handle [in] the Table Handle.
FieldName [in] the name that identifies the field in the table.

Returns

ctdbGetFieldNumber() returns the field number, or -1 on error.

Example

pMyTable1 = ctdbAllocTable(pMyDB1);

ctdbOpenTable(pMyTable1, "customer", CTOPEN_NORMAL);

fldnbr = ctdbGetFieldNumber(pMyTable1, "Name");

See also

ctdbAllocTable(), ctdbGetField(), ctdbGetFieldNbr(), ctdbGetFieldByName(), ctdbGetFieldNumberByName(), ctdbGetFieldLength(), ctdbGetFieldName()

ctdbGetFieldNumberByName

Return the field number, based on the field name and record handle.

Declaration

NINT ctdbGetFieldNumberByName(CTHANDLE Handle, pTEXT FieldName)

Description

ctdbGetFieldNumberByName() returns the field number given the field name and the record handle. Use ctdbGetFieldNumber() to retrieve the field number given the table handle. Use ctdbGetFieldNbr() to retrieve the field number given a field handle.

Handle [in] the record handle.
FieldName [in] the name that identifies the field in the table.

Returns

ctdbGetFieldNumberByName() returns the field number, or -1 on error.

Example

pMyRec1 = ctdbAllocRecord(pMyTable1);

ctdbFirstRecord(pMyRec1);

fldnbr = ctdbGetFieldNumberByName(pMyRec1, "Name");

See also

ctdbAllocTable(), ctdbGetField(), ctdbGetFieldNbr(), ctdbGetFieldByName(), ctdbGetFieldLength(), ctdbGetFieldName()

ctdbGetFieldOffset

Retrieve the field offset in record buffer

Declaration

VRLEN ctdbGetFieldOffset(CTHANDLE Handle, NINT FieldNbr)

Description

ctdbGetFieldOffset() retrieves the field offset in record buffer.

Handle [in] the record handle.
FieldNbr [in] the field number.

Returns

ctdbGetFieldOffset() returns the field offset.

Example

pMyRec1 = ctdbAllocRecord(pMyTable1);

ctdbFirstRecord(pMyRec1);

field0_offset = ctdbGetFieldOffset(pMyRec1, 0);

See also

ctdbGetFieldAddress()

ctdbGetFieldPrecision

Retrieve the field precision.

Declaration

NINT ctdbGetFieldPrecision(CTHANDLE Handle)

Description

ctdbGetFieldPrecision() retrieves the field precision. The field precision represents the total number of digits in a BCD number.

Handle [in] the Field Handle.

Returns

ctdbGetFieldPrecision() returns the field precision (maximum number of digits).

CT_MONEY:

Based on a four-byte signed integer, the maximum value for CT_MONEY is 21474836.47, which gives it a precision of 9 and a scale of 2 (although it appears to be 10 digits, values over precision 9 are not entirely within the boundaries). If you call ctdbGetFieldPrecision() on such a field, it returns 9 by definition.

See also

ctdbGetField(), ctdbGetFieldLength(), ctdbGetFieldName(), ctdbGetFieldNullFlag(), ctdbGetFieldScale(), ctdbSetFieldPrecision()

ctdbGetFieldProperties

Retrieve field properties such as name, type, and length, given a field handle.

Declaration

CTDBRET ctdbGetFieldProperties(CTHANDLE Handle, ppTEXT FieldName,

pCTDBTYPE pType, pVRLEN pLength)

Description

ctdbGetFieldProperties() retrieves field properties such as name, type, and length, given a field handle. These values come from the table definition. Use ctdbSetFieldProperties() to set the field properties.

Handle [in] the Field Handle.
FieldName [out] the field name.
pType [out] the field type.
pLength [out] the field length.

Returns

ctdbGetFieldProperties() returns CTDBRET_OK on success, or a FairCom DB API error code on failure

See also

ctdbAllocField(), ctdbSetFieldProperties()ctdbGetFieldProperties

Retrieve field properties such as name, type, and length, given a field handle.

Declaration

CTDBRET ctdbGetFieldProperties(CTHANDLE Handle, ppTEXT FieldName,

pCTDBTYPE pType, pVRLEN pLength)

Description

Handle [in] the Field Handle.
FieldName [out] the field name.
pType [out] the field type.
pLength [out] the field length.

Returns

ctdbGetFieldProperties() returns CTDBRET_OK on success, or a FairCom DB API error code on failure

See also

ctdbAllocField(), ctdbSetFieldProperties()

ctdbGetFieldScale

Retrieve the field scale.

Declaration

NINT ctdbGetFieldScale(CTHANDLE Handle)

Description

ctdbGetFieldScale() retrieves the field scale (the number of digits to the right of the decimal point).

Handle [in] the Field Handle.

Returns

ctdbGetFieldScale() returns the field scale.

See also

ctdbGetField(), ctdbGetFieldLength(), ctdbGetFieldName(), ctdbGetFieldNullFlag(), ctdbGetFieldPrecision(), ctdbSetFieldScale()

ctdbGetFieldSize

Retrieve the defined field size from the table definition.

Declaration

VRLEN ctdbGetFieldSize(CTHANDLE Handle, NINT FieldNbr)

Description

ctdbGetFieldSize() retrieves the defined size of a field from the table definition, given a record handle and a field number. To get this information given a field handle, use ctdbGetFieldLength(). To get the actual number of bytes being consumed by the data in a single field, in a single record (row) from a table, use ctdbGetFieldDataLength().

Handle [in] the record handle. This must be a record handle, and not any other handle type.
FieldNbr [in] the field number.

Returns

ctdbGetFieldSize() returns the defined field size.

See also

ctdbGetFieldDataLength(), ctdbGetFieldLength()

ctdbGetFieldStatus

Retrieves the changed status of a field handle.

DECLARATION

ULONG ctdbGetFieldStatus(CTHANDLE Handle);

DESCRIPTION

Retrieves the changed status of a field handle. Handle must be a FairCom DB API field handle. The status of a field handle is a bit map describing one or more changes that have occurred with the field object.

RETURN

ctdbGetFieldStatus() returns a bitmap of the following:

Value	Symbolic Constant	Explanation
0x00	CTDBFIELD_OLD	Original field as read from table
0x01	CTDBFIELD_NEW	Field added or inserted
0x02	CTDBFIELD_DEL	Original field deleted
0x04	CTDBFIELD_MOVED	Original field moved
0x10	CTDBFIELD_NAME	Field name changed
0x20	CTDBFIELD_TYPE	Field type changed
0x40	CTDBFIELD_LEN	Field length changed
0x80	CTDBFIELD_RESOURCE	Field resource changed

See Appendix A for a complete listing of valid c-tree Plus error values.

EXAMPLE

/* if field is new delete it */

for (i = 0; i < (NINT) ctdbGetTableFieldCount(hTable); i++)

{

CTHANDLE hField = ctdbGetField(hTable, i);

if (ctdbGetFieldStatus(hField) & CTDBFIELD_NEW)

if (ctdbDelField(hTable, 0) != CTDBRET_OK)

printf("ctdbDelField failed\n");

}

SEE ALSO

ctdbGetIndexStatus(), ctdbGetSegmentStatus()

ctdbGetFieldType

Retrieve the field type.

Declaration

CTDBTYPE ctdbGetFieldType(CTHANDLE Handle)

Description

ctdbGetFieldType() retrieves the field type, given a field handle. Use ctdbGetFieldLength() to retrieve the field length.

Handle [in] the Field Handle.

Returns

ctdbGetFieldType() returns the field type, or 0 on failure. Available types are described in FairCom DB API definitions.

See also

ctdbAllocField(), ctdbGetFieldNumber(), ctdbGetFieldName(), ctdbGetFieldLength(), ctdbSetFieldType()

ctdbGetPadChar

Retrieve the table pad and field delimiter characters.

Declaration

CTDBRET ctdbGetPadChar(CTHANDLE Handle, NINT pPadChar, NINT pDmlChar)

Description

ctdbGetPadChar() retrieves the table pad and field delimiter characters. These characters are used to pad fixed string fields (CT_FSTRING) to allow proper target key formation.

Handle [in] the Table Handle.
pPadChar [out] Pointer to receive the pad character
pDmlChar [out] Pointer to receive the field delimiter character.

Returns

ctdbGetPadChar() returns CTDBRET_OK on success, or FairCom DB API .NET error code on failure.

See also

ctdbSetPadChar(), ctdbUpdatePadChar()

ctdbMergeDatabaseDictionary

Compare and merge FairCom DB API database dictionaries.

Declaration

ctdbEXPORT CTDBRET ctdbDECL ctdbMergeDatabaseDictionary (CTHANDLE src, CTHANDLE dst, mergeFunPtr mrgfun, logFunPtr logfun);

Description

Parameters

src: handle of an exclusively open session where the database dictionary is the dictionary containing the entry to be merged.
dst: handle of an exclusively open session where the database dictionary is the target dictionary for the merge.
mrgfun: function that the FairCom DB API engine calls to perform the comparison and set the actions on the compared items.

The function prototype is:

CTDBRET (ctdbDECL *mergeFunPtr) (pCTDBLIST src_list, pCTDBLIST dst_list);

mrgfun must return either an error code (in which case the ctdbMergeSessionDictionary () function will fail with that error code) or CTDBRET_OK if no error occurred.

The FairCom DB API engine will pass two lists (CTDBLIST) containing items of type MERGEINFO. One per each dictionary entry.

The MERGEINFO structure is defined as follows:

struct tagMERGEINFO

{

DICTDATA info;

NINT todo;

};

info contains the dictionary record.
todo must be set to the action to perform on that entry.
src_list contains the elements from the source dictionary
dst_list contains the elements from the target dictionary.

The function must set for each entry the action to be performed on that entry as follows:

Source List Actions	Description
DIFF_SRC_IGNORE	Ignore the record in the source list and do not copy it on the target dictionary
DIFF_SRC_COPY2DST	Copy the record to the target dictionary for entries on the dst_list.
Destination List Actions	Description
DIFF_DST_KEEP	Keep the entry as it is.
DIFF_DST_REMOVE	Remove the entry.
DIFF_DST_REWRITE	Replace the dest record on disk with the one in the list (in case we merge only some information). Note: This cannot change the UID.

For example, to replace an entry on the target dictionary with one from the source dictionary, the todo of the item in dsl_list must be set to DIFF_DST_REMOVE, the todo of the item in src_list to DIFF_SRC_COPY2DST.

logfun: the function called to return additional information about errors.

The function prototype is:

VOID (ctdbDECL*logFunPtr) (NINT lvl, pTEXT mesg, CTDBRET error, pTEXT extra);

lvl: number indication the error message level. (1 indicating fewer and higher level messages to 3 indicating more numerous detailed messages.)
mesg: the error message
error: the error code
extra: extra information such as the table or database name.

Note: Depending on where an error occurred, this function could be called multiple times with different lvl and mesg.

Return Values

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

Example

Please review the source code for ctsqlmdd.c, FairCom DB SQL Database Move Utility, for a complete implementation using this FairCom DB API function.

See Also

ctrdbMergeSessionDictionary()

ctdbMergeSessionDictionary

Compare and merge FairCom DB API session dictionaries.

Declaration

ctdbEXPORT CTDBRET ctdbDECL ctdbMergeSessionDictionary (CTHANDLE src, CTHANDLE dst, mergeFunPtr mrgfun, logFunPtr logfun);

Description

Parameters

src: handle of an exclusively open session where the session dictionary is the dictionary containing the entry to be merged.
dst: handle of an exclusively open session where the session dictionary is the target dictionary for the merge.
mrgfun: function that the FairCom DB API engine calls to perform the comparison and set the actions on the compared items.

The function prototype is:

CTDBRET (ctdbDECL *mergeFunPtr) (pCTDBLIST src_list, pCTDBLIST dst_list);

mrgfun must return either an error code (in which case the ctdbMergeSessionDictionary () function will fail with that error code) or CTDBRET_OK if no error occurred.

The FairCom DB API engine will pass two lists (CTDBLIST) containing items of type MERGEINFO. One per each dictionary entry.

The MERGEINFO structure is defined as follows:

struct tagMERGEINFO

{

DICTDATA info;

NINT todo;

};

info contains the dictionary record.
todo must be set to the action to perform on that entry.
src_list contains the elements from the source dictionary
dst_list contains the elements from the target dictionary.

The function must set for each entry the action to be performed on that entry as follows:

Source List Actions	Description
DIFF_SRC_IGNORE	Ignore the record in the source list and do not copy it on the target dictionary
DIFF_SRC_COPY2DST	Copy the record to the target dictionary for entries on the dst_list.
Destination List Actions	Description
DIFF_DST_KEEP	Keep the entry as it is.
DIFF_DST_REMOVE	Remove the entry.
DIFF_DST_REWRITE	Replace the dest record on disk with the one in the list (in case we merge only some information). Note: This cannot change the UID.

logfun: the function called to return additional information about errors.

The function prototype is:

VOID (ctdbDECL*logFunPtr) (NINT lvl, pTEXT mesg, CTDBRET error, pTEXT extra);

lvl: number indication the error message level. (1 indicating fewer and higher level messages to 3 indicating more numerous detailed messages.)
mesg: the error message
error: the error code
extra: extra information such as the table or database name.

Note: Depending on where an error occurred, this function could be called multiple times with different lvl and mesg.

Return Values

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

Example

Please review the source code for ctsqlmdd.c, FairCom DB SQL Database Move Utility, for a complete implementation using this FairCom DB API function.

See Also

ctrdbMergeDatabaseDictionary()

ctdbMoveSegment ( See Indexing)

ctdbOpenTable

Open an existing table given its name.

Declaration

CTDBRET ctdbOpenTable(CTHANDLE Handle, pTEXT TableName,

CTOPEN_MODE OpenMode)

Description

ctdbOpenTable() opens an existing table, given its name. The database that contains the table was specified previously, when table handle Handle was allocated. FairCom DB API will look for the table and index files in the server directory (client/server applications) or in the execution directory (standalone applications).

To override this default directory, specify your own directory with ctdbSetTablePath() before you call this function.

To open a table that is protected with a password, call ctdbSetTablePassword() with Handle before you call this function.

To open an existing table given its unique identifier, use ctdbOpenTableByUID(). To create a table, use ctdbCreateTable(). To retrieve the table open mode, use ctdbGetTableOpenMode(). To close an open table, use ctdbCloseTable().

Handle [in] the Table Handle, previously allocated and associated with a database by calling ctdbAllocTable().
TableName [in] the table name.
OpenMode [in] the table open mode. The valid values for the table open mode are listed in FairCom DB API definitions.

To open an existing mirrored table, use ctdbOpenTable() specifying the proper mirror naming convention:

if (ctdbOpenTable(hTable, "customer|mirror", CTOPEN_NORMAL))

printf("ctdbOpenTable failed\n");

CTOPEN_CORRUPT can be used to open tables that would otherwise fail with errors 4187 (CTDBRET_INVFIELDDEF) or 4016 (CTDBRET_FIELDEXIST) due to incompatible DODA definitions.

Returns

ctdbOpenTable() returns CTDBRET_OK on success, or FairCom DB API error on failure.

See also

ctdbAllocTable(), ctdbCreateTable(), ctdbGetTableOpenMode(), ctdbCloseTable(), ctdbOpenTableByUID()

ctdbOpenTableByUID

Open an existing table, given its UID.

Declaration

CTDBRET ctdbOpenTableByUID(CTHANDLE Handle, ULONG uid,

CTOPEN_MODE OpenMode)

Description

ctdbOpenTableByUID() opens an existing table, given its unique identifier. The database that contains the table was specified previously, when table handle ‘Handle’ was allocated. FairCom DB API will look for the table and index files in the server directory (client/server applications) or in the execution directory (standalone applications).

To override this default directory, specify your own directory with ctdbSetTablePath() before you call this function.

To open a table that is protected with a password, call ctdbSetTablePassword() with Handle before you call this function.

To open the table given its name, use ctdbOpenTable(). To create a table, use ctdbCreateTable(). To retrieve the table open mode, use ctdbGetTableOpenMode(). To close an open table, use ctdbCloseTable().

Handle [in] the Table Handle, previously allocated and associated with a database by calling ctdbAllocTable().
uid [in] the table unique identifier.
OpenMode [in] the table open mode. The valid values for the table open mode are listed in FairCom DB API definitions.

Returns

ctdbOpenTableByUID() returns CTDBRET_OK on success, or FairCom DB API error on failure.

See also

ctdbAllocTable(), ctdbCreateTable(), ctdbGetTableOpenMode(), ctdbCloseTable(), ctdbOpenTable()

ctdbSetFieldAsUTF16

Sets the field with a Unicode UTF-16 string.

Declaration

CTDBRET ctdbSetFieldAsUTF16(CTHANDLE Handle, NINT FieldNbr, pWCHAR pValue);

Description

ctdbSetFieldAsUTF16() sets the field with a Unicode UTF-16 string. If the underlying field type is not one of the Unicode field types, the UTF-16 string is converted to the appropriate type before the data is stored in the field.

Handle is a record handle.
FieldNbr is the field number.
pValue is the wide (UTF-16) string buffer.

Beginning with V12.5, this function will fail with CTDBRET_TOOBIG(4043) if the input value exceeds the field length.

Truncation of Values (behavior before V12.5)

The SetFieldAs family of functions behave differently for fixed-length fields vs. variable-length fields:

Variable-length Fields - If the value passed to the SetFieldAs function exceeds the size of the field, it will be stored in the field in its entirety without truncation. Variable-length fields are allowed to exceed the declared field size. If truncation is desired, it will be necessary to check the size of the value and truncate it before passing it to the function. Because SQL cannot handle string fields that are longer than the set limit, your application will need logic to enforce the limit if the table will be opened with SQL.

Fixed-length Fields - If the value passed to the SetFieldAs function exceeds the size of the field, it will be truncated to the length of the field. The following types of fields are truncated at the FairCom DB API level:

SQL type: CHAR
CTDB types: CT_FSTRING, CT_FPSTRING, CT_F2STRING, CT_F4STRING

Return

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	No error occurred.

See Appendix A for a complete listing of valid c-tree Plus error values.

Example

CTDBRET AddData(CTHANDLE hRecord, pTEXT str, NINT val)

{

CTDBRET eRet;

WCHAR WStr[32];

if ((eRet = ctdbClearRecord(hRecord)) != CTDBRET_OK)

{

printf("ctdbClearRecord failed with error %d", eRet);

goto Exit;

}

if ((eRet = (CTDBRET)ctdb_u8TOu16(str, WStr, sizeof(WStr))) != CTDBRET_OK)

{

printf("ctdb_u8TOu16 failed with error %d", eRet);

goto Exit;

}

if ((eRet = ctdbSetFieldAsUTF16(hRecord, 0, WStr)) != CTDBRET_OK)

{

printf("ctdbSetFieldAsUTF16 failed with error %d", eRet);

goto Exit;

}

if ((eRet = ctdbSetFieldAsSigned(hRecord, 1, (CTSIGNED)val)) != CTDBRET_OK)

{

printf("ctdbSetFieldAsSigned failed with error %d", eRet);

goto Exit;

}

if ((eRet = ctdbWriteRecord(hRecord)) != CTDBRET_OK)

{

printf("ctdbWriteRecord failed with error %d", eRet);

goto Exit;

}

Exit:

return eRet;

}

SEE ALSO

ctdbGetFieldAsUTF16()

ctdbSetFieldDefaultDateTimeType

Sets the default field value date and time type.

DECLARATION

CTDBRET ctdbSetFieldDefaultDateTimeType(CTHANDLE Handle, CTDATE_TYPE dateType, CTTIME_TYPE timeType);

DESCRIPTION

Sets the default field value date and time type to be used when converting CT_DATE, CT_TIME and CT_TIMES string values. By default the date type is CTDATE_MDCY and the time type is CTTIME_HMS. Use this function to modify the default values.

ctdbSetFieldDefaultDateTimeType() modifies both the date and time types. If you wish to change only the default date time, but keep the current time type, use the following example:

ctdbSetFieldDefaultDateTimeType(hField, CTDATE_YMD, ctdbGetFieldDefaultTimeType(hField));

You can use the same approach to change only the time type, keeping the current date type:

ctdbSetFieldDefaultDateTimeType(hField,ctdbGetFieldDefaultDateType(hField), CTIME_HMP);

Handle must be a field handle.
dateType is a date type format to be used for converting values between dates and strings. The possible values are:

Value	Symbolic Constant	Explanation
1	CTDATE_MDCY	Date format is mm/dd/ccyy
2	CTDATE_MDY	Date format is mm/dd/yy
3	CTDATE_DMCY	Date format is dd/mm/ccyy
4	CTDATE_DMY	Date format is dd/mm/yy
5	CTDATE_CYMD	Date format is ccyymmdd
6	CTDATE_YMD	Date format is yymmdd

timeType is the time type to be used for converting values between time and strings. The possible values are:

Value	Symbolic Constant	Explanation
1	CTTIME_HMSP	Time format is hh:mm:ss am\|pm
2	CTTIME_HMP	Time format is hh:mm am\|pm
3	CTTIME_HMS	Time format is hh:mm:ss (24 hour)
4	CTTIME_HM	Time format is hh:mm (24 hour)
5	CTTIME_MIL	Time format is hhmm (military)

RETURN

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	No error occurred.

See Appendix A for a complete listing of valid c-tree Plus error values.

EXAMPLE

/* set the field default date and time types */

hField = ctdbGetField(hTable, 5);

if (hField)

if (ctdbSetFieldDefaultDateTimeType(hField, CTDATE_DMY, CTIME_HMP))

printf("ctdbSetFieldDefaultDateTimeType failed\n");

SEE ALSO

ctdbSetFieldDefaultValue(), ctdbGetFieldDefaultValue(), ctdbClearFieldDefaultValue(), ctdbIsFieldDefaultValueSet(), ctdbClearAllFieldDefaultValue(), ctdbGetFieldDefaultDateType(), ctdbGetFieldDefaultTimeType()

ctdbSetFieldDefaultValue

Sets the field default value.

DECLARATION

CTDBRET ctdbSetFieldDefaultValue(CTHANDLE Handle, pTEXT value, VRLEN length)

DESCRIPTION

The default value of a field is used during an alter table operation when a full table rebuild is performed. During a full alter table rebuild, and after the old record buffer data is moved to the new record buffer, the new record buffer is scanned and if a NULL field is found and that NULL field has a default value, the default value is copied to the field buffer.

The field default value is kept as a string representation of the data. It is recommended that numeric data should be converted to string using one of the rich set of FairCom DB API data conversion functions.

Date values should be converted to string using the default date type value. The default date type value can be retrieved by calling ctdbGetFieldDefaultDateType() function. By default, the date type is CTDATE_MDCY.

Time values should be converted to string using the default time type value. The default time type value can be retrieved by calling ctdbGetFieldDefaultTimeType() function. By default, the time type is CTTIME_HMS.

Time stamp values should be converted to string using the default date type and time type values as described above.

Handle must be a FairCom DB API field handle.
value is a string with the default value. No checks are made to ensure the default value matches the correct field type. The caller is responsible for passing the appropriate value.
length correspond to the length of value parameter. You must pass a proper length of the string.

RETURN

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	No error occurred.

See Appendix A for a complete listing of valid c-tree Plus error values.

EXAMPLE

/* set the default value for country - field #5 */

hField = ctdbGetField(hTable, 5);

if (hField)

if (ctdbSetFieldDefaultValue(hField, "USA", 3) != CTDBRET_OK)

printf("ctdbSetFieldDefaultValue failed\n");

EXTENDED DEFAULT FIELD VALUE SUPPORT

In V11 and later, it is possible to set default field values using functions such as SYSDATE, SYSDATETIME, etc. Previously, FairCom DB API only supported defining default values for fields using literal values. This improves FairCom DB API compliance with SQL, where it is possible to set default field values with literals or with functions.

A new enum, CTDEF_TYPE, has been added to use with these new functions:

CTDBRET ctdbDECL ctdbSetFieldDefaultValueType(CTHANDLE Handle, CTDEF_TYPE def_type);

Sets the default value type.

CTDEF_TYPE ctdbDECL ctdbGetFieldDefaultValueType(CTHANDLE Handle);

Gets the default value type.

Valid def_types are:

CTDEF_LITERAL: the value is a literal

CTDEF_USER: the current* user name

CTDEF_NULL: null

CTDEF_SYSDATE: the current* date

CTDEF_SYSTIME: the current* time

CTDEF_SYSTIMESTAMP: the current* timestamp

* “current” means at the time the default gets evaluated to be stored in the field.

To set the default value as a literal and automatically set its type to CTDEF_LITERAL, use a call to ctdbSetFieldDefaultValue.

To set the default value to any of the supported SQL functions, use a call to ctdbSetFieldDefaultValueType and pass the desired type, e.g. CTDEF_SYSDATE.

Default Values with ALTER TABLE

ctdbAlterTable has been enhanced to properly set the default value in new fields when doing a full rebuild.

ctdbAlterTable logic has been slightly changed so that the default value gets applied only to the fields just added, not to existing fields for which it may have been added or changed. Before this modification, existing fields could unintentionally change their values from NULL to the default value.

SEE ALSO

ctdbGetFieldDefaultValue(), ctdbClearFieldDefaultValue(), ctdbIsFieldDefaultValueSet(), ctdbClearAllFieldDefaultValue(), ctdbSetFieldDefaultDateTimeType(), ctdbGetFieldDefaultDateType(), ctdbGetFieldDefaultTimeType()

ctdbSetIdentityField

Sets a field to be an identity field starting with specified value and incrementing by a specified amount.

Declaration

CTDBRET ctdbSetIdentityField(CTHANDLE Handle, pTEXT FieldName, CTINT64 seed, CTINT64 increment)

Description

Sets a field to be an identity field starting with seed value and incrementing by increment.

Note: You must call ctdbAlterTable() to persist the change to the table after this call.

Return Values

ctdbSetIdentityField() returns CTDBRET_OK on success or a c-tree error code on failure.

Example

ctdbSetIdentityField(myTable, "custid", 1, 1);

ctdbAlterTable(mytable, CTDB_ALTER_NORMAL);

See Also

ctdbGetIdentityFieldDetails(), ctdbGetLastIdentity()

ctdbSetPadChar

Set the table pad and field delimiter characters.

Declaration

CTDBRET ctdbSetPadChar(CTHANDLE Handle, NINT pPadChar, NINT pDmlChar)

Description

ctdbSetPadChar() sets the table pad and field delimiter characters. These characters are used to pad fixed string fields (CT_FSTRING) to allow proper target key formation.

Handle [in] the Table Handle.
padchar [in] the pad character
dmlchar [in] the field delimiter character

Returns

ctdbSetPadChar() returns CTDBRET_OK on success, or FairCom DB API C API error code on failure.

See also

ctdbGetPadChar(), ctdbUpdatePadChar()

ctdbUpdatePadChar

Update the table pad and delimiter character resource.

Declaration

CTDBRET ctdbUpdatePadChar(CTHANDLE Handle, NINT padchar, NINT dmlchar,

CTBOOL rebuild)

Description

ctdbUpdatePadChar() updates the table pad and delimiter character resource. The table must be opened exclusive to allow update of the resource.

Handle [in] the Table Handle.
padchar [in] the pad character
dmlchar [in] the field delimiter character.
rebuild [in] indicate if the table should be rebuilt. If rebuild is set to YES, every record is read and the fixed string fields (CT_FSTRING) are padded according to new padding strategy. Notice that this feature is not implemented yet, and no rebuild is done.

Returns

ctdbUpdatePadChar() returns CTDBRET_OK on success, or FairCom DB API C API error code on failure.

See also

ctdbSetPadChar(), ctdbGetPadChar()

Data Definition

ctdbAddDatabase

ctdbAddField

ctdbAddIndex

ctdbAddSegment

ctdbAddJSONSegment

ctdbAttachTable

ctdbAttachTableXtd

ctdbCloneTable

ctdbMoveSegment ( See Indexing)

Was this article helpful?

Data Definition

ctdbAddDatabase

ctdbAddField

ctdbAddIndex

ctdbAddSegment

ctdbAddJSONSegment

ctdbAttachTable

ctdbAttachTableXtd

ctdbCloneTable

ctdbMoveSegment ( See Indexing)

Was this article helpful?

Related Articles

Data types

Concepts (Fields to JSON transform)