KeyAtPercentile

Find key value located at about the given percentile.

Short Name

FRCKEY()

Type

Low level index file function

Declaration

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

Description

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.

Return

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.

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful function call.
60	KFRC_ERR	percnt must be in the range of 0 to 100 inclusive.

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

Example

COUNT     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);

else

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

Limitations

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.