Find Percentage (45)

Find Percentage (45)

The Find Percentage operation (B_GET_PERCENT) is one of two Btrieve API operations that window-oriented applications can use to implement scroll bars. The other is the Get By Percentage operation (44). Find Percentage finds the approximate position of a record either relative to a key path or as the record’s physical location within the file. The position is expressed as a percentage value. See the “Result” section for a definition of the range of percentage values.


	Op Code	Pos Block	Data Buf	Data Buf Len	Key Buffer	Key Number
Sent
Returned

Note: When seeking the percentage relative to a key path, Find Percentage does not require an input value for the Data Buffer parameter. When seeking the percentage as relative to a record’s physical location within the file, Find Percentage does not require an input value for the Key Buffer parameter.

•

The file must be open.

•

If you are seeking the percentage relative to a key path, the file cannot be a data-only file.

•

When you are seeking the percentage by a record’s physical location in the file, you must provide the 4-byte physical location of the record in the Data Buffer parameter. You can retrieve this location with a Get Position operation (22).

1

Set the Operation Code to 45.

2

Pass the Position Block for the file.

3

If you are seeking the percentage relative to the record’s physical location within the file, store the record’s physical address in the Data Buffer parameter. If you are seeking the percentage relative to the record’s key path and wish to specify a granularity for the search, set your Data Buffer parameter as specified in Granularity. Otherwise, you do not need to provide a value for the Data Buffer parameter.

4

Set the Data Buffer Length to a minimum of 4 bytes. (This 4-byte minimum is a requirement of the transactional interface’s internal implementation). If specifying a granularity for the search, set the data buffer length to a minimum of 12 bytes.

5

If you are seeking the percentage relative to a key path, set the Key Buffer parameter to the key value. Otherwise, you do not need to provide a value for the Key Buffer parameter.

6

Set the Key Number parameter as follows:

a.

If you are seeking the percentage by a key path, set the Key Number parameter to the actual key number.

b.

If you are seeking the percentage by the record’s physical location, set the Key Number parameter to -1 (0xFF).

The Find Percentage operation is provided specifically to support scroll bar implementation. Because many factors affect the accuracy of this operation—that is, whether the returned percentage value accurately reflects the position of the record or key value—you should not rely on the accuracy of this operation for other purposes.

To optimize the Find Percentage operation, the transactional interface assumes that a file has an even distribution of records among the data pages and keys among the index pages. However, distribution can be affected by the following situations:

•

The file is not index balanced, and a large number of records within the same range of keys has been deleted.

•

A large number of records within the same range of physical addresses has been deleted.

•

The file contains numerous duplicate key values, and the key is a linked-duplicatable key.

The granularity setting is optional and allows you to choose the factor by which the percentage is measured. In releases prior to Pervasive PSQL 9, this value was always 10,000.

If you want to specify the granularity, follow these steps:

►

To specify a granularity in the Find Percentage operation

1

Place ExPc in the second four bytes of the data buffer.

2

Place the desired granularity in the third four bytes as a LoHi Intel integer. The granularity you choose can be any number from 1 to 0xFFFFFFFF.

3

Ensure that your data buffer length is at least 12 bytes.

For example if you want to get the 100th record from a file that contains 365 records, you can use FindPercentage with 100 as the percentage, and 365 as the granularity.

If the Find Percentage operation is successful, the transactional interface returns the relative position of the specified key value or record to the Data Buffer. This position is expressed as a percentage of the offset into the key path or file and is a value in the range of 0 (0 percent) through 10,000 (100.00 percent). Note this is not the physical or logical position.

The percentage value is returned as a 2-byte integer in low-byte, high-byte order. For example:


Returned Value Hex	Returned Value Dec	Percentage in Key Path or File
88h 13h	00 50	50%

The transactional interface also returns a Data Buffer Length of 4 if the operation is successful.

If the Find Percentage operation is unsuccessful, the transactional interface returns one of the following status codes:


3	The file is not open.
6	The key number parameter is invalid.
7	The key number has changed.
8	The current positioning is invalid.
9	The operation encountered the end-of-file.
22	The data buffer parameter is too short.
41	The transactional interface does not allow the attempted operation.
43	The specified record address is invalid.
82	The transactional interface lost positioning.

The Find Percentage operation does not change any currency information.