ctdbBeginImpersonation

Enables the ability of the thread to support impersonation by another thread.

Declaration

CTDBRET ctdbBeginImpersonation(CTHANDLE Handle, NINT taskId)

Description

Start the impersonation of the specific task ID.

Stores the current "lock mode" in the prevlockmode session property and begins the impersonation for the given taskId (ctImpersonateTask()).

Retrieves the server-side "lock mode" ctdbGetLockMode() after the impersonation and updates the lockmode session property.

Note: This function is not supported by the FairCom Server by default. It requires a custom build of the server available by special request.

Returns

CTDBRET_OK on success.

See Also

ctdbEndImpersonation()

ctdbBigIntToCurrency

Convert a big integer value to a CTCURRENCY value.

Declaration

CTDBRET ctdbBigIntToCurrency(CTBIGINT value, pCTCURRENCY pCurrency)

Description

ctdbBigIntToCurrency() converts a big integer (8 bytes signed integer) value to a CTCURRENCY (8 bytes signed integer) value. Use ctdbCurrencyToBigInt() to convert from a CTCURRENCY value to a big integer (CTBIGINT) value.

• value [in] the CTBIGINT value (8 bytes integer).
• pCurrency [out] the CTCURRENCY value (8 bytes integer).

Returns

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

A possible error associated with ctdbBigIntToCurrency() is CTDBRET_NULARG since a Null argument is not valid in pCurrency.

See also

ctdbCurrencyToBigInt()

ctdbClearAllFieldDefaultValue

Clear the default value associated with all fields in a table.

DECLARATION

CTDBRET ctdbClearAllFieldDefaultValue(CTHANDLE Handle);

DESCRIPTION

ctdbClearAllFieldDefaultValue() clears the default value associated with all fields in a table. The default date and time types for each field are also reset to the default values of CTDATE_MDCY and CTIME_HMS respectively. Handle must be a table handle.

RETURN

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

EXAMPLE

/* clear all default field values *.

if (ctdbClearAllFieldDefaultValue(hTable) != CTDBRET_OK)

    printf("ctdbClearAllFieldDefaultValue failed\n");

SEE ALSO

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

ctdbClearError

Clear the error code.

Declaration

void ctdbClearError(CTHANDLE Handle)

Description

ctdbClearError() clears the error code set by ctdbSetError().

• Handle [in] any handle inside the session (session handle, database handle, table handle, record handle, index handle, field handle or segment handle).

Returns

None.

See also

ctdbSetError(), ctdbGetError()

ctdbClearField

Clear the field data and set the field's NULL flag.

Declaration

CTDBRET ctdbClearField(CTHANDLE Handle, NINT FieldNbr)

Description

ctdbClearField() clears the field data and sets the field's NULL flag.

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

Note: this function only edits a single field in a single record/row.

Additionally, ctdbClearField() also sets the NULL flag. To clear the NULL flag, write a value to the field in its relevant record, even if it is a zero-length string.

Returns

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

See also

ctdbClearRecord, ctdbIsNullField

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

ctdbClearFieldDefaultValue

Clears the default value associated with a FairCom DB API field.

DECLARATION

CTDBRET ctdbClearFieldDefaultValue(CTHANDLE Handle)

DESCRIPTION

Clears the default value associated with a field. The default date and time types are also reset to their default values of CTDATE_MDCY and CTTIME_HMS respectively. Handle must be a field handle.

RETURN

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

EXAMPLE

/* clear the default field value */

hField = ctdbGetField(hTable, 5);

if (hField)

    if (ctdbClearField(hField) != CTDBRET_OK)

        printf("ctdbClearField failed\n");

SEE ALSO

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

ctdbClearRecord

Clear the record buffer.

Declaration

CTDBRET ctdbClearRecord(CTHANDLE Handle)

Description

