ctdbSeekRecord

Set the current record based on an offset and read that record.

Declaration

CTDBRET ctdbSeekRecord(CTHANDLE Handle, CTOFFSET offset)

Description

ctdbSeekRecord() sets the current record based on the specified offset, and reads the record’s data from disk into the record handle’s record buffer. Note that if session-wide record locking is enabled, this function will also lock the record it retrieves.

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

In this release and later, the ctdbSeekRecord() function will correctly position into the set when a record handle has an active criteria set.

Returns

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

See also

ctdbSetRecordPos(), ctdbSetRecordOffset(), ctdbGetRecordPos()

ctdbServerDateTime

(V11 and later) Retrieves the current server-side date and time.

Declaration

CTDATETIME ctdbServerDateTime(CTHANDLE hSession)

where hSession is a session handle.

Return Values

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	Successful operation.

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

ctdbSetAutoCommit

Sets the FairCom DB API auto commit mode.

Declaration

CTDBRET ctdbDECL ctdbSetAutoCommit(CTHANDLE Handle, CTBOOL flag);

Description

ctdbSetAutoCommit() sets the FairCom DB API auto commit mode. The auto commit of transactions are invoked automatically when records are added or updated by a ctdbWriteRecord() call. Automatic transactions may increase performance by reducing network traffic for single record updates since this is equivalent of performing the following functions:

ctdbBegin();

if (ctdbWriteRecord() == CTDBRET_OK)

ctdbCommit();

else

ctdbAbort();

Handle is a session handle.
flag indicates if auto commit mode should be enabled or not.

The following apply when an automatic transaction is performed:

An automatic transaction will only free locks acquired by the ctdbWriteRecord() function.
If an automatic transaction is aborted because of errors detected by ctdbWriteRecord(), all locks acquired by ctdbWriteRecord() are released.
If locks are active, by calling ctdbLock() function, an automatic transaction will not release any locks when it commits or aborts the ctdbWriteRecord() operation.
If OPS_UNLOCK_UPD is on, both commits and aborts on automatic transactions release only locks obtained within trans and/or locks on records updated within transaction, regardless if the FairCom DB API session lock state is active or not.

Return Values

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	No Error

See Also

ctdbGetAutoCommit() ctdbSetOperationState() ctdbGetOperationState()

ctdbSetBatch

Performs operations on a group of records.

DECLARATION

CTDBRET ctdbDECL ctdbSetBatch(CTHANDLE Handle, CTBATCH_MODE mode, VRLEN targetLen, VRLEN bufferLen);

DESCRIPTION

ctdbSetBatch() attempts to initiate a specified operation on a group of records with keys matching a partial key value, an index range expression, or the entire table by physical order.

Handle parameter must be a record handle associated with an opened table.
mode specifies which batch operation is to take place. You must choose at least one of the mandatory modes. You may or one or more of the optional mode to specify further parameters for the batch operation. Please refer to the description of the modes below.
targetLen specifies the number of significant bytes of the partial target key when the batch mode is CTBATCH_GET or CTBATCH_DEL.
bufferLen is the size of the buffer used internally by FairCom DB API code to handle batch operations. A zero value for this parameter indicates the default value size should be used. The default buffer size is calculated as the size of the fixed portion of the record multiplied by 128.

You must specify one of the following Mandatory modes when calling the ctdbSetBatch() function or the CTRecord:SetBatch() method:

MODE	Description
`CTBATCH_GET`	Retrieve a group of related records by partial key
`CTBATCH_RANGE`	Retrieve a group of related records based on an index range expression
`CTBATCH_PHYS`	Retrieve records from a table in physical order. The starting record for the batch retrieval may be specified.
`CTBATCH_DEL`	Delete a group of related records by partial key
`CTBATCH_INS`	Insert a group of records

The following modes are optional and can be OR-ed to the mandatory mode to specify other details on how the batch operation is to be performed.

Mode	Description
`CBATCH_GET_INCREMENTAL`	Used with CTBATCH_GET or CTBATCH_RANGE to retrieve records incrementally by partial key. The call to ctdbSetBatch() only reads the records that fit into the output buffer.
`CTBATCH_GKEY`	Process records with a greater than or equal key match with the target key. When this mode is specified, the number of matched records is not readily available. ctdbBatchLocked() and CTRecord::BatchLocked returns a value one greater than ctdbBatchLoaded() to indicate there may be more records to process.This mode is applicable only with CTBATCH_GET and CTBATCH_DEL modes and can not be used with CTBATCH_LKEY.
`CTBATCH_KEEPBUFFER`	Added in V12.6 when this mode is OR'd into ctdbSetBatch() mode parameter then the code reuses the batch buffer if already allocated and then ctdbEndBatch() does not release it. If this mode is not OR’d in than ctdbSetBatch() behaves as before and if for any reason there is a batch buffer still allocated it gets freed and reallocated.
`CTBATCH_LKEY`	Process records that have a less than or equal key match with the target key.This mode is applicable only with CTBATCH_GET and CTBATCH_DEL modes and can not be used with CTBATCH_GKEY.
`CTBATCH_VERIFY`	Verify that the keys in the index match the values in the key fields of the record.
`CTBATCH_LOCK_KEEP`	Keep all records locked after ...EndBatch() is called. Without this mode, all records locks are released when ...EndBatch() is called. This option is only in effect when used with CTBATCH_LOCK_READ or CTBATCH_LOCK_WRITE.
`CTBATCH_LOCK_READ`	Place a read lock on each record that matches the partial key.
`CTBATCH_LOCK_WRITE`	Place a write lock on each record that matches the partial key.
`CTBATCH_LOCK_BLOCK`	Convert a CTBATCH_LOCK_READ or CTBATCH_LOCK_WRITE to blocking read and blocking write locks, respectively.
`CTBATCH_LOCK_ONE`	Implement an alternative locking strategy: only locks the record during the record read; original locking strategy keeps locks on during entire batch processing.
`CTBATCH_COMPLETE`	...SetBatch() returns a success code only if all matching records are successfully locked. You must specify either CTBATCH_LOCK_READ or CTBATCH_LOCK_WRITE.

Automatic FairCom DB API Batch Buffer Resize

The ctdbSetBatch() function takes a parameter buffeLen which is the size of the buffer used internally by FairCom DB API to handle batch operations.

CTDBRET ctdbDECL ctdbSetBatch(CTHANDLE Handle, CTBATCH_MODE mode, VRLEN targetLen, VRLEN bufferLen)

A value of 0 for this parameter was an indication that the default value size should be used. The default buffer size is calculated as the size of the fixed portion of the record multiplied by 128.

In this release and later, when bufferLen is set to 0, the default buffer size is calculated as described above, and logic is activated to perform automatic buffer resize if the buffer is not large enough to contain one record.

When bufferLen is not 0 and the buffer is not large enough to contain at least one record, the error BTBZ_ERR (429) is returned. In this case, it is possible to activate the logic to automatically resize the buffer by adding the new CTBATCH_AUTORESIZE FairCom DB API batch mode to the mode parameter.

Retrieving records by partial key

All records with key matching a partial target key are loaded into a buffer region maintained internally by FairCom DB API. If the selected records do not fit in the buffer, those that fit are loaded, and subsequent calls will retrieve the remaining records.

The following steps must be taken to perform a batch retrieval operation based on a partial key:

Clear a record buffer by calling ctdbClearRecord() or the CTRecord:Clear() method.
Use ctdbSetFieldAs()... functions or CTRecord::SetFieldAs() methods to set the fields that form the partial target key that will be used to select a group of records.
Call the ctdbSetBatch() function or the CTRecord::SetBatch() method, with CTBATCH_GET mode, to start a new record retrieval batch operation.
If the ctdbSetBatch() function returns with no errors, continue to call the ctdbNextBatch() function repeatedly until all related records are retrieved. ctdbNextBatch() returns BTMT_ERR (428) to indicate no more records are available.
With the FairCom DB API C++ API, call the CTRecord::NextBatch() method repeatedly until all related records are retrieved. CTRecord::NextBatch() returns false to indicate no more records are available.
When you are done with the batch records, call the ctdbEndBatch() function or the CTRecord::EndBatch() method to terminate the batch operation. Please note that another batch operation can only start after the current batch operation is terminated.

Retrieving records by index range

All records that match an index range expression are loaded into a buffer region maintained internally by FairCom DB API. If the selected records do not fit in the buffer, those that fit are loaded, and subsequent calls will retrieve the remaining records.

The following steps must be taken to perform an index range batch retrieval of records:

Establish an index range by calling the ctdbRecordRangeOn() function or the CTRecord::RangeOn() method.
Call the ctdbSetBatch() function or the CTRecord::SetBatch() method with CTBATCH_RANGE mode to start a new record retrieval batch operation.
If the ctdbSetBatch() function returns with no errors, continue to call the ctdbNextBatch() function repeatedly until all related records are retrieved. ctdbNextBatch() returns BTMT_ERR (428) to indicate no more records are available.
With the FairCom DB API C++ API call the CTRecord::NextBatch() method repeatedly until all related records are retrieved. CTRecord::NextBatch() returns false to indicate no more records are available.
When you are done with the batch records, call the ctdbEndBatch() function or the CTRecord::EndBatch() method to terminate the batch operation.
Call the ctdbRecordRangeOff() function or the CTRecord::RangeOff() method to terminate index range operations.

Retrieving records by physical order

All records of a table are loaded by physical order into a buffer region maintained internally by FairCom DB API. If the selected records do not fit in the buffer, those that fit are loaded, and subsequent calls will retrieve the remaining records.

The following steps must be taken to perform a physical order batch retrieval of records:

Call the ctdbSetBatch() function or the CTRecord::SetBatch() method with CTBATCH_PHYS mode to start a new record retrieval batch operation.
If the ctdbSetBatch() function returns with no errors, call ctdbNextBatch() repeatedly until all related records are retrieved. ctdbNextBatch() returns BTMT_ERR (428) to indicate no more records are available.
With the FairCom DB API C++ API continue to call the CTRecord::NextBatch() method repeatedly until all related records are retrieved. CTRecord::NextBatch() returns false to indicate no more records are available.
When you are done with the batch records, call the ctdbEndBatch() function or the CTRecord::EndBatch() method to terminate the batch operation.

Note Setting a batch with CTBATCH_PHYS will cause slightly different behavior from setting it with CTBATCH_GET.

If the number of records exceeds the size of the buffer set when calling SetBatch, the total returned by BatchTotal will be only the number of records that fit into the batch buffer for CTBATCH_PHYS batches. If the batch was set with the CTBATCH_GET mode, the total number of records satisfying the batch will be returned, regardless if they all fit in the batch buffer. If a precise count of the number of records in a file is necessary, use GetRecordCount when you are in CTBATCH_PHYS mode.

