F.99 EstimateKeySpan

---

Find the approximate number of entries between two key values.

Short Name

ESTKEY

TYPE

Low level index file function

DECLARATION

LONG EstimateKeySpan(COUNT keyno, pVOID target1, pVOID target2)

DESCRIPTION

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.

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. After a call to 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 Appendix A "c-tree Plus Error Codes" of the c-tree Plus Programmer's Reference Guide for a complete listing of valid c-tree Plus error values.

EXAMPLE

LONG retval;

COUNT 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 c-tree Plus is shipped. EstimateKeySpan should not be used in situations requiring precise results, since it is based on an approximate method.

SEE ALSO

KeyAtPercentile