ctdbGetActiveDatabaseUID

Retrieve the database UID, given the handle of an "active" (connected) database.

Declaration

CTDBRET ctdbGetActiveDatabaseUID(CTHANDLE Handle, pULONG puid)

Description

ctdbGetActiveDatabaseUID() retrieves the database Unique Identifier, UID, given the Database Handle. Note that the UID of a database persists as long as that database remains in the session dictionary. Removing a database from a session dictionary and then re-adding it to the session dictionary is very likely to change that database’s UID. Use ctdbGetDatabaseUID() to retrieve the database UID, given the database name. Use ctdbFindDatabaseByUID() to locate a database in a session by its unique identifier.

• Handle [in] the Database Handle.
• puid [out] the database UID.

Returns

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

See also
ctdbAllocDatabase(), ctdbFindDatabaseByUID(), ctdbGetDatabaseUID()

ctdbGetActiveResultSet

Declaration

CTHANDLE ctdbGetActiveResultSet(CTHANDLE Handle);

Description

Retrieves the Result Set handle active for the given Record handle.

• Handle [IN] - Record handle

Returns

Returns a Result Set handle if any is active, or NULL on error.

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

See Also
ctdbGetResultSetHandle, ctdbAllocateResultSet, ctdbFreeResultSet, ctdbResultSetOnOff, ctdbGetResultSetByName, ctdbGetResultSetCriHandle, ctdbAddCriteria, ctdbRemoveCriteria, ctdbUpdateCriteria, ctdbGetActiveResultSet

ctdbGetActiveTableByUID

Retrieve the active table handle given its UID.

Declaration

CTHANDLE ctdbGetActiveTableByUID(CTHANDLE Handle, ULONG uid)

Description

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

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

Returns

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

See also

ctdbGetActiveTableUID()

ctdbGetActiveTableUID

Retrieve the tableUID, given a table handle.

Declaration

CTDBRET ctdbGetActiveTableUID(CTHANDLE Handle, pULONG puid)

Description

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

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

Returns

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

See also

ctdbAllocTable(), ctdbFindTableByUID(), ctdbGetTableUID()

ctdbGetAttachMode

Declaration

CTATTACH_MODE ctdbDECL ctdbGetAttachMode(CTHANDLE Handle);

Description

Retrieve the current session attach mode. ctdbGetAttachMode() will not execute a c-tree instance switch.

• Handle is a session handle.

Returns

One of the following values is returned:

See Also
ctdbAttachSession(), ctdbDetachSession()

ctdbGetAutoCommit

Declaration

CTBOOL ctdbDECL ctdbGetAutoCommit(CTHANDLE Handle);

Description

ctdbGetAutoCommit() retrieves the FairCom DB API auto commit mode. The auto commit of transactions are invoked automatically when records are added or updated by ctdbWriteRecord() call.

• Handle must be a session handle.

Return Values

See Also

ctdbSetAutoCommit() ctdbSetOperationState() ctdbGetOperationState()

ctdbGetBatchBufferSize

Return the size of the batch buffer.

DECLARATION

VRLEN ctdbDECL ctdbGetBatchBufferSize(CTHANDLE Handle)

DESCRIPTION

ctdbGetBatchBufferSize() returns the size of the batch buffer currently allocated (or -1 if the handle is not a record handle).

• Handle [in] the record handle.

USE CASE

The CTBATCH_KEEPBUFFER mode of ctdbSetBatch can be used to preserve the batch buffer after the batch is finished and reuse it for another batch. ctdbGetBatchBufferSize() can be used to determine if the buffer has gotten too big. If so, ctdbReleaseBatchBuffer() releases the buffer and reallocates it on the next ctdbSetBatch request.

SEE ALSO

ctdbReleaseBatchBuffer(), ctdbSetBatch

ctdbGetBehavior

Return the status of the specified CTDB runtime behavior.

Declaration

CTBOOL ctDECL ctdbGetBehavior(CTHANDLE Handle, LONG item)

Parameters

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

Returns

ctdbGetBehavior returns YES if the behavior is ON. Otherwise, it returns NO.

See also

ctdbSetBehavior

ctdbGetBinaryFlag

Returns the user-defined characteristics of a field definable by the programmer bindable to the field definition.

Declaration

ctdbGetBinaryFlag(CTHANDLE Handle, NINT fldno);

Description

In V11.5, a set of binary flags has been introduced for the CTDB_BINARY_FLAG enum in CTDBSDK.H. These flags can be assigned to a binary field using ctdbSetFieldBinaryFlag (also called ctdbSetBinaryFlag). These values can be used to indicate particular characteristics of a field definable by the programmer bindable to the field definition.

Return Values

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

See Also

• ctdbSetFieldBinaryFlag (ctdbSetBinaryFlag)

ctdbGetCallback

Retrieves the callback function pointer associate with the callback type.

DECLARATION

ctdbCallbackFunction ctdbGetCallback(CTHANDLE Handle, CTDB_CALLBACK_TYPE CallBackType)

DESCRIPTION

• Handle is a valid FairCom DB API session, database, table or record handle.
• CallBackType is one of the valid callback types.

You can check if a given callback has been registered with a session, database, table or record handle by calling the ctdbGetCallback() function. If a callback function was set, ctdbGetCallback() returns the address of the function. If a particular callback is not set, ctdbGetCallback() returns NULL.

RETURN

Returns the function pointer, or NULL if the callback was not registered.

EXAMPLE

/* allocate a table handle */

CTHANDLE hTable = ctdbAllocTable(hDatabase);

/* make sure CTDB_ON_TABLE_OPEN callback is set */

if (ctdbGetCallback(hTable, CTDB_ON_TABLE_OPEN) == NULL)

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

printf("ctdbSetCallback failed\n");

SEE ALSO

ctdbClearAllCallback(), ctdbClearCallback(), ctdbSetCallback()

ctdbGetCndxIndex

Retrieve the conditional index expression string, given the index number.

Declaration

CTDBRET ctdbGetCndxIndex(CTHANDLE Handle, NINT indexnbr, pTEXT buffer,

NINT bufferlen)

Description

ctdbGetCndxIndex() retrieves the conditional index expression string, given the index number. The conditional expression is added, deleted or updated with ctdbUpdateCndxIndex() or ctdbUpdateCndxIndexByName().

• Handle [in] the Table Handle.
• indexnbr [in] the index number.
• buffer [OUT] pointer to buffer to receive the conditional expression.
• bufferlen [IN] size in bytes of buffer. Maybe retrieved with ctdbGetCndxIndexLength() or ctdbGetCndxIndexLengthByName().

Returns

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

See also

ctdbUpdateCndxIndex(), ctdbUpdateCndxIndexByName(), ctdbGetCndxIndexLength(), ctdbGetCndxIndexLengthByName()

ctdbGetCndxIndexByName

Retrieve the conditional index expression string, given the index name.

Declaration

CTDBRET ctdbGetCndxIndexByName(CTHANDLE Handle, pTEXT indexname,

pTEXT buffer, NINT bufferlen)

Description

ctdbGetCndxIndexByName() retrieves the conditional index expression string, given the index name. The conditional expression is added, deleted or updated with ctdbUpdateCndxIndex() or ctdbUpdateCndxIndexByName().

• Handle [in] the Table Handle.
• indexname [in] the index name.
• buffer [OUT] pointer to buffer to receive the conditional expression.
• bufferlen [IN] size in bytes of buffer. Maybe retrieved with ctdbGetCndxIndexLength() or ctdbGetCndxIndexLengthByName().

Returns

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

See also

ctdbGetCndxIndex(), ctdbUpdateCndxIndex(), ctdbUpdateCndxIndexByName(), ctdbGetCndxIndexLength(), ctdbGetCndxIndexLengthByName()

ctdbGetCndxIndexLength

Retrieve the length in bytes of the conditional expression string, given the index number.

Declaration

NINT ctdbGetCndxIndexLength(CTHANDLE Handle, NINT indexnbr)

Description

ctdbGetCndxIndexLength() retrieves the length in bytes of the conditional expression string, given the index number. To retrieve the conditional expression, use ctdbGetCndxIndex() or ctdbGetCndxIndexByName(). The conditional expression is added, deleted or updated with ctdbUpdateCndxIndex() or ctdbUpdateCndxIndexByName().

• Handle [in] the Table Handle.
• indexnbr [in] the index number.

Returns

ctdbGetCndxIndexLength() returns the conditional index length in bytes on success or -1 on failure.

See also

ctdbGetCndxIndexLengthByName(), ctdbUpdateCndxIndex(), ctdbUpdateCndxIndexByName()

ctdbGetCndxIndexLengthByName

Retrieve the length in bytes of the conditional expression string, given the index name.

Declaration

NINT ctdbGetCndxIndexLengthByName(CTHANDLE Handle, pTEXT indexname)

Description

ctdbGetCndxIndexLengthByName() retrieves the length in bytes of the conditional expression string, given the index name. To retrieve the conditional expression, use ctdbGetCndxIndex() or ctdbGetCndxIndexByName(). The conditional expression is added, deleted or updated with ctdbUpdateCndxIndex() or ctdbUpdateCndxIndexByName().

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

Returns

ctdbGetCndxIndexLengthByName() returns the conditional index length in bytes on success or -1 on failure.

See also

ctdbGetCndxIndexLength(), ctdbUpdateCndxIndex(), ctdbUpdateCndxIndexByName()

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

ctdbGetDatabaseCount

Retrieve the number of databases in the session dictionary.

Declaration

NINT ctdbGetDatabaseCount(CTHANDLE Handle)

Description

ctdbGetDatabaseCount() returns the number of databases in the session dictionary.

• Handle [in] the session handle.

Returns

ctdbGetDatabaseCount() returns the number of databases in the session dictionary, or -1 on error.

See also
ctdbGetTableCount()

ctdbGetDatabaseHandle

Return the database handle.

Declaration

CTHANDLE ctdbGetDatabaseHandle(CTHANDLE Handle)

Description

ctdbGetDatabaseHandle() returns the database handle. To allocate a database handle, use ctdbAllocDatabase().

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

Returns

ctdbGetDatabaseHandle() returns the database handle or NULL on failure.

Example

db_name = ctdbGetDatabaseName(ctdbGetDatabaseHandle(hTable));

See also
ctdbAllocDatabase(), ctdbGetSessionHandle(), ctdbGetTableHandle()

ctdbGetDatabaseName

Return the database name.

Declaration

pTEXT ctdbGetDatabaseName(CTHANDLE Handle)

Description

ctdbGetDatabaseName() returns the database name.

• Handle [in] the Database Handle.

Returns

ctdbGetDatabaseName() returns the database name, or NULL on error.

Example

db_name = ctdbGetDatabaseName(ctdbGetDatabaseHandle(hTable));

See also
ctdbAllocDatabase(), ctdbGetDatabasePath()

ctdbGetDatabasePath

Return the database path.

Declaration

pTEXT ctdbGetDatabasePath(CTHANDLE Handle)

Description

ctdbGetDatabasePath() returns the database path. Note that the database path is set with ctdbCreateDatabase() as part of the database creation process. If no path was specified when the database was created (so the database was created in the default location), then ctdbGetDatabasePath() is likely to return an empty string.

• Handle [in] the Database Handle.

Records

ctdbGetDatabasePath() returns the database path, or NULL if no database path is available.

Example

eRet=ctdbConnect(hDatabase, "myDatabase", "");
db_path=ctdbGetDatabasePath(hDatabase);

See also
ctdbAllocDatabase(), ctdbGetDatabaseName()

ctdbGetDatabaseUID

Return the database UID, given a session handle and database name.

Declaration

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

Description

