|
|
|
EstimateKeySpan
Find the approximate number of entries between two key values.
Short Name
ESTKEY()
Type
Low-Level index file function
Declaration
LONG EstimateKeySpan(FILNO keyno, pVOID target1, pVOID target2)
Description
In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering
EstimateKeySpan() finds the approximate number of entries between the two key values pointed to by target1 and target2. EstimateKeySpan() does not traverse the index to compute the values. Instead, it makes about ten calls to KeyAtPercentile() to determine the relative location of the target values. EstimateKeySpan() does not require target1 and target2 to be in ascending order.
EstimateKeySpan() can be used to select among alternate search paths when a retrieval request may be satisfied by more than one index.
Note: A huge file may return values greater than 4 GB. This function returns the low-order 4-byte word of the 8-byte number of keys. To get the high-order 4-byte word, call ctGETHGH(). A return of zero is not necessarily an error if there are exactly a multiple 4 GB worth of key values.
Return
If EstimateKeySpan() is successful, it returns the approximate number of key value entries located between target1 and target2. If an error occurs or the index is empty, EstimateKeySpan() returns a zero. When EstimateKeySpan() returns zero, check the value of uerr_cod: if uerr_cod is non-zero, an error condition was detected; otherwise, the index is empty. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.
Example
LONG retval;
FILNO keyno;
TEXT t1[24],t2[24];
scanf("%23s %23s",t1,t2);
if (retval = EstimateKeySpan(keyno,t1,t2))
printf("\n %ld entries between %.23s and %.23s", retval,t1,t2);
else if (uerr_cod)
printf("\n error %d occurred",uerr_cod);
else
printf("\n the index is empty");
Limitations
The number of index entries must be maintained by the index header record, which is the default when FairCom DB is shipped. EstimateKeySpan() should not be used in situations requiring precise results, since it is based on an approximate method.
See also
KeyAtPercentile()
