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