ctdbGetDatabaseUID() retrieves the database unique identifier, UID, given the database name. Note that the UID of a database persists as long as that database remains in the session dictionary. Removing a database from a session dictionary and then re-adding it to the session dictionary is very likely to change that database’s UID. Use ctdbGetActiveDatabaseUID() to retrieve the database UID, given the Database Handle. Use ctdbFindDatabaseByUID() to locate a database in a session by its unique identifier.

• Handle [in] - the session handle.
• Name [in] - the database name.
• pUid [out] - the database unique identifier.

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

See also
ctdbAllocSession(), ctdbFindDatabaseByUID(), ctdbGetActiveDatabaseUID()

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

ctdbGetDay

Retrieve the day of the month from a packed CTDATE.

Declaration

NINT ctdbGetDay(CTDATE date)

Description

ctdbGetDay() retrieves the day of the month from as packed CTDATE. To retrieve the month from a packed CTDATE, use ctdbGetMonth(). To retrieve the year from a packed CTDATE, use ctdbGetYear(). To retrieve the day of the week from a packed CTDATE, use ctdbDayOfWeek().

• date is the date in CTDATE format.

Returns

ctdbGetDay() returns the day of the month on success or 0 on error.

See also

ctdbGetMonth(), ctdbGetYear(), ctdbDayOfWeek()

ctdbGetDefaultIndex

Return the current default index.

Declaration

NINT ctdbGetDefaultIndex(CTHANDLE Handle)

Description

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

• Handle [in] the record handle.

Returns

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

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

See also

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

ctdbGetDefaultIndexName

Return the default index name.

Declaration

pTEXT ctdbGetDefaultIndexName(CTHANDLE Handle)

Description

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

• Handle [the] record handle.

Records

ctdbGetDefaultIndexName() returns the current default index name.

ctdbGetDefDateType

Retrieve the default date type.

Declaration

CTDATE_TYPE ctdbGetDefDateType(CTHANDLE Handle)

Description

ctdbGetDefDateType() retrieves the default date type for the present session. Use ctdbSetDefDateType() to define the default date type. Initially, the default is CTDATE_MDCY, indicating month, day, century, year (4 digits for the year). The possible date types are given in FairCom DB API definitions.

• Handle [in] any FairCom DB API Handle.

Returns

ctdbGetDefDateType() returns the default date type, or 0 on error.

ctdbGetDefFloatFormat

Retrieve the default floating point format string

Declaration

cpTEXT ctdbDECL ctdbGetDefFloatFormat(CTHANDLE Handle)

Description

ctdbGetDefFloatFormat() retrieves the default floating point format string.

• Handle [in] any FairCom DB API Handle.

Returns

ctdbGetDefFloatFormat() returns the string format to be used by sprintf() or sscanf().

ctdbGetDefTimeType

Retrieve the default time type.

Declaration

CTTIME_TYPE ctdbGetDefTimeType(CTHANDLE Handle)

Description

ctdbGetDefTimeType() retrieves the default time type for the present session. Initially, the default is CTTIME_HMP, indicating hour, minute and am/pm. The possible time types are given in FairCom DB API definitions. Use ctdbSetDefTimeType() to define the default time type.

• Handle [in] any FairCom DB API Handle.

Returns

ctdbGetDefTimeType() returns the default time type, or 0 on error.

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

Declaration

NINT ctdbDECL ctdbGetErrorIndex(CTHANDLE Handle);

Description

Retrieves the index number that cause a record insert or record update operation to fail. This function should only be called after a ctdbWriteRecord() call fails. The error index number value is maintained until the next call to ctdbWriteRecord().

• Handle must be a record handle

Return Values

A number from 0 to n to indicate which index caused the error. A value of 0 represents the first index, 1 represents the second index, and so on. If the index number can not be obtained, ctdbGetErrorIndex() returns -1.

See Also

ctdbWriteRecord()

ctdbGetField

Retrieve a field handle from a table, based on the field number.

Declaration

CTHANDLE ctdbGetField(CTHANDLE Handle, NINT Index)

Description

ctdbGetField() retrieves a field handle from a table, based on the field number. To retrieve a field handle from a table, based on the field name, use ctdbGetFieldByName(). To retrieve the field number, use ctdbGetFieldNumber().

• Handle [in] the Table Handle.
• Index [in] the field number that identifies the field in the table.

Returns

ctdbGetField() returns the field handle or NULL on error.

See also

ctdbAllocTable(), ctdbGetFieldByName(), ctdbGetFieldNumber()

ctdbGetFieldAddress

Retrieve the field address in record buffer

Declaration

pVOID ctdbGetFieldAddress(CTHANDLE Handle, NINT FieldNbr)

Description

ctdbGetFieldAddress() retrieves the field address in record buffer.

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

Returns

ctdbGetFieldAddress() returns the field address.

See also

ctdbGetFieldOffset()

ctdbGetFieldAsBigint

Retrieve field as big integer value.

Declaration

CTDBRET ctdbGetFieldAsBigint(CTHANDLE Handle, NINT FieldNbr,

pCTBIGINT pValue)

Description

ctdbGetFieldAsBigint() retrieves field as big integer. Use ctdbSetFieldAsBigint() to set field as a big integer value.

• Handle [in] the record handle.
• FieldNbr [in] the field number to be retrieved. To retrieve the field number given the record handle, use ctdbGetFieldNumberByName().
• pValue [out] the pointer to the big integer value.

Returns

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

See also

ctdbAllocRecord(), ctdbSetFieldAsBigint(), ctdbGetFieldAsBool(), ctdbGetFieldAsSigned(), ctdbGetFieldAsUnsigned(), ctdbGetFieldAsDate(), ctdbGetFieldAsTime(), ctdbGetFieldAsMoney(), ctdbGetFieldAsFloat(), ctdbGetFieldAsString(), ctdbGetFieldAsBlob(), ctdbSetFieldAsDateTime(), ctdbGetFieldNumber()

ctdbGetFieldAsBinary

Retrieve field as binary value.

Declaration

CTDBRET ctdbGetFieldAsBinary(CTHANDLE Handle, NINT FieldNbr,

pVOID pValue, VRLEN size)

Description

ctdbGetFieldAsBinary() retrieves field as binary. Any field may be retrieved as a binary value, and when this happens, no conversion is applied, and the binary value of the field is copied into the binary buffer.

Use ctdbSetFieldAsBinary() to set field as a binary value.

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

Returns

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

See also

ctdbAllocRecord(), ctdbSetFieldAsBinary(), ctdbGetFieldAsBool(), ctdbGetFieldAsSigned(), ctdbGetFieldAsUnsigned(), ctdbGetFieldAsDate(), ctdbGetFieldAsTime(), ctdbGetFieldAsMoney(), ctdbGetFieldAsFloat(), ctdbGetFieldAsString(), ctdbGetFieldAsBlob(), ctdbSetFieldAsDateTime(), ctdbGetFieldNumber()

ctdbGetFieldAsBlob

Retrieve field as blob value.

Declaration

CTDBRET ctdbGetFieldAsBlob(CTHANDLE Handle, NINT FieldNbr,

pCTBLOB pValue)

Description

ctdbGetFieldAsBlob() retrieves field as a blob value. Any field may be retrieved as a CTBLOB, and when this happens, no conversion is applied, and the binary value of the field is copied into the binary buffer.

Use ctdbSetFieldAsBlob() to set field as a CTBLOB value.

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetFieldAsBool(), ctdbGetFieldAsSigned(), ctdbGetFieldAsUnsigned(), ctdbGetFieldAsDate(), ctdbGetFieldAsTime(), ctdbGetFieldAsMoney(), ctdbGetFieldAsFloat(), ctdbGetFieldAsDateTime(), ctdbGetFieldAsString(), ctdbSetFieldAsBlob()

ctdbGetFieldAsBool

Retrieve field as boolean value.

Declaration

CTDBRET ctdbGetFieldAsBool(CTHANDLE Handle, NINT FieldNbr,

pCTBOOL pValue)

Description

ctdbGetFieldAsBool() retrieves field as boolean value. Use ctdbSetFieldAsBool() to set field as a CTBOOL value.

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetFieldAsSigned(), ctdbGetFieldAsUnsigned(), ctdbGetFieldAsDate(), ctdbGetFieldAsTime(), ctdbGetFieldAsMoney(), ctdbGetFieldAsFloat(), ctdbGetFieldAsDateTime(), ctdbGetFieldAsString(), ctdbGetFieldAsBlob(), ctdbSetFieldAsBool(), ctdbGetFieldNumber()

ctdbGetFieldAsCurrency

Retrieve field as a currency value.

Declaration

CTDBRET ctdbGetFieldAsCurrency(CTHANDLE Handle, NINT FieldNbr,

pCTCURRENCY pValue)

Description

ctdbGetFieldAsCurrency() retrieves field as currency value. Use ctdbSetFieldAsCurrency() to set field as a currency value.

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

Returns

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

See also

ctdbAllocRecord(), ctdbSetFieldAsCurrency(), ctdbGetFieldAsBool(), ctdbGetFieldAsSigned(), ctdbGetFieldAsUnsigned(), ctdbGetFieldAsDate(), ctdbGetFieldAsTime(), ctdbGetFieldAsMoney(), ctdbGetFieldAsFloat(), ctdbGetFieldAsString(), ctdbGetFieldAsBlob(), ctdbSetFieldAsDateTime(), ctdbGetFieldNumber()

ctdbGetFieldAsDate

Retrieve field as CTDATE value.

Declaration

CTDBRET ctdbGetFieldAsDate(CTHANDLE Handle, NINT FieldNbr,

pCTDATE pValue)

Description

ctdbGetFieldAsDate() retrieves field as CTDATE value. The type CTDATE is an unsigned four-byte integer, interpreted as date. Use ctdbSetFieldAsDate() to set field as a CTDATE value.

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetFieldAsBool(), ctdbGetFieldAsSigned(), ctdbGetFieldAsUnsigned(), ctdbGetFieldAsTime(), ctdbGetFieldAsMoney(), ctdbGetFieldAsFloat(), ctdbGetFieldAsDateTime(), ctdbGetFieldAsString(), ctdbGetFieldAsBlob(), ctdbSetFieldAsDate(), ctdbGetFieldNumber()

ctdbGetFieldAsDateTime

Retrieve field as CTDATETIME value.

Declaration

CTDBRET ctdbGetFieldAsDateTime(CTHANDLE Handle, NINT FieldNbr,

pCTDATETIME pValue)

Description

ctdbGetFieldAsDateTime() retrieves field as CTDATETIME value. Use ctdbSetFieldAsDateTime() to set field as a CTDATETIME value.

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetFieldAsBool(), ctdbGetFieldAsSigned(), ctdbGetFieldAsUnsigned(), ctdbGetFieldAsDate(), ctdbGetFieldAsTime(), ctdbGetFieldAsMoney(), ctdbGetFieldAsFloat(), ctdbGetFieldAsString(), ctdbGetFieldAsBlob(), ctdbSetFieldAsDateTime(), ctdbGetFieldNumber()

ctdbGetFieldAsFloat

Retrieve field as CTFLOAT value.

Declaration

CTDBRET ctdbGetFieldAsFloat(CTHANDLE Handle, NINT FieldNbr,

pCTFLOAT pValue)

Description

ctdbGetFieldAsFloat() retrieves field as float value. Use ctdbSetFieldAsFloat() to set field as a CTFLOAT value.

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetFieldAsBool(), ctdbGetFieldAsSigned(), ctdbGetFieldAsUnsigned(), ctdbGetFieldAsDate(), ctdbGetFieldAsTime(), ctdbGetFieldAsMoney(), ctdbGetFieldAsDateTime(), ctdbGetFieldAsString(), ctdbGetFieldAsBlob(), ctdbSetFieldAsFloat(), ctdbGetFieldNumber()

ctdbGetFieldAsJSON

Get a field as a CTJSON type value.

Declaration

