ctdbGetFirstActiveDatabase

Retrieve the handle of the first active/connected database in the session.

Declaration

CTHANDLE ctdbGetFirstActiveDatabase(CTHANDLE Handle,

pVRLEN pScanIndex)

Description

ctdbGetFirstActiveDatabase() retrieves the handle of the first active/connected database in the session. A database is considered "active" for a given client application if that client has connected that database to his session handle using the ctdbConnect() function. This function is used in conjunction with ctdbGetNextActiveDatabase() to list all of the active databases in a session.

Handle [in] the session handle.
pScanIndex [out] the pointer to a VRLEN to hold the scan state. It is returned by ctdbGetFirstActiveDatabase() and it will be an input to ctdbGetNextActiveDatabase().

Returns

ctdbGetFirstActiveDatabase() returns the handle of the database or NULL if the session contains no active databases.

See also

ctdbAllocSession(), ctdbGetNextActiveDatabase(), ctdbFindActiveDatabase(), ctdbFindActiveDatabaseByUID()

ctdbGetFirstActiveTable

Retrieve the handle of the first active/open table in the database dictionary.

Declaration

CTHANDLE ctdbGetFirstActiveTable(CTHANDLE Handle, pVRLEN pScanRec)

Description

ctdbGetFirstActiveTable() retrieves the handle of the first active/open table in a database dictionary. This function is used in conjunction with ctdbGetNextActiveTable() to get all the active/open tables in a database dictionary. To retrieve the table handle given the table name, use ctdbFindActiveTable().

Handle [in] the Database Handle.
pScanRec [out] the pointer to a VRLEN to hold the scan state. It is returned by ctdbGetFirstActiveTable() and it will be an input and output to/from ctdbGetNextActiveTable().

Returns

ctdbGetFirstActiveTable() returns the table handle or NULL if there are no active/open tables in the database dictionary.

See also

ctdbAllocDatabase(), ctdbGetNextActiveTable(), ctdbFindActiveTable()

ctdbGetHandleType

Retrieves the handle type.

DECLARATION

NINT ctdbGetHandleType(CTHANDLE Handle);

DESCRIPTION

ctdbGetHandleType() retrieves the handle type. Handle can be any valid FairCom DB API handle.

RETURN

ctdbGetHandleType() return one of the following values:

Value	Symbolic Constant
0	NULL or invalid Handle.
0x0db1	CTDB_SESSION_HANDLE_ID
0x0db2	CTDB_DATABASE_HANDLE_ID
0x0db3	CTDB_TABLE_HANDLE_ID
0x0db4	CTDB_RECORD_HANDLE_ID
0x0db5	CTDB_INDEX_HANDLE_ID
0x0db6	CTDB_FIELD_HANDLE_ID
0x0db7	CTDB_SEGMENT_HANDLE_ID

If the Handle parameter passed to ctdbGetHandleType() is NULL or invalid, ctdbGetHandleType() returns 0.

EXAMPLE

pCTDBSESSION pSession;

if (ctdbGetHandleType(Handle) == CTDB+_RECORD_HANDLE_ID)

pSession = ((pCTDBRECORD)Handle)->pSession;

SEE ALSO

ctdbGetLocalTag(), ctdbSetLocalTag()

ctdbGetIdentityFieldDetails

Declaration

pTEXT ctdbGetIdentityFieldDetails(CTHANDLE Handle, pLONG8 seed, pLONG8 increment)

Description

Returns the name, seed, and increment values of the Identity field.

Return Values

ctdbGetIdentityFieldDetails() returns the Identity Field name on success or NULL on failure. Call ctdbGetError() to verify if there was an actual error or if there is no identity field defined.

Example

LONG startval, incval;

TEXT astring[80];
pTEXT idcol = astring;

idcol = ctdbGetIdentityFieldDetails(myTable, &startval, &incval)

if (idcol)

printf("Identity column %s, is assigned a start value of %d and increment of %d\n",

startval, incval);

else

printf("Error in retrieving ID details, %d\n",

ctdbGetError() );

See Also

ctdbGetLastIdentity(). ctdbSetIdentityField()

ctdbGetIndex

Retrieve the handle for index identified by IndexNumber.

Declaration

CTHANDLE ctdbGetIndex(CTHANDLE Handle, NINT IndexNumber)

Description

ctdbGetIndex retrieves the handle for index identified by index number. To retrieve the index handle given the segment handle, use ctdbGetIndexHandle().

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

Returns

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

See also

ctdbAllocTable(), ctdbGetIndexHandle(), ctdbGetIndexNbr()

ctdbGetIndexByName

Retrieve the index handle given the index name

Declaration

CTHANDLE ctdbGetIndexByName(CTHANDLE Handle, pTEXT name)

Description

ctdbGetIndexByName() retrieves the index handle given the index name.

Handle [in] the Table Handle.
name [in] the index name.

Returns

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

See also

ctdbGetIndex(), ctdbGetIndexByUID(), ctdbGetIndexNbrByName()

ctdbGetIndexByUID

Retrieve the index handle given the index UID

Declaration

CTHANDLE ctdbGetIndexByUID(CTHANDLE Handle, ULONG uid)

Description

ctdbGetIndexByUID() retrieves the index handle given the index unique identifier, uid.

Handle [in] the Table Handle.
uid [in] the Index uid number.

Returns

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

See also

ctdbGetIndexNbr(), ctdbGetIndexNbrByName()

ctdbGetIndexDuplicateFlag

Retrieve the allow duplicate key flag for this index.

Declaration

CTBOOL ctdbGetIndexDuplicateFlag(CTHANDLE Handle)

Description

ctdbGetIndexDuplicateFlag() retrieves the allow duplicate key flag for this index. Use ctdbSetIndexDuplicateFlag() to set the allow duplicate key flag for the desired index.

Handle [in] the index handle.

Returns

ctdbGetIndexDuplicateFlag() returns the duplicate key flag for this index (YES or NO).

See also

ctdbAllocIndex(), ctdbSetIndexDuplicateFlag()

ctdbGetIndexEmptyChar

Retrieve the empty char property for this index

Declaration

NINT ctdbGetIndexEmptyChar(CTHANDLE Handle)

Description

ctdbGetIndexEmptyChar() retrieves the empty char property for this index. Use ctdbSetIndexEmptyChar() to set the empty char property for this index. The empty char property is expressed as the decimal equivalent of the ASCII table. For instance, an ASCII space is specified a value of 32, and NUL byte is specified as 0.

Handle [in] the index handle.

Returns

ctdbGetIndexEmptyChar() returns the empty char property.

See also

ctdbAllocIndex(), ctdbSetIndexEmptyChar()v

ctdbGetIndexExtension

Retrieve the table index file name extension.

Declaration

pTEXT ctdbGetIndexExtension(CTHANDLE Handle)

Description

ctdbGetIndexExtension() retrieves the table index file name extension. The default index extension is .idx. To set the index file name extension, use ctdbSetIndexExtension().

Handle [in] the Table Handle.

Returns

ctdbGetIndexExtension() returns the index file name extension.

See also

ctdbAllocTable(), ctdbSetIndexExtension()

ctdbGetIndexHandle

Retrieve the index handle.

Declaration

CTHANDLE ctdbGetIndexHandle(CTHANDLE Handle)

Description

ctdbGetIndexHandle() retrieves the index handle. To allocate an index handle, use ctdbAllocIndex(). To retrieve the index handle given the table and index number, use ctdbGetIndex().

Handle [in] may be an index handle, or the segment handle.

Returns

ctdbGetIndexHandle() returns the index handle or NULL on failure.

See also

ctdbAllocSegment(), ctdbGetFieldHandle(), ctdbAllocIndex(), ctdbGetIndex()

ctdbGetIndexKeyLength

Retrieve the key length for this index.

Declaration

VRLEN ctdbGetIndexKeyLength(CTHANDLE Handle)

Description

ctdbGetIndexKeyLength() retrieves the key length for this index.

Handle [in] the index handle.

Returns

ctdbGetIndexKeyLength() returns the key length or -1 on error.

See also

ctdbAllocIndex()

ctdbGetIndexKeyType

Retrieve the key type for this index.

Declaration

CTDBKEY ctdbGetIndexKeyType(CTHANDLE Handle)

Description

ctdbGetIndexKeyType() retrieves the key type for this index. Use ctdbAddIndex() to add an index to a table.

Handle [in] the index handle.

Use ctdbSetIndexKeyType() to set the Index key type.

Returns

ctdbGetIndexKeyType() returns the key type, or CTINDEX_ERROR on error. Allowed key types are listed in FairCom DB API definitions.

See also

ctdbAllocIndex(), ctdbAddIndex(), ctdbSetIndexKeyType()

ctdbGetIndexName

Retrieve the index name

Declaration

pTEXT ctdbGetIndexName(CTHANDLE Handle)

Description

ctdbGetIndexName() retrieves the index name.

Handle [in] the index handle.

Returns

ctdbGetIndexName() returns the pointer to the index name on success, or NULL on failure.

See also

ctdbAllocIndex(), ctdbGetSegmentNbr(), ctdbGetIndexNbrByName(), ctdbGetIndexNbr()

ctdbGetIndexNbr

Retrieve the index number in the table list.

Declaration

CTDBRET ctdbGetIndexNbr(CTHANDLE Handle, pVRLEN pNumber)

Description

ctdbGetIndexNbr() retrieves the index number in the table list, given an index handle. Use ctdbGetSegmentNbr() to retrieve the segment number.

Handle [in] the index handle.
pNumber [out] the index number.

Returns

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

See also

ctdbAllocIndex(), ctdbGetSegmentNbr(), ctdbGetIndexNbrByName(), ctdbGetIndexName()

ctdbGetIndexNbrByName

Retrieve the index number given the index name

Declaration

NINT ctdbGetIndexNbrByName(CTHANDLE Handle, pTEXT name)

Description

ctdbGetIndexNbrByName() retrieves the index number given the index name.

Handle [in] the Table Handle.
name [in] the index name.

Returns

ctdbGetIndexNbrByName() returns the index number on success, or -1 on error.

See also

ctdbGetIndexNbr(), ctdbGetIndexByName(), ctdbGetIndexByUID()

ctdbGetIndexNullFlag

Retrieve the null key flag for this index

Declaration

CTBOOL ctdbGetIndexNullFlag(CTHANDLE Handle)

Description

ctdbGetIndexNullFlag() retrieves the null key flag for this index. Use ctdbSetIndexNullFlag() to set the null key flag for the desired index.

Handle [in] the index handle.

Returns

ctdbGetIndexNullFlag() returns the null key flag (YES or NO).

See also

ctdbAllocIndex(), ctdbSetIndexNullFlag()

ctdbGetIndexSegmentCount

Retrieve the number of segments associated with this index

Declaration

VRLEN ctdbGetIndexSegmentCount(CTHANDLE Handle)

Description

ctdbGetIndexSegmentCount() retrieves the number of segments associated with this index.

Handle [in] the index handle.

Returns

ctdbGetIndexSegmentCount() returns the number of segments or -1 on error.

See also

ctdbAllocIndex()

ctdbGetIndexTemporaryFlag

Retrieve the flag that indicates this index as temporary.

Declaration

CTBOOL ctdbGetIndexTemporaryFlag(CTHANDLE Handle)

Description

ctdbGetIndexTemporaryFlag() retrieves the flag that indicates this index as temporary. Use ctdbSetIndexTemporaryFlag() to set the temporary flag for this index.

Handle [in] the index handle.

Returns

ctdbGetIndexTemporaryFlag() returns the temporary flag (YES or NO).

See also

ctdbAllocIndex(), ctdbSetIndexTemporaryFlag()

ctdbGetIndexUID

Retrieve the index UID number.

Declaration

CTDBRET ctdbGetIndexUID(CTHANDLE Handle, pTEXT Name, pULONG puid)

Description

ctdbGetIndexUID() retrieves the index unique identifier number.

Handle [in] the Database Handle.
Name [in] the Index name
puid [out] the UID value

Returns

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

See also

ctdbGetIndexNbr()

ctdbGetLibType

Retrieves the c-tree operational model used when compiling the FairCom DB API library.

Declaration

CTLIB_TYPE ctdbGetLibType(CTHANDLE Handle)

Description

ctdbGetLibType provides the ability to detect c-tree Plus operational model used when compiling a FairCom DB API C library.

Handle the Database Handle.

Returns

ctdbGetLibType returns a value of type CTLIB_TYPE.

CTLIB_TYPE	Description
CTLIB_SINGLE	Single user libary.
CTLIB_MUSER	Multi-user libary.
CTLIB_CLIENT	Client libary
CTLIB_LOCLIB	LOCLIB model.
CTLIB_SERVER	Server side library.
CTLIB_THREA	Multi-threaded enabled.
CTLIB_TRAN	Transaction processing enabled.

The return value has the following bits set if the library supports optional features.

Optional Bits

Description

CTLIB_THREA

Multi-threaded enabled.

CTLIB_TRAN

Transaction processing enabled.

See FairCom DB API Errors and Return Values for a complete listing of valid FairCom DB API error codes and return values.

ctdbGetLocalTag

Retrieves the local tag associate with a handle.

DECLARATION

pVOID ctdbGetLocalTag(CTHANDLE Handle);

DESCRIPTION

Retrieves the local tag associated with a handle. A localTag pointer is available for session, database, table and record handles, and is initialized with NULL when the handle is allocated.

Handle is any FairCom DB API session, table, record, or index handle.

RETURN

A pointer to a localTag, or NULL if Handle is NULL.

EXAMPLE

if (ctdbGetLocalTag(Handle))

{

pSession->onFree(ctdbGetLocalTag(Handle));

ctdbSetLocalTag(Handle, NULL);

}

SEE ALSO

ctdbGetHandleType(), ctdbSetLocalTag()

ctdbGetLogonOnly

Retrieve the session logon only flag.

Declaration

CTBOOL ctdbGetLogonOnly(CTHANDLE Handle)

Description

ctdbGetLogonOnly() retrieves the session logon only flag. This flag, when set to YES before the session Logon, will prevent the session from using the session dictionary. If the session dictionary may not be used, the database dictionary cannot be used. With this, any information related to databases or tables cannot be use, but the tables can yet be opened or created using the session handle.

To set the flag, use ctdbSetLogonOnly().

Handle [in] the session handle.

Returns

ctdbGetLogonOnly() returns YES if the flag was set, and NO otherwise.

Example

