Btrieve API Guide (v11)

Get By Percentage(44)

Get By Percentage オペレーション(B_SEEK_PERCENT)は、スクロール バーを実装するウィンドウ指向のアプリケーションで使用することのできる 2 つの Btrieve API オペレーションのうちの 1 つです。もう 1 つは Find Percentage(45) です。Get By Percentage オペレーションは、ファイル内のレコードの相対位置によってレコードを取得します。この位置は、オペレーションを呼び出すときに指定したパーセンテージ値に基づきます。また、この位置は特定のキー パスを基準とするのか、ファイル内のレコードの実際の物理位置を表すのかを指定する必要があります。

パラメーター

 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値

 

戻り値
 

 


メモ

ファイル内のレコードの物理位置を基準としてレコードをシークする場合、Get By Percentage オペレーションからキー バッファー パラメーターには何の情報も返されません。


前提条件

手順

  1. オペレーション コードに 44 を設定します。オプションで、ロック バイアスも指定できます。
  2. ファイルのポジション ブロックを渡します。
  3. パーセンテージの値を 2 バイト整数でデータ バッファーに格納します。パーセンテージ値の許容範囲および関連情報については、「詳細」を参照してください。
  4. データ バッファー長に、返される可能性のある最大レコード長以上の値を設定します(トランザクショナル インターフェイスの内部的な実装は、データ バッファー長に最小値の 4 バイトが設定されていることを必要とします)。検索に精度を設定する場合は、データ バッファー長を最小値の 12 バイトに設定します。
  5. キー番号パラメーターを設定します。
    1. キー パスによってレコードをシークする場合は、キー番号パラメーターに実際のキー番号を設定します。システム定義のログ キー(システム データ)を使用するには、125 を指定します。
    2. ファイル内のレコードの物理位置によってレコードをシークする場合は、キー番号パラメーターに -1(0xFF)を設定します。

詳細

精度を指定しない場合(精度 を参照)、データ バッファー パラメーターの最初の 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 オペレーションの精度を指定するには

  1. データ バッファーの 2 番目の 4 バイトに ExPc を設定します。
  2. 3 番目の 4 バイトに希望する精度を LoHi Intel 整数で指定します。選択できる精度は、1 から 0xFFFFFFFF までの数値です。
  3. データ バッファー長が少なくとも 12 バイトあることを確認してください。

たとえば、365 件のレコードが入っているファイルから 100 番目のレコードを取得したい場合、パーセンテージに 100、精度に 365 を使用して GetByPercentage を実行することができます。

結果

Get By Percentage オペレーションが正常に終了した場合は、トランザクショナル インターフェイスによって、指定したキー パスを基準とする位置またはファイル内の物理位置にあるレコードがデータ バッファーに返されます。さらにトランザクショナル インターフェイスからは、データ バッファー長パラメーターにレコード長がバイト単位で返されます。キー パスによってレコードをシークした場合は、トランザクショナル インターフェイスからキー バッファー パラメーターに指定したキー パスのキー値が返されます。物理レコード順によってレコードをシークした場合は、トランザクショナル インターフェイスからキー バッファー パラメーターには何の情報も返されません。


メモ

Get By Percentage オペレーションでキー パスを基準としてレコードをシークした場合、そのキーに重複値が含まれているときは、トランザクショナル インターフェイスでは常に重複値を含む先頭のレコードが返されます。このような実装の細部によって、オペレーションの精度が影響を受ける場合があります。


Get By Percentage オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。

3
ファイルが開いていません。
6
キー番号パラメーターが不正です。
7
キー番号が変更されました。
8
現在のポジションが不正です。
9
オペレーションが EOF(end-of-file)を検出しました。
22
データ バッファー パラメーターが短すぎます。
41
実行しようとした操作はトランザクショナル インターフェイスでは許可されていません。
43
指定されたレコード アドレスが不正です。
82
トランザクショナル インターフェイスがポジショニングを失いました。

ポジショニング

指定したキー パスを基準としてレコードをシークするとき、Get By Percentage オペレーションが正常に終了した場合は、指定したキー番号と取得したレコードのそれぞれに基づいて新しい論理カレンシーおよび物理カレンシーが確立されます。

ファイル内のレコードの物理位置を基準としてレコードをシークするとき、Get By Percentage オペレーションが正常に終了した場合は、取得したレコードに基づいて新しい物理カレンシーが確立されます。

Get By Percentage オペレーションが正常に実行されなかった場合、トランザクショナル インターフェイスではカレンシーは変更されません。


Find Percentage(45)

Get Direct/Chunk(23)