This difference also affects record locking. If the batch was set with CTBATCH_PHYS, the records are locked when they are read into the buffer, so only the records that have been read into the batch buffer are locked. If the batch was set with CTBATCH_GET, all records are locked on the initial call.

Deleting a group of records

If the intended batch operation is to delete a group of selected records, you need to initially set the partial target key to select the group of related records and then start the batch operation to delete the selected records.

Even if no records are retrieved with the delete operation, ctdbEndBatch() must be called to terminate the current batch operation.

The following steps must be taken to perform a batch delete record operation:

Clear a record buffer by calling the ctdbClearRecord() function or the CTRecord::Clear() method.
Use the ctdbSetFieldAs...() functions or the CTRecord::SetFieldAs...() methods to set the fields that form the partial target key that will be used to select a group of records.
Call the ctdbSetBatch() function or the CTRecord::SetBatch() method with CTBATCH_DEL mode to delete a group of related records.
Call the ctdbEndBatch() function or the CTRecord::EndBatch() method to terminate the delete record batch operation.

Inserting a group of records

A group of new records are loaded into a buffer region maintained internally by FairCom DB API and this group of records are inserted into a table.

When the batch buffer fills up, the group of records stored in the batch buffer are inserted into the table. If ctdbEndBatch() is called and the batch buffer still contains records, a new insert record operation is performed for the remaining records before the batch operation is terminated.

For transaction controlled files, the batch insertion operation is treated as one all or nothing operation. If no explicit transaction is started, each insertion of records with will start and end its own transaction. Even if an explicit transaction is started, each insertion operation is treated independently through safe points.

Currently, all record insertion operations do not perform any conversion of record images, key values and record position for heterogeneous client/server implementations.

The following steps must be taken to perform a batch insert record operation:

Call the ctdbSetBatch() function or the CTRecord::SetBatch() method, with CTBATCH_INS mode, to insert a group of records.
For each record to be inserted perform the following operations:
- Call the ctdbClearRecord() function or the CTRecord::Clear() method to clear a record buffer.
- For each field in the record call one of the ctdbSetFieldAs...() functions or CTRecord::SetFieldAs...() methods to set the field data.
- Call the ctdbInsertBatch() or the CTRecord::InsertBatch() method to insert the record into the batch buffer.
Call the ctdbEndBatch() function or the CTRecord::EndBatch() method to indicate no more records will be inserted.

RETURNS

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

void GetInvoiceItems(CTHANDLE hRecord, NINT Invoice)
{
    NINT count = 0;

    /* set the partial target key */
    ctdbClearRecord(hRecord);
    ctdbSetFieldAsSigned(hRecord, 0, Invoice);
    /* set the batch operation */
    if (ctdbSetBatch(hRecord, CTBATCH_GET, sizeof(Invoice), 0) == CTDBRET_OK)
    {
        /* retrieve records */
        while (ctdbNextBatch(hRecord) == CTDBRET_OK)
            count++;
        /* terminate batch operations */
        ctdbEndBatch(hRecord);
    }
    printf("%d records found\n", count);
}

SEE ALSO

ctdbBatchLoaded(), ctdbBatchLocked(), ctdbBatchMode(), ctdbBatchTotal(), ctdbEndBatch(),
ctdbInsertBatch(), ctdbIsBatchActive(), ctdbNextBatch()

ctdbSetBatchFilter

Sets a record filter to be used in batch operations.

Declaration

CTDBRET ctdbDECL ctdbSetBatchFilter(CTHANDLE Handle, cpTEXT expr)

Description

Handle [IN] - Record handle
expr [IN] - The filter expression in text format. NULL or "" to reset it.

This is the batch version of ctdbFilterRecord(). When performing a record batch, use ctdbSetBatchFilter() as it does not connect to the server but instead sets the information locally in the client so it can piggyback onto the ctdbSetBatch() call avoiding an extra network hit. When performing individual record lookups, use ctdbFilterRecord().

Returns

New error code CTDBRET_ALREADYSET = 4170 indicates that a range or a filter for batch operation is already set.

See Also

ctdbSetBatchRangeOn (ctdbSetBatchRangeOn, ctdbSetBatchRangeOn)()

ctdbSetBatchRangeOff (ctdbSetBatchRangeOff, ctdbSetBatchRangeOff)()

ctdbSetBatchRangeOff

Removes the range for record batch operations.

Declaration

CTDBRET ctdbDECL ctdbSetBatchRangeOff(CTHANDLE Handle)

Description

Handle [IN] - Record handle

This is the batch version of ctdbRecordRangeOff(). When performing a record batch, use ctdbSetBatchRangeOff() as it does not connect to the server but instead clears the information locally in the client avoiding an extra network hit. When performing individual record lookups, use ctdbRecordRangeOff().

Returns

Return CTDBRET_OK on success.

New error code CTDBRET_ALREADYSET = 4170 indicates that a range or a filter for batch operation is already set.

See Also

ctdbSetBatchRangeOn (ctdbSetBatchRangeOn, ctdbSetBatchRangeOn)()

ctdbSetBatchFilter (ctdbSetBatchFilter, ctdbSetBatchFilter)()

ctdbRecordRangeOn()

ctdbRecordRangeOff()

ctdbSetBatchRangeOn

Sets a range to be used in batch operations.

Declaration

CTDBRET ctdbSetBatchRangeOn(CTHANDLE Handle, NINT SegCount, pVOID lRange, pVOID uRange, pNINT operators)

Description

Handle [IN] - Record handle
SegCount [IN] - segcount indicates the number of index segments values that should be used for setting the range, and the number of operators, because there must be one operator for each key segment in lRange and/or uRange.
lRange [IN] - lRange is a buffer with the lower range segment values. Use the function ctdbBuildTargetKey to build the lRange buffer.
uRange [IN] - uRange is a buffer with the upper range segment values. Use the function ctdbBuildTargetKey to build the uRange buffer.
operators [IN] - operators is an array of operators. There must be one operator for each key segment in lRange and/or uRange.

The operators CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT are open -ended and use only the lRange buffer for range values and the equivalent key segment in uRange is ignored and may be set to nul (ASCII \0 values). The operators CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE and CTIX_NOTBET use both lRange and uRange buffers to establish the lower and upper bound values.

This is the batch version of ctdbRecordRangeOn(). When performing a record batch, use ctdbSetBatchRangeOn() as it does not connect to the server but instead sets the information locally in the client so it can piggyback onto the ctdbSetBatch() call avoiding an extra network hit. When performing individual record lookups, use ctdbRecordRangeOn().

Returns

Return CTDBRET_OK on success.

New error code CTDBRET_ALREADYSET = 4170 indicates that a range or a filter for batch operation is already set.

See Also

ctdbSetBatchRangeOff (ctdbSetBatchRangeOff, ctdbSetBatchRangeOff)()

ctdbSetBatchFilter (ctdbSetBatchFilter, ctdbSetBatchFilter)()

ctdbSetBehavior

Set the specified CTDB runtime behavior status.

Declaration

CTDBRET ctDECL ctdbSetBehavior(CTHANDLE Handle, LONG item, CTBOOL state)

Parameters

Handle [in] the session handle.
Item [in] the behavior to be set.

Valid Item values include:

Item	Description	Default
CTDB_BEHAVE_CHECKDATETIME	Check for valid date/time during ctdbSetFieldAs* calls	YES
CTDB_BEHAVE_CHECK_NULL_CONSTRAINT	In V13.0.4 onwards, deny null value insert/update for table fields defined as not nullable	YES
CTDB_BEHAVE_ZERODATE_ISNULL	Set the field to NULL when the date value is 0	NO
CTDB_BEHAVE_NUMERIC_CHECK_DEF	When setting a CT_NUMBER field value, impose the defined scale and precision, rounding if necessary	NO
CTDB_BEHAVE_CTJSON_CHECK_VALUE	When setting a CTJSON field value, validate it as valid JSON	YES
CTDB_BEHAVE_OBJECT_NAME_TRIM_CHECK	Check for valid name (trimmed)	YES
CTDB_BEHAVE_DODA_CHECK	Check for valid DODA field lengths	YES
CTDB_BEHAVE_PAD_FIXED_BINARY	Pad with 0x00 fixed binary fields	YES
CTDB_BEHAVE_DODA_CHECK_STRING_MIN1	String length definition in DODA is either 0, or accounts for at least 1 significant byte	YES

Returns

ctdbSetBehavior returns CTDBRET_OK on success, or a FairCom DB API error on failure.

See also

ctdbGetBehavior

ctdbSetBinaryFlag

See ctdbSetFieldBinaryFlag.

ctdbSetCallback

Establishes a callback function.

Declaration

CTDBRET ctdbSetCallback(CTHANDLE Handle, CTDB_CALLBACK_TYPE

CallBackType,ctdbCallbackFunction CallBackFunc);

Description

ctdbSetCallback() establishes a new callback function to receive calls for a given callback type. Handle can be any valid FairCom DB API session, database, table or record handle. CallBackType is one of the following callback types from the table below. CallBackFunc is an address to a callback function.

Callback Symbolic Constant	Explanation
CTDB_ON_SESSION_LOGON	Called after a successful session logon.
CTDB_ON_SESSION_LOGOUT	Called before a session logout.
CTDB_ON_DATABASE_CONNECT	Called after a successful database connect.
CTDB_ON_DATABASE_DISCONNECT	Called a database disconnect.
CTDB_ON_TABLE_OPEN	Called after c-tree ISAM table open, but before any other table callbacks. This callback can be used to indicate that the table is open and ready for operations.
CTDB_ON_TABLE_CLOSE	Called before the table is closed.
CTDB_ON_TABLE_GET_DODA	Called after the table open code loads the DODA. This callback can be used to change the contents of the DODA before the FairCom DB API field handles are created based on the DODA information and the index and index segment handles are created based on the IFIL information.
CTDB_ON_TABLE_GET_SCHEMA	Called after the table open code load the schema information. This callback can be used to modify the contents of the schema information before the FairCom DB API field handles are created based on the DODA information and the index and index segment handles are created based on the IFIL information.
CTDB_ON_TABLE_GET_EXT_INFO	Called during the table open operation to allow the customization of FairCom DB API’s extended field information.
CTDB_ON_TABLE_GET_RECLEN	Called during the table open operation to allow the customization of the length of the fixed portion of the record.
CTDB_ON_TABLE_ALTER	Called during a FairCom DB API alter table operation to allow the indication if alter table operations are allowed or not for a particular table.
CTDB_ON_TABLE_REBUILD	Called during an alter table full rebuild loop to indicate a percentage progress of the rebuild process.
CTDB_ON_RECORD_INIT	Called to indicate that a record handle is about to become active or an alter table was performed and the record need to be re-initialized.
CTDB_ON_RECORD_RESET	Called to indicate that the record handle is about to become inactive. The record handle is being released or the table is closing.
CTDB_ON_RECORD_BEFORE_READ	Called before a record read operation.
CTDB_ON_RECORD_AFTER_READ	Called after a record read operation.
CTDB_ON_RECORD_BEFORE_BUILD_KEY	Called before c-tree Plus BuildKey function is called.
CTDB_ON_RECORD_AFTER_BUILD_KEY	Called after c-tree Plus BuildKey function is called.
CTDB_ON_RECORD_BEFORE_WRITE	Called before a record write or record update.
CTDB_ON_RECORD_AFTER_WRITE	Called after a record write or record update.