if (!cdbGetLogonOnly(hSession))

err = ctdbConnect(hDatabase, "MyDatabase");

See also

ctdbSetLogonOnly()

ctdbGetNextActiveDatabase

Retrieve the handle of the next active/connected database in the session.

Declaration

CTHANDLE ctdbGetNextActiveDatabase(CTHANDLE Handle, pVRLEN pScanIndex)

Description

ctdbGetNextActiveDatabase() retrieves the handle of the next active/connected database in the session. You must first get the first active database handle in the session with ctdbGetFirstActiveDatabase() before retrieving the next active database handle using this function. A database is considered "active" for a given client application if that client has connected that database to his session handle using the ctdbConnect() function.

Handle [in] the session handle.
pScanIndex [out] the pointer to a VRLEN to hold the scan state. It is returned by ctdbGetFirstActiveDatabase(), and it is updated in the ctdbGetNextActiveDatabase() function.

Returns

ctdbGetNextActiveDatabase() returns the database handle, or NULL if the handle of the last active/connected database in the session has already been retrieved.

See also

ctdbAllocSession(), ctdbGetFirstActiveDatabase(), ctdbFindActiveDatabase(), ctdbFindActiveDatabaseByUID()

ctdbGetNextActiveTable

Retrieve the handle of the next active/open table in the database dictionary.

Declaration

CTHANDLE ctdbGetNextActiveTable(CTHANDLE Handle, pVRLEN pScanRec)

Description

ctdbGetNextActiveTable() retrieves the handle of the next active/open table in the database dictionary. Obtain the handle of the first active/open table in the database with ctdbGetFirstActiveTable() before requesting the handle of the next active table in the database with this function.

Handle [in] the Database Handle.
pScanRec [out] the pointer to a VRLEN to hold the scan state. It is first returned by ctdbGetFirstActiveTable(), and it is updated in the ctdbGetNextActiveTable() function.

Returns

ctdbGetNextActiveTable() returns the database handle, or NULL if the handle of the last active/open table in the database dictionary has already been retrieved.

See also

ctdbAllocSession(), ctdbGetFirstActiveTable(), ctdbFindActiveTable()

ctdbGetRecord

Retrieve the record handle from the table's active record list.

Note: ctdbGetRecord() is a specific-use function to retrieve a record handle from the internal table active record list. If you are simply trying to read a record, ctdbReadRecord() is a more commonly used function

Declaration

CTHANDLE ctdbGetRecord(CTHANDLE Handle, NINT index)

Description

ctdbGetRecord() retrieves the record handle from the table's active record list.

Handle [in] - the Table Handle.
index [in] - the Nth active record to return.

Returns

ctdbGetRecord() returns the record handle on success, or NULL on error.

See also

ctdbReadRecord(), ctdbAllocRecord(), ctdbGetDatabaseHandle(), ctdbGetFieldHandle()

ctdbGetRecordBuffer

Return a pointer to the current record buffer.

Declaration

pVOID ctdbGetRecordBuffer(CTHANDLE Handle)

Description

ctdbGetRecordBuffer() returns a pointer to the current record buffer.

Handle [in] the record handle.

CAUTION: If the record buffer was not set as CTRECBUF_STATIC, ctdb API calls modifying this record handle may cause the internal record buffer to be reallocated. Previously returned record buffer pointers would then reference invalid memory (a dangling pointer).

Returns

ctdbGetRecordBuffer() returns the record buffer, or NULL on error

See also

ctdbAllocRecord(), ctdbGetRecordLength()

ctdbGetRecordCount

Retrieve the number of records in Table.

Declaration

CTDBRET ctdbGetRecordCount(CTHANDLE Handle, pCTUINT64 pCount)

Description

ctdbGetRecordCount() retrieves the number of records in the table.

Handle [in] the record handle.
pCount [out] receives the number of records in the table.

Returns

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

See also

ctdbGetRecordCount behavior on MRT Table modified
ctdbAllocRecord()

ctdbGetRecordCount behavior on MRT Table modified

In V11.5, the behavior of the FairCom DB API function ctdbGetRecordCount has been modified when used on Multi-Schema Tables (MRT Virtual Tables). When used on MRT Tables, ctdbGetRecordCount() used to fail with error code CTDBRET_NOTYET.

The behavior on MRT Tables has been changed as follows:

return the error CTDBRET_ISVTABLE (4155)
set the pCount to the number of total entries in the physical table.

The effect of this change is to return an error as before, although more specific, and also return the number of records in the physical table.

Note: This is a Compatibility Change.

ctdbGetRecordHandle

Retrieve the record handle

Declaration

CTHANDLE ctdbGetRecordHandle(CTHANDLE Handle)

Description

ctdbGetRecordHandle() retrieves the record handle. To allocate a record handle, use ctdbAllocRecord().

Handle [in] must be a record handle, otherwise ctdbGetRecordHandle() returns NULL.

Returns

ctdbGetRecordHandle() returns a record handle on success or NULL on error.

See also

ctdbAllocRecord()

ctdbGetRecordLength

Return the current record length.

Declaration

VRLEN ctdbGetRecordLength(CTHANDLE Handle)

Description

ctdbGetRecordLength() returns the current record length.

Handle [in] the record handle.

Returns

ctdbGetRecordLength() returns the record length or 0 on error.

See also

ctdbAllocRecord(), ctdbGetRecordBuffer(), ctdbGetRecordSize()

ctdbGetRecordNbr

Retrieve the record index number in the table's active record list

Declaration

NINT ctdbGetRecordNbr(CTHANDLE Handle)

Description

ctdbGetRecordNbr() retrieves the record index number in the table's active record list.

Handle [in] the record handle.

Returns

ctdbGetRecordNbr() returns the record index number or -1 on error.

See also

ctdbAllocRecord(), ctdbGetRecordBuffer(), ctdbGetRecordLength()

ctdbGetRecordPos

Retrieve the current record offset position.

Declaration

CTDBRET ctdbGetRecordPos(CTHANDLE Handle, pCTOFFSET pOffset)

Description

ctdbGetRecordPos() retrieves the current record offset position if the table has support to a RECBYT index. When the table is created, by default it includes a RECBYT index. In order to verify if the table has support to a RECBYT index, use ctdbHasRecbyt().

Handle [in] the record handle.
pOffset [out] receives the current record offset position.

Returns

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

See also

ctdbSetRecordPos(), ctdbSetRecordOffset(), ctdbSeekRecord(), ctdbHasRecbyt(), ctdbCreateTable()

ctdbGetRecordSize

Return the allocated record buffer size in bytes.

Declaration

VRLEN ctdbGetRecordSize(CTHANDLE Handle)

Description

ctdbGetRecordSize() returns the allocated record buffer size in bytes.

Handle [in] the record handle.

Returns

ctdbGetRecordSize() returns the record size or 0 on error.

See also

ctdbAllocRecord(), ctdbGetRecordBuffer(), ctdbGetRecordLength()

ctdbGetRowid (see Data Manipulation)

ctdbGetSegment

Retrieve the segment handle of the segment indicated by SegNumber.

Declaration

CTHANDLE ctdbGetSegment(CTHANDLE Handle, NINT SegNumber)

Description

ctdbGetSegment() retrieves the segment handle of the segment indicated by SegNumber.

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

Returns

ctdbGetSegment() returns the segment handle, or NULL on error.

See also

ctdbAllocIndex()

ctdbGetSegmentField

Retrieve the field handle of the segment.

Declaration

CTHANDLE ctdbGetSegmentField(CTHANDLE Handle)

Description

ctdbGetSegmentField() retrieve the field handle of the segment.

Handle [in] the Segment Handle.

Returns

ctdbGetSegmentField() returns the field handle, or NULL on error.

See also

ctdbAllocSegment()

ctdbGetSegmentFieldName

Get the field name of the index segment.

Declaration

pTEXT ctdbGetSegmentFieldName(CTHANDLE Handle)

Description

ctdbGetSegmentFieldName() gets the field name of the index segment.

Handle [in] the Segment Handle.

Returns

ctdbGetSegmentFieldName() returns the field name, or NULL on error

See also

ctdbAllocSegment()

ctdbGetSegmentHandle

Retrieve a segment handle.

Declaration

CTHANDLE ctdbGetSegmentHandle(CTHANDLE Handle)

Description

ctdbGetSegmentHandle() retrieves a segment handle.

Handle [in] the Segment Handle.

Returns

ctdbGetSegmentHandle() returns segment handle on success or NULL on failure.

See also

ctdbAllocSegment()

ctdbGetSegmentMode

Retrieve the segment mode.

Declaration

CTSEG_MODE ctdbGetSegmentMode(CTHANDLE Handle)

Description

ctdbGetSegmentMode() retrieves the segment mode. Use ctdbSetSegmentMode() to set the segment mode.

Handle [in] the Segment Handle.

Returns

ctdbGetSegmentMode() returns the segment mode, or FairCom DB API .NET error on failure.

See also

ctdbAllocSegment(), ctdbSetSegmentMode()

ctdbGetSegmentNbr

Retrieve the segment number in the segment list on the index handle.

Declaration

CTDBRET ctdbGetSegmentNbr(CTHANDLE Handle, pVRLEN pNumber)

Description

ctdbGetSegmentNbr() retrieves the segment number in the segment list, given a Segment Handle. Use ctdbGetIndexNbr() to retrieve the index number.

Handle [in] the Segment Handle.
pNumber [out] the segment number.

Returns

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

See also

ctdbGetIndexNbr()

ctdbGetSegmentPartialField

Retrieves the field handle on which a key segment is based, even if the segment does not match the entire field length.

DECLARATION

CTHANDLE ctdbDECL ctdbGetSegmentPartialField(CTHANDLE Handle);

DESCRIPTION

FairCom DB API was able to find the matching between a key segment and a field only if the key segment started at the beginning of a field and exactly matched the field length, as it is required by FairCom DB SQL. It was desirable to retrieve a field on which the key segment start at the beginning of a field but does not exactly match the entire field.

CtdbGetSegmentPartialField() was added to FairCom DB API C API to retrieve the field handle on which a key segment is based, even if the segment does not match the entire field length.

Handle is the segment handle that we are trying to match to one of the table fields.

ctdbGetSegmentPartialField() returns the handle of the field that matches the key segment definition. If a match can’t be found, or if an error is detected, this function returns NULL.

RETURN

Returns the field handle that matches the segment or NULL if no such match exists.

EXAMPLE

/* try to find a match, or partial match, for the key segment */

CTHANDLE GetFieldMatch(CTHANDLE hIndex, NINT segnbr)

{

CTHANDLE hField = NULL;

CTHANDLE hSegment = ctdbGetSegment(hIndex, segnbr);

if (hSegment)

hField = ctdbGetSegmentPartialField(hSegment);

return hField;

}

SEE ALSO

ctdbGetSegmentField(), ctdbGetSegmentFieldName()

ctdbGetSegmentStatus

Retrieves the status of the segment handle.

DECLARATION

ULONG ctdbGetSegmentStatus(CTHANDLE Handle);

DESCRIPTION

Retrieves the status of a segment handle.

Handle is a segment handle.

The status of the segment handle is a bit map describing one or more changes that have occurred to the segment handle.

RETURN

ctdbGetSegmentStatus returns a bitmap of the following:

Value	Symbolic Constant	Explanation
0x00	CTDBISEG_OLD	Original segment as read from file
0x01	CTDBISEG_NEW	Segment added or inserted
0x02	CTDBISEG_DEL	Original segment deleted
0x04	CTDBISEG_MOVED	Original segment moved
0x10	CTDBISEG_MODE	Segment mode changed
0x20	CTDBISEG_FIELD	Segment field changed

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

EXAMPLE

/* if any segment of an index has changed, call alter table */

for (i = 0; i < (NINT) ctdbGetIndexSegmentCount(hIndex); i++)

{

CTHANDLE hSeg = ctdbGetSegment(hIndex, i);

if (ctdbGetSegmentStatus(hSeg) != CTDBISEG_OLD)

if (ctdbAlterTable(hIndex, CTDB_ALTER_NORMAL) != CTDBRET_OK)

printf("ctdbAlterTable failed\n");

}

SEE ALSO

ctdbGetFieldStatus(), ctdbGetIndexStatus()

ctdbGetServerName

Return the server name associated with the session.

Declaration

pTEXT ctdbGetServerName(CTHANDLE Handle)

Description

ctdbGetServerName() returns the server name associated with the session. You must log on to the server with ctdbLogon() before getting the server name.

Handle [in] the session handle.

Returns

ctdbGetServerName() returns a pointer to the Server name, or NULL on failure.

Example

username=ctdbGetUserLogonName(hSession);

servname=ctdbGetServerName(hSession);

See also

ctdbLogon(), ctdbAllocSession(), ctdbGetUserLogonName()

ctdbGetSessionHandle

Return the session handle from the opaque handle.

Declaration

CTHANDLE ctdbGetSessionHandle(CTHANDLE Handle)

Description

ctdbGetSessionHandle() returns the session handle from the opaque handle, having as parameter any handle inside the session. To allocate a session handle, use ctdbAllocSession().

Handle [in] may be a session handle, a database handle, a table handle, a record handle, a field handle, an index handle, or a segment handle.

Returns

ctdbGetSessionHandle() returns the session handle or NULL on failure.

Example

hSess=ctdbGetSessionHandle(hDatabase);

See also

ctdbAllocSession(), ctdbAllocDatabase(), ctdbAllocTable(), ctdbAllocRecord(), ctdbAllocField(), ctdbAllocIndex(), ctdbAllocSegment(), ctdbGetDatabaseHandle()

ctdbGetSessionParams

Return the session parameter based on the parameter type.

Declaration

NINT ctdbGetSessionParams(CTHANDLE Handle, CTSESSION_PARAM ParamType)

Description

ctdbGetSessionParams() returns the session parameter based on the parameter type. The application must log on to the server with ctdbLogon() before getting the session parameter type.