ctdbEXPORT CTDBRET ctdbDECL ctdbGetFieldAsJSON(CTHANDLE Handle, NINT FieldNbr, CTJSON pValue, VRLEN size);

Description

• Handle [IN] - FairCom DB API C API record handle
• FieldNbr [IN] - Field number
• value [IN] - CTJSON type value

Returns

Return CTDBRET_OK on success.

ctdbGetFieldAsMoney

Retrieve field as CTMONEY value.

Declaration

CTDBRET ctdbGetFieldAsMoney(CTHANDLE Handle, NINT FieldNbr,

pCTMONEY pValue)

Description

ctdbGetFieldAsMoney() retrieves field as CTMONEY value. Use ctdbSetFieldAsMoney() to set field as a CTMONEY value.

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetFieldAsBool(), ctdbGetFieldAsSigned(), ctdbGetFieldAsUnsigned(), ctdbGetFieldAsDate(), ctdbGetFieldAsTime(), ctdbGetFieldAsFloat(), ctdbGetFieldAsDateTime(), ctdbGetFieldAsString(), ctdbGetFieldAsBlob(), ctdbSetFieldAsMoney(), ctdbGetFieldNumber()

ctdbGetFieldAsNumber

Retrieve field as a number value.

Declaration

CTDBRET ctdbGetFieldAsNumber(CTHANDLE Handle, NINT FieldNbr,

pCTNUMBER pValue)

Description

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

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

Returns

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

See also

ctdbAllocRecord(), ctdbSetFieldAsNumber(), ctdbGetFieldAsBool(), ctdbGetFieldAsSigned(), ctdbGetFieldAsUnsigned(), ctdbGetFieldAsDate(), ctdbGetFieldAsTime(), ctdbGetFieldAsMoney(), ctdbGetFieldAsFloat(), ctdbGetFieldAsString(), ctdbGetFieldAsBlob(), ctdbGetFieldNumber(), ctdbSetFieldAsNumber()

ctdbGetFieldAsSigned

Retrieve field as signed value.

Declaration

CTDBRET ctdbGetFieldAsSigned(CTHANDLE Handle, NINT FieldNbr,

pCTSIGNED pValue)

Description

ctdbGetFieldAsSigned() retrieves a field as a signed value. Use ctdbSetFieldAsSigned() to set a field as a CTSIGNED value.

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetFieldAsBool(), ctdbGetFieldAsUnsigned(), ctdbGetFieldAsDate(), ctdbGetFieldAsTime(), ctdbGetFieldAsMoney(), ctdbGetFieldAsFloat(), ctdbGetFieldAsDateTime(), ctdbGetFieldAsString(), ctdbGetFieldAsBlob(), ctdbSetFieldAsSigned(), ctdbGetFieldNumber()

ctdbGetFieldAsString

Retrieve field as CTSTRING value.

Declaration

CTDBRET ctdbGetFieldAsString(CTHANDLE Handle, NINT FieldNbr,

CTSTRING pValue, VRLEN size)

Description

ctdbGetFieldAsString() retrieves field as CTSTRING value. Use ctdbSetFieldAsString() to set field as a CTSTRING value.

• Handle [in] the record handle.
• FieldNbr [in] the field number to be retrieved. To retrieve the field number given the record handle, use ctdbGetFieldNumberByName().
• pValue [out] the pointer to the string value.
• size [in] pValue size in bytes.

Returns

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

Calling this function against a NULL CTDATE or CTTIMESTAMP field will return the following error codes:

• CTDATE: CTDBRET_INVDATE
• CTDATETIME: CTDBRET_INVDATETIME

Calling this function against a NULL field of other types will return CTDBRET_OK and populate the pValue parameter with the following values:

• CTBOOL: ”False”
• CTBIGINT, CTSIGNED, CTUNSIGNED, CTFLOAT, and CTNUMBER: ”0”
• CTMONEY: ”0.00”
• CTCURRENCY: ”0.0000”
• CTTIME: ”12:00 AM”
• CTSTRING: ””

See also

ctdbAllocRecord(), ctdbGetFieldAsBool(), ctdbGetFieldAsSigned(), ctdbGetFieldAsUnsigned(), ctdbGetFieldAsDate(), ctdbGetFieldAsTime(), ctdbGetFieldAsMoney(), ctdbGetFieldAsFloat(), ctdbGetFieldAsDateTime(), ctdbGetFieldAsBlob(), ctdbSetFieldAsString(), ctdbGetFieldNumber()

ctdbGetFieldAsTime

Retrieve field as CTTIME value with whole second precision.

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

Declaration

CTDBRET ctdbGetFieldAsTime(CTHANDLE Handle, NINT FieldNbr,

pCTTIME pValue)

Description

ctdbGetFieldAsTime() retrieves field as CTTIME value. Use ctdbSetFieldAsTime() to set field as a CTIME value.

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetFieldAsBool(), ctdbGetFieldAsSigned(), ctdbGetFieldAsUnsigned(), ctdbGetFieldAsDate(), ctdbGetFieldAsMoney(), ctdbGetFieldAsFloat(), ctdbGetFieldAsDateTime(), ctdbGetFieldAsString(), ctdbGetFieldAsBlob(), ctdbSetFieldAsTime(), ctdbGetFieldNumber(), ctdbGetFieldAsTimeMsec(), ctdbSetFieldAsTimeMsec()

ctdbGetFieldAsTimeMsec

Retrieve the field as a CTTIMEMS type value with millisecond precision.

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

Declaration

CTDBRET ctdbDECL ctdbGetFieldAsTimeMsec(CTHANDLE Handle, NINT FieldNbr, pCTTIMEMS pValue)

Parameters:

• Handle [IN] - CTDB C API record handle
• FieldNbr [IN] - The field number
• pValue [OUT] - Pointer to a CTTIMEMS type value to receive the time

Description

ctdbGetFieldAsTimeMsec() retrieve the field as a CTTIMEMS type value. This time type supports milliseconds.

Return Values

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

See Also

ctdbGetFieldAsTimeMsec, ctdbSetFieldAsTimeMsec, ctdbTimePackMsec, ctdbTimeUnpackMsec, ctdbDateTimeSetTimeMsec, ctdbDateTimeGetTimeMsec, ctdbDateTimePackMsec, ctdbDateTimeUnpackMsec, ctdbGetFieldAsTime(), ctdbSetFieldAsTime()

ctdbGetFieldAsUnsigned

Retrieve field as unsigned value.

Declaration

CTDBRET ctdbGetFieldAsUnsigned(CTHANDLE Handle, NINT FieldNbr,

pCTUNSIGNED pValue)

Description

ctdbGetFieldAsUnsigned() retrieves field as an unsigned value. Use ctdbSetFieldAsUnsigned() to set field as a CTUNSIGNED value.

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetFieldAsBool(), ctdbGetFieldAsSigned(), ctdbGetFieldAsDate(), ctdbGetFieldAsTime(), ctdbGetFieldAsMoney(), ctdbGetFieldAsFloat(), ctdbGetFieldAsDateTime(), ctdbGetFieldAsString(), ctdbGetFieldAsBlob(), ctdbSetFieldAsUnsigned(), ctdbGetFieldNumber()

ctdbGetFieldAsUTF16

Retrieves the field data as a Unicode UTF-16 string.

Declaration

CTDBRET ctdbGetFieldAsUTF16(CTHANDLE Handle, NINT FieldNbr, pWCHAR pValue, VRLEN size);

Description

ctdGetFieldAsUTF16() retrieves the field data as a Unicode UTF-16 string. If the underlying field type is not one of the Unicode field types, the data is converted to UTF-16 strings. Handle is a record handle, FieldNbr is the number of the field, pValue is a pointer to a wide (UTF-16) string buffer and size indicates the size in bytes of the string area.

Return

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

Example

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

{

CTDBRET eRet;

WCHAR WStr[32];

TEXT s[64];

CTSIGNED t;

if ((eRet = ctdbGetFieldAsUTF16(hRecord, 0, WStr, sizeof(WStr))) != CTDBRET_OK)

{

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

goto Exit;

}

if ((eRet = (CTDBRET)ctdb_u16TOu8(WStr, s, sizeof(s))) != CTDBRET_OK)

{

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

goto Exit;

}

if (strcmp(s, str) != 0)

{

printf("UNICODE field contents not the same written");

eRet = CTDBRET_DIFFERENT;

goto Exit;

}

if ((eRet = ctdbGetFieldAsSigned(hRecord, 1, &t)) != CTDBRET_OK)

{

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

goto Exit;

}

if ((NINT)t != val)

{

printf("integer field contents not the same written");

eRet = CTDBRET_DIFFERENT;

goto Exit;

}

Exit:

return eRet;

}

See Also

ctdbSetFieldAsUTF16()

ctdbGetFieldAutoSysTime

Get the setting of an autotimestamp field. If on output, both create and update are set to NO, the field has automatic assignment turned OFF.

Declaration

CTDBRET ctdbDECL ctdbGetFieldAutoSysTime(CTHANDLE Handle, pCTBOOL create, pCTBOOL update)

Description

• Handle [IN] - Field Handle.
• create [OUT] - YES when the field value is assigned on write of new records
• update [OUT] - YES when the field value is assigned on write of existing records

Returns

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

ctdbGetFieldByName

Retrieve a field handle from a table, based on the field name.

Declaration

CTHANDLE ctdbGetFieldByName(CTHANDLE Handle, pTEXT FieldName)

Description

ctdbGetFieldByName() retrieves a field handle from a table, based on the field name. To retrieve a field handle from a table, based on the field number, use ctdbGetField(). To retrieve the field number, use ctdbGetFieldNumber().

• Handle [in] the Table Handle.
• FieldName [in] the field name.

Returns

ctdbGetFieldByName() returns the field handle or NULL on error.

See also

ctdbAllocTable(), ctdbGetField(), ctdbGetFieldNumber()

ctdbGetFieldDataLength

Retrieve the field data actual length

Declaration

VRLEN ctdbGetFieldDataLength(CTHANDLE Handle, NINT FieldNbr)

Description

ctdbGetFieldDataLength() retrieves the actual length of the field data. This is the actual number of bytes being consumed by the data in a single field, in a single record (row) from a table. Use ctdbGetFieldSize() or ctdbGetFieldLength() to retrieve the defined field size from the table definition. Use ctdbGetFieldData() to retrieve the field data.

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

In V11 and later, a new field callback has been added. An array of function callbacks are available in FairCom DB API for table and field level control. These are extensively used by the FairCom DB SQL types SDK callback implementations. This is required, for example, when working with existing data types that are not compatible with expected SQL types. Several modifications were done to make this more effective across all data types.

When field callbacks are in place to manipulate field type and size, the SQL interface calls the following for LONG VARCHAR fields:

1. ctdbGetFieldSize() - Given a record handle and a field number, it returns its defined field size from the table definition.
2. ctdbGetFieldDataLength() - Given a record handle and a field number, it returns the field content size (the number of bytes actually being consumed by the data in the field).

To make these two functions work properly with field callback in place, these changes were made:

1. ctdbGetFieldSize() now takes advantage of the existing CTDB_FIELD_GET_LENGTH callback.
2. A new callback, CTDB_FIELD_DATA_LEN, is called by ctdbGetFieldDataLength().

Returns

ctdbGetFieldDataLength() returns the number of bytes being consumed by the data in this field.

See also

ctdbGetFieldSize()

ctdbGetFieldDefaultDateType

Retrieves the default value date type.

Declaration

CTDATE_TYPE ctdbGetFieldDefaultDateType(CTHANDLE Handle);

Description

Retrieves the default value date type used when converting strings to dates. Handle must be a FairCom DB API field handle.

Return

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

Example

/* check the default date type */
hField = ctdbGetField(hTable, 5);
if (ctdbGetFieldDefaultDateType(hField) != CTDATE_MDCY)
	printf("Default date type is not OK\n");