You need to register your callback functions before they are invoked by FairCom DB API. A callback function is registered by calling the ctdbSetCallback() function and passing the appropriate FairCom DB API handle, the callback function type and the address of a function to receive the callback calls.

You can register any of the defined callback functions using the session handle and every time a database, table or record handle is allocated, they will automatically inherit their callbacks from the session handle. Conversely if you register callbacks using a database handle, every time a table or a record handle is allocated they will automatically inherit their callbacks from the database handle. Record handles will also inherit any callbacks registered with the table handle.

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

/* allocate a new session handle */

CTHANDLE hSession = ctdbAllocSession(CTSESSION_CTREE);

/* set table open callback */

if (ctdbSetCallback(hSession, CTDB_ON_TABLE_OPEN, OnTableOpen) != CTDBRET_OK)

printf("ctdbSetCallback failed\n");

See Also

ctdbClearAllCallback(), ctdbClearCallback(), ctdbGetCallback()

ctdbSetConfigurationFile

Sets the server .DLL configuration file name and path.

Declaration

CTDBRET ctdbSetConfigurationFile(void)

Description

ctdbSetConfigurationFile() sets the server .DLL configuration file name and path.

Returns

Returns CTDBRET_OK on success, or FairCom DB API C API error on failure.

Example

ret = ctdbSetConfigurationFile("ctsrvr.cfg");
ret = ctdbStartDatabaseEngine();
...
...
ret = ctdbStopDatabaseEngine();

See also

ctdbStartDatabaseEngine(), ctdbStopDatabaseEngine()

ctdbSetCtreeOWNER

Sets the OWNER ID in use by FairCom DB.

Declaration

VOID ctdbSetCtreeOWNER( NINT owner )

Description

Intended for internal FairCom DB API use.

Returns

VOID

See also

ctdbGetCtreeOWNER()

ctdbSetCurrentNodeName

Set the client-side node name.

Declaration

CTDBRET ctdbSetCurrentNodeName(CTHANDLE Handle, pTEXT NodeName);

Description

When monitoring c-tree Server attached users, well written FairCom DB API client applications should "register" their workstation (node) name using the standard c-tree SETNODE() (SetNodeName() ) function call.

ctdbSetCurrentNodeName() set a client-side node name.

Handle is a session handle.
NodeName is an string specifying the node name. The specified node name appears in the ctadmn utility under the option for "list clients".

ctdbSetCurrentNodeName() must be called after a successful logon.

This functionality is available only with the c-tree Server. A call to ctdbSetCurrentNodeName() on non-server environment will always return CTDBRET_OK and the node name is ignored.

Return

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	ctdbRecordAtPercentile() 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 c-tree Server node name for this workstation */
if (ctdbSetCurrentNodeName(AnyHandle, "This is my node") != CTDBRET_OK)
    printf("ctdbSetCurrrentNodeName() failed\n");

See also

ctdbSetDefaultIndex(), ctdbBuildTargetKey()

ctdbSetDatabaseExclusive

Sets or clears the database exclusive flag.

Declaration

CTDBRET ctdbSetDatabaseExclusive(CTHANDLE Handle, CTBOOL flag);

Description

ctdbSetDatabaseExclusive() sets or clears the database exclusive flag. If a database exclusive flag is set, only one connection will be allowed on this database. Set the database exclusive flag after allocating the database handle, and before performing a connect. Setting the database exclusive flag after a database is connected will not have any effect during the current connection.

Handle is a database handle.
flag will set or clear the database exclusive flag.

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

/* perform an exclusive logon and connect */
CTHANDLE hSession = ctdbAllocSession(CTSESSION_CTDB);
CTHANDLE hDatabase = ctdbAllocDatabase(hSession);
 
if (hSession)
{
    ctdbSetSessionExclusive(hSession, YES);
    if (ctdbLogon(hSession, "FAIRCOM", "ADMIN", "ADMIN") != CTDBRET_OK)
        printf("ctdbLogon failed\n");
    else
    {
        ctdbSetDatabaseExclusive(hDatabase, YES);
        if (ctdbConnect(hDatabase, "MyData") != CTDBRET_OK)
            printf("ctdbConnect failed\n");
    }
}
ctdbFreeDatabase(hDatabase);
ctdbFreeSession(hSession);

See Also

ctdbSetSessionExclusive(), ctdbIsSessionExclusive(), ctdbIsDatabaseExclusive()

ctdbSetDatabaseTableMarkFilter

Set a table mark filter for database searches

Declaration

CTDBRET ctdbDECL ctdbSetDatabaseTableMarkFilter(CTHANDLE Handle, UCOUNT Dictattr)

Desription

Handle [IN] - Database handle
Dictattr [IN] - Table marks to filter for. Set to 0 to remove the filter

Return

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

See Also

ctdbFindTableDictionaryMark() (ctdbFindTableDictionaryMark, ctdbFindTableDictionaryMark)
ctdbSetTableDictionaryMark() (ctdbSetTableDictionaryMark, ctdbSetTableDictionaryMark)

ctdbSetDefaultFTI

Set the number of a new default FTI.

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

ctdbSetDefaultSqlTableOwner

Set default SQL table owner.

Declaration

CTDBRET ctdbDECL ctdbSetDefaultSqlTableOwner(CTHANDLE Handle, pTEXT newowner)

Description

This function is used in FairCom DB API Session type of CTSESSION_SQL prior to calling ctdbAddTable() to set the SQL OWNER name the table will receive.

Parameters:

Handle - Database handle
sqlowner - Default SQL table owner. If sqlowner is NULL no action is taken

Returns

Return CTDBRET_OK on success.

See also

ctdbAddTable

ctdbSetDefDateType

Set the default date type.

Declaration

CTDBRET ctdbSetDefDateType(CTHANDLE Handle, CTDATE_TYPE DateType)

Description

ctdbSetDefDateType() sets the default date type for the present session. Initially, the default is CTDATE_MDCY, indicating month, day, century, year (4 digits for the year). The possible date types are given in the Date Type Formats table in Date Types. Use ctdbGetDefDateType() to retrieve the default date type.

Handle [in] any FairCom DB API Handle.
DateType [in] a valid date type. Valid types are listed in the Date Type Formats table in Date Types.

Returns

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

See also

ctdbGetDefDateType()

ctdbSetDefFloatFormat

Set the default floating point format string

Declaration

CTDBRET ctdbDECL ctdbSetDefFloatFormat(CTHANDLE Handle, cpTEXT format)

Description

ctdbSetDefFloatFormat() sets the default floating point format string.

Handle [in] any FairCom DB API Handle.
format [in] the string format to be used by sprintf() or sscanf().

Returns

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

See also

ctdbGetDefFloatFormat()

ctdbSetDefTimeType

Set the default time type.

Declaration

CTDBRET ctdbSetDefTimeType(CTHANDLE Handle, CTTIME_TYPE TimeType)

Description

ctdbSetDefTimeType() sets the default time type for the present session. Initially, the default is CTTIME_HMP, indicating hour, minute and am/pm. The possible date types are given in the Time Type Formats table in Time Types. Use ctdbGetDefTimeType() to retrieve the default time type.

Handle [in] any FairCom DB API Handle.
TimeType [in] a valid time type. Valid types are listed in the Time Type Formats table in Time Types.

Returns

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

See also

ctdbGetDefTimeType()

ctdbSetDefFloatFormat

Set the default floating point format string

Declaration

CTDBRET ctdbDECL ctdbSetDefFloatFormat(CTHANDLE Handle, cpTEXT format)

Description

ctdbSetDefFloatFormat() sets the default floating point format string.

Handle [in] any FairCom DB API Handle.
format [in] the string format to be used by sprintf() or sscanf().

Returns

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

See also

ctdbGetDefFloatFormat()

ctdbSetDefTimeType

Set the default time type.

Declaration

CTDBRET ctdbSetDefTimeType(CTHANDLE Handle, CTTIME_TYPE TimeType)

Description

Handle [in] any FairCom DB API Handle.
TimeType [in] a valid time type. Valid types are listed in the Time Type Formats table in Time Types.

Returns

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

See also

ctdbGetDefTimeType()

ctdbSetDictInSuperfile

Sets if the dictionary is created in a superfile (default) or in a standard, system file. By default, dictionaries are created in superfiles.

Declaration

CTDBRET ctdbDECL ctdbSetDictInSuperfile(CTHANDLE Handle, CTBOOL superfile)

Desciption

FairCom DB API now has the capability to create session and database dictionaries as regular tables instead of superfiles. When using this feature, FairCom DB API now creates a directory named the same as the superfile was named. The dictionary tables are created as regular files inside the directory.

The session dictionary is created as ctdbdict.fsd\ctdbdict.dat ctdbdict.fsd\ctdbdict.idx
The database dictionary is created as <databasename>.fdd\ctdbdict.dat and <databasename>.fdd\ctdbdict.idx

To use this new capability, call this function prior to creating the session or the database:

ctdbSetDictInSuperfile() (ctdbSetDictInSuperfile, ctdbSetDictInSuperfile)

The handle must be a session handle when creating a session and a database handle when creating a database.

Handle [IN] - Session or Database handle. When passing a Database handle, the setting applies only to the Database.
superfile [IN] - YES: use superfile; NO: do not use superfile

Returns

Return CTDBRET_OK on success.

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

ctdbSetError

Set the error code.

Declaration

CTDBRET ctdbSetError(CTHANDLE Handle, CTDBRET ErrorCode)

Description

ctdbSetError() sets the error code.

Handle can be any Handle inside the Session (session handle, database handle, table handle, record handle, index handle, field handle, or segment handle).
ErrorCode should be any valid FairCom DB API C API error code.

Returns

ctdbSetError() returns CTDBRET_OK if successful, or NULL on failure.

See also

ctdbGetError(), ctdbClearError()

ctdbSetExtensionHint

Set extension hint in the handle to help with proper file name building at table open time.

Declaration

CTDBRET ctdbDECL ctdbSetExtensionHint(CTHANDLE Handle, EXT_INFO ExtHint)

Description

Calling ctdbSetExtensionHint(hDatabase,...) on a database handle allows setting the extension hint for ctdbAddTable() and ctdbAddTableXtd().