ctdbClearRecord() clears the record buffer that is part of the record handle. Before clearing a record, the record handle should be active (associated with a table). After the call to ctdbClearRecord(), functions that depend on the "current record" (like ctdbNextRecord() and ctdbPrevRecord()) will return an error (CTDBRET_NOTACTIVE), because the specified record handle is no longer associated with a particular record in the table. This function also resets the padding, zeroes out all of the number fields, and sets all of the bits of the NULL flag, meaning "all of the fields in this record handle are NULL (not set to anything yet)."

Note that this function does NOT break the record handle’s association with its table. After calling this function, the record handle is still associated with the table that was specified when the handle was allocated by calling ctdbAllocRecord().

It is very important to clear the record buffer BEFORE using this record handle to add a new record to a table. If the user tries to add a new record, and the buffer is not cleared by calling this function first, the new record will replace (rewrite) the active record (whatever record the specified record handle is currently associated with), or return an error ICUR_ERR (100) in the event the record handle has been instantiated, but not cleared.

• Handle [in] the record handle.

Returns

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

See also

ctdbAllocRecord(), ctdbResetRecord()

ctdbCurrentDate

Retrieve the current system date.

Declaration

CTDBRET ctdbCurrentDate(pCTDATE pDate)

Description

ctdbCurrentDate() retrieves the current system date. ctdbCurrentDateTime() retrieves the current date and time.

• pDate [out] pointer to a CTDATE value to receive the current date.

Returns

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

See also

ctdbCurrentTime(), ctdbCurrentDateTime()

ctdbCurrentDateTime

Retrieve the current system date and time, excluding milliseconds.

Declaration

CTDBRET ctdbCurrentDateTime(pCTDATETIME pDateTime)

Description

ctdbCurrentDateTime() retrieves the current system date and time.

• pDateTime [out] pointer to a CTDATETIME value to receive the current date and time.

Returns

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

NOTE: Although CTDATETIME includes milliseconds, this function truncates them to 0. Use ctdbCurrentDateTimeUTC() if you need millisecond support.

See also

ctdbCurrentDate(), ctdbCurrentTime(), ctdbCurrentDateTimeUTC()

ctdbCurrentDateTimeUTC

Set a DATETIME field with the current UTC time with millisecond precision.

Declaration

CTDBRET ctdbDECL ctdbCurrentDateTimeUTC(pCTDATETIME pDateTime)

Description

• pCTDATETIME pDateTime the DATETIME field.

This function relies on the system, and makes no guarantees for accuracy or monotonic behavior.

Returns

Returns NO_ERROR on success.

ctdbCurrentTime

Retrieve the current system time with whole second precision.

Declaration

CTDBRET ctdbCurrentTime(pCTTIME pTime)

Description

ctdbCurrentTime() retrieves the current system time. ctdbCurrentDateTime() retrieves the current date and time.

• pTime [out] pointer to a CTTIME value to receive the current time.

NOTE: See CTTIMEMS if you need millisecond precision.

Returns

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

See also

ctdbCurrentDate(), ctdbCurrentDateTime()

ctdbEndImpersonation

Disables the ability of the thread to support impersonation by another thread.

Declaration

CTDBRET ctdbEndImpersonation(CTHANDLE Handle)

Description

Finishes current impersonation (ctImpersonateTask()) and updates the "lock mode" on the server side with the lock mode stored before the impersonation in the prelockmode session property.

Note: This function is not supported by the FairCom Server by default. It requires a custom build of the server available by special request.

Returns

CTDBRET_OK on success.

See Also

ctdbBeginImpersonation()

ctdbEstimateSpan

Estimate an approximate number of records between two key target values.

Declaration

LONG ctdbEstimateSpan(CTHANDLE Handle, pVOID key1, pVOID key2);

Description

• Handle is a record handle.
• key1 and key2 are two key target values used to obtain the estimated number of records.

If ctdbEstimateSpan() returns 0, use ctdbGetError() function to retrieve the error code. If ctdbEstimateSpan() returns 0 and ctdbGetError() returns CTDBRET_OK then there are no records between the two key values supplied.

The estimation is based on the record handle current index. The current index may be changed by calling ctdbSetDefaultIndex(). The table must have at least one index to be able to use this function.