See also

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

ctdbGetFieldDefaultTimeType

Retrieves the default value time type.

Declaration

CTTIME_TYPE ctdbGetFieldDefaultTimeType(CTHANDLE Handle);

Description

Retrieves the default value time type used when converting strings to dates. Handle must be a FairCom DB API field handle.

Return

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

Example

/* check the default time type */
hField = ctdbGetField(hTable, 5);
if (ctdbGetFieldDefaultTimeType(hField) != CTDBRET_OK)
    printf("Default time type is not OK\n");

See Also

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

ctdbGetFieldDefaultValue

Retrieves the current field default value.

DECLARATION

pTEXT ctdbGetFieldDefaultValue(CTHANDLE Handle, pVRLEN pLength);

DESCRIPTION

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

RETURN

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

EXAMPLE

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

hField = ctdbGetField(hTable, 5);

if (hField)

{

VRLEN len;

pTEXT value = ctdbGetFieldDefaultValue(hField, &len);

if (value)

{

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

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

else

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

}

else

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

}

SEE ALSO

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

ctdbGetFieldHandle

Retrieve a Field Handle.

Declaration

CTHANDLE ctdbGetFieldHandle(CTHANDLE Handle)

Description

ctdbGetFieldHandle() retrieves a Field Handle. This function can be used to test if a handle is really a field handle. For example, assume a function should take a field handle, but inside the function you cast the CTHANDLE type to the field CTDFIELD structure. For safety, it is a good idea to make sure that the handle is really a field handle as shown in the example below. Another minor reason for this call is to perform a ctdbSWTCREEI() call.

CTBOOL IsFieldNumeric(CTHANDLE hField)

{

CTBOOL Retval = FALSE;

pCTDBFIELD pField = (pCTDBFIELD)ctdbGetFieldHandle(hField);

if (!pField)

{

printf("Error: hField is not a field handle");

}

...

...

return Retval;

}

To allocate a field handle, use ctdbAllocField().

• Handle [in] may be a field handle, an index handle, or a segment handle.

Returns

ctdbGetFieldHandle() returns a field handle on success or NULL on error.

See also

ctdbAllocField(), ctdbGetRecordHandle(), ctdbGetIndexHandle(), ctdbGetSegmentHandle()

ctdbGetFieldLength

Retrieve the field length (the defined size of the field).

Declaration

VRLEN ctdbGetFieldLength(CTHANDLE Handle)

Description

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

• Handle [in] the Field Handle. This must be a field handle, and not any other handle type.

Returns

ctdbGetFieldLength() returns the field length, or -1 on failure

See also

ctdbAllocField(), ctdbGetFieldNumber(), ctdbGetFieldName(), ctdbGetFieldType(), ctdbGetFieldLength(), ctdbSetFieldLength()

ctdbGetFieldName

Retrieve the field name

Declaration

pTEXT ctdbGetFieldName(CTHANDLE Handle)

Description

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

• Handle [in] the Field Handle.

Returns

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

See also

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

ctdbGetFieldNbr

Retrieve the field number in the table fields list

Declaration

NINT ctdbGetFieldNbr(CTHANDLE Handle)

Description

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

• Handle [in] the Field Handle.

Returns

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

See also

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

ctdbGetFieldNullFlag

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

Declaration

CTBOOL ctdbGetFieldNullFlag(CTHANDLE Handle)

Description

ctdbGetFieldNullFlag() retrieves the field null flag.

• Handle [in] the Field Handle.

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

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

Returns

ctdbGetFieldNullFlag() returns the field NULL flag.

See also

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

ctdbGetFieldNumber

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

Declaration

NINT ctdbGetFieldNumber(CTHANDLE Handle, pTEXT FieldName)

Description

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

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

Returns

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

Example

pMyTable1 = ctdbAllocTable(pMyDB1);

ctdbOpenTable(pMyTable1, "customer", CTOPEN_NORMAL);

fldnbr = ctdbGetFieldNumber(pMyTable1, "Name");

See also

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

ctdbGetFieldNumberByName

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

Declaration

NINT ctdbGetFieldNumberByName(CTHANDLE Handle, pTEXT FieldName)

Description

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

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

Returns

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

Example

pMyRec1 = ctdbAllocRecord(pMyTable1);

ctdbFirstRecord(pMyRec1);

fldnbr = ctdbGetFieldNumberByName(pMyRec1, "Name");

See also

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

ctdbGetFieldOffset

Retrieve the field offset in record buffer

Declaration

VRLEN ctdbGetFieldOffset(CTHANDLE Handle, NINT FieldNbr)

Description

ctdbGetFieldOffset() retrieves the field offset in record buffer.

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

Returns

ctdbGetFieldOffset() returns the field offset.

Example

pMyRec1 = ctdbAllocRecord(pMyTable1);

ctdbFirstRecord(pMyRec1);

field0_offset = ctdbGetFieldOffset(pMyRec1, 0);

See also

ctdbGetFieldAddress()

ctdbGetFieldPrecision

Retrieve the field precision.

Declaration

NINT ctdbGetFieldPrecision(CTHANDLE Handle)

Description

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

• Handle [in] the Field Handle.

Returns

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

CT_MONEY:

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

See also

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

ctdbGetFieldProperties

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

Declaration

CTDBRET ctdbGetFieldProperties(CTHANDLE Handle, ppTEXT FieldName,

pCTDBTYPE pType, pVRLEN pLength)

Description

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

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

Returns

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

See also

ctdbAllocField(), ctdbSetFieldProperties()ctdbGetFieldProperties

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

Declaration

CTDBRET ctdbGetFieldProperties(CTHANDLE Handle, ppTEXT FieldName,

pCTDBTYPE pType, pVRLEN pLength)

Description

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

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

Returns

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

See also

ctdbAllocField(), ctdbSetFieldProperties()

ctdbGetFieldScale

Retrieve the field scale.

Declaration

NINT ctdbGetFieldScale(CTHANDLE Handle)

Description

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

• Handle [in] the Field Handle.

Returns

ctdbGetFieldScale() returns the field scale.

See also

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

ctdbGetFieldSize

Retrieve the defined field size from the table definition.

Declaration

VRLEN ctdbGetFieldSize(CTHANDLE Handle, NINT FieldNbr)

Description

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

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

Returns

ctdbGetFieldSize() returns the defined field size.

See also

ctdbGetFieldDataLength(), ctdbGetFieldLength()

ctdbGetFieldStatus

Retrieves the changed status of a field handle.

DECLARATION

ULONG ctdbGetFieldStatus(CTHANDLE Handle);

DESCRIPTION

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

RETURN

ctdbGetFieldStatus() returns a bitmap of the following:

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

EXAMPLE

/* if field is new delete it */

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

{

CTHANDLE hField = ctdbGetField(hTable, i);

if (ctdbGetFieldStatus(hField) & CTDBFIELD_NEW)

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

printf("ctdbDelField failed\n");

}

SEE ALSO

ctdbGetIndexStatus(), ctdbGetSegmentStatus()

ctdbGetFieldStringEncoding

Get the encoding set on the field as a string.

Declaration

ctdbEXPORT cpTEXT ctdbDECL ctdbGetFieldStringEncoding( CTHANDLE Handle )

Description

• Handle [IN] - the associated field handle.

ctdbGetFieldStringEncoding() returns the encoding set on the field as a string or Null if no encoding was set or an error occurred. Check ctdbGetError().

Calling ctdbGetFieldStringEncoding() on a field without an encoding set results in returning NULL.

Returns

FairCom DB API error code

ctdbGetFieldType

Retrieve the field type.

Declaration

CTDBTYPE ctdbGetFieldType(CTHANDLE Handle)

Description

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

• Handle [in] the Field Handle.

Returns

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

See also

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

ctdbGetFilter

Retrieve the filter from the table.

Declaration

pTEXT ctdbGetFilter(CTHANDLE Handle)

Description

ctdbGetFilter() retrieves the current filter expression for the table.

To insert a filter, use ctdbFilterRecord(). To verify if there is a filter active in the table, use ctdbIsFilteredRecord().

• Handle [in] the Table or record handle.

Returns

ctdbGetFilter() returns a pointer to a string with the filter expression. If no filters are active, return NULL.

Example

/* print the expression */

if (ctdbGetFilterType(hRecord) == CTFILTER_TEXT)

printf("Filter expression: %s\n", ctdbGetFilter(hRecord));

See also

ctdbFilterRecord(), ctdbIsFilteredRecord()

ctdbGetFirstActiveDatabase

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

Declaration

CTHANDLE ctdbGetFirstActiveDatabase(CTHANDLE Handle,

pVRLEN pScanIndex)

Description

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

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

Returns

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

See also

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

ctdbGetFirstActiveTable

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

Declaration

CTHANDLE ctdbGetFirstActiveTable(CTHANDLE Handle, pVRLEN pScanRec)

Description

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

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

Returns

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

See also

ctdbAllocDatabase(), ctdbGetNextActiveTable(), ctdbFindActiveTable()

ctdbGetFirstPartition

Retrieves the first partition number of the table.

Declaration

LONG ctdbGetFirstPartition(CTHANDLE Handle)

Description

• ctdbGetFirstPartition() returns the first raw partition number for the file if partitions exist. If -1 is returned, call ctdbGetError() to retrieve the ISAM error code. If this value is zero, the file has no active partitions. If uerr_cod is non-zero, an error occurred. For example, if the specified file number does not correspond to a partition host file, ctdbGetFirstPartition() returns -1 and ctdbGetError() returns PHST_ERR. ctdbGetError() will return CTDBRET_NOTACTIVE, or CTDBRET_NOTTABLE, if an invalid table handle is passed in.

Returns

ctdbGetFirstPartition() returns the first raw partition number or -1 if not found.

See also

ctdbGetLastPartition()

ctdbGetFTI

Retrieve the Full-Text Search handle.

ctdbGetFTIByName

Retrieve the index handle given the index name.

ctdbGetFTIByUID

Retrieve an FTI by its unique ID (the Full Text Index counterpart of ctdbGetIndexByUID).

ctdbGetFTIField

Retrieve the field handle of the field indicated by FieldNumber.

ctdbGetFTIFieldCount

Retrieve the number of segments associated with this index.

ctdbGetFTIFieldMode

Return the field mode specified when adding the field to the FTI.

ctdbGetFTIHandle

Return the Full-Text Search handle or NULL on failure.

ctdbGetFTIName

Retrieve the name of the Full-Text Index (FTI).

ctdbGetFTINbr

Get the number of an FTI in the FTI list (the Full Text Index counterpart of ctdbGetIndexNbr).

ctdbGetFTINbrByName

Retrieve the index number given the index name.

ctdbGetFTIStatus

Retrieve the status of the index handle.

ctdbGetHandleType

Retrieves the handle type.

DECLARATION

NINT ctdbGetHandleType(CTHANDLE Handle);

DESCRIPTION

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

RETURN

ctdbGetHandleType() return one of the following values:

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

EXAMPLE

pCTDBSESSION pSession;

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

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

SEE ALSO

ctdbGetLocalTag(), ctdbSetLocalTag()

ctdbGetHour

Get the hour from a packed CTTIME.

Declaration

NINT ctdbGetHour(CTTIME Time)

Description

ctdbGetHour() gets the hour from a packed CTTIME.

• Time is the packed time in CTTIME format.

Returns

ctdbGetHour() returns the hour on success, or -1 on error.

See also

ctdbGetMinute(), ctdbGetSecond()

ctdbGetIdentityFieldDetails

Declaration

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

Description

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

Return Values

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

Example

LONG startval, incval;

TEXT astring[80];
pTEXT idcol = astring;

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

if (idcol)

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

startval, incval);

else

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

ctdbGetError() );

See Also

ctdbGetLastIdentity(). ctdbSetIdentityField()

