C API Functions B

ctdbBatchFiltered

Retrieves the number of records that are rejected in a batch retrieval operation because they do not match the active filter.

Declaration

ULONG ctdbDECL ctdbBatchFiltered(CTHANDLE Handle)

Description

  • Handle [IN] - Record handle

Handle must be a record handle associated with an open table.

Return Values

Returns the number of records rejected in a batch retrieval operation that do not match the active filter.

Returns zero if a batch retrieval operation is not active.

The value is significant only if the CTBATCH_RET_FILTER mode has been used in the ctdbSetBatch() call.

See Also

ctdbSetBatchFilter (ctdbSetBatchFilter, ctdbSetBatchFilter)()

ctdbSetBatchRangeOn (ctdbSetBatchRangeOn, ctdbSetBatchRangeOn)()

ctdbSetBatchRangeOff (ctdbSetBatchRangeOff, ctdbSetBatchRangeOff)()

 

ctdbBatchLoaded

Retrieves the number of batch records loaded into batch buffer.

DECLARATION

LONG ctdbDECL ctdbBatchLoaded(CTHANDLE Handle);

DESCRIPTION

ctdbBatchLoaded() retrieves the number of batch records loaded into batch buffer for CTBATCH_GET, CTBATCH_RANGE or CTBATCH_PHYS operations. This is the number of records that are ready to be retrieved by ctdbNextBatch() function.

Handle must be a record handle associated with an opened table.

RETURNS

ctdbBatchLoaded() returns the number of records ready for retrieval or a negative value indicating an error. In case of an error, use the ctdbGetError() function to retrieve the error code.

EXAMPLE

/* set the partial target key */
ctdbClearRecord(hRecord);
ctdbSetFieldAsSigned(hRecord, 0, Invoice);
 
/* set the batch operation */
if (ctdbSetBatch(hRecord, CTBATCH_GET, sizeof(Invoice), 0) != CTDBRET_OK)
    printf("ctdbSetBatch failed with error %d\n", ctdbGetError(hRecord));
 
/* show how many records are ready */
printf("%d records are ready for retrieval\n", ctdbBatchLoaded(hRecord));

SEE ALSO

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

 

ctdbBatchLocked

Retrieves the number of locked batch records.

DECLARATION

LONG ctdbDECL ctdbBatchLocked(CTHANDLE Handle);

DESCRIPTION

Retrieves the number of records locked during a CTBATCH_GET, CTBATH_RANGE or CTBATCH_PHYS operation. If CTBATCH_LOCK_READ or CTBATCH_LOCK_WRITE are specified in the batch mode, ctdbBatchLocked() return the total number of records locked. If CTBATCH_LOCK_ONE is specified, or if no CTBATCH_LOCK_READ or CTBATCH_LOCK_WRITE modes are not specified, ctdbBatchLocked() return zero.

Handle must be a record handle associated with an opened table.

RETURNS

ctdbBatchLocked() returns the number of locked records. In case of an error, ctdbBatchLocked() returns a negative value and you may use ctdbGetError() function to retrieve the error code

EXAMPLE

/* set the partial target key */
ctdbClearRecord(hRecord);
ctdbSetFieldAsSigned(hRecord, 0, Invoice);

/* set the batch operation */
if (ctdbSetBatch(hRecord, (CTBATCH_GET | CTBATCH_LOK_READ), sizeof(Invoice), 0) != CTDBRET_OK)
    printf("ctdbSetBatch failed with error %d\n", ctdbGetError(hRecord));

/* show how many records are locked */
printf("%d records are locked\n", ctdbBatchLoaded(hRecord));

SEE ALSO

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

 

ctdbBatchMode

Retrieve the current batch mode.

DECLARATION

CTBATCH_MODE ctdbDECL ctdbBatchMode(CTHANDLE Handle);

DESCRIPTION

ctdbBatchMode() retrieves the current batch mode. The batch mode is set by calling ctdbSetBatch() function. If a batch operation is not active, ctdbBatchMode() return CTBATCH_NONE. Handle must be a record handle associated with an opened table.

RETURNS

ctdbBatchMode() returns the current batch mode or CTBATCH_NONE if no batch operation is currently active.

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

Refer to the FairCom DB API Batch Operations chapter for complete details concerning all of the optional batch modes.

EXAMPLE

