C API Functions N

ctdbNextBatch

Retrieves the next record from batch buffer.

DECLARATION

CTDBRET ctdbDECL ctdbNextBatch(CTHANDLE Handle);

DESCRIPTION

If the mode of the batch operation is one of CTBATCH_GET, CTBATCH_RANGE or CTBATCH_PHYS then it may be necessary to retrieve all records that match the batch criteria. The records are retrieved by calling the ctdbNextBatch() function.

The ctdbNextBatch() function retrieves the record data from the batch buffer maintained by FairCom DB API’s record handle. After a successful call to the ctdbNextBatch() function the field data can be retrieved by calling the appropriate ctdbGetFieldAs..() functions.

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

RETURNS

Value Symbolic Constant Explanation
0 CTDBRET_OK No error occurred.
428 BTMT_ERR No more records can be retrieved. (Indicates every record in batch was retrieved.)

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

EXAMPLE

/* retrieve records */
while (ctdbNextBatch(hRecord) == CTDBRET_OK)
{
    TEXT invoice[32], item[32];
 
    ctdbGetFieldAsString(hRecord, 0, invoice, sizeof(invoice));
    ctdbGetFieldAsString(hRecord, 1, item, sizeof(item));
    printf("%-11s %s\n", invoice, item);
}

SEE ALSO

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

ctdbNextDatabase

Get the name and path of the next database in this session dictionary.

Declaration

CTDBRET ctdbNextDatabase(CTHANDLE Handle, pTEXT Name, VRLEN NameSize,

pTEXT Path, VRLEN PathSize)

Description

ctdbNextDatabase() gets the name and path of the next database in this session dictionary.

  • Handle [in] the session handle.
  • Name [out] receives the database name.
  • NameSize [in] Name size in bytes. If Name is not large enough to receive the database name, ctdbNextDatabase() will return CTDBRET_ARGSMALL (4006).
  • Path [out] receives the database path, if the name is located and it is large enough to hold the path.
  • PathSize [in] Path size in bytes. If Path is not large enough to receive the database path, ctdbNextDatabase() will return CTDBRET_ARGSMALL (4006).

Use ctdbNextDatabase() with ctdbFirstDatabase() to obtain the names and paths of all the databases that are in this session dictionary. Use ctdbGetDatabaseCount() to retrieve the total number of databases in the session dictionary.

Returns

ctdbNextDatabase() returns CTDBRET_OK on success, or INOT_ERR (101) after the last database in the session dictionary has been retrieved, or a c-tree error code on failure.

Example


ctdbFirstDatabase(hSession, name, sizeof(name), path, sizeof(path));

do {

printf("\n\nDatabase: %s (%s)\n", path, name);

}

while (

ctdbNextDatabase(hSession, name, sizeof(name), path, sizeof(path))

== CTDBRET_OK );

 

See also

ctdbFirstDatabase(), ctdbFindDatabase(), ctdbGetDatabaseCount()

 

 

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

ctdbNextResource

Locate and retrieve the next resource in a table.

Declaration

CTDBRET ctdbDECL ctdbNextResource(CTHANDLE resource, CTBOOL lock)

Description

ctdbNextResource() retrieve the next resource stored in a table. The resource parameter is a handle allocated with ctdbAllocHandle(). lock is used to indicate if the resource should be locked, if it is found. To retrieve all of the resources stored in a table, call ctdbNextResource() and then call this function until it returns RNOT_ERR (408). To retrieve all the resources stored in a table starting from a given resource type and number, allocate a resource handle, set the resource type and a resource number, and then call this function until it returns RNOT_ERR (408).

Return

ctdbNextResource() returns CTDBRET_OK on success. After the last resource has been retrieved from the table, ctdbNextResource() returns RNOT_ERR (408).

Example

/* read resources with type >= type and number > 0 */

CTDBRET DisplayResources(CTHANDLE hTable, ULONG type)