ctdbGetIdxno

Retrieve the index file number from a index handle.

DECLARATION

NINT ctdbGetIdxno(CTHANDLE Handle)

DESCRIPTION

Retrieves the index file number to be used with c-tree ISAM or low-level index functions.

• Handle must be an index or segment handle.

Returns the index number on success or -1 on failure. If ctdbGetIdxno() function 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

/* retrieve the first key of first index */

TEXT keyval[256];

COUNT idxno = (COUNT)ctdbGetIdxno(ctdbGetIdnex(hTable, 0));

if (FirstKey(idxno, 0), keyval)

printf("FirstKey failed\n");

SEE ALSO

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

ctdbGetIdxnoByName

Retrieve the index file number from a table handle.

Declaration

NINT ctdbGetIdxnoByName(CTHANDLE Handle, pTEXT indexname)

Description

Retrieve the index file number to be used with c-tree ISAM or low-level index functions.

• Handle is a table handle.
• indexname is a string containing the index name.

Return the index number on success or -1 on failure. If ctdbGetIdxnoByNumber() return -1, the error code can be retrieved by calling ctdbGetError() function.

Return

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

/* retrieve the first key of first index */

TEXT keyval[256];

COUNT idxno = (COUNT)ctdbGetIdxnoByName(hTable, "indexname");

if (FirstKey(idxno, 0), keyval)

printf("FirstKey failed\n");

See also

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

ctdbGetIdxnoByNumber

Retrieve the index file number from a table handle.

DECLARATION

NINT ctdbGetIdxnoByNumber(CTHANDLE Handle, NINT index)

DESCRIPTION

Retrieves the index file number to be used with c-tree ISAM and low-level index functions.

• Handle is a table handle.
• index is a FairCom DB API index number. The first FairCom DB API index number is zero.

Returns the index number on success or -1 on failure. If ctdbGetIdxnoByNumber() returns -1, the error code can be retrieved by calling ctdbGetError() function.

RETURN

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

EXAMPLE

/* retrieve the first key of first index */

TEXT keyval[256];

COUNT idxno = (COUNT)ctdbGetIdxnoByNumber(hTable, 0);

if (FirstKey(idxno, 0), keyval)

printf("FirstKey failed\n");

SEE ALSO

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

ctdbGetIndex

Retrieve the handle for index identified by IndexNumber.

Declaration

CTHANDLE ctdbGetIndex(CTHANDLE Handle, NINT IndexNumber)

Description

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

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

Returns

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

See also

ctdbAllocTable(), ctdbGetIndexHandle(), ctdbGetIndexNbr()

ctdbGetIndexByName

Retrieve the index handle given the index name

Declaration

CTHANDLE ctdbGetIndexByName(CTHANDLE Handle, pTEXT name)

Description

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

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

Returns

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

See also

ctdbGetIndex(), ctdbGetIndexByUID(), ctdbGetIndexNbrByName()

ctdbGetIndexByUID

Retrieve the index handle given the index UID

Declaration

CTHANDLE ctdbGetIndexByUID(CTHANDLE Handle, ULONG uid)

Description

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

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

Returns

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

See also

ctdbGetIndexNbr(), ctdbGetIndexNbrByName()

ctdbGetIndexCndxExpr

Retrieve the conditional expression given for the index handle.

Declaration

pTEXT ctdbDECL ctdbGetIndexCndxExpr(CTHANDLE Handle)

Description

Handle [IN] - Index handle

Return Values

Returns Conditional expression

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

See Also

Conditional Expressions

ctdbGetIndexDistinctKeyCountFlag

Get the status of the distinct count flag for an index. To optimize some SQL queries, provides a better estimation of the duplicate index selectivity by determining how many distinct keys there are in an index allowing duplicates. The CTDBINDEX_DUPCNTFLAG index status value indicates that the index has distinct key count capability.

Declaration

CTBOOL ctdbGetIndexDistinctKeyCountFlag(CTHANDLE Handle);

Description

ctdbGetIndexDistinctKeyCountFlag() retrieves the setting of the distinct count flag for an index. Use ctdbSetIndexDistinctKeyCountFlag() to set the flag.

• Handle [in] the index handle.

See also

ctdbSetIndexDistinctKeyCountFlag

ctdbGetIndexDuplicateFlag

Retrieve the allow duplicate key flag for this index.

Declaration

CTBOOL ctdbGetIndexDuplicateFlag(CTHANDLE Handle)

Description

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

• Handle [in] the index handle.

Returns

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

See also

ctdbAllocIndex(), ctdbSetIndexDuplicateFlag()

ctdbGetIndexEmptyChar

Retrieve the empty char property for this index

Declaration

NINT ctdbGetIndexEmptyChar(CTHANDLE Handle)

Description

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

• Handle [in] the index handle.

Returns

ctdbGetIndexEmptyChar() returns the empty char property.

See also

ctdbAllocIndex(), ctdbSetIndexEmptyChar()v

ctdbGetIndexExtension

Retrieve the table index file name extension.

Declaration

pTEXT ctdbGetIndexExtension(CTHANDLE Handle)

Description

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

• Handle [in] the Table Handle.

Returns

ctdbGetIndexExtension() returns the index file name extension.

See also

ctdbAllocTable(), ctdbSetIndexExtension()

ctdbGetIndexFilename

Retrieves the current index file name associated with an index.

Declaration

pTEXT ctdbGetIndexFilename(CTHANDLE Handle);

• Handle is an index handle returned by ctdbAddIndex() or ctdbGetIndex() calls.

Description

ctdbGetIndexFilename() may return NULL indicating that the index is a member of an index superfile.

Return

ctdbGetIndexFilename() returns the physical filename of the index.

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.

See also

ctdbSetIndexFilename(), ctdbAddIndex(), ctdbGetIndex()

ctdbGetIndexHandle

Retrieve the index handle.

Declaration

CTHANDLE ctdbGetIndexHandle(CTHANDLE Handle)

Description

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

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

Returns

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

See also

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

ctdbGetIndexKeyLength

Retrieve the key length for this index.

Declaration

VRLEN ctdbGetIndexKeyLength(CTHANDLE Handle)

Description

ctdbGetIndexKeyLength() retrieves the key length for this index.

• Handle [in] the index handle.

Returns

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

See also

ctdbAllocIndex()

ctdbGetIndexKeyType

Retrieve the key type for this index.

Declaration

CTDBKEY ctdbGetIndexKeyType(CTHANDLE Handle)

Description

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

• Handle [in] the index handle.

Use ctdbSetIndexKeyType() to set the Index key type.

Returns

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

See also

ctdbAllocIndex(), ctdbAddIndex(), ctdbSetIndexKeyType()

ctdbGetIndexKSeg

Retrieves the index current extended key segment definition.

DECLARATION

CTDBRET ctdbGetIndexKSeg(CTHANDLE Handle, pctKSEGDEF pKSeg);

DESCRIPTION

ctdbGetIndexKSeg() retrieves the current index-wide extended key segment definition. Handle must be a FairCom DB API index handle and pKSeg is a pointer to an extended key segment definition structure which will receive the definition.

RETURN

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

EXAMPLE

ctKSEGDEF kseg;

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

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

SEE ALSO

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

ctdbGetIndexName

Retrieve the index name

Declaration

pTEXT ctdbGetIndexName(CTHANDLE Handle)

Description

ctdbGetIndexName() retrieves the index name.

• Handle [in] the index handle.

Returns

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

See also

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

ctdbGetIndexNbr

Retrieve the index number in the table list.

Declaration

CTDBRET ctdbGetIndexNbr(CTHANDLE Handle, pVRLEN pNumber)

Description

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

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

Returns

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

See also

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

ctdbGetIndexNbrByName

Retrieve the index number given the index name

Declaration

NINT ctdbGetIndexNbrByName(CTHANDLE Handle, pTEXT name)

Description

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

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

Returns

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

See also

ctdbGetIndexNbr(), ctdbGetIndexByName(), ctdbGetIndexByUID()

ctdbGetIndexNullFlag

Retrieve the null key flag for this index

Declaration

CTBOOL ctdbGetIndexNullFlag(CTHANDLE Handle)

Description

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

• Handle [in] the index handle.

Returns

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

See also

ctdbAllocIndex(), ctdbSetIndexNullFlag()

ctdbGetIndexSegmentCount

Retrieve the number of segments associated with this index

Declaration

VRLEN ctdbGetIndexSegmentCount(CTHANDLE Handle)

Description

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

• Handle [in] the index handle.

Returns

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

See also

ctdbAllocIndex()

ctdbGetIndexStatus

Retrieves the status of the index handle.

DECLARATION

ULONG ctdbGetIndexStatus(CTHANDLE Handle);

DESCRIPTION

Retrieves the status of the index handle. Handle is a FairCom DB API index handle.The status of the index handle is a bit map describing one or more changes that have occurred to the index object.

RETURN

ctdbGetIndexStatus() returns a bitmap of the following::

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

EXAMPLE

/* if the index has been changed, call alter table */

CTHANDLE hIndex = ctdbGetIndex(hTable, 0);

if (ctdbGetIndexStatus(hIndex) != CTDBINDEX_OLD)

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

printf("ctdbAlterTable failed\n");

SEE ALSO

ctdbGetFieldStatus(), ctdbGetSegmentStatus()

ctdbGetIndexTemporaryFlag

Retrieve the flag that indicates this index as temporary.

Declaration

CTBOOL ctdbGetIndexTemporaryFlag(CTHANDLE Handle)

Description

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

• Handle [in] the index handle.

Returns

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

See also

ctdbAllocIndex(), ctdbSetIndexTemporaryFlag()

ctdbGetIndexUID

Retrieve the index UID number.

Declaration

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

Description

ctdbGetIndexUID() retrieves the index unique identifier number.

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

Returns

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

See also

ctdbGetIndexNbr()

ctdbGetKeepLock

Retrieves the current extended keep lock mode.

DECLARATION

CTKEEP_MODE ctdbDECL ctdbGetKeepLock(CTHANDLE Handle);

DESCRIPTION

ctdbGetKeepLock() retrieves the current state of how the transaction commit and abort will handle locks acquired before and during the transaction.

• Handle is a session handle.

RETURN

One of the following keep lock modes is returned:

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

EXAMPLE

/* make sure the current keep lock mode is CTKEEP_LOCK */

if (ctdbGetKeepLock(hSession) != CTKEEP_LOCK)

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

printf("ctdbSetKeepLock failed\n");

SEE ALSO

ctdbAbort ctdbBegin(), ctdbCommit(), ctdbSetKeepLock()

ctdbGetLastIdentity

Declaration

CTDBRET ctdbGetLastIdentity(CTHANDLE Handle, pLONG8 value)

Description

Returns the last Identity value.

Return Values

ctdbGetLastIdentity returns the last Identity value assigned.

Example

ctdbGetLastIdentity( myTable, &lastval );

See Also

ctdbGetIdentityFieldDetails(), ctdbSetIdentityField()

ctdbGetLastPartition

Retrieves the last partition number of the table.

Declaration

LONG ctdbGetLastPartition(CTHANDLE Handle)

Description

ctdbGetLastPartition() returns the last raw partition number for the file if partitions exist. If -1 is returned, call ctdbGetError() to retrieve the ISAM error code. If this value is zero, the file has no active partitions. If uerr_cod is non-zero, an error occurred. For example, if the specified file number does not correspond to a partition host file, ctdbGetLastPartition() returns -1 and ctdbGetError() returns PHST_ERR. ctdbGetError() will return CTDBRET_NOTACTIVE, or CTDBRET_NOTTABLE, if an invalid table handle is passed in.

Returns
ctdbGetLastPartition() returns the last raw partition number or -1 if not found.

See also
ctdbGetFirstPartition()

ctdbGetLibType

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

Declaration

