ctdbBuildTargetKey

Build a target key based on data in record buffer.

Declaration

CTDBRET ctdbBuildTargetKey(CTHANDLE Handle, CTFIND_MODE FindMode,

                           pVOID targetkey, pVRLEN targetlen)

Description

ctdbBuildTargetKey() builds a target key based on data in the record buffer.

• Handle [in] the record handle.
• FindMode [in] the find mode. Available values are found in FairCom DB API definitions.
• targetkey [out] the target key.
• targetlen [in/out] the target key length. Before calling ctdbBuildTargetKey() set targetlen with the size of the targetkey buffer.

Note: The FindMode CTFIND_EQ requires that the target contains values for all segments that compose the index and the index cannot allow duplicates.

Note: When using this function with the FindTarget() function, you must supress the transformation of the already-transformed key in FindTarget() since it must not be transformed. In order to do this, you may define a macro NOTRANSFORM with a value of 0x1000 and OR it into the mode passed to FindTarget().

Returns

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

ctdbDeleteRecord

Delete an existing record.

Declaration

CTDBRET ctdbDeleteRecord(CTHANDLE Handle)

Description

ctdbDeleteRecord() deletes an existing record from a table. While not enforced by the FairCom DB API API, it is strongly recommended that a WRITE_LOCK be acquired on the record before it is deleted by calling this function. To lock the record, use either session-wide record locking (ctdbLock()) or manually lock the record by calling ctdbdbLockRecord().

Once a record has been deleted, FairCom DB API automatically releases any locks that were held by that record. Outside of a transaction, the locks are released before the ctdbDeleteRecord() function returns. Inside a transaction, the locks are held until the transaction is ended (the ctdbCommit() or the ctdbAbort() function returns).

Note that if the table was opened in CTOPEN_CHECKLOCK or CTOPEN_CHECKREAD mode (see ctdbOpenTable()), then the corresponding locks must be obtained before the record is read / deleted.

• Handle [in] the record handle.

Returns

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

See also

ctdbAllocRecord(), ctdbLock(), ctdbdbLockRecord(), ctdbReadRecord(), ctdbWriteRecord()

ctdbDuplicateRecord

Return a duplicate copy of a record.

Declaration

CTHANDLE ctdbDuplicateRecord(CTHANDLE Handle)

Description

ctdbDuplicateRecord ()duplicates an existing record.

• Handle [in] the record handle to be duplicated.

Returns

ctdbDuplicateRecord() returns a copy of the record, or NULL on failure.

ctdbFindRecord

Find a record using the FindMode as the find strategy.

Declaration

CTDBRET ctdbFindRecord(CTHANDLE Handle, CTFIND_MODE FindMode)

Description

ctdbFindRecord() finds a record in the table associated with the record handle, using the FindMode strategy. The record data is retrieved from disk into the record handle’s record buffer and the current record is set to that record. Note that if session-wide record locking is enabled, this function will also lock the record it retrieves.

• Handle [in] the record handle.
• FindMode [in] the mode to use to look for the record in the table. The find modes are listed in FairCom DB API definitions.

Before using ctdbFindRecord(),

• clear the record buffer with ctdbClearRecord()
• select the index to search with ctdbSetDefaultIndex()
• set search target values with one or more of the ctdbSetFieldAs...() functions
• call ctdbFindRecord()

Note: The FindMode CTFIND_EQ requires that the target contains values for all segments that compose the index and the index cannot allow duplicates.

Use ctdbFirstRecord() to retrieve the first record of a table, ctdbNextRecord() to retrieve the next record of a table, ctdbPrevRecord() to retrieve the previous record of a table, and ctdbLastRecord() to retrieve the last record of a table. Use ctdbFindTarget() to find a record using a given target key.

Returns

ctdbFindRecord() returns CTDBRET_OK if the record was found, or INOT_ERR (101) if no record was found. Any other return value indicates an error condition (FairCom DB API error).

Example

ctdbClearRecord(hRec);

ctdbSetDefaultIndex(hRec, 1);

ctdbSetFieldAsString(hRec, ctdbGetFieldNumberByName(hRec, "Name"), name);

ctdbFindRecord(hRec, CTFIND_EQ);

See also

ctdbAllocRecord(), ctdbFirstRecord(), ctdbNextRecord(), ctdbPrevRecord(), ctdbLastRecord(), ctdbFindTarget(), ctdbClearRecord(), ctdbSetDefaultIndex()