Parameters:

Handle [IN] - Table Handle.
ExtHint [IN] - The extension hint for ctdbOpen, ctdbAddTable, ctdbAddTableXtd:

EXT_DETECT - Backward compatible behavior: FairCom DB API will detect if the file terminates with ".*" and remove it from the file name and then add the current table extension.

EXT_PRESENT - File names contain file extension: The file name is specified with file extension; FairCom DB API will detect if the file terminates with ".*" and use what matches as extension, in case of no match the extension is set to "" (none).

EXT_MISSING - File names do not contain file extension: The file name is specified without extension; FairCom DB API will add the current extension.

For ctdbAddTableXtd only:

EXT_PRESENT_L - Logical file name contains file extension; physical does not.

EXT_PRESENT_P - Physical file name contains file extension; logical does not.

Return Values

Returns CTDBRET_OK on success, else returns the appropriate error code.

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;

}

ctdbSetFieldBinaryFlag

Set extra field information on how the binary content of the field needs to be handled. FairCom DB API has specific behaviors for CT_ARRAY, CT_2STRING, and CT_NUMBER.

Alternate name for this function: ctdbSetBinaryFlag().

Note: ctdbSetBinaryFlag() requires a field number parameter, which is not required by ctdbSetFieldBinaryFlag():
CTDBRET ctdbDECL ctdbSetBinaryFlag(CTHANDLE Handle, NINT fldno, CTDB_BINARY_FLAG flag);

Declaration

CTDBRET ctdbSetFieldBinaryFlag(CTHANDLE Handle, CTDB_BINARY_FLAG flag)

Parameters:

Handle [IN] - Field handle.
CTDB_BINARY_FLAG - A value of the CTDB_BINARY_FLAG enum defined in CTDBSDK.H. The possible field binary flag values are:

CTDB_BINARY_UNKNOWN - (CT_ARRAY or CT_2STRING fields) Table created by FairCom DB API prior to V9. Indicates that the field may or may not have an extra 4 bytes at the beginning of data.

CTDB_BINARY_FIXED - (CT_ARRAY or CT_2STRING fields) Table created by FairCom DB API V9 or later, so CT_ARRAY and CT_2STRING fields are handled correctly.

CTDB_BINARY_WITH_LENGTH - (CT_ARRAY or CT_2STRING fields) Table was created prior to V9 and only FairCom DB SQL has operated on it, so the CT_ARRAY and CT_2STRING fields have four bytes at the beginning of the data. This flag was most likely updated by a utility.

CTDB_BINARY_WITHOUT_LENGTH - (CT_ARRAY or CT_2STRING fields) Table created by FairCom DB API prior to V9. A utility has updated this resource.

CTDB_BINARY_VARCHAR - (CT_2STRING) Fields created by FairCom DB SQL V10 and later. This field content is interpreted by SQL as a VARCHAR.

CTDB_NUMBER_MONEY - (CT_NUMBER field) This field is interpreted by SQL as a MONEY type.

CTDB_BINARY_CLOB and CTDB_BINARY_BLOB - (CLOB and BLOB fields in V10 and later) - Reserved for future use.

CTDB_FIELDFLAG_USER1 - CTDB_FIELDFLAG_USER10 (V11.5 and later) - (All field types) These values can be used on any field type to carry information that can be used by the programmer to determine a different handling of the field content. For example, when using the FairCom DB API Type SDK (callbacks), these flags can be used to signal fields that need to be converted from a proprietary type to a c-tree defined type so they can be properly handled by FairCom DB API/SQL.

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.

See Also

ctdbGetBinaryFlag

ctdbSetFieldCallback

Allows setting a callback function on a specific field. The same table can have fields with and without callbacks.

Declaration

CTDBRET ctdbDECL ctdbSetFieldCallback(CTHANDLE Handle, CTDB_FIELD_CALLBACK_TYPE CallBackType, ctdbFldCallbackFunc CallBackFunc);

Handle is a pCTDBField handle.
CallbackType is one of the callbacks defined in the CTDB_FIELD_CALLBACK_TYPE enum (see Callback Types below).
CallBackFunc is a pointer to the callback function.

Description

It can be very powerful to have callback support at the time of retrieving or setting field information/content. This allows a typical use of callbacks, data conversion, to be performed at field access time instead of when reading/writing the entire buffer, with the benefit of converting only the field actually accessed.

The prototype for the callback is:

CTDBRET callbackfnc(CTHANDLE Handle, pVOID buffer, pVRLEN size, CTDB_FIELD_METATYPE rtype);

Handle will be set to the pCTDBDATA for the field to be accessed
buffer:

the destination buffer for CTDB_FIELD_GET

the source buffer for CTDB_FIELD_SET (may be different in case of t_string, t_fstring, t_vstring, at this time these rtypes are not implemented)

pointer to a CTBOOL to be set for CTDB_FIELD_ISNULL

pointer to CTDBTYPE to be set for CTDB_FIELD_GET_TYPE

pointer to VRLEN to be set for CTDB_FIELD_GET_LENGTH

size: pointer to a VRLEN containing the buffer size in input to be set in output to contain the "used" length
rtype: data type metadata of the buffer.

Metatypes

FairCom DB API implemented a series of ctdbGetFieldAs and ctdbSetFieldAs functions that allow the programmer to get/set the field using a datatype (As*) different from the field data type. FairCom DB API performs the necessary conversion between the wanted data type and the field data type. To do this, it virtually grouped the field types in "metatypes": for each metatype there is an internal function _ctdbGet*Field() that extracts the information from the record buffer into memory passed into the function. The same concept applies to the Set functions. The callbacks are implemented in the _ctdbGet*Field() function because this allows the callback writer to focus on how to extract the data in the buffer into the exact field type it maps to, not the data type requested by the application.

The defined metatypes are:

CTDB_FIELD_METATYPE	Field Type	*Type of Buffer**
t_invalid	N/A	N/A
t_bool	CT_BOOL	CTBOOL
t_signed	CT_CHAR CT_INT2 CT_INT4 CT_MONEY	CTSIGNED
t_unsigned	CT_CHARU CT_INT2U CT_INT4U CT_DATE CT_TIME	CTUNSIGNED
t_fstring [set only]	CT_ARRAY CT_FSTRING CT_F2STRING CT_F4STRING	NOT YET IMPLEMENTED
t_vstring [set only]	CT_STRING CT_PSTRING CT_2STRING CT_4STRING	NOT YET IMPLEMENTED
t_string [get only]	CT_ARRAY CT_FSTRING CT_F2STRING CT_F4STRING CT_STRING CT_PSTRING CT_2STRING CT_4STRING	CTSTRING
t_bigint	CT_BIGINT	CTBIGINT
t_ubigint	CT_UBIGINT	CTUBIGINT
t_currency	CT_CURRENCY	CTCURRENCY
t_number	CT_NUMBER	CTNUMBER
t_float	CT_SFLOAT CT_DFLOAT CT_EFLOAT CT_TIMES	CTFLOAT

If the CTDB_FIELD_GET_TYPE callback is in place for the field, the field type used within the various ctdbGetFieldAs* (as well as Set*) functions is determined by the value set by this callback.

Example

Suppose your buffer contains a 12-byte string representing a datetime formatted as YYMMDDHHMMSS and you want to represent it as a CT_DATE field. The application calls ctdbGetFieldAsString(), which calls the CTDB_FIELD_GET callback function requiring a t_unsigned, so the only conversion you need to think about for the field is from "string" to CTDATE and then store it in "buffer" that is a CTSIGNED pointer.

Then FairCom DB API will take care of converting CTDATE into a properly formatted string as requested by the ctdbGetFieldAsString() original call. It would have been possible to interface directly to the callbacks from the ctdbGetFieldAs* functions, however the number of conversion cases to be handled in the callback would have grown exponentially.

Note: The field callbacks must be set on the fields they apply to after opening the table. There is no need for a mechanism to propagate them to the records.

Callback Types

CTDB_FIELD_GET_TYPE: Called by ctdbGetFieldType and ctdbGetFieldProperty to retrieve the field type. This is useful if as part of the callback logic the field type does not match the one in the DODA structure.

CTDB_FIELD_GET_LENGTH: Called by ctdbGetFieldLength and ctdbGetFieldProperty to retrieve the field (defined) length. This is useful if as part of the callback logic the field len does not match the one in the DODA structure.

CTDB_FIELD_GET: Called by internal _ctdbGet*Field() function (see description later).

CTDB_FIELD_SET: Called by internal _ctdbSet*Field() function (see description later).

CTDB_FIELD_ISNULL: Called by ctdbIsNullField() to check if the field is NULL. When the callback is in place, ctdbIsNullField returns what was set by the callback.

CTDB_FIELD_CLEAR: Called by ctdbClearFiled() to set the field value to NULL. When the callback is in place, the callback it is responsible for the record buffer handling.

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.

ctdbSetFieldDefaultDateTimeType

Sets the default field value date and time type.

DECLARATION

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

DESCRIPTION

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

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

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

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

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

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

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

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

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

RETURN

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	No error occurred.

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

EXAMPLE

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

hField = ctdbGetField(hTable, 5);

if (hField)

if (ctdbSetFieldDefaultDateTimeType(hField, CTDATE_DMY, CTIME_HMP))

printf("ctdbSetFieldDefaultDateTimeType failed\n");

SEE ALSO

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

ctdbSetFieldDefaultValue

Sets the field default value.

DECLARATION

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

DESCRIPTION

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

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

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

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

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

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

RETURN

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	No error occurred.

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

EXAMPLE

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

hField = ctdbGetField(hTable, 5);

if (hField)

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

printf("ctdbSetFieldDefaultValue failed\n");

EXTENDED DEFAULT FIELD VALUE SUPPORT

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

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

CTDBRET ctdbDECL ctdbSetFieldDefaultValueType(CTHANDLE Handle, CTDEF_TYPE def_type);

Sets the default value type.

CTDEF_TYPE ctdbDECL ctdbGetFieldDefaultValueType(CTHANDLE Handle);

Gets the default value type.

Valid def_types are:

CTDEF_LITERAL: the value is a literal

CTDEF_USER: the current* user name

CTDEF_NULL: null

CTDEF_SYSDATE: the current* date

CTDEF_SYSTIME: the current* time

CTDEF_SYSTIMESTAMP: the current* timestamp

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

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

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

Default Values with ALTER TABLE

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

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

SEE ALSO

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

ctdbSetFieldDefaultValueAsBinary

Declaration

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

Description

ctdbSetFieldDefaultValueAsBinary() sets the default field value to binary.

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.

ctdbSetFieldHotAlterCallbackFunction

Set the field hot alter table callback function.

Declaration

CTDBRET ctdbDECL ctdbSetFieldHotAlterCallbackFunction(CTHANDLE Handle, cpTEXT functionName)