ctdbEstimateSpan(), which is based on c-tree low level function EstimateKeySpan(), does not traverse the index to compute the values. Instead, it makes about ten calls to the c-tree low level function KeyAtPercentile() to determine the relative location of the target values.

The key target values used by ctdbEstimateSpan() can be created using ctdbBuildTargetKey().

Return

ctdbEstimateSpan() returns an estimate of the number of records between key1 and key2. Call ctdbGetError() to retrieve the error code.

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

Example

Suppose that a student table has two fields (Name - CT_FSTRING and Age - CT_INT2) and one index on field Age. The sample function estimate the number of students with ages between 10 and 12:

LONG EstimateStudents(CTHANDLE hRecord)

{

TEXT key1[32];

TEXT key2[32];

VRLEN key1Len = 32;

VRLEN key2Len = 32;

/* build the first key for age = 10 years */

ctdbClearRecord(hRecord);

ctdbSetFieldAsSigned(hRecord, 1, 10);

if (ctdbBuildTargetKey(hRecord, CTFIND_EQ, key1, &key1Len))

return 0;

/* build the second key for age = 12 years */

ctdbClearRecord(hRecord);

ctdbSetFieldAsSigned(hRecord, 1, 12);

if (ctdbBuildTargetKey(hRecord, CTFIND_EQ, key2, &key2Len))

return 0;

/* estimate the number of students */

return ctdbEstimateSpan(hRecord, key1, key2);

}
 

See also

ctdbSetDefaultIndex(), ctdbBuildTargetKey()

ctdbGetCtreeOWNER

Returns OWNER ID in use by FairCom DB.

Declaration

NINT ctdbGetCtreeOWNER( VOID )

Description

Intended for internal FairCom DB API use.

Returns

Positive OWNER value on success or zero on error.

See also

ctdbSetCtreeOWNER()

ctdbGetDatno

Retrieve the table data file number.

DECLARATION

NINT ctdbGetDatno(CTHANDLE Handle)

DESCRIPTION

Retrieves the table data file number.

• Handle must be a table handle, or a handle that can be converted into a table handle such as a record, segment, index or field handle.

Return the table datno on success or -1 on failure. If ctdbGetDatno() returns -1, the error code can be retrieved by calling the ctdbGetError() function.

RETURN

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

EXAMPLE

CTDBRET DeleteTable(CTHANDLE hSession, pTEXT tablename)