Handle [in] the session handle.
ParamType [in] the parameter type. Valid values for ParamTypes are:
- CT_BUFS: the number of index file buffers, minimum 3
- CT_FILS: initial block of file structures.
- CT_SECT: the number of node sectors. Minimum of one required. sect multiplied by 128 equals the index node size.
- CT_DBUFS: the number of buffers for data files I/O
- CT_USERPROF: is the user profile mask, and accepts the following values:
  - USERPRF_CLRCHK - instructs single-user TRANPROC applications to remove S*.FCS and L*.FCS files upon a successful application shutdown. The c-tree Plus checkpoint code determines at the time of a final checkpoint if there are no pending transactions or file opens, and if this user profile bit has been turned on. If so, the S*.FCS and L*.FCS files are deleted. However, if the application is causing log files to be saved (very unusual for a single-user application), then the files are not cleared. The USERPRF_CLRCHK option is off by default. See 13.3 "Single-User Transaction Processing" in the c-tree Plus Programmer's Reference Guide for additional information.
  - USERPRF_LOCLIB - specifies this instance of c-tree Plus is to be directed to a local database. Applicable only to client/server when using "Local Library Support".
  - USERPRF_NDATA - enable the manual mode of UNIFRMAT support. Enabling the manual record transformation mode would only be desirable when performing custom record level byte flipping or when record structures contain no numeric data (i.e., LONG, FLOAT, . . .). A side benefit of enabling this manual mode is the virtual elimination of Server DODA requests, thereby reducing network traffic by one function call per file open.
  - USERPRF_NTKEY - disables the automatic TransformKey() feature. See "TransformKey" in the c-tree Plus Programmer's Reference Guide for more information.
  - USERPRF_PTHTMP - changes GetCtTempFileName() from its default operation of returning a temporary file name to specifying a directory name where temporary files are to reside.
  - USERPRF_SAVENV - enable the automatic SAVENV feature. See the Begin() function description for more information.

To use more than one value, OR the values together. Leave CT_USERPROF set to zero to accept the defaults.

Returns

Returns the parameter value. If an invalid handle or parameter type is passed, ctdbGetSessionParams() returns 0.

Example

CTSESSION_TYPE ctdbsess=CTSESSION_CTDB;

CTHANDLE hSession = ctdbAllocSession(ctdbsess);

CTDBRET err;

NINT ret, newbuf;

err = ctdbLogon(hSession, "FAIRCOMS", "ADMIN", "ADMIN");

ret = ctdbGetSessionParams(hSession, CT_BUFS);

newbuf = ret + 2;

err = ctdbSetSessionParams(hSession, CT_BUFS, newbuf);

See also

ctdbGetServerName(), ctdbGetUserLogonName(), ctdbAllocSession(), ctdbSetSessionParams()

ctdbGetSessionPath

Return the default session path.

Declaration

CTDBRET ctdbGetSessionPath(CTHANDLE Handle, pTEXT Path,

VRLEN PathSize)

Description

ctdbGetSessionPath() returns the session path that is stored in the session handle. Note that the returned session path will be empty unless you have previously called ctdbSetSessionPath() with that session handle. Use ctdbSetSessionPath() to set the session path.

Handle [in] the session handle.
Path [out] the pointer to a C string where the session path is returned.
PathSize [in] the Path size in bytes. If Path is not large enough to hold the session path, the error CTDBRET_ARGSMALL (4006) is returned.

Returns

ctdbGetSessionPath() returns CTDBRET_OK if successful, or the c-tree Plus error code on failure, or CTDBRET_ARGSMALL (4006) if the Path is not large enough to hold the session path.

Example

eRet = ctdbLogon(handle, "FAIRCOMS", "ADMIN", "ADMIN");

eRet = ctdbGetSessionPath(handle, ses_path, sizeof(ses_path));

See also

ctdbSetSessionPath()

ctdbGetSessionType

Retrieve the current session type.

Declaration

CTSESSION_TYPE ctdbGetSessionType(CTHANDLE Handle)

Description

ctdbGetSessionType() retrieves the current session type. The session type is initially set when ctdbAllocSession() is called to allocate a new session handle, and it can be modified using ctdbSetSessionType().

Handle [in] the session handle.

Returns

ctdbGetSessionType() returns the session type. If the session handle is not valid, ctdbGetSessionType() always return CTSESSION_CTDB.

See also

ctdbSetSessionType()

ctdbGetTable

Return the table handle, given its position in the database active table list.

Declaration

CTHANDLE ctdbGetTableNbr(CTHANDLE Handle, NINT index)

Description

ctdbGetTable() retrieves the table handle, given its position in the database's active table list.

Handle [in] Database Handle.
index [in] the table position in the database table list.

Returns

ctdbGetTable() returns the table handle or null on error

See also

ctdbGetTableName(), ctdbGetTableNbr()

ctdbGetTableCount

Retrieve the number of tables in the database dictionary.

Declaration

NINT ctdbGetTableCount(CTHANDLE Handle)

Description

ctdbGetTableCount() returns the number of tables in the database dictionary that is connected to the specified handle. Note that databases which were created in a CTSESSION_SQL-mode session will automatically have several dozen system tables, in addition to any tables that were added by client applications.

Handle [in] the Database Handle.

Returns

ctdbGetTableCount() returns the number of tables in the database dictionary, or -1 on error.

See also

ctdbGetDatabaseCount()

ctdbGetTableCreateMode

Retrieve the table create mode.

Declaration

CTCREATE_MODE ctdbGetTableCreateMode(CTHANDLE Handle)

Description

ctdbGetTableCreateMode() retrieves the table creation mode. To retrieve the table open mode, use ctdbGetTableOpenMode(). To create a table, use ctdbCreateTable().

Handle [in] the Table Handle.

Returns

ctdbGetTableCreateMode() returns the table create mode. The valid values for the table create mode are listed in FairCom DB API definitions. This function returns zero on error.

See also

ctdbAllocTable(), ctdbGetTableOpenMode(), ctdbCreateTable()

ctdbGetTableDefaultDataExtentSize

Retrieve the table default data extent size

Declaration

NINT ctdbGetTableDefaultDataExtentSize(CTHANDLE Handle)

Description

ctdbGetTableDefaultDataExtentSize() retrieves the table default data extent size. Use ctdbGetTableDefaultIndexExtentSize() to retrieve the table default index extend size. Use ctdbSetTableDefaultDataExtentSize() to set the table default data extent size.

Handle [in] the Table Handle.

Returns

ctdbGetTableDefaultDataExtentSize() returns the table default data extent size.

See also

ctdbGetTableDefaultIndexExtentSize(), ctdbSetTableDefaultDataExtentSize()

ctdbGetTableDefaultIndexExtentSize

Retrieve the table default index extent size

Declaration

NINT ctdbGetTableDefaultIndexExtentSize(CTHANDLE Handle)

Description

ctdbGetTableDefaultIndexExtentSize() retrieves the table default index extent size. Use ctdbGetTableDefaultDataExtentSize() to retrieve the table default data extend size. Use ctdbSetTableDefaultIndexExtentSize() to set the table default index extent size. Use ctdbGetDefaultIndex() to retrieve the table default index.

Handle [in] the Table Handle.

Returns

ctdbGetTableDefaultIndexExtentSize() returns the table default index extent size.

See also

ctdbGetDefaultIndex(), ctdbGetTableDefaultDataExtentSize(), ctdbSetTableDefaultIndexExtentSize()

ctdbGetTableExtension

Retrieve the table filename extension.

Declaration

pTEXT ctdbGetTableExtension(CTHANDLE Handle)

Description

ctdbGetTableExtension() retrieves the table filename extension. To retrieve the path, use ctdbGetTablePath(), and to retrieve the name, use ctdbGetTableName().

Handle [in] the Table Handle.

Returns

ctdbGetTableExtension() returns the Table extension name or NULL on failure

See also

ctdbAllocTable(), ctdbGetTableName(), ctdbGetTablePath(), ctdbSetTableExtension()

ctdbGetTableFieldCount

Retrieve the number of fields associated with the table.

Declaration

VRLEN ctdbGetTableFieldCount(CTHANDLE Handle)

Description

ctdbGetTableFieldCount() retrieves the number of fields associated with the table.

Handle [in] the Table Handle.

Returns

ctdbGetTableFieldCount() returns the number of fields or -1 on error.

See also

ctdbAllocTable(), ctdbGetTableIndexCount()

ctdbGetTableGroupid

Retrieve the table group ID.

Declaration

pTEXT ctdbGetTableGroupid(CTHANDLE Handle, pTEXT groupid)

Description

ctdbGetTableGroupid() retrieves the table group ID. To set the table group ID, use ctdbSetTableGroupid().

Handle [in] the Table Handle.

Returns

ctdbGetTableGroupid() returns the table group ID.

See also

ctdbAllocTable(), ctdbSetTableGroupid()

ctdbGetTableHandle

Return a table handle

Declaration

CTHANDLE ctdbGetTableHandle(CTHANDLE Handle)

Description

ctdbGetTableHandle() retrieves the table handle.

Handle [in] may be table handle, a record handle, a field handle, an index handle, a segment handle.

Returns

ctdbGetTableHandle() returns the table handle or NULL on failure.

See also

ctdbAllocTable(), ctdbGetDatabaseHandle(), ctdbGetSessionHandle(), ctdbGetRecordHandle()

ctdbGetTableIndexCount

Retrieve the number of indexes associated with the table.

Declaration

VRLEN ctdbGetTableIndexCount(CTHANDLE Handle)

Description

ctdbGetTableIndexCount() retrieves the number of indexes associated with the table.

Handle [in] the Table Handle.

Returns

ctdbGetTableIndexCount() returns the number of indexes or -1 on error.

See also

ctdbAllocTable(), ctdbGetDefaultIndex()

ctdbGetTableName

Retrieve the table name.

Declaration

pTEXT ctdbGetTableName(CTHANDLE Handle)

Description

ctdbGetTableName() retrieves the table name. The name has no path (drive/directory) or filename extension. To retrieve the path, use ctdbGetTablePath(); to retrieve the filename extension, use ctdbGetTableExtension().

Handle [in] the Table Handle.

Returns

ctdbGetTableName() returns the Table name or NULL on failure

See also

ctdbAllocTable(), ctdbGetTablePath(), ctdbGetTableExtension()

ctdbGetTableNbr

Return the table index number in the database's active table list.

Declaration

NINT ctdbGetTableNbr(CTHANDLE Handle)

Handle [in] Table Handle.

Description

ctdbGetTableNbr() retrieves the table index number in the database's active table list. Given the index number, the table handle may be retrieved using ctdbGetTable().

Returns

ctdbGetTableNbr() returns the table index number or -1 on error

See also

ctdbGetTableName(), ctdbGetTable()

ctdbGetTableOpenMode

Retrieve the table open mode.

Declaration

CTOPEN_MODE ctdbGetTableOpenMode(CTHANDLE Handle)

Description

ctdbGetTableOpenMode() retrieves the table open mode. Notice that a few modes are used when a file is created and cannot be changed after that. Two such modes are ctFIXED and VLENGTH, since it is not possible to change a file from fixed to variable length after its creation. Other values like EXCLUSIVE or SHARED may be changed after the table creation. To retrieve the table creation mode, use ctdbGetTableCreateMode(). To open a table, use ctdbOpenTable().

Handle [in] the Table Handle.

The valid values for the table open mode are listed in FairCom DB API definitions.

Returns

ctdbGetTableOpenMode() returns the table open mode.

See also

ctdbAllocTable(), ctdbOpenTable()

ctdbGetTableOwner

Declaration

pTEXT ctdbGetTableOwner(CTHANDLE Handle);

Description

Retrieves the table owner.

Return Values

If the table owner was not previously set by ctdbSetTableOwner(), ctdbGetTableOwner() returns NULL.

Handle is a table handle allocated by ctdbAllocTable().

See Also

ctdbSetTableOwner()

ctdbGetTablePassword

Retrieve the table password.

Declaration

pTEXT ctdbGetTablePassword(CTHANDLE Handle)

Description

ctdbGetTablePassword() retrieves the table password. Use ctdbSetTablePassword() to set the table password.

Handle [in] the Table Handle.

Returns

ctdbGetTablePassword() returns the table password.

See also

ctdbAllocTable(), ctdbSetTablePassword()

ctdbGetTablePath

Retrieve the table drive/directory path

Declaration

pTEXT ctdbGetTablePath(CTHANDLE Handle)

Description

ctdbGetTablePath() retrieves the table drive/directory path. To retrieve the table name, use ctdbGetTableName(). Use ctdbSetTablePath() to set the table path.

Handle [in] the Table Handle.

Returns

ctdbGetTablePath() returns the Table path or NULL on failure

See also

ctdbAllocTable(), ctdbGetTableName(), ctdbSetTablePath()

ctdbGetTablePermission

Retrieve the table permission.

Declaration

LONG ctdbGetTablePermission(CTHANDLE Handle)

Description

ctdbGetTablePermission() retrieves the table permission. The possible permissions are set by ctdbSetTablePermission() and they are all listed in FairCom DB API definitions.

Handle [in] the Table Handle.

Returns

ctdbGetTablePermission() returns the table permission.

See also

ctdbAllocTable(), ctdbSetTablePermission()

ctdbGetTableStatus

Declaration

ULONG ctdbGetTableStatus(CTHANDLE Handle);

Description

Retrieves the table status. The table status indicates which rebuild action will be taken by an alter table operation.

Handle is a table handle.

Return Values

Returns CTDB_REBUILD_NONE if the table is not changed or a bit mask of the values below describing the table status.

The possible rebuild status returns are:

Rebuild Status Value	Rebuild Status Symbolic Code	Explanation
0	CTDB_REBUILD_NONE	Nothing to be done, no changes to table
1	CTDB_REBUILD_DODA	Update the table DODA
2	CTDB_REBUILD_RESOURCE	Update table FC!DFLD resource
4	CTDB_REBUILD_INDEX	Add new indices to table
8	CTDB_REBUILD_ALL	Rebuild all indices
16	CTDB_REBUILD_FULL	Full table rebuild. A temporary table is created and all data is moved to new table and the indexes are built on the fly.

Example

ULONG status = ctdbGetTableStatus(hTable);

if (status & CTDB_REBUILD_ALL || status & CTDB_REBUILD_FULL)

ctdbAlterTable(hTable, CTDB_ALTER_FULL)

else if (status)

ctdbAlterTable(hTable, CTDB_ALTER_NORMAL);

See Also

ctdbGetIndexStatus(), ctdbGetSegmentStatus(), ctdbAlterTable()

ctdbGetTableUID

Retrieve the table Unique Identifier given a database handle and a table name.

Declaration

CTDBRET ctdbGetTableUID(CTHANDLE Handle, pTEXT Name, pULONG puid)

Description

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

Handle [in] the Database Handle.
Name [in] the table name.
puid [out] the table unique identifier.

Returns

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

See also