Description

FairCom DB now supports passing the names of a shared library and a field conversion function to the hot alter table function. This permits application developers to set a user-defined field conversion function to convert field values from one version of a schema to another version.

We now extend our FairCom DB API API to specify the conversion callback library at a table level and the callback conversion function name at a field level. If the callback library name at table level is not specified, we retrieve the last one used. If no callback library has ever been specified, we return an error.

Returns

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

ctdbGetTableHotAlterCallbackLib

ctdbSetTableHotAlterCallbackLib

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

ctdbSetForcedFSTRINGDelimiter

Set the CT_FSTRING forced delimiter flag for the table.

Declaration

CTDBRET ctdbDECL ctdbSetForcedFSTRINGDelimiter(CTHANDLE Handle, CTBOOL terminated)

Parameters

Handle [in] the Table Handle.
terminated [in] indicates whether the CT_FSTRING fields are forced to be terminated with dlmchar (YES) or not (NO).

Returns

ctdbSetForcedFSTRINGDelimiter returns CTDBRET_OK on success.

ctdbSetFTICndxExpr

Set the conditional expression for this Full Text Index.

ctdbSetFTIOption

Allows several Full-Text Search values to be set depending on the option.

ctdbSetIdentityField

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

Declaration

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

Description

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

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

Return Values

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

Example

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

ctdbAlterTable(mytable, CTDB_ALTER_NORMAL);

See Also

ctdbGetIdentityFieldDetails(), ctdbGetLastIdentity()

ctdbSetIndexCndxExpr

Add, change, or delete the conditional expression associated with an index.

Declaration

CTDBRET ctdbSetIndexCndxExpr(CTHANDLE Handle, pTEXT conditionExpr)

Description

ctdbSetIndexCndxExpr() adds, changes, or deletes the conditional expression associated with an index. After the conditional expression is successfully associated with the index the index data is not automatically rebuilt. To retrieve the conditional expression, use ctdbGetCndxIndex() or ctdbGetCndxIndexByName().

Handle [in] the Table Handle.
conditionExpr [in] string containing the conditional expression.

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

Returns

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

See also

ctdbAlterTable(), ctdbGetCndxIndex(), ctdbGetCndxIndexByName()

ctdbSetIndexDistinctKeyCountFlag

Set the status of the distinct count flag for an index. To optimize some SQL queries, a better estimation of the duplicate index selectivity is required, which implies determining how many distinct keys there are in an index that allows duplicates. The CTDBINDEX_DUPCNTFLAG index status value indicates that the index has distinct key count capability.

Declaration

CTDBRET ctdbSetIndexDistinctKeyCountFlag(CTHANDLE Handle, CTBOOL Flag);

Description

ctdbSetIndexDistinctKeyCountFlag() sets the distinct count flag for an index. Use ctdbGetIndexDistinctKeyCountFlag() to retrieve the setting of this flag.

Handle [in] the index handle.
Flag [in] the distinct count flag.

It is possible to "promote" a duplicate index to a duplicate index with a distinct count by opening the table, calling ctdbSetIndexDistinctKeyCountFlag() for the index and finally calling ctdbAlterTable() to execute the changes.

A FairCom DB API utility, ctdbdistinct, is available to enable the distinct key count feature for existing index files. This utility is created from mtmake by default.

See also

ctdbGetIndexDistinctKeyCountFlag

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

ctdbSetIndexFilename

Specify the Physical index file name.

Declaration

CTDBRET ctdbSetIndexFilename(CTHANDLE Handle, pTEXT path, pTEXT filename);

Description

Handle is an index handle returned by ctdbAddIndex() or ctdbGetIndex() calls.
path specifies the directory location of the index file. A NULL value for path indicates that the index file is to be located in the same directory as the data file.
filename specifies the name of the index file. If filename is NULL, this index is to be a member of the previous index file. If the filename of all index files are NULL, then all indexes will be placed in one physical index file located in the same directory as the data file, and the index file name is the same as the data file name, with the current index file extension.

An application can change the current index file extension by calling ctdbSetIndexExtension().

Return

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

See Appendix A "c-tree Plus Error Codes" in c-tree Plus Programmer's Reference Guide for a complete listing of valid c-tree Plus error values.

Example

CTHANDLE hTable = ctdbAllocTable(hDatabase);

CTHANDLE hIndex;

ctdbAddField(hTable, "name", CT_FSTRING, 20);

ctdbAddField(hTable, "age", CT_INT2);

hIndex = ctdbAddIndex(hTable, "index1", CTINDEX_FIXED, NO, NO);

ctdbSetIndexFilename(hIndex, NULL, "myindex1");

ctdbAddSegmentByName(hTable, 0, "name", CTSEG_SCHSEG);

ctdbAddIndex(hTable, "index2", CTINDEX_FIXED, NO, NO);

ctdbAddSegmentByName(hTable, 1, "age", CTSEG_SCHSEG);

hIndex = ctdbAddIndex(hTable, "index3", CTINDEX_FIXED, NO, NO);

ctdbSetIndexFilename(hIndex, NULL, "myindex2");

ctdbAddSegmentByName(hTable, 2, "name", CTSEG_SCHSEG);

ctdbAddSegmentByName(hTable, 2, "age", CTSEG_SCHSEG);

if (ctdbCreateTable(hTable, "mytable", CTCREATE_NORMAL) != CTDBRET_OK)

printf("ctdbCreateTable failed with code %d\n", ctdbGetError(hTable));

See also

ctdbGetIndexFilename(), ctdbSetIndexExtension(), ctdbAddIndex(), ctdbGetIndex()

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

ctdbSetIndexKSeg

Establishes an index-wide extended key segment definition.

DECLARATION

CTDBRET ctdbSetIndexKSeg(CTHANDLE Handle, pctKSEGDEF pKSeg);

DESCRIPTION

ctdbSetIndexKSeg() establishes an index-wide extended key segment definition. Handle must be an index handle and pKSeg is a pointer to an extended key segment definition structure with the extended key definition.

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

ctKSEGDEF kseg;

kseg.kseg_ssiz = ctKSEG_SSIZ_COMPUTED;

kseg.kseg_type = ctKSEG_TYPE_UNICODE;

kseg.kseg_styp = ctKSEG_STYP_UTF16;

kseg.kseg_comp = ctKSEG_COMPU_S_DEFAULT | ctKSEG_COMPU_N_NONE;

kseg.kseg_desc = "en_US"

if ((eRet = ctdbSetIndexKSeg(hIndex, &kseg)) != CTDBRET_OK)

printf("ctdbSetIndexKSeg failed with error %d\n", eRet);

SEE ALSO

ctdbSetTableKSeg(), ctdbGetTableKSeg(), ctdbGetIndexKSeg(),
ctdbSetSegmentKSeg(), ctdbGetSegmentKSeg(), ctdbSetKSegDefaults()

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

ctdbSetIndexPrimaryFlag

Sets the flag that marks an index as the primary key index of its table.

If an index does not meet the following criteria required to be a primary index, and you attempt to make it one, an error will be returned: rimaryindex

It must be a unique index
Its fields must be non-nullable
It cannot have a conditional table filter expression
It cannot be a temporary index

DECLARATION

CTDBRET ctdbDECL ctdbSetIndexPrimaryFlag(CTHANDLE Handle, CTBOOL PrimaryFlag)

Parameters

Handle [IN] - Index handle.
PrimaryFlag [IN] - Primary index flag.

RETURN

Return CTDBRET_OK on success.

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.

ctdbSetKeepLock

Sets the current keep lock mode when a transaction is committed or aborted.

DECLARATION

CTDBRET ctdbSetKeepLock(CTHANDLE Handle, CTKEEP_MODE mode);

DESCRIPTION

When a transaction is terminated by calling either the ctdbCommit() or ctdbAbort() function, all locks are automatically freed — both session-wide record locks (automatically acquired as a result of calling ctdbLock() and then reading a record from a table file), and manually locked records (acquired by calling ctdbLockRecord() on an individual record). Locks acquired both inside and outside the transaction are released. Not only that, ctdbCommit() and ctdbAbort() also disable (turn off) session-wide record locking. This is the default behavior. However, an application might want to control which locks are kept when the transaction ends, and whether the session-wide record locking mode is turned off or not. To support this ability, FairCom DB API introduced a function to control how locks and the session-wide record locking mode are handled when a transaction terminates.

By default, the FairCom DB API begin transaction function, ctdbBegin(), will begin a transaction by invoking c-tree’s TRANBEG() function with the ctTRNLOG and ctENABLE_BLK modes set. If the TRANBEG() function succeeds, FairCom DB API’s ctdbBegin() function automatically calls LKISAM() to suspend locks enabled by TRANBEG(), allowing users to enable any locks they wish: read locks, write locks, blocking or non-blocking. In this case, the FairCom DB API commit or abort transaction functions, ctdbCommit() and ctdbAbort(), call the appropriate c-tree ISAM functions to terminate the transaction and free all locks.

ctdbSetKeepLock() sets the extended keep lock mode applied when an active transaction is committed or aborted by calling ctdbCommit() or ctdbAbort().

Handle is a session handle and the keep lock mode is one of the following pre-defined constants:

Value	Symbolic Constant	Explanation
0	CTKEEP_FREE	Release all locks. Clear LKISAM state, turning off session-wide record locking. This is the default mode.
1	CTKEEP_LOCK	Keep all locks acquired before and during transaction, leaving session-wide record locking as it was. The LKISAM state is not cleared.
2	CTKEEP_OUT	Release only locks obtained within transaction and/or locks on records updated within transaction. The LKISAM state is not cleared, leaving session-wide record locking as it was.
3	CTKEEP_OUTALL	Unconditionally keep all locks acquired before transaction began. Free locks obtained within the transaction. The LKISAM state is not cleared, leaving session-wide record locking as it was.

RETURN

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	No error occurred.

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

EXAMPLE

/* set the keep lock */

if (ctdbSetKeepLock(hSession, CTKEEP_LOCK) != CTDBRET_OK)

printf("ctdbSetKeepLock failed\n");

/* begin the transaction */

ctdbBegin(hSession);

/* do some operations and commit transaction */

ctdbCommit(hSession);

