Get By Percentage (44)

The Get By Percentage operation (B_SEEK_PERCENT) is one of two Btrieve API operations that can be used by window-oriented applications for implementing scroll bars. The other is the Find Percentage (45). Get By Percentage retrieves a record by that record's relative position in the file, where the position is based on a percentage value you supply when you call the operation. You must also specify whether the position is relative to a specified key path or represents the record's actual physical location in the file.

Parameters


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

Note
The Get By Percentage operation, when seeking the record by its physical location in the file, does not return any information in the Key Buffer parameter.

Prerequisites

The file must be open.

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

Procedure

Set the Operation Code to 44. Optionally, you can include a lock bias:

+100-Single wait record lock.

+200-Single no-wait record lock.

+300-Multiple wait record lock.

+400-Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.

Pass the Position Block for the file.

Store the percentage value as a 2-byte integer in the Data Buffer. See the "Details" section for the acceptable range of percentage values and related information.

Set the Data Buffer Length to a value greater than or equal to the length of the largest possible record that could be returned. (The transactional interface's internal implementation requires that you set the Data Buffer Length value to a minimum of 4 bytes). If specifying a granularity for the search, set the data buffer length to a minimum of 12 bytes.

Set the Key Number parameter.

If you are seeking the record by a key path, set the Key Number parameter to the actual key number. To use the system-defined log key (also called system data), specify 125.

If you are seeking the record by the record's physical position in the file, set the Key Number parameter to -1 (0xFF).

Details

If you are not specifying a granularity (see Granularity ), the range of acceptable percentage values for the first two bytes of the Data Buffer parameter is from 0 (indicating the beginning of the key path or file) through 10,000 (the end of the key path or file). The value corresponds to a range of 0% to 100.00%, assuming two implied decimal places. If you want to find the record approximately 33.33% through the file, pass the value 3333 in the Data Buffer. Be sure to store the value as an integer (in low-byte, high-byte order). For example, to seek to the 50 percent point in the file, use a value of 5,000 (0x1388). After byte-swapping 0x1388, store 0x88 and 0x13 in the first two bytes of 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 .

The Get By Percentage operation is provided specifically to support scroll bar implementation. Because many factors affect the accuracy of this operation-that is, whether the returned record is positioned at the actual percentage point you specify in the file-you should not rely on the accuracy of this operation for other purposes.

To optimize the Get By 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.

Granularity

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 Get By Percentage operation

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

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.

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 GetByPercentage with 100 as the percentage, and 365 as the granularity.

Result

If the Get By Percentage operation is successful, the transactional interface returns to the Data Buffer a record that is either from the designated position relative to the specified key path or from the physical position in the file. The transactional interface returns the length of the record in bytes into the Data Buffer Length parameter. If the operation seeks the record by a key path, the transactional interface returns the key value for the specified key path in the Key Buffer parameter. If the operation seeks the record by physical record order, the transactional interface does not return any information in the Key Buffer parameter.

Note
When Get By Percentage is seeking a record relative to a key path, and the key contains duplicate values, the transactional interface always returns the first record containing the duplicated value. This implementation detail can affect the accuracy of the operation.

If the Get By 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.

Positioning

If successful when seeking a record relative to a specified key path, the Get By Percentage operation establishes the new logical and physical currencies based respectively on the specified Key Number and the retrieved record.

If successful when seeking a record based on the record's physical location within the file, the Get By Percentage operation establishes the new physical currency based on the retrieved record.

If the Get By Percentage operation is unsuccessful, the transactional interface changes no currency.