ctdbAllocDatabase(), ctdbFindTableByUID(), ctdbGetActiveTableUID()

ctdbGetUserLogonName

Return the user name associated with the session.

Declaration

pTEXT ctdbGetUserLogonName(CTHANDLE Handle)

Description

ctdbGetUserLogonName() returns the user name associated with the session. It is necessary to logon to the server with ctdbLogon() before getting the user name.

Handle [in] the session handle.

Returns

ctdbGetUserLogonName() returns a pointer to the User name, or NULL on failure.

Example

username=ctdbGetUserLogonName(hSession);

servname=ctdbGetServerName(hSession);

See also

ctdbGetServerName(), ctdbAllocSession()

ctdbGetUserTag

Retrieve the user tag.

Declaration

CTDBRET ctdbGetUserTag(CTHANDLE Handle, pVOID tagptr)

Description

ctdbGetUserTag() retrieves the user tag.

Handle [in] any FairCom DB API Handle.
tagptr [out] the pointer to receive the user tag.

Returns

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

See also

ctdbSetUserTag()

ctdbHasDelField

Tests for the presence of the internal delete flag.

Declaration

CTBOOL ctdbDECL ctdbHasDelField(CTHANDLE Handle);

Description

ctdbHasDelField() tests for the presence of the internal delete flag, $DELFLD$, field in a table. $DELFLD$ is a hidden field that FairCom DB API automatically creates as the first field in the record buffer. $DELFLD$ is defined as a 4-byte CT_ARRAY field (to ensure proper alignment of subsequent fields) and its only purpose is to keep a place at the beginning of the record to hold the c-tree delete record flag byte when a record is deleted. This field is handled internally by FairCom DB API and should never be modified by the user.

ctdbHasDelField() receives a table handle as parameter and returns YES if the table was created with a $DELFLD$ field. ctdbHasDelField() returns NO if the table was not created with a $DELFLD$ field.

Return

Symbolic Constant	Explanation
YES	$DELFLD$ in table.
NO	$DELFLD$ not in table.

ctdbHasNullFieldSupport

Indicate if a table has Null field support.

Declaration

CTBOOL ctdbHasNullFieldSupport(CTHANDLE Handle)

Description

ctdbHasNullFieldSupport() indicates if a table has Null field support.

Handle [in] the Table Handle.

Returns

ctdbHasNullFieldSupport() returns YES if the table has NULL field support, NO otherwise.

See also

ctdbIsNullField()

ctdbHasRecbyt

Indicate if the table has support for recbyt index.

Declaration

CTBOOL ctdbHasRecbyt(CTHANDLE Handle)

Description

ctdbHasRecbyt() indicates if the table has support for RECBYT index. This support is enabled by default when the table is created. If a table has support to a RECBYT index, the record position or offset may be retrieved with ctdbGetRecordPos().

Handle [in] the Table Handle.

Returns

ctdbHasRecbyt() returns yes if the function has support, and no otherwise.

See also

ctdbAllocTable(), ctdbGetRecordPos(), ctdbCreateTable()

ctdbHasRowid

Indicate if the table has support for rowid index.

Declaration

CTBOOL ctdbHasRowid(CTHANDLE Handle)

Description

ctdbHasRowid() indicates if the table has support for a ROWID index. By default, all tables created by FairCom DB API have support for ROWID. To create a table without support for ROWID, use the create mode CTCREATE_NOROWID in ctdbCreateTable().

ROWID holds the auto-increment value generated automatically by c-tree every time a new record is added to the table. This is a read-only field.

Handle [in] the Table Handle.

Returns

ctdbHasRowid() returns yes if the function has support, and no otherwise.

See also

ctdbAllocTable(), ctdbFindRowid(), ctdbGetRowid(), ctdbCreateTable(), ctdbHasRecbyt()

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".

See also

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

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".

See also

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

ctdbInsSegment

Insert a segment before the segment indicated by SegNumber

Declaration

CTHANDLE ctdbInsSegment(CTHANDLE Handle, NINT SegNumber,

CTHANDLE FieldHandle, CTSEG_MODE SegMode)

Description

ctdbInsSegment() inserts a segment before the segment indicated by SegNumber segment, given the index handle. The operation of inserting a segment links the index with the field in the table. In order to insert a segment with this function, the segment must be defined based on individual full fields, using what is known as record schema. See the c-tree Plus documentation for further information on record schemas. This function handles the segment handle allocation. Segment handle deallocation is automatically handled by ctdbCloseTable() and ctdbCloseAll().

Use ctdbInsSegmentByName() or ctdbInsSegmentByNbr() to insert a segment given the index number.Use ctdbAddSegment() to add a segment to an index. Use ctdbDelSegment() to delete a segment from an index.

After the segments, indexes, and fields have been defined, the table can be created or altered with ctdbCreateTable() or ctdbAlterTable().

Handle [in] the index handle.
SegNumber [in] the position to insert the new segment - insert the new segment before this segment number.
FieldHandle [in] the Field Handle.
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. ctdbInsSegmentEx() accepts any segment mode.

Returns

ctdbInsSegment() returns the new segment handle on success, or NULL on failure.

Example

pMyIndex = ctdbGetIndex(pMyTable, 0); // retrieve first index handle

pMyNewIseg = ctdbInsSegment(pMyIndex, 0, , CTSEG_ UREGSEG);

RetVal = ctdbAlterTable(pMyTable, 0);

See also

ctdbAddSegment(), ctdbDelSegment(), ctdbInsSegmentByName(), ctdbInsSegmentByNbr(), ctdbInsSegmentEx()

ctdbInsSegmentByName

Insert a segment before the segment indicated by SegNumber, given the field name.

Declaration

CTHANDLE ctdbInsSegmentByName(CTHANDLE Handle, NINT IndexNbr, NINT SegNumber,

pTEXT FieldName, CTSEG_MODE SegMode)

Description

ctdbInsSegmentByName() inserts a new segment index before the segment indicated by SegNumber, given the index number and the field name. The operation of inserting a segment links the index with the field in the table. In order to insert a segment with this function, the segment must be defined based on individual full fields, using what is known as record schema. See the c-tree Plus documentation for further information on record schemas. This function handles the segment handle allocation. Segment 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().

Handle [in] the Table Handle.
IndexNbr [in] the Index number.
SegNumber [in] the segment before which the new segment will be inserted.
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. ctdbInsSegmentEx() accepts any segment mode.

Returns

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

Example

pMyNewIseg = ctdbInsSegmentByNbr(pMyTable,0,0,Balance,CTSEG_ REGSEG);

RetVal = ctdbAlterTable(pMyTable, 0);

See also

ctdbInsSegment(), ctdbInsSegmentByNbr(), ctdbInsSegmentEx()

ctdbInsSegmentByNbr

Insert a segment before the segment indicated by SegNumber, given the field and index numbers.

Declaration

CTHANDLE ctdbInsSegmentByNbr(CTHANDLE Handle, NINT IndexNbr,

NINT SegNumber, NINT FieldNbr, CTSEG_MODE SegMode)

Description

ctdbInsSegmentByNbr() inserts a segment before the segment indicated by SegNumber, given the index and field numbers. The operation of inserting a segment links the index with the field in the table. In order to insert a segment with this function, the segment must be defined based on individual full fields, using what is known as record schema. See the c-tree Plus documentation for further information on record schemas. This function handles the segment handle allocation. Segment 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().

Handle [in] the Table Handle.
IndexNbr [in] the Index number.
SegNumber [in] the segment before which the new segment will be inserted.
FieldNbr [in] the Field number.
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. ctdbInsSegmentEx() accepts any segment mode.

Returns

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

Example

pMyNewIseg = ctdbInsSegmentByNbr(pMyTable, 0, 0, 1, CTSEG_ REGSEG);

RetVal = ctdbAlterTable(pMyTable, 0);

See also

ctdbInsSegmentByName(), ctdbInsSegment(), ctdbInsSegmentEx()

ctdbInsSegmentEx

Insert a new extended index segment before the segment indicated.

Declaration

CTHANDLE ctdbInsSegmentEx(CTHANDLE Handle, NINT SegNumber, NINT offset,

NINT length, CTSEG_MODE SegMode)

Description

ctdbInsSegmentEx() inserts a new extended index segment before the segment SegNumber. A segment is denominated extended if it is based on the segment offset. This function handles the segment handle allocation. Segment 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().

Handle [in] the index handle.
SegNumber [in] the segment number before which we should insert the new segment.
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 Section FairCom DB API definitions. Notice that ctdbInsSegmentEx() does work with Absolute byte offset segments.

Returns

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

Example

pMyIndex = ctdbGetIndex(pMyTable, 0); // retrieve first index handle

pMyNewIseg = ctdbInsSegmentEx(pMyIndex, 0, 32, 4, CTSEG_ UREGSEG);

RetVal = ctdbAlterTable(pMyTable, 0);

See also

ctdbInsSegmentByName(), ctdbInsSegment(), ctdbInsSegmentByNbr(), ctdbAddSegmentEx()

ctdbIsActiveDatabase

Retrieve the active state of a database.

Declaration

CTBOOL ctdbIsActiveDatabase(CTHANDLE Handle)

Description

ctdbIsActiveDatabase() retrieves the active state of a database, connected or disconnected. A database is active when it is connected. To connect the database, use ctdbConnect().

Handle [in] the Database Handle.

Returns

ctdbIsActiveDatabase() returns YES if the database is connected and NO if the database is disconnected.

See also

ctdbAllocDatabase(), ctdbIsActiveSession(), ctdbIsActiveTable(), ctdbConnect()

ctdbIsActiveSession

Check if a session is active. A session is active when the session handle has been allocated and the session is logged in to the server.

Declaration

CTBOOL ctdbIsActiveSession(CTHANDLE Handle)

Description

ctdbIsActiveSession() checks to see if a session is active. A session is defined as active when the session handle has been allocated by ctdbAllocSession() and the session is logged in to the server with ctdbLogon().

Handle [in] the session handle.

Returns

ctdbIsActiveSession() returns YES if the session is active and NO otherwise.

Example

act=ctdbIsActiveSession(hSession);

if (act)

printf("\n\nThe server is active.\n");

else

{

printf("\n\nThe Session is not active. Logon first.\n");

ctdbLogon(hSession, "FAIRCOMS", "ADMIN", "ADMIN");

}

See also

ctdbLogon(), ctdbAllocSession(), ctdbIsActiveDatabase(), ctdbIsActiveTable()

ctdbIsActiveTable

Retrieve the active state of a table.

Declaration

CTBOOL ctdbIsActiveTable(CTHANDLE Handle)

Description

ctdbIsActiveTable() retrieves the active state of a table. A table is active if it is open.

Handle [in] the Table Handle.

Returns

ctdbIsActiveTable() returns YES if the table is open and NO otherwise.

See also

ctdbAllocTable(), ctdbFreeTable(), ctdbIsActiveSession(), ctdbIsActiveDatabase()

ctdbIsDatabaseExclusive (See Batch Operations)

ctdbIsEditedRecord

Retrieve the edited record flag.

Declaration

CTBOOL ctdbIsEditedRecord(CTHANDLE Handle)

Description

ctdbIsEditedRecord() retrieves the edited record flag. If YES, the record has been edited since it has been read from the table. Functions like ctdbSetFieldAsString() and all other ctdbSetFieldAs...() functions set the edited record flag to YES. Functions like ctdbAllocRecord(), ctdbClearRecord(), ctdbResetRecord(), ctdbFindRecord() and other search functions clear the edited record flag. Use ctdbIsNewRecord() to check the new record flag.

Handle [in] the record handle.

Returns

ctdbIsEditedRecord() returns the edited record flag.

See also

ctdbAllocRecord(), ctdbIsNewRecord()

ctdbIsExtSegment

Check if the segment mode is one of the extended modes.

Declaration

CTBOOL ctdbIsExtSegment(CTSEG_MODE SegMode)

Description

ctdbIsExtSegment() checks to see if the segment mode is one of the extended modes. Extended segments must have been added to the index with ctdbAddSegmentEx().

SegMode [in] the segment mode.

Returns

ctdbIsExtSegment() returns YES if the segment mode is extended, NO otherwise.

See also

ctdbAddSegmentEx()

ctdbIsFieldDefaultValueSet (See Batch Operations)

ctdbIsFieldNumeric

Indicate if a field represents a numeric field type.

Declaration

CTBOOL ctdbIsFieldNumeric(CTHANDLE Handle)

Description

ctdbIsFieldNumeric() indicates if the field handle represents a field with a numeric value. The numeric field types are: CT_CHAR, CT_CHARU, CT_INT2, CT_INT2U, CT_INT4, CT_INT4U, CT_DATE, CT_TIME, CT_MONEY, CT_TIMES, CT_SFLOAT, CT_DFLOAT, CT_EFLOAT, CT_CURRENCY, CT_NUMBER, and CT_INT8.

Handle [in] a Field Handle.

Returns

ctdbIsFieldNumeric() returns YES if the field represents a numeric value and NO if the field does not represent a numeric value

Example

/* if fields hField1 and hField2 are numeric, add the values and store the result in hField1 */

if (ctdbIsFieldNumeric(hField1) && ctdbIsFieldNumeric(hField2))

{

CTNUMBER res, val1, val2;

ctdbGetFieldAsNumber(hRecord, ctdbGetFieldNbr(hField1), &val1);

ctdbGetFieldAsNumber(hRecord, ctdbGetFieldNbr(hField2), &val2);

ctdbNumberAdd(&val1, &val2, &res);

ctdbSetFieldAsNumber(hRecord, ctdbGetFieldNbr(hField1), &res);

}

See also

ctdbGetFieldNbr(), ctdbGetFieldProperties()

ctdbIsNewRecord

Retrieve the new record flag.

Declaration

CTBOOL ctdbIsNewRecord(CTHANDLE Handle)

Description

ctdbIsNewRecord() retrieves the new record flag. The new record flag is set to YES by functions like ctdbAllocRecord(), ctdbClearRecord(), ctdbDeleteRecord(). Functions like ctdbFindRecord(), ctdbWriteRecord() set the new record flag to NO. Use ctdbIsEditedRecord() to check the edited record flag.

Handle [in] the record handle.

Returns

ctdbIsNewRecord() returns the new record flag.

See also

ctdbAllocRecord(), ctdbIsEditedRecord()

ctdbIsNullField

Check if the contents of a field are null.

Declaration