CTLIB_TYPE ctdbGetLibType(CTHANDLE Handle)

Description

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

• Handle the Database Handle.

Returns

ctdbGetLibType returns a value of type CTLIB_TYPE.

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

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

ctdbGetLocalTag

Retrieves the local tag associate with a handle.

DECLARATION

pVOID ctdbGetLocalTag(CTHANDLE Handle);

DESCRIPTION

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

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

RETURN

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

EXAMPLE

if (ctdbGetLocalTag(Handle))

{

pSession->onFree(ctdbGetLocalTag(Handle));

ctdbSetLocalTag(Handle, NULL);

}

SEE ALSO

ctdbGetHandleType(), ctdbSetLocalTag()

ctdbGetLockMode

Retrieve the current session-wide lock mode.

Declaration

CTLOCK_MODE ctdbGetLockMode(CTHANDLE Handle)

Description

ctdbGetLockMode() retrieves the current session-wide lock mode. Valid lock modes are presented in Session-Wide Lock Modes. Note that this function does not give the lock status of an individual record. Instead, it tells you if session-wide record locking is turned on or off, suspended or not, etc., so you know if a record will be automatically locked the next time you read it from disk.

• Handle [in] the Session or any other FairCom DB API .NET Handle.

Returns
ctdbGetLockMode() returns the session-wide lock mode.

See also
ctdbLock(), ctdbIsLockActive(), Locking, Session-Wide Lock Modes

ctdbGetLogonOnly

Retrieve the session logon only flag.

Declaration

CTBOOL ctdbGetLogonOnly(CTHANDLE Handle)

Description

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

To set the flag, use ctdbSetLogonOnly().

• Handle [in] the session handle.

Returns

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

Example

if (!cdbGetLogonOnly(hSession))

err = ctdbConnect(hDatabase, "MyDatabase");

See also

ctdbSetLogonOnly()

ctdbGetMinute

Get the minute from a packed CTTIME.

Declaration

NINT ctdbGetMinute(CTTIME Time)

Description

ctdbGetMinute() gets the minute from a packed CTTIME.

• Time is the packed time in CTTIME format.

Returns

ctdbGetMinute() returns the minute, on success or -1 on error.

See also

ctdbGetHour(), ctdbGetSecond()

ctdbGetMonth

Retrieve the month of the year from a packed CTDATE.

Declaration

NINT ctdbGetMonth(CTDATE date)

Description

ctdbGetMonth() retrieves the month of the year from a packed CTDATE. To retrieve the day of the month from a packed CTDATE, use ctdbGetDay(). To retrieve the year from a packed CTDATE, use ctdbGetYear().

• date is the date in CTDATE format.

Returns

ctdbGetMonth() returns the month of the year on success or 0 on error.

See also

ctdbGetDay(), ctdbGetYear()

ctdbGetNextActiveDatabase

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

Declaration

CTHANDLE ctdbGetNextActiveDatabase(CTHANDLE Handle, pVRLEN pScanIndex)

Description

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

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

Returns

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

See also

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

ctdbGetNextActiveTable

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

Declaration

CTHANDLE ctdbGetNextActiveTable(CTHANDLE Handle, pVRLEN pScanRec)

Description

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

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

Returns

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

See also

ctdbAllocSession(), ctdbGetFirstActiveTable(), ctdbFindActiveTable()

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

ctdbGetPadChar

Retrieve the table pad and field delimiter characters.

Declaration

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

Description

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

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

Returns

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

See also

ctdbSetPadChar(), ctdbUpdatePadChar()

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

ctdbGetRebuildProgress

Retrieves the table’s rebuild progress counter.

DECLARATION

NINT ctdbGetRebuildProgress(CTHANDLE Handle);

DESCRIPTION

When a full alter table rebuild is in progress, the table handle keeps a counter of the progress. The progress is kept in terms of percent completed with values from 0% to 100%.

You can use this function with a CTDB_ON_TABLE_REBUILD callback to retrieve the progress indicator. CTDB_ON_TABLE_REBUILD is called for each percentage point. Before any records are processed, CTDB_ON_TABLE_REBUILD callback is called with a percentage value of zero to indicate that the operation is about to start. After all records are processed, CTDB_ON_TABLE_REBUILD is called again, this time with a percentage value of 100 to indicate the end of rebuild.

RETURN

A progress counter value from 0 to 100.

EXAMPLE

CTDBRET ctdbDECL OnTableRebuild(CTHANDLE Handle)

{

/* display a dot for every 5% rebuild completed */

NINT perc = ctdbGetREbuildProgress(Handle);

if (perc > 0 && (perc % 5) == 0)

printf(".");

return CTDBRET_OK;

}

SEE ALSO

ctdbClearAllCallback(), ctdbClearCallback(), ctdbGetCallback(), ctdbSetCallback()

ctdbGetRecord

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

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

Declaration

CTHANDLE ctdbGetRecord(CTHANDLE Handle, NINT index)

Description

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

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

Returns

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

See also

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

ctdbGetRecordBuffer

Return a pointer to the current record buffer.

Declaration

pVOID ctdbGetRecordBuffer(CTHANDLE Handle)

Description

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

• Handle [in] the record handle.

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

Returns

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

See also

ctdbAllocRecord(), ctdbGetRecordLength()

ctdbGetRecordCount

Retrieve the number of records in Table.

Declaration

CTDBRET ctdbGetRecordCount(CTHANDLE Handle, pCTUINT64 pCount)

Description

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

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

Returns

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

See also

• ctdbGetRecordCount behavior on MRT Table modified
• ctdbAllocRecord()

ctdbGetRecordCount behavior on MRT Table modified

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

The behavior on MRT Tables has been changed as follows:

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

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

Note: This is a Compatibility Change.

ctdbGetRecordHandle

Retrieve the record handle

Declaration

CTHANDLE ctdbGetRecordHandle(CTHANDLE Handle)

Description

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

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

Returns

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

See also

ctdbAllocRecord()

ctdbGetRecordKeyPos

Retrieve the given record position in the default index.

Syntax

CTDBRET ctdbDECL ctdbGetRecordKeyPos(CTHANDLE Handle, pCTOFFSET pPosition)

Parameters

• Handle [IN] - FairCom DB API C API record handle
• pPosition [OUT] - Position in the given index

Description

Retrieves the given record position in the default index. The returned position is the Ordinal key position, not a file offset.

Return

CTDBRET_OK on success.

ctdbGetRecordLength

Return the current record length.

Declaration

VRLEN ctdbGetRecordLength(CTHANDLE Handle)

Description

ctdbGetRecordLength() returns the current record length.

• Handle [in] the record handle.

Returns

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

See also

ctdbAllocRecord(), ctdbGetRecordBuffer(), ctdbGetRecordSize()

ctdbGetRecordLock

Return the record lock status.

Declaration

CTLOCK_MODE ctdbGetRecordLock(CTHANDLE Handle)

Description

ctdbGetRecordLock() retrieves the record lock status.

• Handle [in] the record handle.

Returns

ctdbGetRecordLock() returns the lock mode of a single record, in particular, CTLOCK_FREE if the record is not locked, CTLOCK_READ if the record has a read lock or CTLOCK_WRITE if the record has a write lock. This works both for records automatically locked with session-wide record locking (see ctdbLock()), and for records manually locked via calls to ctdbLockRecord().

See also

ctdbAllocRecord(), ctdbLockRecord(), ctdbUnlockRecord(), Locking

ctdbGetRecordNbr

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

Declaration

NINT ctdbGetRecordNbr(CTHANDLE Handle)

Description

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

• Handle [in] the record handle.

Returns

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

See also

ctdbAllocRecord(), ctdbGetRecordBuffer(), ctdbGetRecordLength()

ctdbGetRecordPos

Retrieve the current record offset position.

Declaration

CTDBRET ctdbGetRecordPos(CTHANDLE Handle, pCTOFFSET pOffset)

Description

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

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

Returns

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

See also

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

ctdbGetRecordSize

Return the allocated record buffer size in bytes.

Declaration

VRLEN ctdbGetRecordSize(CTHANDLE Handle)

Description

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

• Handle [in] the record handle.

Returns

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

See also

ctdbAllocRecord(), ctdbGetRecordBuffer(), ctdbGetRecordLength()

ctdbGetResourceData

Return a pointer to the resource data.

DECLARATION

pVOID ctdbDECL ctdbGetResourceData(CTHANDLE resource);

DESCRIPTION

Returns a pointer to the resource data. Call this function to retrieve the resource data pointer after a resource is read by one of ctdbFirstResource(), ctdbNextResource(), ctdbFindResource() or ctdbFindResourceByName().

• resource is a handle returned by ctdbAllocResource().

RETURN

Return a pointer to resource data

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(), ctdbFirstResource(), ctdbNextResource(), ctdbFindResource(), ctdbFindResourceByName(), ctdbGetResourceType(), ctdbSetResourceType(), ctdbGetResourceNumber(), ctdbSetResourceNumber(), ctdbGetResourceName(), ctdbSetResourceName(), ctdbGetResourceDataLength(), ctdbGetResourceData(), ctdbSetResourceData(), ctdbIsResourceLocked(), ctdbUnlockResource()

ctdbGetResourceDataLength

Retrieves the resource data length.

DECLARATION

VRLEN ctdbDECL ctdbGetResourceDataLength(CTHANDLE resource);

DESCRIPTION

Retrieves the resource data length as the number of bytes occupied by the resource data.

• resource is a handle allocated by ctdbAllocResource().

RETURN

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(), ctdbFirstResource(), ctdbNextResource(), ctdbFindResource(), ctdbFindResourceByName(), ctdbGetResourceType(), ctdbSetResourceType(), ctdbGetResourceNumber(), ctdbSetResourceNumber(), ctdbGetResourceName(), ctdbSetResourceName(), ctdbUpdateResource(), ctdbGetResourceData(), ctdbSetResourceData(), ctdbIsResourceLocked(), ctdbUnlockResource()

ctdbGetResourceName

Retrieve the resource name.

DECLARATION

pTEXT ctdbDECL ctdbGetResourceName(CTHANDLE resource);

DESCRIPTION

Retrieve the resource name. A NULL value may be returned to indicate that the resource name was not set.

RETURN

Returns a pointer to the resource name

EXAMPLE

if (ctdbGetResourceName(hRes) == NULL)

ctdbSetResourceName(hRes, "MyResource");

SEE ALSO

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

ctdbGetResourceNumber

Retrieve the resource number.

DECLARATION

ULONG ctdbDECL ctdbGetResourceNumber(CTHANDLE resource);

DESCRIPTION

Retrieves the resource number. resource is a handle allocated by ctdbAllocResource().

RETURN

Return the resource number

EXAMPLE

if (ctdbGetResourceNumber(hRes) != number)

ctdbSetResourceNumber(hRes, number);

SEE ALSO

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

ctdbGetResourceType

Retrieve the resource type.

DECLARATION

ULONG ctdbDECL ctdbGetResourceType(CTHANDLE resource);

DESCRIPTION

Retrieve the resource type. resource is a handle allocated by ctdbAllocResource().

RETURN

Returns the resource type.

EXAMPLE

if (ctdbGetResourceType(hRes) != type)

ctdbSetResourceType(hRes, type);

SEE ALSO

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

ctdbGetResultSetByName

Retrieves the CTResultSet handle for a given name.

Declaration

CTHANDLE ctdbGetResultSetByName(CTHANDLE Handle, pTEXT ResSetName)

Parameters:

• Handle [IN] - Table handle
• ResSetName [IN] - Result Set name

Description

The result set handle is allocated (ctdbAllocateResultSet()) for a specific table handle, and then it is possible to add one or more criteria (ctdbAddCriteria()). The criteria have a field to be checked against the table handle that owns the result set, one or two values (depending on the comparison operator) and the operator to be used. The operator can be on of: CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT, CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE or CTIX_NOTBET. When the result set has all the criteria added, it can be turned on or off (ctdbResultSetOnOff()) for any record handle that is allocated for the same table handle that owns the result set.

