c-treeDB API API for C

ctdbRecordRangeOn

Establish a new index range on a record handle.

Declaration

CTDBRET ctdbRecordRangeOn(CTHANDLE Handle, NINT SegCount,

pVOID lRange, pVOID uRange, pNINT operators);

Description

ctdbRecordRangeOn() establish a new range based on the key segment values passed on lRange and uRange buffers, and the operators for each segment. Once the range is set, use ctdbFirstRecord(), ctdbNextRecord(), ctdbPrevRecord() and ctdbLastRecord() to navigate the records in the specified range. The range is set for all index entries that are situated between the lower bounds and upper bounds values. The segment values are stored in lRange and uRange buffers in the same order and type of the index segment definition. If a previous range exists for this index, the previous range is released and the new range is established. Ranges take precedence over sets. While a record handle has both a Set (ctdbRecordSetOn()) and a Range enabled, the Range takes precedence and the Set is ignored.

Handle is the record handle.
SegCount indicates the number of index segments values that should be used for setting the range, and the number of operators, since there must be one operator for each key segment in lRange and/or uRange.
lRange is a buffer with the lower range segment values. Use the function ctdbBuildTargetKey() to build the lRange buffer.
uRange is a buffer with the upper range segment values. Use the function ctdbBuildTargetKey() to build the uRange buffer.
operators operators is an array of operators. There must be one operator for each key segment in lRange and/or uRange. The operators CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT are open ended and use only the lRange buffer for range values and the equivalent key segment in uRange is ignored and maybe set to null (ascii \0 values). The operators CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE and CTIX_NOTBET use both lRange and uRange buffers to establish the lower and upper bound values.

Return

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	ctdbRecordRangeOn() returns CTDBRET_OK on success or c-treeDB API SDK error code on failure.

See c-treeDB API Errors and Return Values for a complete listing of valid c-treeDB API error codes and return values.

Example

/* display all records where age is greater than 65 */

/* NOTE: Always check the return type of API functions for errors. */

/* This code omits much of that for brevity. */

void DisplayAll(CTHANDLE hRecord)

{

UTEXT lRange[32];

VRLEN lRangeLen = 32;

NINT op[1] = {CTIX_GT};

NINT fldno = ctdbGetFieldNumberByName(hHandle, "age");

CTDBRET eRet;

ctdbClearRecord(hRecord);

ctdbSetFieldAsSigned(hRecord, fldno, 65);

ctdbSetDefaultIndex(hRecord, 0);

ctdbBuildTargetKey(hRecord, CTFIND_EQ, lRange, &lRangeLen);

eRet = ctdbRecordRangeOn(hRecord, 1, lRange, NULL, op);

if (eRet == CTDBRET_OK)

{

eRet = ctdbFirstRecord(hRecord);

while (eRet == CTDBRET_OK)

{

TEXT str[128];

ctdbGetFieldAsString(hRecord, 0, str, sizeof(str));

printf("%s\n", str);

eRet = ctdbNextRecord(hRecord);

}

if (ctdbIsRecordRangeOn(hRecord))

ctdbRecordRangeOff(hRecord);

}