ctdbFindRowid

Find a record based on its rowid.

Declaration

CTDBRET ctdbFindRowid(CTHANDLE Handle, CTROWID rowid,

CTFIND_MODE FindMode)

Description

ctdbFindRowid() retrieves the record, given its rowid. The record data is retrieved from disk into the record handle’s record buffer and the current record is set to that record. Note that if session-wide record locking is enabled, this function will also lock the record it retrieves.

• Handle [in] the record handle.
• rowid [in] the rowid value.
• FindMode [in] the mode to use to look for the record in the table. The find modes are listed in FairCom DB API definitions.

Note: The FindMode CTFIND_EQ requires that the target contains values for all segments that compose the index and the index cannot allow duplicates.

Returns

ctdbFindRowid() returns CTDBRET_OK on success, or INOT_ERR (101) if no record is found with the specified rowid. Any other return value indicates an error condition (FairCom DB API error).

See also

ctdbAllocRecord(), ctdbGetRowid(), ctdbHasRowid()

ctdbFindTarget

Find a record using a target key.

Declaration

CTDBRET ctdbFindTarget(CTHANDLE Handle, pVOID target,

CTFIND_MODE FindMode)

Description

ctdbFindTarget() finds a record with a given target key. The record data is retrieved from disk into the record handle’s record buffer and the current record is set to that record. Note that if session-wide record locking is enabled, this function will also lock the record it retrieves. Use ctdbFindRecord() to find a record with the FindMode() strategy.

• Handle [in] the record handle.
• target [in] string with the key target to lookup in the table.
• FindMode [in] the mode to use to look for the record in the table. The find modes are listed in FairCom DB API definitions.

The target key MUST be transformed (use ctdbBuildTargetKey() if necessary).

Note: The Find Mode CTFIND_EQ requires that the target contains values for all segments that compose the index and the index cannot allow duplicates.

Note: Prior to FairCom DB V9.1, the key target in FindTarget() must NOT be transformed. When using functions such as TransformKey() or BuildTargetKey(), you must suppress the transformation of the already-transformed key. In order to do this, you may define a macro NOTRANSFORM with a value of 0x1000 and OR it into the mode passed to FindTarget().

Returns

ctdbFindTarget() returns CTDBRET_OK if the record was found, or INOT_ERR (101) if no record is found. Any other return value indicates an error condition (FairCom DB API error).

See also

ctdbAllocRecord(), ctdbFindRecord()

ctdbFirstRecord

Get the first record of a table

Declaration

CTDBRET ctdbFirstRecord(CTHANDLE Handle)

Description

ctdbFirstRecord() retrieves the first record of a table and copies the record data from disk into the specified record handle’s record buffer, and sets the current record to that first record. The ordering of the records is done through one of the indexes that was defined during the table creation. To define which index is sorting the table, use ctdbSetDefaultIndex(). Initially, the default index is the first defined index during the table creation.

• Handle [in] the record handle.

If sets are enabled by ctdbRecordSetOn(), ctdbFirstRecord() will retrieve the first record in the set. Use ctdbNextRecord() to retrieve the next record on a table, ctdbPrevRecord() to retrieve the previous record on a table, and ctdbLastRecord() to retrieve the last record on a table. Use ctdbFindRecord() to find a specific record on a table. Note that, if session-wide record locking is enabled, this function will also lock the record it retrieves.

Returns

ctdbFirstRecord() returns CTDBRET_OK on success, or INOT_ERR (101) if the table contains no records, or a FairCom DB API error on failure.

See also

ctdbAllocRecord(), ctdbNextRecord(), ctdbPrevRecord(), ctdbLastRecord(), ctdbFindRecord(), ctdbRecordSetOn(), ctdbSetDefaultIndex()

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

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

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

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

ctdbJumpToRecord

Move to record by jumping forward or backward a number of records.

Declaration

CTDBRET ctdbDECL ctdbJumpToRecord(CTHANDLE Handle, LONG numberOfRecords)

Description

ctdbJumpToRecord() moves to a record by jumping forward or backward a number of records. A negative number jumps backward.

• Handle [in] - The record handle.
• numberOfRecords [in] - The number of records to skip (positive value to skip forward; negative value to skip backwards).

Returns

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

See also

ctdbAllocRecord(), ctdbFirstRecord(), ctdbPrevRecord(), ctdbLastRecord(), ctdbFindRecord(), ctdbRecordSetOn()