/* check if a batch operation is in progress */
if (ctdbBatchMode(hRecord) != CTBATCH_NONE)
    printf("Batch operation is underway\n");
else
    printf("No batch operations\n");

SEE ALSO

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

 

ctdbBatchTotal

Retrieves the total number of records affected by a batch retrieval operation.

DECLARATION

LONG ctdbDECL ctdbBatchTotal(CTHANDLE Handle);

DESCRIPTION

ctdbBatchTotal() retrieves the total number of records selected by a batch retrieval operation. If a batch operation is not active, ctdbBatchTotal() returns zero. Handle must be a record handle associated with an opened table.

RETURNS

Returns the total number of records selected by a batch retrieval operation. In case of an error, ctdbBatchLocked() returns a negative value and you may use ctdbGetError() function to retrieve the error code.

EXAMPLE

ctdbClearRecord(hRecord);
ctdbSetFieldAsSigned(hRecord, 0, Invoice);

/* set the batch operation */
if (ctdbSetBatch(hRecord, (CTBATCH_GET | CTBATCH_LOK_READ), sizeof(Invoice), 0) != CTDBRET_OK)
    printf("ctdbSetBatch failed with error %d\n", ctdbGetError(hRecord));

/* show total number of records */
printf("%d records selected\n", ctdbBatchTotal(hRecord));

SEE ALSO

ctdbBatchLoaded ctdbBatchLocked ctdbBatchMode ctdbEndBatch ctdbInsertBatch ctdbIsBatchActive ctdbNextBatch ctdbSetBatch

ctdbBegin

Start a transaction.

Declaration

CTDBRET ctdbBegin(CTHANDLE Handle)

Description

ctdbBegin() marks the beginning of a transaction. All file updates done after this call will be held until they are committed with a matching call to ctdbCommit(), or aborted with a matching call to ctdbAbort(). Notice that the record locks still must be manually acquired with a call to ctdbLockRecord(), or, even better, automatically acquired via the session-wide locking mechanism (see ctdbLock()). If for any reason the transaction cannot be committed, it can be finished (by discarding it) with a call to ctdbAbort(). This function can be used to perform transaction-controlled file creates.

It is important to realize that FairCom DB API transactions are session-wide, and since FairCom DB API does not support nested transactions, you can only have one transaction "open" at a time. If you call ctdbBegin() twice in a row, the second call will return an error. You can use save points to mimic nested transactions, though (see ctdbSetSavePoint() and ctdbSetSingleSavePoint()). Transactions only affect certain types of tables; see the Creating tables for transaction processing section in Transactions under Data Integrity.

  • Handle [in] - the session handle. Any handle will work, but you save a tiny bit of CPU by using the session handle.

Returns

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

Example


ctdbBegin(pSession);

if (ctdbCreateTable(tHandle1,"table1",CTCREATE_NORMAL) == CTDBRET_OK)

       ctdbCommit(pSession);

else

       ctdbAbort(pSession);

 

See also

ctdbAbort(), ctdbClearSavePoint(), ctdbCommit(), ctdbRestoreSavePoint(), ctdbSetSavePoint(), ctdbSetSingleSavePoint()

ctdbBeginImpersonation

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

Declaration

CTDBRET ctdbBeginImpersonation(CTHANDLE Handle, NINT taskId)

Description

Start the impersonation of the specific task ID.

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

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

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

Returns

CTDBRET_OK on success.

See Also

ctdbEndImpersonation()

ctdbBigIntToCurrency

Convert a big integer value to a CTCURRENCY value.

Declaration

CTDBRET ctdbBigIntToCurrency(CTBIGINT value, pCTCURRENCY pCurrency)

Description

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

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

Returns

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

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

See also

ctdbCurrencyToBigInt()

 

ctdbBigIntToFloat

Convert a big integer value to a float.

Declaration

CTDBRET ctdbBigIntToFloat(CTBIGINT value, pCTFLOAT pFloat)

Description

ctdbBigIntToFloat() converts a big integer value to a float. A big integer is an 8 bytes integer value. Use ctdbFloatToBigInt() to convert from a float to a big integer. Use ctdbBigIntToLong() to convert a big integer value to a LONG.

  • value [in] the big integer value (8 bytes signed integer).
  • pFloat [out] the float value.

Returns

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