CTBOOL ctdbIsNullField(CTHANDLE Handle, NINT FieldNbr)

Description

ctdbIsNullField() checks to see if the contents of a field are null.

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

Note: this function looks at a single field in a single record/row.

Returns

ctdbIsNullField() returns YES if the field is NULL, or NO if the field is not NULL.

See also

ctdbHasNullFieldSupport(), ctdbGetFieldNullFlag(), ctdbClearField

To read/write the "NOT NULL" attribute of a column in the SQL layer, see ctdbGetFieldNullFlag and, see ctdbSetFieldNullFlag

ctdbIsRecordRangeOn

Indicate if an index range operation is active for this record handle.

Declaration

CTBOOL ctdbIsRecordRangeOn(CTHANDLE Handle);

Description

ctdbIsRecordRangeOn() returns YES if a index range operation is active for this record handle, or NO is no index range is active.

Handle is a record handle.

Return

Value	Symbolic Constant	Explanation
0	NO	No index range operation is active
1	YES	Index range operation is active

See FairCom DB API Errors and Return Values for a complete listing of valid FairCom DB API error codes and return values.

Example

/* display all records where age is greater than 65 */

void DisplayAll(CTHANDLE hRecord)

{

UTEXT lRange[32];

VRLEN lRangeLen = 32;

NINT op[1] = {CTIX_GT};

NINT fldno = ctdbGetFieldNumberByName(hHandle, "age");

CTDBRET eRet;

ctdbClearRecord(hRecord);

ctdbSetFieldAsSigned(hRecord, fldno, 65);

ctdbSetDefaultIndex(hRecord, 0);

ctdbBuildTargetKey(hRecord, CTFIND_EQ, lRange, &lRangeLen);

eRet = ctdbRecordRangeOn(hRecord, 1, lRange, NULL, op);

if (eRet == CTDBRET_OK)

{

eRet = ctdbFirstRecord(hRecord);

while (eRet == CTDBRET_OK)

{

TEXT str[128];

ctdbGetFieldAsString(hRecord, 0, str, sizeof(str));

printf("%s\n", str);

eRet = ctdbNextRecord(hRecord);

}

if (ctdbIsRecordRangeOn(hRecord))

ctdbRecordRangeOff(hRecord);

}

See also

ctdbRecordRangeOn(), ctdbRecordRangeOff()

ctdbIsRecordSetOn

Declaration

CTBOOL ctdbDECL ctdbIsRecordSetOn(CTHANDLE Handle);

Description

Indicates if record set is active or not. A record set is active after a successful call to ctdbRecordSetOn(). A record set can be switched off by calling ctdbRecordSetOff().

Handle must be a record handle.

Return Values

Returns YES if a record set if active and NO if a record set is not active.

See Also

ctdbRecordSetOn(), ctdbRecordSetOff()

ctdbIsVariableField

Indicate if a field is allocated in the variable portion of the record.

Declaration

CTBOOL ctdbIsVariableField(CTHANDLE Handle, NINT FieldNbr)

Description

ctdbIsVariableField() Indicates if a field, represented by the field number, is allocated in the variable portion of the record.

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

Returns

ctdbIsVariableField() returns YES if the field is allocated in the variable portion of the record, NO otherwise.

ctdbLogon

Log on to FairCom Server or FairCom DB instance session.

Declaration

CTDBRET ctdbLogon(CTHANDLE Handle, pTEXT dbengine, pTEXT userid,

pTEXT password)

Description

ctdbLogon() logs on to the c-tree Server or FairCom DB instance. Before any database operation can take place, initiate a session with ctdbAllocSession() and then logon to the c-tree Server or c-tree Plus instance using ctdbLogon() before calling ctdbAllocDatabase().

Before logon to the c-tree Server or a FairCom DB instance, it is necessary to have a session dictionary. To create a session dictionary, use the function ctdbCreateSession().

Handle [in] the session handle.
dbengine [in] the string with the c-tree Server name or FairCom DB instance name. If dbengine is NULL ctdbLogon() uses the string "FAIRCOMS" as the default server name or c-tree Plus instance.
userid [in] the string with the user name. If userid is NULL ctdbLogon() uses the string " " as the default user name.
password [in] the string with the user password. If password is NULL ctdbLogon() uses the string " " as the default user password.

To logout from the c-tree Server or FairCom DB instance, use the ctdbLogout() function.

Returns

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

Example

CTSESSION_TYPE ctdbsess=CTSESSION_CTDB;

CTHANDLE hSession = ctdbAllocSession(ctdbsess);

CTDBRET err;

err = ctdbLogon(hSession, "FAIRCOMS", "ADMIN", "ADMIN");

err = ctdbCreateDatabase(hSession, "MyDatabase", "");

err = ctdbLogout(hSession);

ctdbFreeSession(hSession);

See also

ctdbLogout(), ctdbAllocDatabase(), ctdbCreateSession(), ctdbIsActiveSession()

ctdbLogout

Logout from a FairCom Server session or from a FairCom DB instance.

Declaration

CTDBRET ctdbLogout(CTHANDLE Handle)

Description

ctdbLogout() logs out from the c-tree Server or FairCom DB instance.

Handle [in] the session handle.

Returns

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

Example

CTSESSION_TYPE ctdbsess=CTSESSION_CTDB;

CTHANDLE hSession = ctdbAllocSession(ctdbsess);

CTDBRET err;

err = ctdbLogon(hSession, "FAIRCOMS", "ADMIN", "ADMIN");

err = ctdbCreateDatabase(hSession, "MyDatabase", "");

err = ctdbLogout(hSession);

ctdbFreeSession(hSession);

See also

ctdbLogon(), ctdbAllocSession()

ctdbMoveField

Move a field to another location.

Declaration

CTDBRET ctdbMoveField(CTHANDLE Handle, NINT newIndex)

Description

ctdbMoveField() moves the field to a new location.

Handle [in] the field handle of the field that is being moved.
newIndex [in] Index of the new location of the field.

Returns

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

See also

ctdbAllocTable(), ctdbAddField(), ctdbInsField(), ctdbDelField()

ctdbNextDatabase

Get the name and path of the next database in this session dictionary.

Declaration

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

pTEXT Path, VRLEN PathSize)

Description

ctdbNextDatabase() gets the name and path of the next database in this session dictionary.

Handle [in] the session handle.
Name [out] receives the database name.
NameSize [in] Name size in bytes. If Name is not large enough to receive the database name, ctdbNextDatabase() will return CTDBRET_ARGSMALL (4006).
Path [out] receives the database path, if the name is located and it is large enough to hold the path.
PathSize [in] Path size in bytes. If Path is not large enough to receive the database path, ctdbNextDatabase() will return CTDBRET_ARGSMALL (4006).

Use ctdbNextDatabase() with ctdbFirstDatabase() to obtain the names and paths of all the databases that are in this session dictionary. Use ctdbGetDatabaseCount() to retrieve the total number of databases in the session dictionary.

Returns

ctdbNextDatabase() returns CTDBRET_OK on success, or INOT_ERR (101) after the last database in the session dictionary has been retrieved, or a c-tree error code on failure.

Example

ctdbFirstDatabase(hSession, name, sizeof(name), path, sizeof(path));

do {

printf("\n\nDatabase: %s (%s)\n", path, name);

}

while (

ctdbNextDatabase(hSession, name, sizeof(name), path, sizeof(path))

== CTDBRET_OK );

See also

ctdbFirstDatabase(), ctdbFindDatabase(), ctdbGetDatabaseCount()

ctdbNextTable

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

Declaration

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

pTEXT Path, VRLEN PathSize)

Description

ctdbNextTable gets the name and the path of the next 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.

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

Returns

ctdbNextTable() returns CTDBRET_OK on success, or the c-tree error code on failure. Note that INOT_ERR (101) is returned after the last table in the database dictionary has been retrieved.

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

ctdbFirstTable(), ctdbFindTable(), ctdbGetTableCount()

ctdbSetDefaultIndex

Set the number of the new default index.

Declaration

CTDBRET ctdbSetDefaultIndex(CTHANDLE Handle, NINT indexno)

Description

ctdbSetDefaultIndex() sets the number of the new default index. Use ctdbGetDefaultIndex() to retrieve the table default index. Initially, the default index is the first index created during the table definition.

To force a physical data table traversal without using any indexes, specify the following constant:

CTDB_DATA_IDXNO

If not disabled during the table creation, two default indexes are created during the table definition, besides the indexes defined by the user. These indexes may be used to sort the table, and they are:

ROWID - this unique index represents the ordering of the table by input order. To set this index as the default, the Index parameter should be set to CTDB_ROWID_IDXNO;
RECBYT - this index represents the offset of the record inside the table. It is used internally to improve backward physical traversal of variable-length records. To set this index as the default, the Index parameter should be set to CTDB_RECBYT_IDXNO.

See the discussion on Hidden fields regarding these two indexes.

Use ctdbSetDefaultIndexByName() to set the table default index by name.

Handle [in] the record handle.
Index [in] the index number to be set as default.

Returns

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

See also

ctdbAllocRecord(), ctdbSetTableDefaultIndexExtentSize(), ctdbGetDefaultIndex(), ctdbSetDefaultIndexByName()

ctdbSetDefaultIndexByName

Set the default index by its name

Declaration

CTDBRET ctdbSetDefaultIndexByName(CTHANDLE Handle, pTEXT name)

Description

ctdbSetDefaultIndexByName() sets the default index by its name. See the discussion on the default index presented in the ctdbSetDefaultIndex() function. Use ctdbGetDefaultIndexName() to retrieve the table default index name. Use ctdbSetDefaultIndex() to set the table default index by number.

Handle [in] the record handle.
name [in] the index name to be set as default.

Returns

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

See also

ctdbAllocRecord(), ctdbGetDefaultIndexName(), ctdbSetDefaultIndex()

ctdbSetEditedRecord

Set the record changed flag.

Declaration

CTDBRET ctdbSetNewRecord(CTHANDLE Handle, CTBOOL flag)

Description

ctdbSetEditedRecord() sets the the record changed flag.

Handle [in] the Session Handle.
flag [in] record changed flag value.

Returns

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

See also

ctdbSetNewRecord()

ctdbSetFieldAsBigint

Set field as big integer value.

Declaration

CTDBRET ctdbSetFieldAsBigint(CTHANDLE Handle, NINT FieldNbr,

CTBIGINT Value)

Description

ctdbSetFieldAsBigint() sets a field as big integer. Use ctdbGetFieldAsBigint() to retrieve a field as a big integer value.

Handle [in] the record handle.
FieldNbr [in] the field number to be set. To retrieve the field number given the field name, use ctdbGetFieldNumberByName().
Value [in] the big integer value to set to the field.

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetFieldAsBigint(), ctdbGetFieldNumberByName()

ctdbSetFieldAsBinary

Set field as binary value.

Declaration

CTDBRET ctdbSetFieldAsBinary(CTHANDLE Handle, NINT FieldNbr,

pVOID pValue, VRLEN size)

Description

ctdbSetFieldAsBinary() sets a field as binary. Use ctdbGetFieldAsBinary() to retrieve a field as a binary value.

Handle [in] the record handle.
FieldNbr [in] the field number to be set. To retrieve the field number given the field name, use ctdbGetFieldNumberByName().
pValue [in] the pointer to the binary value to set to the field.
size [in] pValue size in bytes.

Truncation of Values (behavior before V12.5)

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

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetFieldAsBinary(), ctdbGetFieldNumberByName()

ctdbSetFieldAsBlob

Set field as CTBLOB type value.

Declaration

CTDBRET ctdbSetFieldAsBlob(CTHANDLE Handle, NINT FieldNbr,

pCTBLOB pValue)

Description

ctdbSetFieldAsBlob() sets a field as CTBLOB type value. Use ctdbGetFieldAsBlob() to retrieve a field as CTBLOB.

Handle [in] the record handle.
FieldNbr [in] the field number to be set. To retrieve the field number given the field name, use ctdbGetFieldNumberByName().
pValue [in] the pointer to the CTBLOB value to set to the fiel

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:

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetFieldAsBlob()

ctdbSetFieldAsBool

Set field as CTBOOL type value.

Declaration

CTDBRET ctdbSetFieldAsBool(CTHANDLE Handle, NINT FieldNbr,

CTBOOL Value)

Description

ctdbSetFieldAsBool() sets a field as CTBOOL type value. Use ctdbGetFieldAsBool() to retrieve a field as CTBOOL.

Handle [in] the record handle.
FieldNbr [in] the field number to be set. To retrieve the field number given the field name, use ctdbGetFieldNumberByName().
Value [in] the CTBOOL value to set to the field.

Truncation of Values (behavior before V12.5)

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

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetFieldAsBool(), ctdbGetFieldNumber()

ctdbSetFieldAsCurrency

Set field as a currency value.

Declaration

CTDBRET ctdbSetFieldAsCurrency(CTHANDLE Handle, NINT FieldNbr,

CTCURRENCY Value)

Description

ctdbSetFieldAsCurrency() sets a field as currency value. Use ctdbGetFieldAsCurrency() to retrieve a field as a currency value.

Handle [in] the record handle.
FieldNbr [in] the field number to be set. To retrieve the field number given the field name, use ctdbGetFieldNumberByName().
Value [in] the currency value.

Truncation of Values (behavior before V12.5)

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

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetFieldNumberByName(), ctdbGetFieldAsCurrency()

ctdbSetFieldAsDate

Set field as CTDATE type value.

Declaration

CTDBRET ctdbSetFieldAsDate(CTHANDLE Handle, NINT FieldNbr,

CTDATE Value)

Description

ctdbSetFieldAsDate() sets a field as CTDATE type value. Use ctdbGetFieldAsDate() to retrieve a field as CTDATE.

Handle [in] the record handle.
FieldNbr [in] the field number to be set. To retrieve the field number given the field name, use ctdbGetFieldNumberByName().
Value [in] the CTDATE value to set to the field.

Truncation of Values (behavior before V12.5)

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

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetFieldAsDate(), ctdbGetFieldNumberByName()

ctdbSetFieldAsDateTime

Set field as CTDATETIME type value.

Declaration

CTDBRET ctdbSetFieldAsDateTime(CTHANDLE Handle, NINT FieldNbr,

CTDATETIME value)

Description

ctdbSetFieldAsDateTime() sets a field as CTDATETIME type value. Use ctdbGetFieldAsDateTime() to retrieve a field as CTDATETIME.