/* do some other operations and release the locks *.

ctdbUnlock(hSession);

SEE ALSO

ctdbAbort, ctdbBegin(), ctdbCommit(), ctdbGetKeepLock()

ctdbSetKSegDefaults

Sets the system-wide default values for the extended key segment definition.

DECLARATION

CTDBRET ctdbSetKSegDefaults(pctKSEGDEF pKSeg);

DESCRIPTION

Sets the system-wide default values for the extended key segment definition. pKSeg is a pointer to an extended key segment definition structure which will receive the definition. The default values are:

kseg_ssiz = ctKSEG_SSIZ_COMPUTED;

kseg_type = ctKSEG_TYPE_UNICODE;

kseg_styp = ctKSEG_STYP_UTF16;

kseg_comp = ctKSEG_COMPU_S_DEFAULT | ctKSEG_COMPU_N_NONE;

kseg_desc = "en_US"

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

ctKSEGDEF kseg;

if ((eRet = ctdbSetKSegDefaults(&kseg)) != CTDBRET_OK)

printf("ctdbSetKSegDefaults failed with error %d\n", eRet);

SEE ALSO

ctdbSetTableKSeg(), ctdbGetTableKSeg(), ctdbSetIndexKSeg(), ctdbGetIndexKSeg(),
ctdbSetSegmentKSeg(), ctdbGetSegmentKSeg()

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

ctdbSetLogPath

Set transaction log path for standalone applications.

Declaration

CTDBRET ctdbDECL ctdbSetLogPath(CTHANDLE hSession, pTEXT path)

Description

hSession - a valid session handle
path - path to locate transaction logs

Standalone applications can now set a transaction log path as c-tree server's can do. Keeping the transaction logs in a secure separate location ensure the highest recovery options for applications. ctdbSetLogPath() defines this location.

These functions are methods of CTSession objects at the higher-level APIs (FairCom DB API C++, .NET, FairCom DB API Java).

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

ctdbSetPadChar

Set the table pad and field delimiter characters.

Declaration

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

Description

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

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

Returns

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

See also

ctdbGetPadChar(), ctdbUpdatePadChar()

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

ctdbSetSavePoint

Establish a transaction save point.

Declaration

NINT ctdbSetSavePoint(CTHANDLE Handle)

Description

ctdbSetSavePoint() establishes a transaction save point.

Handle [in] the session handle.

Returns

ctdbSetSavePoint() returns the save point number, or 0 on failure.

See also

ctdbBegin(), ctdbCommit(), ctdbAbort(), ctdbRestoreSavePoint()

ctdbSetSegmentField

Change the underlying segment field. This function only applies to index segments based on a field handle.

Declaration

CTDBRET ctdbDECL ctdbSetSegmentField(CTHANDLE Handle,CTHANDLE field)

Description

Handle [in] - Segment handle to be changed.
field [IN] - New field handle.

Returns

Returns CTDBRET_OK on success.

See also

ctdbAllocSegment(), ctdbGetSegmentField()

ctdbSetSegmentKSeg

Establishes a segment extended key definition.

DECLARATION

CTDBRET ctdbSetSegmentKSeg(CTHANDLE Handle, pctKSEGDEF pKSeg);

DESCRIPTION

ctdbSetSegmentKSeg() establishes a segment extended key segment definition. Handle must be a segment handle and pKSeg is a pointer to an extended key segment definition structure with the extended key definition.

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

ctKSEGDEF kseg;

kseg.kseg_ssiz = ctKSEG_SSIZ_COMPUTED;

kseg.kseg_type = ctKSEG_TYPE_UNICODE;

kseg.kseg_styp = ctKSEG_STYP_UTF16;

kseg.kseg_comp = ctKSEG_COMPU_S_DEFAULT | ctKSEG_COMPU_N_NONE;

kseg.kseg_desc = "en_US"

if ((eRet = ctdbSetSegmentKSeg(hIndex, &kseg)) != CTDBRET_OK)

printf("ctdbSetSegmentKSeg failed with error %d\n", eRet);

SEE ALSO

ctdbSetTableKSeg(), ctdbGetTableKSeg(), ctdbSetIndexKSeg(), ctdbGetIndexKSeg(),
ctdbGetSegmentKSeg(), ctdbSetKSegDefaults()

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

ctdbSetSessionExclusive

Sets or clears the session exclusive flag.

DECLARATION

CTDBRET ctdbSetSessionExclusive(CTHANDLE Handle, CTBOOL flag);

DESCRIPTION

ctdbSetSessionExclusive() sets or clears the session exclusive flag. If a session exclusive flag is set, only one CTSESSION_CTDB or CTSESSION_SQL session will be allowed. Set the session exclusive flag after allocating the session handle, but before performing a logon. Setting the session exclusive flag after a session logon is performed will not have any effect during the current session. Handle is a session handle. If flag is YES, this will set the exclusive flag, while NO will clear the exclusive flag.

RETURN

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	No error occurred.

See Errors for a complete listing of valid c-tree error values.

EXAMPLE

/* perform an exclusive logon */
CTHANDLE hSession = ctdbAllocSession(CTSESSION_CTDB);
 
if (hSession)
{
	ctdbSetSessionExclusive(hSession, YES);
    if (ctdbLogon(hSession, "FAIRCOM", "ADMIN", "ADMIN") != CTDBRET_OK)
        printf("ctdbLogon failed\n");
}
ctdbFreeSession(hSession);

SEE ALSO
ctdbIsSessionExclusive(), ctdbSetDatabaseExclusive(), ctdbIsDatabaseExclusives()

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

A wrapper function for ReplaceSavePoint.

ctdbSetStatusLogPath

Set CTSTATUS.FCS path location for standalone applications.

Declaration

CTDBRET ctdbDECL ctdbSetStatusLogPath(CTHANDLE hSession, pTEXT path)

Description

hSession - a valid session handle
path - path to locate CTSTATUS.FCS

Standalone applications can now set a CTSTATUS.FCS log path. ctdbSetStatusLogPath() defines this location.

These functions are methods of CTSession objects at the higher-level APIs (FairCom DB API C++, .NET, FairCom DB API Java).

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

ctdbSetTableDictionaryMark

Set the table dictionary mark.

Declaration

CTDBRET ctdbDECL ctdbSetTableDictionaryMark(CTHANDLE Handle, UCOUNT mark)

Description

Handle [IN] - Table handle
mark [IN] - Table dictionary mark

Returns

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

Table Marks

