|
Get By Percentage オペレーション(B_SEEK_PERCENT)は、スクロール バーを実装するウィンドウ指向のアプリケーションで使用することのできる 2 つの Btrieve API オペレーションのうちの 1 つです。もう 1 つは Find Percentage(45)です。Get By Percentage オペレーションは、ファイル内のレコードの相対位置によってレコードを取得します。この位置は、オペレーションを呼び出すときに指定したパーセンテージ値に基づきます。また、この位置は特定のキー パスを基準とするのか、ファイル内のレコードの実際の物理位置を表すのかを指定する必要があります。
メモ
ファイル内のレコードの物理位置を基準としてレコードをシークする場合、Get By Percentage オペレーションからキー バッファー パラメーターには何の情報も返されません。
精度を指定しない場合(精度を参照)、データ バッファー パラメーターの最初の 2 バイトに対するパーセンテージ値の許容範囲は、0(キー パスまたはファイルの先頭を表します)から 10,000(キー パスまたはファイルの末尾を表します)までです。この値は、小数点以下 2 桁を含むものとして、0% から 100.00% の範囲に対応しています。ファイル中の 33.33% あたりにあるレコードを検索する場合は、データ バッファーに値 3333 を渡します。値は、下位バイト、上位バイトの順の整数として格納してください。たとえば、ファイル内の 50% の地点をシークするには、5,000(0x1388)という値を使います。0x1388 の下位バイトと上位バイトを入れ替え、0x88 と 0x13 をデータ バッファー パラメーターの先頭の 2 バイトに格納します。
レコードのキー パスを基準にパーセンテージをシークし、その検索に精度を指定する場合は、精度で指定されているようにデータ バッファー パラメーターを設定します。
Get By Percentage オペレーションは、特にスクロール バーの実装をサポートする目的で用意されています。このオペレーションの精度、つまり、返されたレコードがファイル内の指定したパーセンテージ地点に実際に位置しているかどうかは、さまざまな要因によって影響を受けます。このため、スクロール バーの実装以外の目的で使用する場合は、このオペレーションの精度を信頼しないでください。
Get By Percentage オペレーションを最適化するため、トランザクショナル インターフェイスでは、ファイルのレコードはデータ ページ間に、キーはインデックス ページ間に均等に分布していることを前提としています。ただし、分布状態は次のような状況によって影響を受けます。
精度の設定はオプションで、パーセンテージを測定する要素を選択することができます。Pervasive PSQL 9 より前のリリースでは、この値は常に 10,000 でした。
精度を指定する場合は、以下の手順に従ってください。
Get By Percentage オペレーションの精度を指定するには
たとえば、365 件のレコードが入っているファイルから 100 番目のレコードを取得したい場合、パーセンテージに 100、精度に 365 を使用して GetByPercentage を実行することができます。
Get By Percentage オペレーションが正常に終了した場合は、トランザクショナル インターフェイスによって、指定したキー パスを基準とする位置またはファイル内の物理位置にあるレコードがデータ バッファーに返されます。さらにトランザクショナル インターフェイスからは、データ バッファー長パラメーターにレコード長がバイト単位で返されます。キー パスによってレコードをシークした場合は、トランザクショナル インターフェイスからキー バッファー パラメーターに指定したキー パスのキー値が返されます。物理レコード順によってレコードをシークした場合は、トランザクショナル インターフェイスからキー バッファー パラメーターには何の情報も返されません。
メモ
Get By Percentage オペレーションでキー パスを基準としてレコードをシークした場合、そのキーに重複値が含まれているときは、トランザクショナル インターフェイスでは常に重複値を含む先頭のレコードが返されます。このような実装の細部によって、オペレーションの精度が影響を受ける場合があります。
Get By Percentage オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
指定したキー パスを基準としてレコードをシークするとき、Get By Percentage オペレーションが正常に終了した場合は、指定したキー番号と取得したレコードのそれぞれに基づいて新しい論理カレンシーおよび物理カレンシーが確立されます。
ファイル内のレコードの物理位置を基準としてレコードをシークするとき、Get By Percentage オペレーションが正常に終了した場合は、取得したレコードに基づいて新しい物理カレンシーが確立されます。
Get By Percentage オペレーションが正常に実行されなかった場合、トランザクショナル インターフェイスではカレンシーは変更されません。
|