ctdbLastRecord

Get the last record on a table.

Declaration

CTDBRET ctdbLastRecord(CTHANDLE Handle)

Description

ctdbLastRecord() retrieves the last record on a table and copies the record data from disk into the specified record handle’s record buffer, and sets the current record to that last record.

• Handle [in] the record handle.

If sets are enabled by ctdbRecordSetOn(), ctdbLastRecord() will retrieve the last record in the set. Use ctdbFirstRecord() to retrieve the first record on a table, ctdbNextRecord() to retrieve the next record on a table, and ctdbPrevRecord() to retrieve the previous record on a table. Use ctdbFindRecord() to find a specific record on a table. Note that if session-wide record locking is enabled, this function will also lock the record it retrieves.

Returns

ctdbLastRecord() returns CTDBRET_OK on success, or INOT_ERR (101) if the table is empty, or a FairCom DB API error on failure.

See also

ctdbAllocRecord(), ctdbFirstRecord(), ctdbNextRecord(), ctdbPrevRecord(), ctdbFindRecord(), ctdbRecordSetOn()

ctdbNextRecord

Get the next record on a table.

Declaration

CTDBRET ctdbNextRecord(CTHANDLE Handle)

Description

ctdbNextRecord() retrieves the next record on a table and copies the record data from disk into the specified record handle’s record buffer, and advances the current record to the next record of that table. Note that if session-wide record locking is enabled, this function will also lock the record it retrieves.

• Handle [in] the record handle.

If sets are enabled by ctdbRecordSetOn(), ctdbNextRecord() will retrieve the next record in the set. Use ctdbFirstRecord() to retrieve the first record on a table, ctdbPrevRecord() to retrieve the previous record on a table, and ctdbLastRecord() to retrieve the last record on a table. Use ctdbFindRecord() to find a specific record on a table. ctdbNextRecord() and ctdbPrevRecord() must be used after at least one call was done to ctdbFirstRecord(), ctdbLastRecord(), or ctdbFindRecord().

Returns

ctdbNextRecord() returns CTDBRET_OK on success, or INOT_ERR (101) if the current record was the last record of the table, or ICUR_ERR (100) if there is no current record, or a FairCom DB API error on failure.

See also

ctdbAllocRecord(), ctdbFirstRecord(), ctdbPrevRecord(), ctdbLastRecord(), ctdbFindRecord(), ctdbRecordSetOn()

ctdbPrevRecord

Get the previous record in a table.

Declaration

CTDBRET ctdbPrevRecord(CTHANDLE Handle)

Description

ctdbPrevRecord() retrieves the previous record in a table and copies the record data from disk into the specified record handle’s record buffer, and moves the current record to the previous record in that table. Note that if session-wide record locking is enabled, this function will also lock the record it retrieves.

• Handle [in] the record handle.

If sets are enabled by ctdbRecordSetOn(), ctdbPrevRecord() will retrieve the previous record in the set. Use ctdbFirstRecord() to retrieve the first record on a table, ctdbNextRecord() to retrieve the next record on a table, and ctdbLastRecord() to retrieve the last record on a table. Use ctdbFindRecord() to find a specific record on a table. ctdbNextRecord() and ctdbPrevRecord() must be used after at least one call was done to ctdbFirstRecord(), ctdbLastRecord(), or ctdbFindRecord().

Returns

ctdbPrevRecord() returns CTDBRET_OK on success, or INOT_ERR (101) if the current record was the first record in the table, or ICUR_ERR (100) if there is no current record, or a FairCom DB API C API error on failure.

See also

ctdbAllocRecord(), ctdbFirstRecord(), ctdbNextRecord(), ctdbLastRecord(), ctdbFindRecord(), ctdbRecordSetOn()

ctdbReadRecord

Reread a record from its offset

Declaration

CTDBRET ctdbReadRecord(CTHANDLE Handle)

Description

ctdbReadRecord() rereads a record from its offset. The record cursor must have been activated with a call to one of the search routines, and no subsequent call to ctdbClearRecord().

• Handle [in] the record handle.

Returns

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

See also

ctdbAllocRecord(), ctdbWriteRecord(), ctdbClearRecord()

ctdbRecordAtPercentile

Find a record located at about the given percentile value.

Declaration

CTDBRET ctdbRecordAtPercentile(CTHANDLE Handle, NINT pecent);

Description

ctdbRecordAtPercentile() read the record located at, approximately, the given percentile value.