Limitations

• A result set can't be turned on for a record that is already filtered. And when a record has a result set turned on, it is not possible to add any other filter. This limitation may be relaxed in the future.
• When a result set is changed (ctdbAddCriteria(), ctdbRemoveCriteria() and ctdbUpdateCriteria()), it must be re-applied to the record handle (ctdbResultSetOnOff()) to have these changed take effect..

Returns

A CTResultSet handle. NULL otherwise.

Example

   CTHANDLE hResSet;
   CTHANDLE hResSetCri;
 
/* Allocate a Result Set for Table */
if (!(hResSet = ctdbAllocateResultSet( hTable, "resSet1" )))
    Handle_Error("Test_ResultSet1(); ctdbAllocateResultSet()");

/* Add a new criteria for the Result Set just allocated */
if (!(hResSetCri = ctdbAddCriteria( hResSet, hField0, "1002", NULL, CTIX_EQ )))
    Handle_Error("Test_ResultSet1(); ctdbAddCriteria()");

/* Turn on the Result Set for the current record handle */
if (ctdbResultSetOnOff( hResSet, hRecord, YES, YES, CTLOC_NONE ) != CTDBRET_OK)
    Handle_Error("Test_ResultSet1(); ctdbResultSetOnOff()");

/* Display records on the Result Set */
Display_Records(hRecord);

/* Release Result Set handle */
ctdbFreeResultSet( hResSet );

See also

• ctdbGetResultSetHandle, ctdbAllocateResultSet, ctdbFreeResultSet, ctdbResultSetOnOff, ctdbGetResultSetByName, ctdbGetResultSetCriHandle, ctdbAddCriteria, ctdbRemoveCriteria, ctdbUpdateCriteria, ctdbGetActiveResultSet

ctdbGetResultSetCriHandle

Retrieves the CTResultSetCri handle for a given name.

Declaration

CTHANDLE ctdbGetResultSetCriHandle(CTHANDLE Handle)

Parameter:

• Handle [IN] - Result Set Criteria handle.

Description

The result set handle is allocated (ctdbAllocateResultSet()) for a specific table handle, and then it is possible to add one or more criteria (ctdbAddCriteria()). The criteria have a field to be checked against the table handle that owns the result set, one or two values (depending on the comparison operator) and the operator to be used. The operator can be on of: CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT, CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE or CTIX_NOTBET. When the result set has all the criteria added, it can be turned on or off (ctdbResultSetOnOff()) for any record handle that is allocated for the same table handle that owns the result set.

Limitations

• A result set can't be turned on for a record that is already filtered. And when a record has a result set turned on, it is not possible to add any other filter. This limitation may be relaxed in the future.
• When a result set is changed (ctdbAddCriteria(), ctdbRemoveCriteria() and ctdbUpdateCriteria()), it must be re-applied to the record handle (ctdbResultSetOnOff()) to have these changed take effect..

Returns

A CTResultSetCri handle. NULL otherwise.

Example

   CTHANDLE hResSet;
   CTHANDLE hResSetCri;
 
/* Allocate a Result Set for Table */
if (!(hResSet = ctdbAllocateResultSet( hTable, "resSet1" )))
    Handle_Error("Test_ResultSet1(); ctdbAllocateResultSet()");

/* Add a new criteria for the Result Set just allocated */
if (!(hResSetCri = ctdbAddCriteria( hResSet, hField0, "1002", NULL, CTIX_EQ )))
    Handle_Error("Test_ResultSet1(); ctdbAddCriteria()");

/* Turn on the Result Set for the current record handle */
if (ctdbResultSetOnOff( hResSet, hRecord, YES, YES, CTLOC_NONE ) != CTDBRET_OK)
    Handle_Error("Test_ResultSet1(); ctdbResultSetOnOff()");

/* Display records on the Result Set */
Display_Records(hRecord);

/* Release Result Set handle */
ctdbFreeResultSet( hResSet );

See also

• ctdbGetResultSetHandle, ctdbAllocateResultSet, ctdbFreeResultSet, ctdbResultSetOnOff, ctdbGetResultSetByName, ctdbGetResultSetCriHandle, ctdbAddCriteria, ctdbRemoveCriteria, ctdbUpdateCriteria, ctdbGetActiveResultSet

ctdbGetResultSetHandle

Retrieves the Result Set handle based on a CTResultSet or CTResultSetCri handle.

Declaration

CTHANDLE ctdbGetResultSetHandle(CTHANDLE Handle);

Parameter:

• Handle [IN] - Result Set or Result Set Criteria handle.

Description

The result set handle is allocated (ctdbAllocateResultSet()) for a specific table handle, and then it is possible to add one or more criteria (ctdbAddCriteria()). The criteria have a field to be checked against the table handle that owns the result set, one or two values (depending on the comparison operator) and the operator to be used. The operator can be on of: CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT, CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE or CTIX_NOTBET. When the result set has all the criteria added, it can be turned on or off (ctdbResultSetOnOff()) for any record handle that is allocated for the same table handle that owns the result set.

Limitations

• A result set can't be turned on for a record that is already filtered. And when a record has a result set turned on, it is not possible to add any other filter. This limitation may be relaxed in the future.
• When a result set is changed (ctdbAddCriteria(), ctdbRemoveCriteria() and ctdbUpdateCriteria()), it must be re-applied to the record handle (ctdbResultSetOnOff()) to have these changed take effect.

Returns

A handle to a result set type. NULL on error.

Example

   CTHANDLE hResSet;
   CTHANDLE hResSetCri;
 
/* Allocate a Result Set for Table */
if (!(hResSet = ctdbAllocateResultSet( hTable, "resSet1" )))
    Handle_Error("Test_ResultSet1(); ctdbAllocateResultSet()");

/* Add a new criteria for the Result Set just allocated */
if (!(hResSetCri = ctdbAddCriteria( hResSet, hField0, "1002", NULL, CTIX_EQ )))
    Handle_Error("Test_ResultSet1(); ctdbAddCriteria()");

/* Turn on the Result Set for the current record handle */
if (ctdbResultSetOnOff( hResSet, hRecord, YES, YES, CTLOC_NONE ) != CTDBRET_OK)
    Handle_Error("Test_ResultSet1(); ctdbResultSetOnOff()");

/* Display records on the Result Set */
Display_Records(hRecord);

/* Release Result Set handle */
ctdbFreeResultSet( hResSet );

See also

• ctdbGetResultSetHandle, ctdbAllocateResultSet, ctdbFreeResultSet, ctdbResultSetOnOff, ctdbGetResultSetByName, ctdbGetResultSetCriHandle, ctdbAddCriteria, ctdbRemoveCriteria, ctdbUpdateCriteria, ctdbGetActiveResultSet

ctdbGetRowid

Retrieve the record rowid.

Declaration

CTDBRET ctdbGetRowid(CTHANDLE Handle, pCTROWID pRowid)

Description

ctdbGetRowid() retrieves the record ROWID.

• Handle [in] the record handle.
• pRowid [out] the ROWID value.

Returns

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

See also