Handle [in] the record handle.
FieldNbr [in] the field number to be set. To retrieve the field number given the field name, use ctdbGetFieldNumberByName().
Value [in] the CTDATETIME value to set to the field.

Truncation of Values (behavior before V12.5)

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

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetFieldAsDateTime(), ctdbGetFieldNumber()

ctdbSetFieldAsFloat

Set field as CTFLOAT type value.

Declaration

CTDBRET ctdbSetFieldAsFloat(CTHANDLE Handle, NINT FieldNbr,

CTFLOAT Value)

Description

ctdbSetFieldAsFloat() sets a field as CTFLOAT type value. Use ctdbGetFieldAsFloat() to retrieve a field as CTFLOAT.

Handle [in] the record handle.
FieldNbr [in] the field number to be set. To retrieve the field number given the field name, use ctdbGetFieldNumberByName().
Value [in] the CTFLOAT value to set to the field.

Truncation of Values (behavior before V12.5)

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

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

Returns

ctdbSetFieldAsFloat returns CTDBRET_OK if successful, or the c-tree error code on failure.

See also

ctdbAllocRecord(), ctdbGetFieldAsFloat(), ctdbGetFieldNumber()

ctdbSetFieldAsJSON

Set the field as a CTJSON type value.

Declaration

ctdbEXPORT CTDBRET ctdbDECL ctdbSetFieldAsJSON(CTHANDLE Handle, NINT FieldNbr, CTJSON Value);

Description

Handle [IN] - CTDB C API record handle
FieldNbr [IN] - The field number
Value [IN] - CTJSON type value to set the field

Returns

Return CTDBRET_OK on success.

ctdbSetFieldAsMoney

Set field as CTMONEY type value.

Declaration

CTDBRET ctdbSetFieldAsMoney(CTHANDLE Handle, NINT FieldNbr,

CTMONEY Value)

Description

ctdbSetFieldAsMoney() sets a field as CTMONEY type value. Use ctdbGetFieldAsMoney() to retrieve a field as CTMONEY.

Handle [in] the record handle.
FieldNbr [in] the field number to be set. To retrieve the field number given the field name, use ctdbGetFieldNumberByName().
Value [in] the CTMONEY value to set to the field.

Truncation of Values (behavior before V12.5)

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

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetFieldAsMoney(), ctdbGetFieldNumber()

ctdbSetFieldAsNumber

Set field as a number value.

Declaration

CTDBRET ctdbSetFieldAsNumber(CTHANDLE Handle, NINT FieldNbr,

pCTNUMBER pValue)

Description

ctdbSetFieldAsNumber() set field as number. Use ctdbGetFieldAsNumber() to retrieve a field as a number value.

Handle [in] the record handle.
FieldNbr [in] the field number to be set. To retrieve the field number given the field name, use ctdbGetFieldNumberByName().
pValue [in] the pointer to the number value to set to the field.

Truncation of Values (behavior before V12.5)

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

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetFieldAsNumber()

ctdbSetFieldAsSigned

Set field as CTSIGNED type value.

Declaration

CTDBRET ctdbSetFieldAsSigned(CTHANDLE Handle, NINT FieldNbr,

CTSIGNED Value)

Description

ctdbSetFieldAsSigned() sets a field as CTSIGNED type value. Use ctdbGetFieldAsSigned() to retrieve a field as CTSIGNED.

Handle [in] the record handle.
FieldNbr [in] the field number to be set. To retrieve the field number given the field name, use ctdbGetFieldNumberByName().
Value [in] the CTSIGNED value to set to the field.

Truncation of Values (behavior before V12.5)

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

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetFieldNumber()

ctdbSetFieldAsString

Set field as CTSTRING type value.

Declaration

CTDBRET ctdbSetFieldAsString(CTHANDLE Handle, NINT FieldNbr,

CTSTRING Value)

Description

ctdbSetFieldAsString() sets a field as CTSTRING type value. To set a CT_BOOL field, the value being set must be equal to "TRUE" or "FALSE", case insensitive, otherwise, the function will return CTDBRET_CANTCONVERT (4042). Use ctdbGetFieldAsString() to retrieve a field as CTSTRING.

Handle [in] the record handle.
FieldNbr [in] the field number to be set. To retrieve the field number given the field name, use ctdbGetFieldNumberByName().
Value [in] the CTSTRING value to set to the field.

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:

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

Returns

ctdbSetFieldAsString() returns CTDBRET_OK if successful, or the c-tree error code on failure. Error CTDBRET_CANTCONVERT (4042) indicate Value can't be converted to the specified field type.

See also

ctdbAllocRecord(), ctdbGetFieldAsString(), ctdbGetFieldNumber()

ctdbSetFieldAsTime

Set field as CTTIME type value with whole second precision.

NOTE: See ctdbSetFieldAsTimeMsec() if you need millisecond precision.

Declaration

CTDBRET ctdbSetFieldAsTime(CTHANDLE Handle, NINT FieldNbr,

CTTIME Value)

Description

ctdbSetFieldAsTime() sets a field as CTTIME type value. Use ctdbGetFieldAsTime() to retrieve a field as CTTIME. The default time format to set a time field is CTTIME_HMP (HH:MM am/pm). To modify it, use ctdbSetDefTimeType().

Handle [in] the record handle.
FieldNbr [in] the field number to be set. To retrieve the field number given the field name, use ctdbGetFieldNumberByName().
Value [in] the CTTIME value to set to the field.

Truncation of Values (behavior before V12.5)

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

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetFieldAsTime(), ctdbGetFieldNumber(), ctdbGetFieldAsTimeMsec(), ctdbSetFieldAsTimeMsec()

ctdbSetFieldAsTimeMsec

Set a field as a CTTIMEMS type value with millisecond precision.

NOTE: See ctdbSetFieldAsTime() if you don't need millisecond precision.

Declaration

CTDBRET ctdbDECL ctdbSetFieldAsTimeMsec(CTHANDLE Handle, NINT FieldNbr, CTTIMEMS value)

Parameters:

Handle [IN] - CTDB C API record handle
FieldNbr [IN] - Field number
value [IN] - CTTIMEMS type value

Description

ctdbSetFieldAsTimeMsec() sets a field as a CTTIMEMS type value. This allows it to support milliseconds.

Return Values

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	Successful operation.

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

ctdbSetFieldAsUnsigned

Set field as CTUNSIGNED type value.

Declaration

CTDBRET ctdbSetFieldAsUnsigned(CTHANDLE Handle, NINT FieldNbr,

CTUNSIGNED Value)

Description

ctdbSetFieldAsUnsigned() sets a field as CTUNSIGNED type value. Use ctdbGetFieldAsUnsigned() to retrieve a field as CTUNSIGNED.

Handle [in] the record handle.
FieldNbr [in] the field number to be set. To retrieve the field number given the field name, use ctdbGetFieldNumberByName().
Value [in] the CTUNSIGNED value to set to the field.

Truncation of Values (behavior before V12.5)

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

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetFieldAsUnsigned(), ctdbGetFieldNumber()

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:

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

ctdbSetFieldAutoSysTime

Set field attributes for automatic time/datetime assignment. If both create and update are set to NO automatic assignment is disabled.

Declaration

CTDBRET ctdbDECL ctdbSetFieldAutoSysTime(CTHANDLE Handle, CTBOOL create, CTBOOL update)

Description

If both create and update are set to NO, the automatic assignment is turned off.

Handle [IN] - Field handle
create [IN] - the field value is assigned on write of new records
update [IN] - the field value is assigned on write of existing records

Returns

CTDBRET_OK on success or c-tree error code on failure.

Example

CTDBRET Retval = CTDBRET_OK;

CTHANDLE pField1;

Retval = ctdbSetFieldAutoSysTime(pField1, YES, NO);

if (Retval)

{

ctrt_printf("Error: ctdbSetFieldAutoSysTime(1) failed:%d\n", Retval);

goto err_ret;

}

ctdbSetFieldLength

Set the field length in the table definition.

Declaration

CTDBRET ctdbSetFieldLength(CTHANDLE Handle, VRLEN len)

Description

ctdbSetFieldLength() sets the field length in the table definition. This affects the entire column of the table: it is not manipulating a field from a single record (row) of the table. Use ctdbGetFieldLength() or ctdbGetFieldSize() to retrieve the field length from the table definition. Use ctdbSetFieldProperties() to set the field length, type, and name.

Handle [in] the Field Handle.

len [in] the field length. 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

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

See also

ctdbGetFieldLength(), ctdbSetFieldProperties

ctdbSetFieldName

Change the field name

Declaration

CTDBRET ctdbSetFieldName(CTHANDLE Handle, pTEXT name)

Description

ctdbSetFieldName() changes the field name. Use ctdbGetFieldName() to retrieve the field name.

Handle [in] the Field Handle.
name [in] the new field name.

Returns

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

See also

ctdbGetFieldName()

ctdbSetFieldNullFlag

Enable or disable the SQL “NOT NULL” property of this field's column, in order to control whether the SQL layer will allow NULL values to be written to fields in this column or not.

Declaration

CTDBRET ctdbSetFieldNullFlag(CTHANDLE Handle, CTBOOL flag)

Description

Handle [in] the Field Handle which specifies the column to change.
flag [in] the null flag value.

The FairCom DB API null flag controls the NOT NULL property of a column. Setting this column property has no effect on individual record null values: it is NOT enforced at the FairCom DB API layer. This attribute only applies to the FairCom DB SQL layer for constraint on values. It is useful to set this flag in c-tree data files before SQL import such that the property is maintained.

Note: this is a schema change for an entire column and has nothing to do with individual records from the table. See ctdbIsNullField and ctdbClearField to edit NULL values of single fields in single records. This schema change works as follows: a TRUE Null Flag sets / enables the SQL “NOT NULL” property of the column, which means that that column is not allowed to have NULL values. A FALSE Null Flag disables the SQL “NOT NULL” property of the column, which means that that column is allowed to have NULL values.

Returns

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

See also

ctdbGetFieldNullFlag()

ctdbSetFieldPrecision

Set the field precision.

Declaration

CTDBRET ctdbSetFieldPrecision(CTHANDLE Handle, NINT fprec)

Description

ctdbSetFieldPrecision() sets the field precision (maximum number of digits).

Handle [in] the Field Handle.
fprec [in] the field precision.

Returns

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

See also

ctdbGetFieldPrecision()

ctdbSetFieldProperties

Set field properties such as name, type and length.

Declaration

CTDBRET ctdbSetFieldProperties(CTHANDLE Handle, pTEXT FieldName,

CTDBTYPE Type, VRLEN Length)

Description

ctdbSetFieldProperties() sets field properties such as name, type, and length from the table definition. Use ctdbGetFieldProperties() to retrieve the field properties.

Handle [in] the Field Handle.
FieldName [in] the field name.
Type [in] the field type. Available types are listed in the left-hand column ("FairCom DB API Field Type") in Field Types.

Length [in] the field length. 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

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

See also

ctdbAllocTable(), ctdbGetFieldProperties()

ctdbSetFieldScale

Set the field scale.

Declaration

CTDBRET ctdbSetFieldScale(CTHANDLE Handle, NINT fscale)

Description

ctdbSetFieldScale() sets the field scale (the number of digits to the right of the decimal point).

Handle [in] the Field Handle.
fscale [in] the field scale.

Returns

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

See also

ctdbGetFieldScale()

ctdbSetFieldStringEncoding

Set the field string encoding.

CTDBRET ctdbDECL ctdbSetFieldStringEncoding( CTHANDLE Handle, pTEXT encoding )

Parameters:

Handle [IN] - A FairCom DB API associated field handle
encoding [IN] - A string describing the encoding used for the field content. FairCom DB API does not enforce any check on the value passed in, however, JTDB, JDBC, ADO.Net providers and SQL expect to be able to identify the encoding therefore you must use values as defined by IANA.org.

Returns:

Returns the encoding set on the field on success or a FairCom DB API error on failure.

Calling ctdbSetFieldStringEncoding() on a field type that is not a string field fails with error CTDBRET_INVTYPE.

ctdbSetFieldType

Sets the field type

Declaration

CTDBRET ctdbSetFieldType(CTHANDLE Handle, CTDBTYPE type);

Description

ctdbSetFieldType() sets the field type. Use ctdbGetFieldType() to retrieve the field type.

Handle [in] the Field Handle.
type [in] the Field Type. Available types are listed in the left-hand column ("FairCom DB API Field Type") in Field Types.

Returns

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

See also

ctdbGetFieldType()

ctdbSetIndexDuplicateFlag

Set the allow duplicate flag for this index.

Declaration

CTDBRET ctdbSetIndexDuplicateFlag(CTHANDLE Handle, CTBOOL DupFlag)

Description

ctdbSetIndexDuplicateFlag() sets the allow duplicate key flag for this index. Use ctdbGetIndexDuplicateFlag() to retrieve the allow duplicate key flag for the desired index.

Handle [in] the index handle.
DupFlag [in] the flag to indicate if duplicates are allowed.

Returns

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

See also

ctdbAllocIndex(), ctdbGetIndexDuplicateFlag()

ctdbSetIndexEmptyChar

Set the empty char property for the index

Declaration

CTDBRET ctdbSetIndexEmptyChar(CTHANDLE Handle, NINT EmptyChar)

Description

ctdbSetIndexEmptyChar() sets the empty char property for this index. Use ctdbGetIndexEmptyChar() to retrieve the empty char property for this index. The empty char property is expressed as the decimal equivalent of the ASCII table. For instance, an ASCII space is specified a value of 32, and NULL byte is specified as 0.

Handle [in] the index handle.
EmptyChar [in] the empty char value.

Returns

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

See also

ctdbAllocIndex(), ctdbGetIndexEmptyChar()

ctdbSetIndexExtension

Set table index file name extension

Declaration

CTDBRET ctdbSetIndexExtension(CTHANDLE Handle, cpTEXT ext)

Description

ctdbSetIndexExtension() sets the index table file name extension. The default value for the index extension is .idx. To retrieve the index table file name extension, use ctdbGetIndexExtension().

Handle [in] the Table Handle.
exit [in] the index table file name extension.

Returns

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

See also

ctdbAllocTable(), ctdbGetIndexExtension()

ctdbSetIndexKeyType

Set the index key type.

Declaration

CTDBRET ctdbSetIndexKeyType(CTHANDLE Handle, CTDBKEY KeyType)

Description

