Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic


Find key value located at about the given percentile.

Short Name



Low-Level index file function


LONG KeyAtPercentile(FILNO keyno, pVOID idxval, COUNT percnt)


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

KeyAtPercentile() finds the key value located, approximately, at the percentile specified by percnt. The key value is copied into the area pointed to by idxval. percnt should be in the range from zero (0) to one-hundred (100).

KeyAtPercentile() is very efficient since it does not traverse all of the key values in order to determine the key value located at the specified percentile. However, KeyAtPercentile() is only approximate because it assumes that the key values are uniformly distributed among all of the b-tree leaf nodes. For more accuracy, use GetORDKey() or NbrOfKeysInRange().

KeyAtPercentile() can be used to support scroll bar positioning, found in many windowing environments, in those cases when the position must be maintained in key sequential order.

See also Record Offsets Under Huge File Support.


If KeyAtPercentile() is successful, it returns the data record position associated with the key value in the index which is located, approximately, at the specified percentile value. If an error occurs or the index is empty, then KeyAtPercentile() returns zero. After a call to KeyAtPercentile() returns zero, check the value of uerr_cod: if uerr_cod is non-zero, an error condition was detected; otherwise, the index is empty.


Symbolic Constant




Successful function call.



percnt must be in the range of 0 to 100 inclusive.

See c-tree Error Codes for a complete listing of valid c-tree error values.


FILNO keyno;

TEXT idxval[24];

if (KeyAtPercentile(keyno,idxval,75))

printf("\n value at the 75th percentile is %.23s",idxval);

else if (uerr_cod)

printf("\n error %d occurred",uerr_cod);


printf("\n the index is empty");


Since KeyAtPercentile() is only approximate, it may be necessary in scroll bar applications to ensure that the result of KeyAtPercentile() is consistent with the current location. For example, you may want to detect the direction of the scroll bar motion and ensure that the key value returned is consistent. For more accuracy, use GetORDKey() or NbrOfKeysInRange().

While KeyAtPercentile() is approximate, it is self-consistent. As you increase (decrease) percnt, the associated key values will increase (decrease) in value.

See also

EstimateKeySpan(), GetORDKey(), NbrOfKeysInRange()