{

CTDBRET eRet;

CTHANDLE hRes = ctdbAllocResource(hTable, type, 0, NULL);

/* check if resource was allocated */

if (!hRes)

return ctdbGetError(hTable);

 

/* note that no resource locks are acquired since we are not changing the resources */

while ((eRet = ctdbNextResource(hRes)) == CTDBRET_OK)

{

/* display resource type, number and name */

printf("Resource type: %u, number: %u", ctdbGetResourceType(hRes), ctdbGetResourceNumber(hRes));

if (ctdbGetResourceName(hRes) != NULL)

printf(", name: \"\"\n", ctdbGetResourceName(hRes));

else

printf(", name: NULL"\n");

}

ctdbFreeResource(hRes);

return eRet;

}

See Also

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

 

 

ctdbNextTable

Get the name and path of the next table in a database dictionary.

Declaration

CTDBRET ctdbNextTable(CTHANDLE Handle, pTEXT Name, VRLEN NameSize,

pTEXT Path, VRLEN PathSize)

Description

ctdbNextTable gets the name and the path of the next table in a database dictionary.

  • Handle [in] the Database Handle.
  • Name [out] receives the table name.
  • NameSize [in] the Name size in bytes.
  • Path [out] receives the table path.
  • PathSize [in] the Path size in bytes.

ctdbNextTable(), in conjunction with ctdbFirstTable(), may be used to obtain the names and paths of all tables available in this database dictionary. ctdbGetTableCount() may be used to retrieve the total number of tables in the database.

Returns

ctdbNextTable() returns CTDBRET_OK on success, or the c-tree error code on failure. Note that INOT_ERR (101) is returned after the last table in the database dictionary has been retrieved.

Example


ctdbFirstTable(hDB, t_name, sizeof(t_name), t_path, sizeof (t_path));

do

{ printf("\ntable name: %s", t_name); }

while (ctdbNextTable(hDB, t_name, sizeof(t_name), t_path,

sizeof(t_path)) == CTDBRET_OK);


See also

ctdbFirstTable(), ctdbFindTable(), ctdbGetTableCount()

 

 

ctdbNextTableXtd

Get the next table in a database dictionary.

Declaration

CTDBRET ctdbDECL ctdbNextTableXtd(CTHANDLE Handle, pCTDBDICTDATA data)

Description

Handle [IN] - Database handle.

data [OUT] - dictionary data for the table

Return Values

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

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

See Also

ctdbNextTable

ctdbNumberAbs

Return the absolute value of a CTNUMBER type value.

Declaration

CTDBRET ctdbNumberAbs(pCTNUMBER pSource, pCTNUMBER pResult)

Description

ctdbNumberAbs() returns the absolute value of a CTNUMBER type value.

  • pSource [in] the value to be converted to absolute.
  • pResult [out] the absolute value.

Returns

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

The possible errors associated with ctdbNumberAbs() are:

  • CTDBRET_NULARG (4007): Null argument not valid in any operand

See also

ctdbNumberAdd(), ctdbNumberSub(), ctdbNumberMul(), ctdbNumberDiv(), ctdbNumberCmp(), ctdbNumberNegate(), ctdbNumberZero(), ctdbNumberRound(), ctdbNumberCopy(), ctdbNumberGetDecimal()

 

ctdbNumberAdd

Add two Number values. pResult = left + right

Declaration

CTDBRET ctdbNumberAdd(pCTNUMBER pLeft, pCTNUMBER pRight,
                      pCTNUMBER pResult)

Description

ctdbNumberAdd() add number pLeft to pRight and store the result in ‘pResult’. Do not make regular additions with CTNUMBER values.

  • pLeft [in] pointer to the first value to be added.
  • pRight [in] pointer to the second value to be added.
  • pResult [out] pointer to the result of the add operation.

Returns

ctdbNumberAdd() returns CTDBRET_OK on success, or FairCom DB API error on failure. The possible error associated with ctdbNumberAdd() is:

  • CTDBRET_OVERFLOW (4038): Operation caused overflow

See also

ctdbNumberSub(), ctdbNumberMul(), ctdbNumberDiv()

 

ctdbNumberCmp

Compare two CTNUMBER type values.

Declaration

NINT ctdbNumberCmp(pCTNUMBER num1, pCTNUMBER num2)

Description

ctdbNumberCmp() compares two CTNUMBER values.

  • num1 [IN], num2 [IN] pointers to the values to be compared.

Returns

ctdbNumberCmp() returns a negative value if num1 < num2, positive value if num1 > num2, and zero if num1 == num2

See also

ctdbNumberAdd(), ctdbNumberSub(), ctdbNumberMul(), ctdbNumberDiv(), ctdbNumberAbs(), ctdbNumberNegate(), ctdbNumberZero(), ctdbNumberRound(), ctdbNumberCopy(), ctdbNumberGetDecimal()

 

ctdbNumberCopy

Copy a number from pSource to pDest.

Declaration

CTDBRET ctdbNumberCopy(pCTNUMBER pDest, pCTNUMBER pSource)

Description

ctdbNumberAbs() copies a number from pSource to pDest.

  • pDest [out] pointer to the destination of the copy operation.
  • pSource [in] pointer to the source value to be copied.

Returns

ctdbNumberAbs() returns CTDBRET_OK on success, or FairCom DB API error on failure. The possible errors associated with ctdbNumberAbs() are:

  • CTDBRET_NULARG (4007): Null argument not valid in any operand

See also

ctdbNumberAdd(), ctdbNumberSub(), ctdbNumberMul(), ctdbNumberDiv(), ctdbNumberCmp(), ctdbNumberNegate(), ctdbNumberZero(), ctdbNumberRound(), ctdbNumberCopy(), ctdbNumberGetDecimal()

 

ctdbNumberDiv

Divide one Number value by another Number value. pResult = pLeft / pRight.

Declaration

CTDBRET ctdbNumberDiv(pCTNUMBER pLeft, pCTNUMBER pRight,
                      pCTNUMBER pResult)

Description

ctdbNumberDiv() divide one Number value by another Number value. pResult = pLeft / pRight. Do not make regular division with CTNUMBER values.

  • pLeft [in] the value to be divided by pRight (divisor).
  • pRight [in] the value to divide into pLeft (dividend).
  • pResult [out] the result of the Div operation.

Returns

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

The possible errors associated with ctdbNumberDiv() are:

  • CTDBRET_NULARG (4007): Null argument not valid in any operand
  • CTDBRET_DIVBYZERO (4040): Division by zero error

See also

ctdbNumberAdd(), ctdbNumberSub(), ctdbNumberMul()

 

ctdbNumberGetDecimal

Retrieve the number of digits before and after the decimal point.

Declaration

CTDBRET ctdbNumberGetDecimal(pCTNUMBER data, pNINT digit_before,
                             pNINT digit_after)

Description

ctdbNumberGetDecimal() retrieves the number of digits before and after the decimal point.

  • data [in] pointer to number.
  • digit_before [out] the number of digits before the decimal place.
  • digit_after [out] the number of digits after the decimal place.

Returns

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

The possible errors associated with ctdbNumberGetDecimal() are:

  • CTDBRET_NULARG (4007): Null argument not valid in any operand
  • CTDBRET_INVNUMBER (4060): Number value invalid (out of bounds)

See also

ctdbNumberAdd(), ctdbNumberSub(), ctdbNumberMul(), ctdbNumberDiv(), ctdbNumberAbs(), ctdbNumberCmp(), ctdbNumberZero(), ctdbNumberCopy(), ctdbNumberGetDecimal(), ctdbNumberCopy(), ctdbNumberRound()

 

ctdbNumberMul

Multiply two CTNUMBER values.

Declaration

CTDBRET ctdbNumberMul(pCTNUMBER pLeft, pCTNUMBER pRight,
                      pCTNUMBER pResult)

Description

ctdbNumberMul multiplies two Number values. pResult = pLeft * pRight. Do not use regular multiplication with CTNUMBER values.

  • pLeft [in] the first value to be multiplied.
  • pRight [in] the second value to be multiplied.
  • pResult [out] the result of the multiplication operation.

Returns

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

The possible errors associated with ctdbNumberMul() are:

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

See also

ctdbNumberAdd(), ctdbNumberSub(), ctdbNumberDiv()

 

ctdbNumberNegate

Negate a number.

Declaration

CTDBRET ctdbNumberNegate(pCTNUMBER pSource, pCTNUMBER pResult)

Description

ctdbNumberNegate negates a number (eg. -Number).

  • pSource [in] the value to be negated.
  • pResult [out] the negated value (= -pSource).

Returns

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

The possible errors associated with ctdbNumberNegate() are:

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

See also

ctdbNumberAdd(), ctdbNumberSub(), ctdbNumberMul(), ctdbNumberDiv(), ctdbNumberAbs(), ctdbNumberCmp(), ctdbNumberZero(), ctdbNumberRound(), ctdbNumberCopy(), ctdbNumberGetDecimal()

 

ctdbNumberOfKeyEntries

Declaration

LONG ctdbDECL ctdbNumberOfKeyEntries(CTHANDLE Handle, NINT index);

Description

ctdbNumberOfKeyEntries() retrieves the number key entries in an index file identified by its index number.

  • Handle is a table handle or a handle that can be evaluated into a table handle.
  • index identifies the index to obtain the number of entries. The first index number is zero.

Return Values

ctdbNumberOfKeyEntries() returns the number of key entries in the index. ctdbNumberOfKeyEntries() returns -1 and users should call the ctdbGetError() function to retrieve the error code.

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

Example


LONG Estimate(CTHANDLE Handle, NINT index)

{

LONG Retval = 0;

TEXT key1[16], key2[16];

VRLEN klen;

/* set the default index */

ctdbSetDefaultIndex(Handle, index);

/* load the first record */

ctdbFirstRecord(Handle);

/* build the target key for the first record */

klen = sizeof(key1);

ctdbBuildTargetKey(Handle, CTFIND_EQ, key1, &klen);

/* load the last record */

ctdbLastRecord(Handle);

/* build the target key for the last record */

klen = sizeof(key2);

ctdbBuildTargetKey(Handle, CTFIND_EQ, key2, &klen);

/* get the estimated span */

Retval = ctdbEstimateSpan(Handle, key1, key2);

if (Retval > 0)

Retval--;

return Retval;

}

 

See Also

ctdbGetError(), ctdbEstimateKeySpan()

 

 

 

ctdbNumberRound

Round a number to a scale.

Declaration

CTDBRET ctdbNumberRound(pCTNUMBER num, NINT scale)

Description

ctdbNumberRound() rounds a number to a certain number of decimal digits.

  • num [in] pointer to the number to be rounded.
  • scale [out] the number of decimal digits.

Returns

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

The possible errors associated with ctdbNumberRound() are:

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

See also

ctdbNumberAdd(), ctdbNumberSub(), ctdbNumberMul(), ctdbNumberDiv(), ctdbNumberAbs(), ctdbNumberCmp(), ctdbNumberZero(), ctdbNumberCopy(), ctdbNumberGetDecimal(), ctdbNumberCopy(), ctdbNumberGetDecimal()

 

ctdbNumberSub

Subtract two Number values. pResult = pLeft - pRight.

Declaration

CTDBRET ctdbNumberSub(pCTNUMBER pLeft, pCTNUMBER pRight, pCTNUMBER pResult)

Description

ctdbNumberSub() subtracts two Number values. pResult = pLeft - pRight. Do not make regular subtractions with CTNUMBER values.

  • pLeft [in] the first value, from which the pRight value will be subtracted.
  • pRight [in] the second value, which is the value to subtract from pLeft.
  • pResult [out] the result of the subtraction operation.

Returns

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

The possible errors associated with ctdbNumberSub() are:

  • CTDBRET_NULARG (4007): Null argument not valid in any operand
  • CTDBRET_UNDERFLOW (4039): Operation caused underflow
  • CTDBRET_OVERFLOW (4038): Operation caused overflow

See also

ctdbNumberAdd(), ctdbNumberMul(), ctdbNumberDiv()

 

ctdbNumberToBigInt

Convert a CTNUMBER value to a big integer.

Declaration

CTDBRET ctdbNumberToBigInt(pCTNUMBER pNumber, pCTBIGINT pValue)

Description

ctdbNumberToBigInt() converts a CTNUMBER value to a big integer (8 bytes). Use ctdbBigIntToNumber() to convert from a big integer to CTNUMBER. Use ctdbNumberToLong() to convert CTNUMBER to a LONG (4 bytes integer).

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

Returns

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

The possible error associated with ctdbNumberToBigInt() is:

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

See also

ctdbBigIntToNumber(), ctdbNumberToLong()

 

ctdbNumberToCurrency

Convert a CTNUMBER value to a currency value.

Declaration

CTDBRET ctdbNumberToCurrency(pCTNUMBER pNumber, pCTCURRENCY pValue)

Description

ctdbNumberToCurrency() converts a CTNUMBER value to a CTCURRENCY value. Use ctdbCurrencyToNumber() to convert from a CTCURRENCY to CTNUMBER. Use ctdbNumberToMoney() to convert CTNUMBER to a CTMONEY.

  • pNumber [in] pointer to the CTNUMBER to be converted.
  • pValue [out] pointer the output CTCURRENCY value.

Returns

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

The possible error associated with ctdbNumberToCurrency() is:

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

See also

ctdbCurrencyToNumber(), ctdbNumberToLong(), ctdbNumberToMoney()

 

ctdbNumberToFloat

Convert a CTNUMBER value to a floating point value.

Declaration

CTDBRET ctdbNumberToFloat(pCTNUMBER pNumber, pCTFLOAT pValue)

Description

ctdbNumberToFloat() converts a CTNUMBER value to a floating point value. Use ctdbFloatToNumber() to convert from float to CTNUMBER.

  • pNumber [in] pointer to CTNUMBER.
  • pValue [out] pointer to floating point value.

Returns

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

The possible error associated with ctdbNumberToFloat() is:

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

See also

ctdbFloatToNumber()

 

ctdbNumberToLong

Convert a CTNUMBER value to a LONG.

Declaration

CTDBRET ctdbNumberToLong(pCTNUMBER pNumber, pLONG pValue)

Description

ctdbNumberToLong() converts a CTNUMBER value to a LONG. Use ctdbLongToNumber() to convert from LONG to CTNUMBER. Use ctdbNumberToBigInt() to convert a CTNUMBER to a big integer (8 byte integer).

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

Returns

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

The possible error associated with ctdbNumberToLong() is:

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

See also

ctdbLongToNumber(), ctdbNumberToBigInt()

 

ctdbNumberToMoney

Convert a CTNUMBER value to CTMONEY.

Declaration

CTDBRET ctdbNumberToMoney(pCTNUMBER pNumber, pCTMONEY pMoney)

Description

ctdbNumberToMoney() converts a CTNUMBER value to a CTMONEY. Use ctdbMoneyToNumber() to convert from CTMONEY to CTNUMBER. Use ctdbNumberToCurrency() to convert CTNUMBER to a CTCURRENCY.

 

ctdbNumberToString

Convert a CTNUMBER value to a string.

Declaration

CTDBRET ctdbNumberToString(pCTNUMBER pNumber, pTEXT pStr, VRLEN size)

Description

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

  • pNumber [in] pointer to CTNUMBER value.
  • pStr [out] the pointer to the string that will result from the conversion.
  • size [in] the buffer size (in bytes) of the string.

Returns

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

The possible errors associated with ctdbNumberToString() are:

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

See also

ctdbStringToNumber()

 

pNumber [in] pointer to the CTNUMBER value.

  • pMoney [out] pointer to the CTMONEY value.

Returns

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

The possible error associated with ctdbNumberToMoney() is:

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

See also

ctdbMoneyToNumber(), ctdbNumberToCurrency()

 

ctdbNumberZero

Set the value of a number to zero.

Declaration

CTDBRET ctdbNumberZero(pCTNUMBER pNumber)

Description

ctdbNumberZero() sets the value of a number to zero.

  • pNumber [in] pointer to a number.

Returns

ctdbNumberZero() returns CTDBRET_OK on success, or FairCom DB API error on failure. Use ctdbIsNumberZero() to check if a number is zero.

The possible error associated with ctdbNumberZero() is:

  • CTDBRET_NULARG (4007): Null argument not valid in any operand

See also

ctdbIsNumberZero(), ctdbNumberAbs(), ctdbNumberCmp(), ctdbNumberNegate(), ctdbNumberRound(), ctdbNumberCopy(), ctdbNumberGetDecimal()