Handle is a record handle and percent indicate the percentile value. The valid values for percent are from 0 to 100, indicating 0% to 100%. ctdbRecordAtPercentile() return CTDBRET_OK on success.

The record is located using the record handle current index. You may select a new current index by calling ctdbSetDefaultIndex() function. The table must have at least one index to be able to use this function.

The record returned is an approximation location indicated by the percentual value passed to ctdbRecordAtPercentile().

ctdbRecordAtPercentile(), which is based on c-tree low level function KeyAtPercentile(), and it is very efficient since it does not traverse all of the key values in order to determine the record located at the specified percentile. However, ctdbRecordAtPercentile() is only an approximation since it assumes that key values are uniformly distributed among all of the b-tree leaf nodes.

ctdbRecordAtPercentile() may be used to support scroll bar positioning, found in many GUI windowing environments, in the cases when the position must be maintained in key sequential order.

Return

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

Example

/* display the record at 50% of table */

if (ctdbRecordAtPercentile(hRecord, 50) == CTDBRET_OK)

{

DisplayTheRecord(hRecord);

}

else

{

printf("Faield with error %d\n", ctdbGetError(hRecord));

}

See also

ctdbSetDefaultIndex()

ctdbRecordSetOff

Disable and free an existing record set.

Declaration

CTDBRET ctdbRecordSetOff(CTHANDLE Handle)

Description

ctdbRecordSetOff() disables and free an existing record set. To enable a new record set, use ctdbRecordSetOn().

• Handle [in] the record handle.

Returns

ctdbRecordSetOff() returns CTDBRET_OK if successful, or the c-tree error code on failure. The possible errors associated with ctdbRecordSetOff() are:

• CTDBRET_NOTRECORD (4024): Invalid Record Handle

Example

ctdbRecordSetOn(pRec, 5);

ctdbSetDefaultIndexByName(pRec, "last name");

ctdbSetFieldAsString(pRec, 0, "silva");

ctdbFirstRecord(pRec);

ctdbRecordSetOff(pRec);

See also

ctdbAllocRecord(), ctdbRecordSetOn()

ctdbRecordSetOn

Enable a new record set. The target key is built from the contents of the record buffer.

Declaration

CTDBRET ctdbRecordSetOn(CTHANDLE Handle, NINT siglen)

Description

ctdbRecordSetOn() enables a new record set. The target key is built from the contents of the record buffer.

• Handle [in] the record handle.
• siglen [in] the number of key bytes to be used by the set.

When record set is enabled, the record operations will be substituted by the set operations. This means that, when record set is enabled, operations like ctdbFirstRecord() will search for the first record in the set instead of the first record in the entire table.

Just one record set can be enabled for each record handle. If it is necessary to have more than one record set enabled at the same time, more than one record handle will be required. To disable and free an existing record set, use ctdbRecordSetOff().

If used in conjunction with filters (ctdbFilterRecord()), may behave as a simple query.

Returns

ctdbRecordSetOn() returns CTDBRET_OK if successful, or the c-tree error code on failure. The possible errors associated with ctdbRecordSetOn() are:

• CTDBRET_NOTRECORD (4024): Invalid record handle
• CTDBRET_NOTACTIVE (4012): Table is not active
• CTDBRET_NOINDEX (4048): No index in the active table
• CTDBRET_NOMEMORY (4001): No memory to allocate the key

Example

/* display all records in set - no error checking */

void DisplayAll(CTHANDLE pRec)

{

NINT count = 0;

ctdbClearRecord(pRec);

ctdbSetDefaultIndexByName(pRec, "index_name");

ctdbSetFieldAsString(pRec, 0, "silva");

ctdbRecordSetOn(pRec, 5);

if (ctdbFirstRecord(pRec) == CTDBRET_OK)

{

do

{

count++;

PrintRecord(pRec);

}

while (ctdbNextRecord(pRec) == CTDBRET_OK);

}

printf("%d records in set\n", count);

}

See also

ctdbAllocRecord(), ctdbRecordSetOff(), ctdbFilterRecord()

ctdbRemoveTable

Removes any c-tree table.

Declaration

CTDBRET ctdbDECL ctdbRemoveTable(CTHANDLE Handle);

• Handle is a table handle.

Description

The ctdbRemoveTable() function allows any table data file and its associated index files to be deleted from disk, including tables that are not members of a database / not created in a CTSESSION_CTDB or CTSESSION_SQL session. This function is intended for CTSESSION_CTREE tables, which are not a part of a database.

