FairCom DB API for C

ctdbEstimateSpan

Estimate an approximate number of records between two key target values.

Declaration

LONG ctdbEstimateSpan(CTHANDLE Handle, pVOID key1, pVOID key2);

Description

Handle is a record handle.
key1 and key2 are two key target values used to obtain the estimated number of records.

If ctdbEstimateSpan() returns 0, use ctdbGetError() function to retrieve the error code. If ctdbEstimateSpan() returns 0 and ctdbGetError() returns CTDBRET_OK then there are no records between the two key values supplied.

The estimation is based on the record handle current index. The current index may be changed by calling ctdbSetDefaultIndex(). The table must have at least one index to be able to use this function.

ctdbEstimateSpan(), which is based on c-tree low level function EstimateKeySpan(), does not traverse the index to compute the values. Instead, it makes about ten calls to the c-tree low level function KeyAtPercentile() to determine the relative location of the target values.

The key target values used by ctdbEstimateSpan() can be created using ctdbBuildTargetKey().

Return

ctdbEstimateSpan() returns an estimate of the number of records between key1 and key2. Call ctdbGetError() to retrieve the error code.

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

Example

Suppose that a student table has two fields (Name - CT_FSTRING and Age - CT_INT2) and one index on field Age. The sample function estimate the number of students with ages between 10 and 12:

LONG EstimateStudents(CTHANDLE hRecord)

{

TEXT key1[32];

TEXT key2[32];

VRLEN key1Len = 32;

VRLEN key2Len = 32;

/* build the first key for age = 10 years */

ctdbClearRecord(hRecord);

ctdbSetFieldAsSigned(hRecord, 1, 10);

if (ctdbBuildTargetKey(hRecord, CTFIND_EQ, key1, &key1Len))

return 0;

/* build the second key for age = 12 years */

ctdbClearRecord(hRecord);

ctdbSetFieldAsSigned(hRecord, 1, 12);

if (ctdbBuildTargetKey(hRecord, CTFIND_EQ, key2, &key2Len))

return 0;

/* estimate the number of students */

return ctdbEstimateSpan(hRecord, key1, key2);

}