ctdbSetIndexKeyType() sets the key type for this index. Use ctdbAddIndex() to add an index to a table. Use ctdbGetIndexKeyType() to retrieve the Index key type. The valid key types are listed in FairCom DB API definitions.

Handle [in] the index handle.
KeyType [in] the key type. See the allowed values in FairCom DB API definitions.

Valid keytype values are:

CTINDEX_FIXED: Fixed-length key
CTINDEX_LEADING: Leading-character compression
CTINDEX_PADDING: Padding compression
CTINDEX_LEADPAD: Leading and padding compression

Note: Key compression imposes a significant performance impact, especially when deleting records. Use this feature only when absolutely necessary to keep index space requirements to a minimum.

In V11 and later, a new key type, CTINDEX_DFRIDX, has been added to indicate a deferred index.

Another new type, CTINDEX_NOMOD, was added to indicate an index with unmodifiable ISAM and FairCom DB API keys.

Returns

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

See also

ctdbAllocIndex(), ctdbGetIndexKeyType()

ctdbSetIndexName

Change the index name.

Declaration

CTDBRET ctdbSetIndexName(CTHANDLE Handle, pTEXT IndexName)

Description

ctdbSetIndexName() changes the index name. The index name can only be changed before the table is created. ctdbSetIndexName() will fail if the table is active.

Handle [in] the index handle.
IndexName [in] the new index name.

Returns

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

See also

ctdbCreateTable(), ctdbAddIndex()

ctdbSetIndexNullFlag

Set the null key flag for this index.

Declaration

CTDBRET ctdbSetIndexNullFlag(CTHANDLE Handle, CTBOOL NullFlag)

Description

ctdbSetIndexNullFlag() sets the null key flag for this index. Use ctdbGetIndexNullFlag() to retrieve the null key flag for the desired index.

Handle [in] the index handle.
NullFlag [in] the null key flag for this index.

Returns

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

See also

ctdbAllocIndex(), ctdbGetIndexNullFlag()

ctdbSetIndexTemporaryFlag

Set the temporary flag for this index

Declaration

CTDBRET ctdbSetIndexTemporaryFlag(CTHANDLE Handle, CTBOOL TempFlag)

Description

ctdbSetIndexTemporaryFlag() sets the temporary flag for this index. Use ctdbGetIndexTemporaryFlag() to retrieve the flag that indicates this index as temporary.

Handle [in] the index handle.
TempFlag [in] the temporary index flag.

Returns

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

See also

ctdbAllocIndex(), ctdbGetIndexTemporaryFlag()

ctdbSetJSONSegmentField

Change underlying JSON field segment properties.

Declaration

CTDBRET ctdbSetJSONSegmentField(CTHANDLE Handle, CTHANDLE field, pTEXT key, CTDBTYPE type, VRLEN size);

Description