If the table was opened under a database handle, the table is closed and ctdbDeleteTable() is called. The handle must be active.

If the table was opened under a database handle, meaning that the provided table handle is "active", this function closes that table and then calls ctdbDeleteTable() to delete the files. If the table handle is not active, the table is opened exclusive by this function and then deleted. In this case, you must first set the path, file extension, and password for the table handle before calling ctdbRemoveTable(). See ctdbSetTablePath(), ctdbSetTableExtension(), and ctdbSetTablePassword(). Note that it is simpler to delete the table and index files using ctdbDeleteTable(), so use that function if you can.

V11.5 and Later

In V11.5 and later, ctdbRemoveTable() expects the table handle to have the path, password, file extension, and name information. A non-active table handle does not have this information. (Close and create clean up and deactivate the table handle.) While the path, password and file extensions can be set by the FairCom DB API API, there is no function to set the name. As a result, ctdbRemoveTable() does not work on non-active tables and could have failed with various errors.

This function will now fail immediately and return error CTDBRET_NOTACTIVE (4012) if the table handle is not active.

ctdbRemoveTable() deletes a c-tree data file and associated index files from disk. If the table was opened under a database handle, the table is closed and ctdbDeleteTable() is called. The handle must be active.

Compatibility Change: This modification is a change in behavior.

Return

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

Example

/* delete a FairCom DB API table */

if (ctdbRemoveTable(MyHandle) != CTDBRET_OK)

printf("ctdbRemoveTable Failed!\n");

See also

ctdbDeleteTable()

ctdbRenameTable

Renames the specified table from oldname to newname.

Declaration

ctdbRenameTable(CTHANDLE Handle, pTEXT oldname, pTEXT newname);

Description

• Handle a database handle
• newname a string containing the original table name
• newname a string containing the new table name

SESSION_CTREE Mode

Prior to release V11, the FairCom DB API ctdbRenameTable() function was able to rename tables only with a valid database handle involved in the process, which made this function unusable when working with CTREE session modes.

In release V11 and later, new functionality has been implemented in ctdbRenameTable() so that, if a table handle that directly refers to a session is passed to the function, the rename is done at the CTREE level. If the first parameter is a database handle or a table handle referring to a database, the function continues to work as it has in the past.

Return Values

ctdbSeekRecord

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

Declaration

CTDBRET ctdbSeekRecord(CTHANDLE Handle, CTOFFSET offset)

Description

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

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

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

Returns

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

See also

ctdbSetRecordPos(), ctdbSetRecordOffset(), ctdbGetRecordPos()

ctdbWriteRecord

Add a new record or update an existing record to a table.

Declaration

CTDBRET ctdbWriteRecord(CTHANDLE Handle)

Description

ctdbWriteRecord() adds a new record to a table or updates an existing record in the table. If you want the former to happen (add a new record to the table), then call the ctdbClearRecord() function to clear the record buffer before using the ctdbSetRecordBuffer() function or the ctdbSetFieldAs() functions to fill the record buffer with the contents of the new record. If you wish, instead, to update the record that the record handle currently points at, do not call ctdbClearRecord(). Just use the ctdbSetRecordBuffer() function or the ctdbSetFieldAs() functions to set the buffer before writing the record by calling this function.

If you are using this function to update an existing record, it is recommended that a WRITE_LOCK be acquired on the record as it is read from the table file, using session-wide record locking. First call ctdbLock() to turn on session-wide record locking in WRITE mode, then read the existing record for the table, which will automatically aquire a WRITE lock for the record. Then, the desired modifications to the record can be made, then this function can be called to write the changes to the table file, and then the record can be unlocked by turning off session-wide record locking (ctdbUnlock()), or by manually unlocking the record (ctdbUnlockRecord()). If this operation is done inside a transaction, the record will be automatically unlocked when the transaction is ended (by calling ctdbCommit() or ctdbAbort()).

If you are using this function to add a new record to a table, session-wide record locking can be used in a similar way. First call ctdbLock() to turn on session-wide record locking, then this function can be called to auto-lock the record and write the changes to the table file, and then the record can be unlocked as described in the previous paragraph.

• Handle [in] the record handle.

Returns

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

See also

ctdbAllocRecord(), ctdbReadRecord(), ctdbDeleteRecord(), ctdbSetRecordBuffer(), ctdbGetErrorIndex()