ctdbAllocRecord(), ctdbFindRowid(), ctdbHasRowid(

ctdbGetSecond

Get the whole seconds from a packed CTTIME.

Declaration

NINT ctdbGetSecond(CTTIME Time)

Description

ctdbGetSecond() gets the second from a packed CTTIME.

• Time is the packed time in CTTIME format.

Returns

ctdbGetSecond() returns the minute, on success or -1 on error.

See also

ctdbGetMinute(), ctdbGetHour()

ctdbGetSegment

Retrieve the segment handle of the segment indicated by SegNumber.

Declaration

CTHANDLE ctdbGetSegment(CTHANDLE Handle, NINT SegNumber)

Description

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

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

Returns

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

See also

ctdbAllocIndex()

ctdbGetSegmentField

Retrieve the field handle of the segment.

Declaration

CTHANDLE ctdbGetSegmentField(CTHANDLE Handle)

Description

ctdbGetSegmentField() retrieve the field handle of the segment.

• Handle [in] the Segment Handle.

Returns

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

See also

ctdbAllocSegment()

ctdbGetSegmentFieldName

Get the field name of the index segment.

Declaration

pTEXT ctdbGetSegmentFieldName(CTHANDLE Handle)

Description

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

• Handle [in] the Segment Handle.

Returns

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

See also

ctdbAllocSegment()

ctdbGetSegmentHandle

Retrieve a segment handle.

Declaration

CTHANDLE ctdbGetSegmentHandle(CTHANDLE Handle)

Description

ctdbGetSegmentHandle() retrieves a segment handle.

• Handle [in] the Segment Handle.

Returns

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

See also

ctdbAllocSegment()

ctdbGetSegmentKSeg

Retrieves the segment extended key definition.

DECLARATION

CTDBRET ctdbGetSegmentKSeg(CTHANDLE Handle, pctKSEGDEF pKSeg);

DESCRIPTION

ctdbGetSegmentKSeg() retrieves the current extended key segment definition.

• Handle must be a segment handle.
• pKSeg is a pointer to an extended key segment definition structure which will receive the definition.

RETURN

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

EXAMPLE

ctKSEGDEF kseg;

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

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

SEE ALSO

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

ctdbGetSegmentLength

Retrieves the length of an index segment.

Declaration

NINT ctdbDECL ctdbGetSegmentLength(CTHANDLE Handle)

Description

• Handle [IN] - Segment handle

Returns

Returns the segment length. Returns 0 on error.

ctdbGetSegmentMode

Retrieve the segment mode.

Declaration

CTSEG_MODE ctdbGetSegmentMode(CTHANDLE Handle)

Description

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

• Handle [in] the Segment Handle.

Returns

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

See also

ctdbAllocSegment(), ctdbSetSegmentMode()

ctdbGetSegmentNbr

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

Declaration

CTDBRET ctdbGetSegmentNbr(CTHANDLE Handle, pVRLEN pNumber)

Description

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

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

Returns

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

See also

ctdbGetIndexNbr()

ctdbGetSegmentPartialField

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

DECLARATION

CTHANDLE ctdbDECL ctdbGetSegmentPartialField(CTHANDLE Handle);

DESCRIPTION

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

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

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

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

RETURN

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

EXAMPLE

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

CTHANDLE GetFieldMatch(CTHANDLE hIndex, NINT segnbr)

{

CTHANDLE hField = NULL;

CTHANDLE hSegment = ctdbGetSegment(hIndex, segnbr);

if (hSegment)

hField = ctdbGetSegmentPartialField(hSegment);

return hField;

}

SEE ALSO

ctdbGetSegmentField(), ctdbGetSegmentFieldName()

ctdbGetSegmentStatus

Retrieves the status of the segment handle.

DECLARATION

ULONG ctdbGetSegmentStatus(CTHANDLE Handle);

DESCRIPTION

Retrieves the status of a segment handle.

• Handle is a segment handle.

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

RETURN

ctdbGetSegmentStatus returns a bitmap of the following:

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

EXAMPLE

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

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

{

CTHANDLE hSeg = ctdbGetSegment(hIndex, i);

if (ctdbGetSegmentStatus(hSeg) != CTDBISEG_OLD)

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

printf("ctdbAlterTable failed\n");

}

SEE ALSO

ctdbGetFieldStatus(), ctdbGetIndexStatus()

ctdbGetServerName

Return the server name associated with the session.

Declaration

pTEXT ctdbGetServerName(CTHANDLE Handle)

Description

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

• Handle [in] the session handle.

Returns

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

Example

username=ctdbGetUserLogonName(hSession);

servname=ctdbGetServerName(hSession);

See also

ctdbLogon(), ctdbAllocSession(), ctdbGetUserLogonName()

ctdbGetSessionHandle

Return the session handle from the opaque handle.

Declaration

CTHANDLE ctdbGetSessionHandle(CTHANDLE Handle)

Description

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

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

Returns

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

Example

hSess=ctdbGetSessionHandle(hDatabase);

See also

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

ctdbGetSessionParams

Return the session parameter based on the parameter type.

Declaration

NINT ctdbGetSessionParams(CTHANDLE Handle, CTSESSION_PARAM ParamType)

Description

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

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

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

Returns

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

Example

CTSESSION_TYPE ctdbsess=CTSESSION_CTDB;

CTHANDLE hSession = ctdbAllocSession(ctdbsess);

CTDBRET err;

NINT ret, newbuf;

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

ret = ctdbGetSessionParams(hSession, CT_BUFS);

newbuf = ret + 2;

err = ctdbSetSessionParams(hSession, CT_BUFS, newbuf);

See also

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

ctdbGetSessionPath

Return the default session path.

Declaration

CTDBRET ctdbGetSessionPath(CTHANDLE Handle, pTEXT Path,

VRLEN PathSize)

Description

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

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

Returns

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

Example

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

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

See also

ctdbSetSessionPath()

ctdbGetSessionType

Retrieve the current session type.

Declaration

CTSESSION_TYPE ctdbGetSessionType(CTHANDLE Handle)

Description

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

• Handle [in] the session handle.

Returns

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

See also

ctdbSetSessionType()

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

ctdbGetTable

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

Declaration

CTHANDLE ctdbGetTableNbr(CTHANDLE Handle, NINT index)

Description

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

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

Returns

ctdbGetTable() returns the table handle or null on error

See also

ctdbGetTableName(), ctdbGetTableNbr()

ctdbGetTableCount

Retrieve the number of tables in the database dictionary.

Declaration

NINT ctdbGetTableCount(CTHANDLE Handle)

Description

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

• Handle [in] the Database Handle.

Returns

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

See also

ctdbGetDatabaseCount()

ctdbGetTableCreateMode

Retrieve the table create mode.

Declaration

CTCREATE_MODE ctdbGetTableCreateMode(CTHANDLE Handle)

Description

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

• Handle [in] the Table Handle.

Returns

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

See also

ctdbAllocTable(), ctdbGetTableOpenMode(), ctdbCreateTable()

ctdbGetTableDefaultDataExtentSize

Retrieve the table default data extent size

Declaration

NINT ctdbGetTableDefaultDataExtentSize(CTHANDLE Handle)

Description

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

• Handle [in] the Table Handle.

Returns

ctdbGetTableDefaultDataExtentSize() returns the table default data extent size.

See also

ctdbGetTableDefaultIndexExtentSize(), ctdbSetTableDefaultDataExtentSize()

ctdbGetTableDefaultIndexExtentSize

Retrieve the table default index extent size

Declaration

NINT ctdbGetTableDefaultIndexExtentSize(CTHANDLE Handle)

Description

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

• Handle [in] the Table Handle.

Returns

ctdbGetTableDefaultIndexExtentSize() returns the table default index extent size.

See also

ctdbGetDefaultIndex(), ctdbGetTableDefaultDataExtentSize(), ctdbSetTableDefaultIndexExtentSize()

ctdbGetTableExtension

Retrieve the table filename extension.

Declaration

pTEXT ctdbGetTableExtension(CTHANDLE Handle)

Description

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

• Handle [in] the Table Handle.

Returns

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

See also

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

ctdbGetTableFieldCount

Retrieve the number of fields associated with the table.

Declaration

VRLEN ctdbGetTableFieldCount(CTHANDLE Handle)

Description

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

• Handle [in] the Table Handle.

Returns

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

See also

ctdbAllocTable(), ctdbGetTableIndexCount()

ctdbGetTableFirstDataExtentSize

Retrieve the table first data extent size. (Introduced V12.0.1)

Declaration

NINT ctdbDECL ctdbGetTableFirstDataExtentSize(CTHANDLE Handle)

Description

Parameters

• Handle [IN] - Table handle

Returns

Returns the table first data extent size.

See also

ctdbGetTableFirstIndexExtentSize, ctdbSetTableFirstDataExtentSize, ctdbSetTableFirstIndexExtentSize

ctdbGetTableFirstIndexExtentSize

Retrieve the table first index extent size. (Introduced V12.0.1)

Declaration

NINT ctdbDECL ctdbGetTableFirstIndexExtentSize(CTHANDLE Handle)

Description

Parameters

• Handle [IN] - Table handle

Returns

Returns the table first index extent size.

See also

ctdbGetTableFirstDataExtentSize, ctdbSetTableFirstDataExtentSize, ctdbSetTableFirstIndexExtentSize

ctdbGetTableFTICount

Retrieve the number of FTS indexes associated with the table.

ctdbGetTableGroupid

Retrieve the table group ID.

Declaration

pTEXT ctdbGetTableGroupid(CTHANDLE Handle, pTEXT groupid)

Description

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

• Handle [in] the Table Handle.

Returns

ctdbGetTableGroupid() returns the table group ID.

See also

ctdbAllocTable(), ctdbSetTableGroupid()

ctdbGetTableHandle

Return a table handle

Declaration

CTHANDLE ctdbGetTableHandle(CTHANDLE Handle)

Description

ctdbGetTableHandle() retrieves the table handle.

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

Returns

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

See also

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

ctdbGetTableHotAlterCallbackLib

Return the callback library name for hot alter table.

Declaration

pTEXT ctdbDECL ctdbGetTableHotAlterCallbackLib(CTHANDLE Handle)

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

ctdbGetTableHotAlterCallbackLib() returns pointer to the internal library name buffer.

See also

FairCom DB API API Functions for User-Defined Hot Alter Table Field Conversion Callback

ctdbSetTableHotAlterCallbackLib

ctdbSetFieldHotAlterCallbackFunction

ctdbGetTableIndexCount

Retrieve the number of indexes associated with the table.

Declaration

VRLEN ctdbGetTableIndexCount(CTHANDLE Handle)

Description

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

• Handle [in] the Table Handle.

Returns

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

See also

ctdbAllocTable(), ctdbGetDefaultIndex()

ctdbGetTableKSeg

Retrieves the current table-wide extended key segment definition.

DECLARATION

CTDBRET ctdbGetTableKSeg(CTHANDLE Handle, pctKSEGDEF pKSeg);

DESCRIPTION

ctdbGetTableKSeg() retrieves the current table-wide extended key segment definition. Handle must be a FairCom DB API table handle and pKSeg is a pointer to an extended key segment definition structure which will receive the definition.

Note: The kseg_type member of the extended key segment definition structure must be set on input to the type of segment to be retrieved.

RETURN

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

EXAMPLE

ctKSEGDEF kseg;

if ((eRet = ctdbGetTableKSeg(hTable, &kseg)) != CTDBRET_OK)
    printf("ctdbGetTableKSeg failed with error %d\n", eRet);

SEE ALSO
ctdbSetTableKSeg(), ctdbSetIndexKSeg(), ctdbGetIndexKSeg(), ctdbSetSegmentKSeg(), ctdbGetSegmentKSeg(), ctdbSetKSegDefaults()

ctdbGetTableName

Retrieve the table name.

Declaration

pTEXT ctdbGetTableName(CTHANDLE Handle)

Description

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

• Handle [in] the Table Handle.

Returns

ctdbGetTableName() returns the Table name or NULL on failure

See also

ctdbAllocTable(), ctdbGetTablePath(), ctdbGetTableExtension()

ctdbGetTableNbr

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

Declaration

NINT ctdbGetTableNbr(CTHANDLE Handle)

• Handle [in] Table Handle.

Description

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

Returns

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

See also

ctdbGetTableName(), ctdbGetTable()

ctdbGetTableOpenMode

Retrieve the table open mode.

Declaration

CTOPEN_MODE ctdbGetTableOpenMode(CTHANDLE Handle)

Description

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

• Handle [in] the Table Handle.

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

Returns

ctdbGetTableOpenMode() returns the table open mode.

See also

ctdbAllocTable(), ctdbOpenTable()

ctdbGetTableOwner

Declaration

pTEXT ctdbGetTableOwner(CTHANDLE Handle);

Description

Retrieves the table owner.

Return Values

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

• Handle is a table handle allocated by ctdbAllocTable().

See Also

ctdbSetTableOwner()

ctdbGetTablePassword

Retrieve the table password.

Declaration

pTEXT ctdbGetTablePassword(CTHANDLE Handle)

Description

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

• Handle [in] the Table Handle.

Returns

ctdbGetTablePassword() returns the table password.

See also

ctdbAllocTable(), ctdbSetTablePassword()

ctdbGetTablePath

Retrieve the table drive/directory path

Declaration

pTEXT ctdbGetTablePath(CTHANDLE Handle)

Description

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

• Handle [in] the Table Handle.

Returns

ctdbGetTablePath() returns the Table path or NULL on failure

See also

ctdbAllocTable(), ctdbGetTableName(), ctdbSetTablePath()

ctdbGetTablePermission

Retrieve the table permission.

Declaration

LONG ctdbGetTablePermission(CTHANDLE Handle)

Description

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

• Handle [in] the Table Handle.

Returns

ctdbGetTablePermission() returns the table permission.

See also

ctdbAllocTable(), ctdbSetTablePermission()

ctdbGetTableStatus

Declaration

ULONG ctdbGetTableStatus(CTHANDLE Handle);

Description

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

• Handle is a table handle.

Return Values

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

The possible rebuild status returns are:

Example

ULONG status = ctdbGetTableStatus(hTable);
 

if (status & CTDB_REBUILD_ALL || status & CTDB_REBUILD_FULL)

ctdbAlterTable(hTable, CTDB_ALTER_FULL)

else if (status)

ctdbAlterTable(hTable, CTDB_ALTER_NORMAL);

See Also

ctdbGetIndexStatus(), ctdbGetSegmentStatus(), ctdbAlterTable()

ctdbGetTransactionMode

Declaration

CTBEGIN_MODE ctdbDECL ctdbGetTransactionMode(CTHANDLE Handle);

Description

Returns the transaction mode used when starting a transaction.

c-tree Plus offers a rich array of data integrity options. Full transaction processing offers the safest and best performance of all the available options. There are times when other c-tree Plus options, such as PREIMG, might be advantageous.

Return Values

ctdbGetTransactionMode() returns one of the following values:

See Also

ctdbGetTransactionMode()

ctdbGetTableUID

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

Declaration

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

Description

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

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

Returns

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

See also

ctdbAllocDatabase(), ctdbFindTableByUID(), ctdbGetActiveTableUID()

ctdbGetUserLogonName

Return the user name associated with the session.

Declaration

pTEXT ctdbGetUserLogonName(CTHANDLE Handle)

Description

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

• Handle [in] the session handle.

Returns

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

Example

username=ctdbGetUserLogonName(hSession);

servname=ctdbGetServerName(hSession);

See also

ctdbGetServerName(), ctdbAllocSession()

ctdbGetUserTag

Retrieve the user tag.

Declaration

CTDBRET ctdbGetUserTag(CTHANDLE Handle, pVOID tagptr)

Description

ctdbGetUserTag() retrieves the user tag.

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

Returns

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

See also

ctdbSetUserTag()

ctdbGetYear

Retrieve the year from a packed CTDATE.

Declaration

NINT ctdbGetYear(CTDATE date)

Description

ctdbGetYear() retrieves the year from a packed CTDATE. To retrieve the day of the month from a packed CTDATE, use ctdbGetDay(). To retrieve the month of the year from a packed CTDATE, use ctdbGetMonth().

• date is the date in CTDATE format.

Returns

ctdbGetYear() returns the day of the month on success or 0 on error.

See also

ctdbGetMonth(), ctdbGetDay()