{

CTDBRET Retval = CTDBRET_OK;

CTHANDLE hTable = ctdbAllocTable(hSession);

if (hTable)

{

/* open the table exclusive */

if ((Retval = ctdbOpenTable(hTable, tablename, CTOPEN_EXCLUSIVE)) != CTDBRET_OK)

return Retval;

/* delete a file */

if ((Retval = (CTDBRET)DeleteRFile((COUNT)ctdbGetDatno(hTable)) != CTDBRET_OK)

return Retval;

}

else

Retval = CTDBRET_NOMEMORY;

return Retval;

}

SEE ALSO

ctdbSwitchInstance(), ctdbSwitchContext(), ctdbGetIdxno(), ctdbGetIdxnoByName(), ctdbGetIdxnoByNumber(), ctdbGetError()

ctdbGetError

Return the last error logged by any function in the FairCom DB API C API.

Declaration

CTDBRET ctdbGetError(CTHANDLE Handle)

Description

ctdbGetError() returns the last error logged by any function in the FairCom DB API C API that was called from the specified session. This function should only be called to check for errors if a FairCom DB API C API function fails. In this situation, it does return the last error condition.

• Handle should be any Handle inside the Session (session handle, database handle, table handle, record handle, index handle, field handle or segment handle).

Returns

ctdbGetError() returns the last error logged by any function in the FairCom DB API, or NULL on failure.

ctdbGetErrorIndex (See Indexing)

ctdbGetOperationState

Declaration

CTOPS_MODE ctdbDECL ctdbGetOperationState(CTHANDLE Handle);

Description

Retrieve the c-tree operation modes for special performance-related functionality and test operational states for critical events.

• Handle is a session handle.

Return Values

ctdbGetOperationState() returns a combination of the following CTOPS_MODE codes on success:

See Also

ctdbGetOperationState() ctdbGetAutoCommit() ctdbSetAutoCommit()

ctdbGetPathPrefix

Returns the client-side path prefix.

DECLARATION

pTEXT ctdbGetPathPrefix(CTHANDLE hSession);

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

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

EXAMPLE

/* get the current path prefix */

YourPathPrefix = ctdbGetPathPrefix(AnyHandle);

if (CurrentPathPrefix == NULL)

printf("ctdbGetPathPrefix() returned no path.\n");

SEE ALSO

ctdbSetPathPrefix()

ctdbGetProductVersion

Retrieve the product version.

Declaration

CTDBRET ctdbGetProductVersion(CTHANDLE Handle, ppTEXT prodVersion, COUNT bufLen);

Description

ctdbGetProductVersion() retrieves the product version. The Handle parameter is not used so it can be NULL.

In V10.3 and later, the FairCom DB Server's "mini" version number, build date, and base build date (if any) are returned. These values allow a client to display the same full server build date that the FairCom DB Server displays.

Parameters:

• Handle [IN] - Session handle (can be NULL).
• prodVersion [OUT] - Product version.
• bufLen [IN] - Buffer Length.

Returns

cctdbGetProductVersion() returns CTDBRET_OK on success.

Example

NINT	Retcode;
TEXT	vers_buf[40];

Retcode = ctdbGetProductVersion(NULL,&vers_buf,sizeof(vers_buf));

ctdbGetSystemConfig

Retrieves c-tree system configuration values.

DECLARATION

LONG ctdbGetSystemConfig(NINT index);

DESCRIPTION

ctdbGetSystemConfig() retrieves c-tree Plus system configuration values, as well as some of the important dynamic aspects of the system, such as the memory usage and the number of files in use. To determine if a particular system configuration option is active, call ctdbGetSystemConfig(), passing the corresponding pre-defined constant for that option, and check if the value returned is non-zero.

The following pre-defined constant should be passed to ctdbGetSystemConfig():

The following constants only apply to client-server implementations:

The following constants are static compile time values:

The constants above and the pre-initialization resources section below have client and c-tree Server versions, except for the following three subscripts:

Constants ending with ‘app’ are specific to the client side of a client/server application. To check the same system setting for the c-tree Server, use the same subscript without the app extension. For example, to determine if Conditional Index support is active on the c-tree Server, use cfgCONDIDX as the subscript and cfgCONDIDXapp for the client side.

The pre-initialization resource constants below may be specified prior to a FairCom DB API initialization call, i.e ctdbLogon(), CTSession::Logon(), or CTSession.Logon(), in addition to having both a client and c-tree Server version, as discussed above.

1Pascal length byte

FairCom DB supports two different methods for specifying the length byte in a pascal data type. The original and non-traditional approach does not include the length byte in the byte count. For example, with a 1-byte data type, CT_FPSTRING, the smallest valid length byte would be 0. The new method follows the more traditional pascal convention of including the length byte in the byte count. For example, with the traditional approach, the smallest valid length for a 1-byte data type would be 1. Therefore, if cfgPASCALstapp or cfgPASCAL24app return a non-zero value, the new traditional approach is active.

To receive a valid return value from cfgPATH_SEPARATOR, ctPATH_SEP must be defined. The default definition found in ctopt2.h is:

#define ctPATH_SEP '?'

This definition specifies that the system default path separator will be used. To use the same separator for all platforms, you might want to choose one of the following:

#define ctPATH_SEP '\\'

/* define for Windows */
 

#define ctPATH_SEP '/'

/* define for most Unix systems */
 

#define ctPATH_SEP ':'

/* define for Mac OSX */

/* where the Uninitialized value is NINT_ERR for a client or FINT_ERR for a bound application */

The following constants can be used to capture system-wide cache and buffer statistics, (cache pages hold data record images and buffers hold index nodes), allowing an application to track the use of these resources.

RETURN

Returns a value that depends on the configuration constant passed to ctdbGetSystemConfig()

EXAMPLE

/* check if TRANPROC was turned on */

if (ctdbGetSystemConfig(ctTRANPROC))

printf("TRANPROC was turned on during compilation\n");

else

printf("TRANPROC was turned off during compilation\n");

SEE ALSO

none

ctdbRebuildTable

Calls the RBLIFILX() function to rebuild a c-tree table.

Declaration

CTDBRET ctdbRebuildTable(CTHANDLE Handle, CTREBUILD_MODE mode);

Description

• Handle [IN] Table handle
• mode [IN] The following modes are available:

Note: Exercise care when using CTREBUILD_DATAONLY and CTCREBUILD_UPDATEIFIL modes together as the index files will be removed from the table IFIL definition even if the index files still exist in the file system. This can cause later problems if ctdbAlterTable() is called to recreate the removed indexes.

ctdbRebuildTable() calls the FairCom DB RBLIFILX() function to rebuild a c-tree table. When used in conjunction with the open modes CTOPEN_CORRUPT and CTOPEN_DATAONLY, the ctdbRebuildTable() function can be used as a direct replacement for the c-tree ctrbldif rebuild utility.

The following steps are performed by FairCom DB API during a table rebuild process:

1. If a transaction is active, and the table being rebuilt was created with CTCREATE_TRNLOG or CTCREATE_PREIMG, the transaction is committed before the table is rebuilt, and the transaction is restarted after the table rebuild process is completed.
2. The update corrupt flag, updflg, of the header of the data file is cleared.
3. The internal delete stack chain of fixed-length data files or the internal delete management index of variable length data files are rebuilt.
4. The existing index files are removed and new index files are rebuilt over the existing files, optimized for both size and speed.

You must open the table before ctdbRebuildTable() is executed. It is recommended that the table be opened with CTOPEN_EXCLUSIVE mode. If the table is corrupt, you will need to open the table with the CTOPEN_CORRUPT mode and then call ctdbRebuildTable() to rebuild the data and index files. If there are missing or corrupt index files, open the table with CTOPEN_DATAONLY mode and ctdbRebuildTable() will reconstruct the missing index files.

There may be situations when you need to invoke this function to rebuild only the data file. After the data file rebuild is successful, you may need to call ctdbRebuildTable() again to rebuild the index files.

Return Values

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

See Also

ctdbAlterTable()

ctdbResetAll

Reset all record buffers associated with a table.

Declaration

CTDBRET ctdbResetAll(CTHANDLE Handle)

Description

ctdbResetAll() resets all record buffers associated with a table.

• Handle [in] the Table Handle.

Returns

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

See also

ctdbResetRecord()

ctdbResetRecord

Reset the record buffer to its original state

Declaration

CTDBRET ctdbResetRecord(CTHANDLE Handle)

Description

ctdbResetRecord() resets the record buffer to its original state.

• Handle [in] the record handle.

Returns

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

See also

ctdbResetAll(), ctdbClearRecord()

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

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

ctdbSetCallback (See Callback)

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

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

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

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

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.

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

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

ctdbTimeCheck

Check if the given time is valid.

Declaration

CTDBRET ctdbTimeCheck(NINT hour, NINT minute, NINT second)

Description

ctdbTimeCheck() checks to see if the given time is valid. To check if the date is valid, use ctdbDateCheck().

• hour is the hour, and it is supposed to be in the range 0 ≤ hour ≤ 23
• minute is the minute, and it is supposed to be in the range 0 ≤ minute ≤ 59
• second is the second, and it is supposed to be in the range 0 ≤ minute ≤ 59

Returns

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

The possible errors associated with ctdbTimeCheck() are:

• CTDBRET_INVHOUR (4034): Invalid hour
• CTDBRET_INVMINUTE (4035): Invalid minute
• CTDBRET_INVSECOND (4036): Invalid second

See also

ctdbDateCheck()