The possible error associated with ctdbBigIntToFloat() is CTDBRET_NULARG since a Null argument is not valid in pFloat.

See also

ctdbFloatToBigInt(), ctdbBigIntToLong()

 

ctdbBigIntToLong

Convert a big integer value to a LONG.

Declaration

CTDBRET ctdbBigIntToLong(CTBIGINT value, pLONG pLong)

Description

ctdbBigIntToLong() converts a big integer value to a LONG. A big integer is an 8 bytes integer value. Use ctdbLongToBigInt() to convert from a LONG to a big integer.

  • value [in] the big integer value (8 bytes signed integer).
  • pLong [out] the CTSIGNED LONG value (4 bytes signed integer).

Returns

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

Possible errors associated with ctdbBigIntToLong() are:

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

See also

ctdbLongToBigInt()

 

ctdbBigIntToNumber

Convert a big integer to a CTNUMBER value.

Declaration

CTDBRET ctdbBigIntToNumber(CTBIGINT value, pCTNUMBER pNumber)

Description

ctdbBigIntToNumber() converts a big integer value to CTNUMBER. Use ctdbNumberToBigInt() to convert from a big integer to CTNUMBER.

  • value [in] the CTBIGINT value.
  • pNumber [out] pointer to CTNUMBER.

Returns

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

The possible error associated with ctdbBigIntToNumber() is:

  • CTDBRET_NULARG (4007): Null argument not valid in pNumber

See also

ctdbNumberToBigInt()

 

ctdbBigIntToString

Convert a big integer value to a string.

Declaration

CTDBRET ctdbBigIntToString(CTBIGINT value, pTEXT pStr, NINT size)

Description

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

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

Returns

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

The possible error associated with ctdbBigIntToString() is:

  • CTDBRET_NULARG (4007): Null argument not valid in pStr

See also

ctdbStringToBigInt()

 

ctdbBlobClear

Clear a blob variable by releasing memory associated with data.

Declaration

CTDBRET ctdbBlobClear(pCTBLOB pBlob)

Description

ctdbBlobClear() clears a blob variable by releasing memory associated with data, setting data to NULL and size to zero.

  • pBlob [in] the blob pointer.

Returns

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

See also

ctdbBlobGetData(), ctdbBlobCmp(), ctdbBlobGetSize(), ctdbBlobSet(), ctdbBlobFree()

 

ctdbBlobCmp

Compare two blobs.

Declaration

NINT ctdbBlobCmp(pCTBLOB left, pCTBLOB right)

Description

ctdbBlobCmp() compares two blobs.

  • left [in] the first blob pointer.
  • right [in] the second blob pointer

Returns

ctdbBlobCmp() return a negative value if left < right, positive if left > right, and zero if both blobs are equal

See also

ctdbBlobGetData(), ctdbBlobClear(), ctdbBlobGetSize(), ctdbBlobSet()

 

ctdbBlobGetData

Return a pointer to the blob data.

Declaration

pVOID ctdbBlobGetData(pCTBLOB pBlob)

Description

ctdbBlobGetData() retrieves a pointer to the blob data.

  • pBlob [in] the blob pointer.

Returns

ctdbBlobGetData() returns the pointer to the blob data

See also

ctdbBlobGetSize(), ctdbBlobClear(), ctdbBlobCmp(), ctdbBlobSet()

 

ctdbBlobGetSize

Return the allocated size of a blob.

Declaration

VRLEN ctdbBlobGetSize(pCTBLOB pBlob)

Description

ctdbBlobGetSize() retrieves the allocated size of a blob.

  • pBlob [in] the blob pointer.

Returns

ctdbBlobGetSize() returns the allocated size of a blob

See also

ctdbBlobGetData(), ctdbBlobClear(), ctdbBlobCmp(), ctdbBlobSet()

 

ctdbBlobSet

Set the blob data.

Declaration

CTDBRET ctdbBlobSet(pCTBLOB pBlob, pVOID buffer, VRLEN size)

Description

ctdbBlobSet() sets the blob data.

  • pBlob [in/out] the blob pointer.
  • buffer [in] the pointer to data.
  • size [in] the number of bytes in the buffer

Returns

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

See also

ctdbBlobGetData(), ctdbBlobCmp(), ctdbBlobGetSize(), ctdbBlobFree()

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.

 

api methods c functions

Was this article helpful?

Give feedback about this article

Related Articles