In V12 and later, a new concept has been implemented in FairCom DB API that makes it faster and easier to find specific files in applications with a large quantity of files: table marks. A table mark is a mark (or flag) associated with the table when it is added to a database (so it's a mark in the database dictionary). We currently support up to 16 different marks on each table. These marks can be used to "brand" the table with some meaning.

At this time, the only table mark implemented is _DICT_VERMARK_TBL_APP_LIST, which signifies that the table is branded so as to simulate the effect of the APP_NAME_LIST keyword, but instead of being listed in ctsrvr.cfg it is marked in the database dictionary.

The ctdbAddTableXtd() function has been modified so that the first parameter, Handle (previously interpreted as a database handle), can now be a table handle. If it is a table handle, the database handle is derived from it, and the dictionary mark setting in the table handle is used when adding the table to the dictionary.

New API functions have been created to support this feature:

ctdbFindTableDictionaryMark() (ctdbFindTableDictionaryMark, ctdbFindTableDictionaryMark)

ctdbSetDatabaseTableMarkFilter() (ctdbSetDatabaseTableMarkFilter, ctdbSetDatabaseTableMarkFilter)

ctdbSetTableDictionaryMark() (ctdbSetTableDictionaryMark, ctdbSetTableDictionaryMark)

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

ctdbSetTableFirstDataExtentSize

Set table first data extent size (creation time size).

Declaration

CTDBRET ctdbDECL ctdbSetTableFirstDataExtentSize(CTHANDLE Handle, NINT size)

Description

Parameters

Handle [IN] - Table handle
size [IN] - Extent size

Returns

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

ctdbSetTableFirstIndexExtentSize

Set table First index extent size (creation time size).

Declaration

CTDBRET ctdbDECL ctdbSetTableFirstIndexExtentSize(CTHANDLE Handle, NINT size)

Description

Parameters

Handle [IN] - Table handle
size [IN] - Extent size

Returns

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

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

ctdbSetTableHotAlterCallbackLib

Set the callback library name for hot alter table.

Declaration

CTBOOL ctdbDECL ctdbSetTableHotAlterCallbackLib(CTHANDLE Handle, cpTEXT libName)

Description

Returns

ctdbSetTableHotAlterCallbackLib() returns FairCom DB API YES or NO.

ctdbSetFieldHotAlterCallbackFunction

ctdbGetTableHotAlterCallbackLib

ctdbSetTableKSeg

Establishes a table wide extended key segment definition.

DECLARATION

CTDBRET ctdbSetTableKSeg (CTHANDLE Handle, pctKSEGDEF pKSeg);

DESCRIPTION

ctdbSetTableKSeg() establishes a table wide extended key segment definition. Handle must be a FairCom DB API table handle. pKSeg is a pointer to an extended key segment definition structure with the extended key definition.

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

ctKSEGDEF kseg;

kseg.kseg_ssiz = ctKSEG_SSIZ_COMPUTED;

kseg.kseg_type = ctKSEG_TYPE_UNICODE;

kseg.kseg_styp = ctKSEG_STYP_UTF16;

kseg.kseg_comp = ctKSEG_COMPU_S_DEFAULT | ctKSEG_COMPU_N_NONE;

kseg.kseg_desc = "en_US"

if ((eRet = ctdbSetTableKSeg(hTable, &kseg)) != CTDBRET_OK)

printf("ctdbSetTableKSeg failed with error %d\n", eRet);

See Also

ctdbGetTableKSeg(), ctdbSetIndexKSeg(), ctdbGetIndexKSeg(),
ctdbSetSegmentKSeg(), ctdbGetSegmentKSeg(), ctdbSetKSegDefaults()

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

ctdbSetTablePartitionBase

Set partition rule using an expression.

Declaration

CTDBRET ctdbDECL ctdbSetTablePartitionBase(CTHANDLE Handle, LONG base)

Description

Sets a partition rule using an expression.

Parameters:

Handle - [IN] CTTABLE table handle
base - [IN] LONG Partition number to set as base

Return Values

FairCom DB API error code.

ctdbSetTablePartitionIndexNbr

Set the Partition index number.

Declaration

CTDBRET ctdbDECL ctdbSetTablePartitionIndexNbr(CTHANDLE Handle, NINT idxno)

Description

Set the Partition index number.

Parameters:

Handle [IN] - Table handle
idxno [IN] - The index number for partition key*

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.

ctdbSetTablePartitionMaximumActive

Sets a maximum number of active partitions for auto purging feature.

Declaration

CTDBRET ctdbDECL ctdbSetTablePartitionMaximumActive(CTHANDLE Handle, UCOUNT max)

Description

Handle [IN] - Table handle
max [IN] - Number of maximum active partitions
Partition file support has been available since FairCom DB V10. This V12 addition sets the number of maximum active partitions. When the maximum is exceeded, c-tree's Auto-Purge feature takes care of purging.

Returns

Error code.

ctdbSetTablePartitionNumberBits

Set the number of bits used to store the raw partition number.

Declaration

CTDBRET ctdbDECL ctdbSetTablePartitionNumberBits(CTHANDLE Handle, UCOUNT bitno)

Description

Sets the number of bits used to store the raw partition number.

By default, 16 bits of the 64-bit record offset are used to reference the raw partition number, allowing each partitioned file to support up to 65535 member files over its lifetime. This function allows adjusting this when it is called before creating the file.

A value of 0 defaults to 16 bits, values less than 4 bits default to 4 bits (maximum 15 member files), and 32 bits is the maximum value.

Parameters

Handle [IN] - Table handle
bitno [IN] - Number of bits to be used for raw partition number

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.

ctdbSetTablePartitionRule

Set partition rule using an expression.

Declaration

CTDBRET ctdbDECL ctdbSetTablePartitionRule(CTHANDLE Handle, pTEXT expr)

Description

Sets a partition rule using an expression.

Parameters:

Handle [IN] - Table handle
expr [IN] - expression that evaluates into an integer that will be used as partition number

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.

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

ctdbSetTempPath

Set temporary file path for single-user applications

Declaration

CTDBRET ctdbDECL ctdbSetTempPath(CTHANDLE hSession, pTEXT path)

Description

pSession [IN] - session handle
path [IN] - temporary file path

Can be used in standalone compiles to define the directory for temporary files.

Returns

FairCom DB API error code.

ctdbSetTransactionMode

OR-ed in to form the transaction mode used when a c-tree transaction is started.

Declaration

CTDBRET ctdbDECL ctdbSetTransactionMode(CTHANDLE Handle, CTBEGIN_MODE mode);

Description

Handle is a session handle.
mode is a combination of possible mode values:

CTBEGIN_MODE Symbolic Constant	Description
CTBEGIN_NONE	No begin transaction mode set. Default mode apply.
CTBEGIN_PREIMG	Transaction atomicity only. Auto-recovery is not available. Mutually exclusive with CTBEGIN_TRNLOG.
CTBEGIN_TRNLOG	Full transaction processing functionality including auto-recovery. Mutually exclusive to CTBEGIN_PREIMG. This is the default begin transaction mode.
CTBEGIN_DEFER	Defer begin transaction until update.
CTBEGIN_AUTOSAVE	Automatically invokes savepoints after each successful record or resource update.

This mode will be OR-ed in to form the transaction mode used when a c-tree transaction is started. If the transaction mode is CTBEGIN_NONE, the ctTRNLOG mode is used to start a new transaction.

Return Values

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	Successful operation.

See Also

ctdbGetTransactionMode()

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

ctdbStartDatabaseEngine

Starts the FairCom DB database engine .DLL model.

Declaration

CTDBRET ctdbStartDatabaseEngine(void)

Description

A developer can call ctdbStartDatabaseEngine() once before making any other FairCom DB API or FairCom DB calls, and then call function ctdbStopDatabaseEngine() when finished with database activities to shut down the database engine. ctdbStartDatabaseEngine() must be called before any other FairCom DB API calls are performed. ctdbStartDatabaseEngine() loads the ctsrvr.cfg configuration file, creates the data and index caches, and initializes the multithreading subsystem.

Note that automatic recovery takes place on startup which can result in short delays after making this call, especially if the process was interrupted previously and an application shutdown without calling ctdbStopDatabaseEngine().

Returns

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

Example

ret = ctdbSetConfigurationFile("ctsrvr.cfg");
ret = ctdbStartDatabaseEngine();
...
...
ret = ctdbStopDatabaseEngine();

See also

ctdbStopDatabaseEngine(), ctdbSetConfigurationFile()

ctdbStartFTIBackgroundLoad

Starts a background index loader for the Full-Text Index (FTI).

ctdbStopDatabaseEngine

Stops the FairCom DB database engine .DLL model.

Declaration

CTDBRET ctdbStopDatabaseEngine(void)

Description

ctdbStopDatabaseEngine() shuts down the FairCom DB database engine .DLL model. This ensures a clean shutdown, resulting in quicker startups at the next application instance. It also ensures all files are properly closed and flushed to disk.

Returns

Returns CTDBRET_OK on success, or FairCom DB API C API error on failure.

Example

ret = ctdbSetConfigurationFile("ctsrvr.cfg");
ret = ctdbStartDatabaseEngine();
...
...
ret = ctdbStopDatabaseEngine();

See also

ctdbStartDatabaseEngine(), ctdbSetConfigurationFile()

ctdbStringToBigInt

Convert a string to a big integer value.

Declaration

CTDBRET ctdbStringToBigInt(pTEXT pStr, pCTBIGINT pValue)

Description

ctdbStringToBigInt() converts a string to a big integer value. A big integer is an 8 bytes integer value. Use ctdbBigIntToString() to convert from a big integer to a string.

pStr [in] the string value.
pValue [out] the big integer value (8 bytes signed integer).

Returns

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

The possible error associated with ctdbStringToBigInt() is:

CTDBRET_NULARG (4007): Null argument not valid in pValue

See also

ctdbBigIntToString()

ctdbStringToCurrency

Convert a string value to a CTCURRENCY value.

Declaration

CTDBRET ctdbStringToCurrency(pTEXT pStr, pCTCURRENCY pCurrency)

Description

ctdbStringToCurrency() converts a string value to a CTCURRENCY (8 bytes signed integer) value. Use ctdbCurrencyToString() to convert from a CTCURRENCY value to a string.

pStr [in] the string value.
pCurrency [out] the CTCURRENCY value (8 bytes integer).

Returns

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

The possible error associated with ctdbStringToCurrency() is:

CTDBRET_NULARG (4007): Null argument not valid in pStr

See also

ctdbCurrencyToString()

ctdbStringToDate

Convert a date in string format to CTDATE packed format.

Declaration

CTDBRET ctdbStringToDate(pTEXT pStr, CTDATE_TYPE DateType,
                         pCTDATE pDate)

Description

ctdbStringToDate() converts a date in string format to CTDATE packed format. Use ctdbDateToString() to convert a packed CTDATE into a string.

pStr [in] the pointer to the string.
DateType [in] the date type. Valid types are listed in FairCom DB API Data Types.
pDate [out] the pointer to date that will result from the conversion.

Returns

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

The possible errors associated with ctdbStringToDate() are:

CTDBRET_NULARG (4007): Null argument not valid in pStr
CTDBRET_NOMEMORY (4001): Not enough memory
CTDBRET_INVFORMAT (4028): Invalid format in DateType
CTDBRET_INVDATE (4029): Invalid packed CTDATE

See also

ctdbStringToTime(), ctdbDateToString()

ctdbStringToDateTime

Convert a date in string format into a packed CTDATETIME.

Declaration

CTDBRET ctdbStringToDateTime(pTEXT pStr, pCTDATETIME pDateTime,
                          CTDATE_TYPE DateType, CTTIME_TYPE TimeType)

Description

ctdbStringToDateTime() converts a date string to a packed CTDATETIME. The date is converted based on the DateType parameter, and the time is converted based on the TimeType parameter.

pStr [in] a pointer to the string with the date and time value.
pDateTime [out] Pointer to a CTDATETIME type value to received the converted string date and time
DateType [in] the date type. Valid types are listed FairCom DB API Data Types.
TimeType [in] the time type. Valid types are listed in FairCom DB API Data Types.

Returns

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

The possible errors associated with ctdbStringToDateTime() are:

CTDBRET_NULARG (4007): Null argument not valid in pStr
CTDBRET_INVDATE (4029): Invalid format in DateType
CTDBRET_INVTYPE (4019): Invalid type in DateType or TimeType
CTDBRET_ARGSMALL (4006): Buffer is too small (increase size)

See also

ctdbDateTimeToString(), ctdbStringToTime() (ctdbStringToTime, ctdbStringToTime), ctdbStringToDate()

ctdbStringToMoney

Convert a string value to a CTMONEY type value.

Declaration

CTDBRET ctdbStringToMoney(pTEXT pStr, pCTMONEY pMoney)

Description

ctdbStringToMoney() converts from a string to CTMONEY. Use ctdbMoneyToString() to converts a CTMONEY value to a string.

pStr [in] the pointer to the string.
pMoney [out] the pointer to a CTMONEY type value.

Returns

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

The possible errors associated with ctdbStringToMoney() are:

CTDBRET_NULARG (4007): Null argument not valid in pStr
CTDBRET_OVERFLOW (4038): Operation caused overflow

See also

ctdbMoneyToString()

ctdbStringToNumber

Convert a string type value to a CTNUMBER.

Declaration

CTDBRET ctdbStringToNumber(pTEXT pStr, pCTNUMBER pNumber)

Description

ctdbStringToNumber() converts a string to a CTNUMBER . Use ctdbNumberToString() to convert from CTNUMBER to a string.

pStr [in] the input string to the conversion.
pNumber [out] pointer to CTNUMBER that will result from the conversion.

Returns

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

The possible errors associated with ctdbStringToNumber() are:

CTDBRET_NULARG (4007): Null argument not valid in pStr
CTDBRET_OVERFLOW (4038): Operation caused overflow

See also

ctdbNumberToString()

ctdbStringToTDateTime

Convert a date and time in a string ot a double containing a delphi TDateTime value.

Declaration

CTDBRET ctdbDECL ctdbStringToTDateTime(cpTEXT pStr, DOUBLE* tdatetime, CTDATE_TYPE DateType, CTTIME_TYPE TimeType)

Description

ctdbStringToTDateTime() converts a date and time in a string to a double containing a delphi TDateTime value.

Parameters:

pStr [IN] - string containing the date and time
unixtime [OUT] - pointer to a time_t type value to receive the converted string date and time
DateType [IN] - one of the date types
TimeType [IN] - one of the time types

Return values

Returns CTDBRET_OK on success.

ctdbStringToTime

Convert a time in string format to CTTIME packed format with whole second precision.

Note See ctdbStringToTimeMsec() if you need millisecond precision.

Declaration

CTDBRET ctdbStringToTime(pTEXT pStr, CTTIME_TYPE TimeType,
                         pCTTIME pTime)

Description

ctdbStringToTime() converts a time in string format to CTTIME packed format. Use ctdbTimeToString() to convert a packed CTTIME into a string.

pStr [in] the pointer to the string.
TimeType [in] the time types. Valid types described in FairCom DB API Data Types.
pTime [out] the pointer to a CTTIME value that will result from the conversion.

Returns

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

The possible errors associated with ctdbStringToTime() are:

CTDBRET_NULARG (4007): Null argument not valid in pStr
CTDBRET_NOMEMORY (4001): Not enough memory
CTDBRET_INVFORMAT (4028): Invalid format in TimeType
CTDBRET_INVTIME (4033): Invalid packed CTTIME

See also

ctdbTimeToString(), ctdbStringToTimeMsec(), ctdbTimeMsecToString()

ctdbStringToTimeMsec

Convert a time in string format to CTTIMEMS packed format with millisecond precision.

Note See ctdbStringToTime() if you don't need millisecond precision."

Declaration

CTDBRET ctdbDECL ctdbStringToTimeMsec(pTEXT pStr, CTTIME_TYPE TimeType, pCTTIMEMS pTime)

Parameters:

pStr [IN] - Time in string format
TimeType [IN] - One of the time types
pTime [OUT] - Packed time (with milliseconds)

Description

FairCom DB API function to convert a string to a timems value (time with milliseconds).

V11.5 and later support the CTTIME_HMST time format: Time is h|hh:mm:ss.ttt (24-hour time; t is milliseconds). The millisecond portion is optional, if missing it defaults to 0.

This function supports the CTTIME_HHMST mode, which forces the hour to be two digits and returns time as hh:mm:ss.ttt (24- hour time).

Return Values

Return CTDBRET_OK on success.

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.

See Also

ctdbTimeMsecToString, ctdbStringToTime(), ctdbTimeToString()

ctdbStringToUnixTime

Convert a date and time in a string to a packed CTDATETIME type value

Declaration

CTDBRET ctdbDECL ctdbStringToUnixTime(cpTEXT pStr, time_t* unixtime, CTDATE_TYPE DateType, CTTIME_TYPE TimeType)

Description

ctdbStringToUnixTime() converts a date and time in a string to a packed CTDATETIME type value

Parameters:

pStr [IN] - String containint the date and time
unixtime [OUT] - Pointer to a time_t type value to received the converted string date and time
DateType [IN] - One of the date types
TimeType [IN] - One of the time types

Return Values

Return CTDBRET_OK on success

ctdbSwitchContext

Force an ISAM context switch.

Declaration

CTDBRET ctdbSwitchContext(CTHANDLE Handle)

Description

Force a switch to the FairCom DB ISAM context indicated by the record handle. Each record handle has its own c-tree ISAM context id.

When most FairCom DB API record handling functions are called, they automatically perform a c-tree ISAM context switch. ctdbSwitchContext() may be useful before calling specific c-tree ISAM or low level calls to make sure the correct ISAM context is active before making those calls.

Handle is a record handle. The handle must be a record handle. No other type of FairCom DB API handle is acceptable.

Returns

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	Successful function.

See Errors for a complete listing of valid c-tree error values.

Example

/* force a context switch */
if (ctdbSwitchContext(hRecord) != CTDBRET_OK)
    printf("ctdbSwitchContext failed\n");
/* call ResetRecord */
if (ResetRecord((COUNT)ctdbGetDatno(hRecord), SWTCURI))
    printf("ResetRecord failed\n");

See also
ctdbSwitchInstance(), ctdbGetDatno(), ctdbGetIdxno(), ctdbGetIdxnoByName(), ctdbGetIdxnoByNumber()

ctdbSwitchInstance

Force a c-tree instance switch.

Declaration

CTDBRET ctdbSwitchInstance(CTHANDLE Handle)

Description

Force a switch to the c-tree instance indicated by the Session handle. Each session handle has its unique c-tree instance ID.

When most FairCom DB API C functions are called, they automatically perform a c-tree instance switch. ctdbSwitchInstance() may be useful before calling specific c-tree ISAM or low level calls to make sure the correct instance is active before making those calls.

Handle is a Session handle. You can pass any FairCom DB API handle to ctdbSwitchInstance().

Return

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	Successful function.

See Errors for a complete listing of valid c-tree error values.

Example

/* declare and allocate the remote and local session handles */
CTHANDLE hRemote = ctdbAllocSession(CTSESSION_CTREE);
CTHANDLE hLocal = ctdbAllocSession(CTSESSION_CTREE);

/* logon to c-tree server using the remote session handle */
if (ctdbLogon(hRemove, "FAIRCOMS", "ADMIN", "ADMIN") !=  CTDBRET_OK)
    printf("Remote ctdbLogon failed\n");
/* logon to local session using the local session handle */
if (ctdbLogon(hLocal, "local", "ADMIN", "ADMIN) != CTDBRET_OK)
    printf("Local ctdbLogon failed\n");
/* perform a c-tree instance switch and call CtreeUserOperation function */
if (ctdbSwitchInstance(hRemote) != CTDBRET_OK)
    printf("ctdbSwitchInstance failed\n");
CtreeUserOperation("!mkdir faircom", buffer, sizeof(buffer);

See also
ctdbSwitchContext(), ctdbGetDatno(), ctdbGetIdxno(), ctdbGetIdxnoByName(), ctdbGetIdxnoByNumber()

ctdbSystemFilterOff

Deletes a permanent system-wide record filter.

DECLARATION

CTDBRET ctdbDECL ctdbSystemFilterOff(CTHANDLE Handle, CTSYSFILTER mode);

DESCRIPTION

Deletes a permanent system-wide record filter. The table must be opened exclusive and the user must have file definition permission for the table. Handle is a table handle or any FairCom DB API handle that can produce a table handle, such as a record, field, index or segment handle.

For the parameter mode you must specify one of the following:

Permanent Filter Symbolic Constant	Explanation
CTSYSFILTER_READ	Indicates you are deleting a system-wide read record filter.
CTSYSFILTER_WRITE	Indicates you are deleting a system-wide write record filter.
CTSYSFILTER_READ \| CTSYSFILTER_WRITE	Indicates you are deleting both a system-wide read record filter and a system-wide write record filter.

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

/* delete a system wide filter */

if (ctdbSystemFilterOff(hTable, CTSYSFILTER_READ | CTSYSFILTER_WRITE)) != CTDBRET_OK)

printf("ctdbSystemFilterOff failed\n");

SEE ALSO

ctdbSystemFilterOn()

ctdbSystemFilterOn

Establishes a permanent system-wide data record filter.

DECLARATION

CTDBRET ctdbDECL ctdbSystemFilterOn(CTHANDLE Handle, CTSYSFILTER mode);

DESCRIPTION

Establishes a permanent system-wide data record filter, that is, the filter applies to all users, read and/or write record filter. Depending on the server file security setting, the table must be opened exclusive and the user must have file definition permission for the table. A table may have at most one read and one write system wide filter. A write filter will be called when data records are added, updated or deleted. Once a read or a write filter is established, it can only be deleted by calling the function ctdbSystemFilterOff().

Handle is a table handle or any FairCom DB API handle that can produce a table handle, such as a record, field, index or segment handle. For the mode parameter, you must specify one of the following:

Permanent Filter Symbolic Constant	Explanation
CTSYSFILTER_READ	Indicates you are setting a system-wide read record filter.
CTSYSFILTER_WRITE	Indicates you are setting a system-wide write record filter.
CTSYSFILTER_READ \| CTSYSFILTER_WRITE	Indicates you are setting both a system-wide read record filter and a system-wide write record filter.

System-wide filters must be callback filters. The actual callback evaluation takes place in a new callback function ctfiltercb_rowl() located in module ctclbk.c.

There different levels of security settings when users modify data file definition resources such as IFIL and DODA. The c-tree Server can be configured for three different levels of data file resource security:

FILEDEF_SECURITY_LEVEL	Explanation
LOW	Lowest security setting. There is no protection as any user may add or delete data file definition resources. This setting may be used to keep the c-tree Server data compatible with legacy applications.
MEDIUM	Default security setting. Any user may add or delete data file definition resources, but the file must be opened exclusive. This default setting may be enough to keep the c-tree Server data compatible with most legacy applications.
HIGH	Highest security setting. A user must have file definition permission before a definition resource is added or deleted. The file must be opened exclusive. This setting is appropriate for applications that require the highest level of security and may cause compatibility problems with existing legacy applications.

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

/* establish a new system wide filter */

if (ctdbSystemFilterOn(hTable, CTSYSFILTER_READ | CTSYSFILTER_WRITE)) != CTDBRET_OK)

printf("ctdbSystemFilterOn failed\n");

SEE ALSO

ctdbSystemFilterOff()

C API Functions S

ctdbSeekRecord

ctdbServerDateTime

ctdbSetAutoCommit

ctdbSetBatch

ctdbSetBatchFilter

ctdbSetBatchRangeOff

ctdbSetBatchRangeOn

ctdbSetBehavior

ctdbSetBinaryFlag

ctdbSetCallback

ctdbSetConfigurationFile

ctdbSetCtreeOWNER

ctdbSetCurrentNodeName

ctdbSetDatabaseExclusive

ctdbSetDatabaseTableMarkFilter

ctdbSetDefaultFTI

ctdbSetDefaultIndex

ctdbSetDefaultIndexByName

ctdbSetDefaultSqlTableOwner

ctdbSetDefDateType

ctdbSetDefFloatFormat

ctdbSetDefTimeType

ctdbSetDefFloatFormat

ctdbSetDefTimeType

ctdbSetDictInSuperfile

ctdbSetEditedRecord

ctdbSetError

ctdbSetExtensionHint

ctdbSetFieldAsBigint

ctdbSetFieldAsBinary

ctdbSetFieldAsBlob

ctdbSetFieldAsBool

ctdbSetFieldAsCurrency

ctdbSetFieldAsDate

ctdbSetFieldAsDateTime

ctdbSetFieldAsFloat

ctdbSetFieldAsJSON

ctdbSetFieldAsMoney

ctdbSetFieldAsNumber

ctdbSetFieldAsSigned

ctdbSetFieldAsString

ctdbSetFieldAsTime

ctdbSetFieldAsTimeMsec

ctdbSetFieldAsUnsigned

ctdbSetFieldAsUTF16

ctdbSetFieldAutoSysTime

ctdbSetFieldBinaryFlag

ctdbSetFieldCallback

ctdbSetFieldDefaultDateTimeType

ctdbSetFieldDefaultValue

ctdbSetFieldDefaultValueAsBinary

ctdbSetFieldHotAlterCallbackFunction

ctdbSetFieldLength

ctdbSetFieldName

ctdbSetFieldNullFlag

ctdbSetFieldPrecision

ctdbSetFieldProperties

ctdbSetFieldScale

ctdbSetFieldStringEncoding

ctdbSetFieldType

ctdbSetForcedFSTRINGDelimiter

ctdbSetFTICndxExpr

ctdbSetFTIOption

ctdbSetIdentityField

ctdbSetIndexCndxExpr

ctdbSetIndexDistinctKeyCountFlag

ctdbSetIndexDuplicateFlag

ctdbSetIndexEmptyChar

ctdbSetIndexExtension

ctdbSetIndexFilename

ctdbSetIndexKeyType

ctdbSetIndexKSeg

ctdbSetIndexName

ctdbSetIndexNullFlag

ctdbSetIndexPrimaryFlag

ctdbSetIndexTemporaryFlag

ctdbSetJSONSegmentField

ctdbSetKeepLock

ctdbSetKSegDefaults