c-treeDB API for C++ - Developers Guide

CTRecord::EstimateSpan

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

Declaration

LONG CTRecord::EstimateSpan(pVOID key1, pVOID key2);

Description

key1 and key2 are two key target values used to obtain the estimated number of records.

If CTRecord::EstimateSpan() returns 0, use CTRecord::GetError() function to retrieve the error code. If CTRecord::EstimateSpan() returns 0 and CTRecord::GetError() 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 CTIndex::SetDefault(). The table must have at least one index to be able to use this function.

CTRecord::EstimateSpan(), which is based on the c-tree low level function CTRecord::EstimateSpan(), does not traverse the index to compute the values. Instead, it makes approximately 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 CTRecord::EstimateSpan() can be created using CTRecord::BuildTargetKey().

Return

CTRecord::EstimateSpan() returns an estimate of records between key1 and key2. Call the CTRecord::GetError() method to check for error conditions.

Example

LONG Estimate(CTRecord& Handle, NINT index)

{

LONG Retval = 0;

TEXT key1[16], key2[16];

VRLEN klen;

try

{

// set the default index

Handle->SetDefaultIndex(index);

// load the first record

Handle->First();

// build the target key for the first record

klen = sizeof(key1);

Handle->BuildTargetKey(CTFIND_EQ, key1, &klen);

// load the last record

Handle->Last();

// build the target key for the last record

klen = sizeof(key2);

Handle->BuildTargetKey(CTFIND_EQ, key2, &klen);

// get the estimated span

Retval = Handle->EstimateSpan(key1, key2);

if (Retval > 0)

Retval--;

}

catch (CTException &err)

{

printf("Error: %s with error %d\n", err.GetErrorMsg(), err.GetErrorCode());

}

return Retval;

}