Handle [IN] - Index handle
field [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

This function only applies to index segments based on a field handle setting it to a CT_JSON field.

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.

Returns

Return the segment handle on success or NULL on failure.

ctdbSetLocalTag

Sets the localTag pointer.

DECLARATION

CTDBRET ctdbSetLocalTag(CTHANDLE Handle, pVOID pTag);

DESCRIPTION

The local tag pointer, pTag, is a place holder for data storage specific to each callback type implementation. A callback function implementation may use this tag to store local data.

The localTag pointer is available for FairCom DB API session, database, table and record handles, and it is initialized with NULL when the handle is allocated.

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

if (ctdbSetLocalTag(Handle, pSession->onAlloc(1000)))

printf("ctdbSetLocalTag failed\n");

SEE ALSO

ctdbGetHandleType(), ctdbGetLocalTag()

ctdbSetLogonOnly

Set the session logon only flag.

Declaration

CTDBRET ctdbSetLogonOnly(CTHANDLE Handle, CTBOOL flag)

Description

ctdbSetLogonOnly() sets the session logon only flag. This flag, when set to YES before the session Logon, will prevent the session from using the session dictionary. If the session dictionary may not be used, the database dictionary cannot be used. With this, any information related to databases or tables cannot be use, but the tables can yet be opened or created using the session handle, as can be seen in the example below.

To retrieve the flag, use ctdbGetLogonOnly().

Handle [in] the Sesion Handle.
flag [in] logon only flag value.

Returns

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

Example

CTSESSION_TYPE ctdbsess=CTSESSION_CTDB;

CTHANDLE hSession = ctdbAllocSession(ctdbsess);

CTHANDLE hTable = ctdbAllocTable(hSession);

CTDBRET err;

err = ctdbSetLogonOnly(hSession, YES);

err = ctdbLogon(hSession, "FAIRCOMS", "ADMIN", "ADMIN");

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

err = ctdbLogout(hSession);

ctdbFreeTable(hTable);

ctdbFreeSession(hSession);

See also

ctdbGetLogonOnly(), ctdbLogon()

ctdbSetNewRecord

Set the new record flag.

Declaration

CTDBRET ctdbSetNewRecord(CTHANDLE Handle, CTBOOL flag)

Description

ctdbSetNewRecord() sets the new record flag.

Handle [in] the Sesion Handle.
flag [in] new record flag value.

Returns

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

See also

ctdbSetEditedRecord()

ctdbSetOperationState

Sets the c-tree operation modes for special performance-related functionality.

Declaration

CTDBRET ctdbDECL ctdbSetOperationState(CTHANDLE Handle, CTOPS_MODE mode, CTOPS_STATE state);

Description

ctdbSetOperationState() sets the c-tree operation modes for special performance-related functionality and test operational states for critical events.

Handle is a session handle.
mode uses a combination of the following values:

Operations Mode	Description
OPS_READLOCK	Enable automatic, low level, blocking read locks on each record access that does not already have a lock.
OPS_LOCKON_GET	Lock next fetch only.
OPS_UNLOCK_ADD	Automatic unlock on add.
OPS_UNLOCK_RWT	Automatic unlock on rewrite.
OPS_UNLOCK_UPD	(OPS_UNLOCK_ADD \| OPS_UNLOCK_RWT)
OPS_LOCKON_BLK	Blocking lock on next fetch only.
OPS_LOCKON_ADD_BLK	Enable blocking write lock mode during record add call then restore original lock mode.
OPS_FUNCTION_MON	Toggle function monitor. (Server)
OPS_LOCK_MON	Toggle lock monitor. (Server)
OPS_TRACK_MON	Toggle memory track monitor. (Server)
OPS_MIRROR_NOSWITCH	Don’t continue if mirror or primary fails. (Server)
OPS_MIRROR_TRM	A primary or mirror has been shutdown.
OPS_MEMORY_SWP	Memory swapping active.
OPS_AUTOISAM_TRN	Automatic ISAM transactions.
OPS_KEEPLOK_TRN	Keep locks involved in automatic transactions on record adds and updates after commit.
OPS_SERIAL_UPD	Changes GetSerialNbr() operation.
OPS_DEFER_CLOSE	Defer file closes or deletes during transactions.
OPS_CONV_STRING	Change all CT_STRING fields having a non-zero field length in the fixed length portion of the record buffer to CT_FSTRING fields. (Client)
OPS_DISK_IO	Set sysiocod on disk reads and writes.

state must be set with one of the following state values:

Operation State	Description
OPS_STATE_OFF	Turn a status bit off.
OPS_STATE_SET	Set the entire status word.
OPS_STATE_ON	Turn a status bit on.
OPS_STATE_RET	Return the entire status word.

ctdbSetOperationState() returns CTDBRET_OK on success.

Return Values

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	No error occurred.

See Also

ctdbGetOperationState() ctdbGetAutoCommit() ctdbSetAutoCommit()

ctdbSetPathPrefix

Set the client-side path prefix.

Declaration

CTDBRET ctdbSetPathPrefix(CTHANDLE hSession, pTEXT pathPrefix);

Description

A path prefix can be set anytime after the session handle is allocated. If a path prefix is set before a session logon, the new path prefix will affect the location of the session dictionary file. If a path prefix is set after a session logon, but before a database connect, then the path prefix affects only the database dictionary and any tables that are manipulated during that session.

A path prefix can be removed at any time by setting a NULL value for the path prefix. You can use ctdbGetPathPrefix() to check if a path prefix is set or not. If ctdbGetPathPrefix() returns NULL, then no path prefix is set.

Return

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	ctdbSetPathPrefix() returns CTDBRET_OK on success or FairCom DB API SDK error code on failure.

See FairCom DB API Errors and Return Values for a complete listing of valid FairCom DB API error codes and return values.

Example

/* set the current path prefix */

if (ctdbSetPathPrefix(AnyHandle, "c:\myDirectory") != CTDBRET_OK)

printf("ctdbSetPathPrefix() failed\n");

/* clear the current path prefix */

if (ctdbSetPathPrefix(AnyHandle, NULL) != CTDBRET_OK)

printf("ctdbSetPathPrefix() failed\n");

See also

ctdbGetPathPrefix()

ctdbSetRecordBuffer

Set the record buffer with user supplied data.

Declaration

CTDBRET ctdbSetRecordBuffer(CTHANDLE Handle, pVOID pBuffer,

VRLEN reclen, CTRECBUF_MODE mode)

Description

ctdbSetRecordBuffer() sets the record buffer with user supplied data. The record buffer NEW and MODIFIED flags are set to YES. After a call to ctdbSetRecordBuffer(), a call to ctdbWriteRecord() will add a new record to the record's table.

Handle [in] the record handle.
pBuffer [in] the pointer to a user buffer containing the record data. If the record buffer is NULL, the record is set to automatic.
reclen [in] the length in bytes of the user record buffer
mode [in] the mode of operation. Valid values are given in the table below.

Mode	Explanation
CTRECBUF_AUTO	This is the default mode for the record buffer operation. The record manager will allocate or reallocate the record buffer as needed to hold the record data.
CTRECBUF_STATIC	The user is responsible for supplying a record buffer large enough to handle any record data. If a record operation is attempted and the record buffer is not long enough to hold the data, an CTDBRET_INVRECBUF is returned to indicate that the record buffer is not large enough.
CTRECBUF_RAW	OR this mode in to indicate that the record manager is not supposed to update the internal control structures of the record buffer.

Returns

ctdbSetRecordBuffer() returns CTDBRET_OK on success, or a FairCom DB API C API error code on failure. The error CTDBRET_INVRECBUF (4063) means that the buffer is not large enough to hold the data. Increase the buffer or use the mode CTRECBUF_AUTO.

See also

ctdbWriteRecord(), ctdbSetRecordPos(), ctdbSetRecordOffset()

ctdbSetRecordOffset

Update the record offset.

Declaration

CTDBRET ctdbSetRecordOffset(CTHANDLE Handle, CTOFFSET offset )

Description

ctdbSetRecordOffset() updates the record offset. The current record pointer is not moved and no record data is updated.

Handle [in] the record handle.
offset [in] the new record byte offset.

Returns

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

See also

ctdbSetRecordPos(), ctdbSeekRecord(), ctdbGetRecordPos(), ctdbSetRecordBuffer()

ctdbSetRecordPos

Set the current record offset position.

Declaration

CTDBRET ctdbSetRecordPos(CTHANDLE Handle, CTOFFSET offset)

Description

ctdbSetRecordPos() sets the current record position. The record buffer is not updated. Follow the ctdbSetRecordPos() with a call to ctdbReadRecord() to update the record buffer.

Handle [in] the record handle.
offset [in] the current record offset position.

Returns

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

See also

ctdbSetRecordOffset(), ctdbReadRecord(), ctdbSeekRecord(), ctdbGetRecordPos(), ctdbSetRecordBuffer()

ctdbSetResourceData

Set the resource data.

DECLARATION

CTDBRET ctdbDECL ctdbSetResourceData(CTHANDLE resource, cpVOID data, VRLEN size);

DESCRIPTION

Set the resource data. The internal resource buffer is resized and the resource data is copied. If the resource data parameter is NULL, the internal resource data buffer is released.

resource is a handle allocated with ctdbAllocHandle().
data is a pointer to resource data. If data is NULL the internal resource data buffer is cleared. size indicate the number of bytes pointed by data.

RETURN

ctdbSetResourceData() return CTDBRET_OK on success.

EXAMPLE

CTDBRET ReadMyResource(CTHANDLE Handle, ULONG type, ULONG number, ppVOID data, pVRLEN size)

{

CTDBRET eRet;

CTHANDLE hRes = ctdbAllocResource(Handle, type, number, NULL);

/* check the resource handle allocation */

if (hRes == NULL)

{

eRet = ctdbGetError(Handle);

goto Exit;

}

/* get the resource */

if ((eRet = ctdbFindResource(hRes, type, number, NO)) != CTDBRET_OK)

goto Exit;

/* allocate a buffer large enough for the resource data */

*size = ctdbGetResourceDataLength(hRes);

if (*size > 0)

{

*data = (pVOID)malloc(*size);

if (*data == NULL)

{

eRet = CTDBRET_NOMEMORY;

goto Exit;

}

memcpy(*data, ctdbGetResourceData(hRes), *size);

}

Exit:

if (hRes)

ctdbFreeResource(hRes);

return eRet;

}

SEE ALSO

ctdbAllocResource(), ctdbFreeResource(), ctdbAddResource(), ctdbDeleteResource(), ctdbUpdateResource(), ctdbFirstResource(), ctdbNextResource(), ctdbFindResource(), ctdbFindResourceByName(), ctdbGetResourceType(), ctdbGetResourceNumber(), ctdbSetResourceNumber(), ctdbGetResourceName(), ctdbSetResourceName(), ctdbGetResourceDataLength(), ctdbGetResourceData(), ctdbSetResourceType(), ctdbIsResourceLocked(), ctdbUnlockResource()

ctdbSetResourceName

Set the resource name.

DECLARATION

CTDBRET ctdbDECL ctdbSetResourceName(CTHANDLE resource, pTEXT name);

DSCRIPTION

Set the resource name.

resource is a handle allocated by ctdbAllocHandle().
name is a resource name. A NULL value is acceptable to clear the current resource name.

RETURN

ctdbSetResourceName() returns CTDBRET_OK on success

EXAMPLE

if (ctdbGetResourceName(hRes) != NULL)

ctdbSetResourceName(hRes, NULL);

SEE ALSO

ctdbAllocResource(), ctdbFreeResource(), ctdbAddResource(), ctdbDeleteResource(), ctdbUpdateResource(), ctdbFirstResource(), ctdbNextResource(), ctdbFindResource(), ctdbFindResourceByName(), ctdbGetResourceType(), ctdbGetResourceNumber(), ctdbSetResourceNumber(), ctdbGetResourceName(), ctdbSetResourceType(), ctdbGetResourceDataLength(), ctdbGetResourceData(), ctdbSetResourceData(), ctdbIsResourceLocked(), ctdbUnlockResource()

ctdbSetResourceNumber

Set a resource number.

DECLARATION

CTDBRET ctdbDECL ctdbSetResourceNumber(CTHANDLE resource, ULONG number);

DESCRIPTION

Sets a resource number.

resource is a handle allocated by ctdbAllocResource().
number is a resource number value.

RETURN

ctdbSetResourceNumber() returns CTDBRET_OK on success.

EXAMPLE

if (ctdbGetResourceNumber(hRes) != number)

ctdbSetResourceNumber(hRes, number);

SEE ALSO

ctdbAllocResource(), ctdbFreeResource(), ctdbAddResource(), ctdbDeleteResource(), ctdbUpdateResource(), ctdbFirstResource(), ctdbNextResource(), ctdbFindResource(), ctdbFindResourceByName(), ctdbGetResourceType(), ctdbGetResourceNumber(), ctdbSetResourceType(), ctdbGetResourceName(), ctdbSetResourceName(), ctdbGetResourceDataLength(), ctdbGetResourceData(), ctdbSetResourceData(), ctdbIsResourceLocked(), ctdbUnlockResource()

ctdbSetResourceType

Set the resource type.

DECLARATION

CTDBRET ctdbDECL ctdbSetResourceType(CTHANDLE resource, ULONG type);

DESCRIPTION

Set the resource type. resource is a handle allocated by ctdbAllocResource() and type is a number representing the resource type.

RETURN

ctdbSetResourceType() returns CTDBRET_OK on success.

EXAMPLE

if (ctdbGetResourceType(hRes) != type)

ctdbSetResourceType(hRes, type);

SEE ALSO

ctdbAllocResource(), ctdbFreeResource(), ctdbAddResource(), ctdbDeleteResource(), ctdbUpdateResource(), ctdbFirstResource(), ctdbNextResource(), ctdbFindResource(), ctdbFindResourceByName(), ctdbGetResourceType(), ctdbGetResourceNumber(), ctdbSetResourceNumber(), ctdbGetResourceName(), ctdbSetResourceName(), ctdbGetResourceDataLength(), ctdbGetResourceData(), ctdbSetResourceData(), ctdbIsResourceLocked(), ctdbUnlockResource()

ctdbSetSegmentMode

Set the segment mode.

Declaration

CTDBRET ctdbSetSegmentMode(CTHANDLE Handle, CTSEG_MODE SegMode)

Description

ctdbSetSegmentMode() sets the segment mode. When the table is created, the segment mode is defined with the segments. If this information has to be changed later, ctdbSetSegmentMode() may be used. In this case, ctdbAlterTable() must be called after that to modify the table structure. Use ctdbGetSegmentMode() to retrieve the segment mode.

Handle [in] the Segment Handle.
SegMode [in] one of the valid segment modes, presented in FairCom DB API definitions.

Returns

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

Example

seg = ctdbGetSegmentMode(hSegment);

if (seg == CTSEG_SCHSEG)

{

err = ctdbSetSegmentMode(hSegment, CTSEG_USCHSEG);

err = ctdbAlterTable(hTable);

}

See also

ctdbAllocSegment(), ctdbGetSegmentMode(), ctdbAlterTable()

ctdbSetSessionParams

Set the session parameter based on the parameter type.

Declaration

CTDBRET ctdbSetSessionParams(CTHANDLE Handle, CTSESSION_PARAM

ParamType, NINT value)

Description

ctdbSetSessionParams() sets the session parameter based on the parameter type. It is necessary to set parameters before logging on to the server with ctdbLogon().

Handle [in] the session handle.
ParamType [in] the parameter type. Allowed values are:
- CT_BUFS: the number of index file buffers, minimum 3
- CT_FILS: initial block of file structures.
- CT_SECT: the number of node sectors. Minimum of one required. sect multiplied by 128 equals the index node size.
- CT_DBUFS: the number of buffers for data files I/O
- CT_USERPROF: is the user profile mask, and accepts the following values:
  - USERPRF_CLRCHK - instructs single-user TRANPROC applications to remove S*.FCS and L*.FCS files upon a successful application shutdown. The c-tree Plus checkpoint code determines at the time of a final checkpoint if there are no pending transactions or file opens, and if this user profile bit has been turned on. If so, the S*.FCS and L*.FCS files are deleted. However, if the application is causing log files to be saved (very unusual for a single-user application), then the files are not cleared. The USERPRF_CLRCHK option is off by default.
  - USERPRF_LOCLIB - specifies this instance of c-tree Plus is to be directed to a local database. Applicable only to client/server when using "Local Library Support".
  - USERPRF_NDATA - enable the manual mode of UNIFRMAT support. Enabling the manual record transformation mode would only be desirable when performing custom record level byte flipping or the record structures contain no numeric data (i.e., LONG, FLOAT, . . .). A side benefit of enabling this manual mode is the virtual elimination of Server DODA requests, thereby reducing network traffic by one function call per file open.
  - USERPRF_NTKEY - disables the automatic TransformKey() feature. See the Trans function description for more information.
  - USERPRF_PTHTMP - changes GetCtTempFileName() from its default operation of returning a temporary file name to specifying a directory name where temporary files are to reside.
  - USERPRF_SAVENV - enable the automatic SAVENV feature. See the Begin() function description for more information.

To use more than one value, OR the values together. Leave CT_USERPROF set to zero to accept the defaults.

value is the numeric value to be attributed to the parameter specified by ParamType.

Returns

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

Example

CTSESSION_TYPE ctdbsess=CTSESSION_CTDB;

CTHANDLE hSession = ctdbAllocSession(ctdbsess);

CTDBRET err;

NINT ret, newbuf;

err = ctdbLogon(hSession, "FAIRCOMS", "ADMIN", "ADMIN");

ret = ctdbGetSessionParams(hSession, CT_BUFS);

newbuf = ret + 2;

err = ctdbSetSessionParams(hSession, CT_BUFS, newbuf);

See also

ctdbGetSessionParams(), ctdbAllocSession()

ctdbSetSessionPath

Set the default session path.

Declaration

CTDBRET ctdbSetSessionPath(CTHANDLE Handle, pTEXT Path)

Description

ctdbSetSessionPath() sets the default session path in the session handle, where the session dictionary is located or will be created. Subsequent calls to functions like ctdbLogon() will use the session dictionary located in this path. Think of this call as setting the "working directory" for your session on the server.

Handle [in] the session handle.
Path [in] the pointer to the new default session path.

Returns

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

Example

ctdbSetSessionPath(handle, "c:\mySession");

eRet = ctdbLogon(handle, "FAIRCOMS", "ADMIN", "ADMIN");

See also

ctdbGetSessionPath(), ctdbLogon(), ctdbCreateSession()

ctdbSetSessionType

Change the session type.

Declaration

CTDBRET ctdbSetSessionType(CTHANDLE Handle, CTSESSION_TYPE SessionType)

Description

ctdbSetSessionType() changes the session type. The session type is initially set when ctdbAllocSession() is called to allocate a new session handle. ctdbSetSessionType() allow users to change the session type after it has been allocated.

Handle [in] the session handle.
SessionType [in] the new session type. The valid types are CTSESSION_CTDB, CTSESSION_CTREE, or CTSESSION_SQL

Returns

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

See also

ctdbGetSessionType()

ctdbSetSingleSavePoint (missing)

ctdbSetTableDefaultDataExtentSize

Set table default data extent size. (Introduced V12.0.1)

Declaration

CTDBRET ctdbSetTableDefaultDataExtentSize(CTHANDLE Handle, NINT size)

Description

ctdbSetTableDefaultDataExtentSize() sets the table default data extent size. Use ctdbSetTableDefaultIndexExtentSize() to set the table default index extend size. Use ctdbGetTableDefaultDataExtentSize() to retrieve the table default data extent size.

Handle [in] the Table Handle.
size [in] the extent size.

Returns

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

See also

ctdbAllocTable(), ctdbSetTableDefaultIndexExtentSize(), ctdbGetTableDefaultDataExtentSize()

ctdbSetTableDefaultIndexExtentSize

Set the table default index extent size. (Introduced V12.0.1)

Declaration

CTDBRET ctdbSetTableDefaultIndexExtentSize(CTHANDLE Handle, NINT size)

Description

ctdbSetTableDefaultIndexExtentSize() sets the table default index extent size. Use ctdbSetTableDefaultDataExtentSize() to set the table default data extend size. Use ctdbGetTableDefaultIndexExtentSize() to retrieve the table default index extent size. Use ctdbSetDefaultIndex() to set the table default index.

Handle [in] the Table Handle.
size [in] the size to be extent.

Returns

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

See also

ctdbAllocTable(), ctdbSetTableDefaultDataExtentSize(), ctdbSetDefaultIndex(), ctdbGetTableDefaultIndexExtentSize()

ctdbSetTableExtension

Set a new table extension

Declaration

CTDBRET ctdbSetTableExtension(CTHANDLE Handle, cpTEXT fExt)

Description

ctdbSetTableExtension() sets a new table extension. Use ctdbGetTableExtension() to retrieve the table extension.

Handle [in] the Table Handle.
fExt [in] the new table extension.

Returns

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

See also

ctdbAllocTable(), ctdbGetTableExtension()

ctdbSetTableGroupid

Set the table group ID.

Declaration

CTDBRET ctdbSetTableGroupid(CTHANDLE Handle, pTEXT groupid)

Description

ctdbSetTableGroupid() sets the table group ID. To retrieve the table group ID, use ctdbGetTableGroupid().

Handle [in] the Table Handle.
groupid [in] the table group id. If groupid is NULL, no action is taken.

Returns

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

See also

ctdbAllocTable(), ctdbGetTableGroupid()

ctdbSetTableOwner

Set the table owner.

Declaration

CTDBRET ctdbSetTableOwner(CTHANDLE Handle, pTEXT owner);

Description

Sets the table owner. You should set the table owner before the table is created to allow the proper c-tree security setting to take place.

Handle is a table handle allocated by ctdbAllocTable().
owner is a string with the table owner name. owner can be NULL, in which case the table owner name will be cleared.

Return Values

ctdbSetTableOwner() returns CTDBRET_OK on success.

See Also

ctdbGetTableOwner()

ctdbSetTablePassword

Set the table password.

Declaration

CTDBRET ctdbSetTablePassword(CTHANDLE Handle, pTEXT password)

Description

ctdbSetTablePassword() sets the table password. To retrieve the table password, use ctdbGetTablePassword().

Handle [in] the Table Handle.
Password [in] the table password.

Returns

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

See also

ctdbAllocTable(), ctdbGetTablePassword()

ctdbSetTablePath

Set a new table path.

Declaration

CTDBRET ctdbSetTablePath(CTHANDLE Handle, pTEXT Path)

Description

ctdbSetTablePath() sets a new table path. Set a table path before a table is created, otherwise the table will be created in the default (server or application) directory. After table creation, the table path is stored in the database dictionary and the user does not need to know it in order to open the table by name. If, for any reason, it is needed to retrieve the table path, use ctdbGetTablePath().

Handle [in] the Table Handle.
Path [in] the Table Path.

Returns

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

Example

ctdbSetTablePath(hTable, "C:\mydatabase");

eRet = ctdbCreateTable(hTable, table_name, CTCREATE_NORMAL);

See also

ctdbGetTablePath(), ctdbCreateTable()

ctdbSetTablePermission

Set table permission mask.

Declaration

CTDBRET ctdbSetTablePermission(CTHANDLE Handle, LONG permmask)

Description

ctdbSetTablePermission() sets the table permission mask. To retrieve the table permission mask, use ctdbGetTablePermission().

Handle [in] the Table Handle.
permmask [in] the Table Permission mask. The valid values for permmask are presented in FairCom DB API definitions.

Returns

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

See also

ctdbAllocTable(), ctdbGetTablePermission()

ctdbSetUserTag

Set the user tag.

Declaration

CTDBRET ctdbSetUserTag(CTHANDLE Handle, pVOID tagptr)

Description

ctdbSetUserTag() sets the user tag.

Handle [in] any FairCom DB API SDK Handle.
tagptr [in] the pointer associated with the value to be set to the user tag.

Returns

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

See also

ctdbGetUserTag()

ctdbUpdateCreateMode

Update the table create mode.

Declaration

CTDBRET ctdbUpdateCreateMode(CTHANDLE Handle, CTCREATE_MODE mode)

Description

ctdbUpdateCreateMode() updates the table create mode (which was specified when the table was created with the ctdbCreateTable() function). ctdbUpdateCreateMode() changes critical file mode attributes, such as the level of transaction control. This function is intended for use by experts, and should not be used unless you really understand all the implications. Since calling this function can cause the settings stored in the table handle to get out of sync with the table dictionary, the programmer should close and then re-open the table after using this function (see ctdbCloseTable(), ctdbOpenTable()).

No check is made to determine if the mode change will damage data. No check is made if the new mode is valid.

Note: Use this function with caution, as data may be lost. For example, changing a data file from transaction processing to no transaction processing makes automatic recovery unavailable.

Handle [in] the Table Handle.
mode [in] the new table create mode. It must be perfectly formed, as it will replace the current table create mode. Use the function ctdbGetTableCreateMode() to retrieve the current create mode and apply the changes on a fully qualified create mode. Update only the following create table modes:
- CTCREATE_PREIMG
- CTCREATE_TRNLOG
- CTCREATE_WRITETHRU
- CTCREATE_CHECKLOCK
- CTCREATE_CHECKREAD
- CTCREATE_HUGEFILE

Returns

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

See also

ctdbCreateTable()

Data Structures

ctdbGetRecordCount behavior on MRT Table modified

ctdbGetRowid (see Data Manipulation)

ctdbInsSegment

ctdbIsDatabaseExclusive (See Batch Operations)

ctdbSetSingleSavePoint (missing)

Was this article helpful?

Data Structures

ctdbGetRecordCount behavior on MRT Table modified

ctdbGetRowid (see Data Manipulation)

ctdbInsSegment

ctdbIsDatabaseExclusive (See Batch Operations)

ctdbSetSingleSavePoint (missing)

Was this article helpful?

Related Articles

Data types

Use cases (JSON to table transform)

Selectively return fields