Btrieve API Guide (v11)

Find Percentage(45)

Find Percentage オペレーション(B_GET_PERCENT)は、スクロール バーを実装するウィンドウ指向のアプリケーションで使用することのできる 2 つの Btrieve API オペレーションのうちの 1 つです。もう 1 つのオペレーションは Get By Percentage オペレーション(44)です。Find Percentage では、キー パスまたはファイル内でのレコードの物理位置を基準として、それに対応するレコードのおおよその位置を検出します。位置はパーセンテージ値で表されます。パーセンテージ値の範囲の定義については、「結果」のセクションを参照してください。

パラメーター

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

戻り値
 

 
 


メモ

Find Percentage を使って、キー パスを基準に対応するパーセンテージをシークする場合は、データ バッファー パラメーターに値を入力する必要はありません。ファイル内でのレコードの物理位置を基準に対応するパーセンテージをシークする場合は、キー バッファー パラメーターに値を入力する必要はありません。


前提条件

手順

  1. オペレーション コードに 45 を設定します。
  2. ファイルのポジション ブロックを渡します。
  3. ファイル内のレコードの物理位置を基準にパーセンテージをシークする場合は、レコードの物理アドレスをデータ バッファー パラメーターに格納します。レコードのキー パスを基準にパーセンテージをシークし、その検索に精度を指定する場合は、精度で指定されているようにデータ バッファー パラメーターを設定します。それ以外の場合は、データ バッファー パラメーターに値を入れる必要はありません。
  4. データ バッファー長に最小値である 4 バイトを設定します(この 4 バイトという最小長は、トランザクショナル インターフェイスの内部的な実装に必要とされます)。検索に精度を設定する場合は、データ バッファー長を最小値の 12 バイトに設定します。
  5. キー パスを基準にパーセンテージをシークする場合は、キー値をキー バッファー パラメーターに設定します。それ以外の場合は、キー バッファー パラメーターに値を入れる必要はありません。
  6. キー番号パラメーターを以下のとおりに設定します。
    1. キー パスによってパーセンテージをシークする場合は、キー番号パラメーターに実際のキー番号を設定します。
    2. レコードの物理位置によってパーセンテージをシークする場合は、キー番号パラメーターに -1(0xFF)を設定します。

詳細

Find Percentage オペレーションは、特にスクロール バーの実装をサポートする目的で用意されています。このオペレーションの精度、つまり、返されたパーセンテージ値がレコードまたはキー値の位置をどれだけ精確に反映しているかどうかは、さまざまな要因によって影響を受けます。このため、スクロール バーの実装以外の目的で使用する場合は、このオペレーションの精度を信頼しないでください。

Find Percentage オペレーションを最適化するため、トランザクショナル インターフェイスでは、ファイルのレコードはデータ ページ間に、キーはインデックス ページ間に均等に分布していることを前提としています。ただし、分布状態は次のような状況によって影響を受けます。

精度

精度の設定はオプションで、パーセンテージを測定する要素を選択することができます。Pervasive PSQL 9 より前のリリースでは、この値は常に 10,000 でした。

精度を指定する場合は、以下の手順に従ってください。

Find Percentage オペレーションの精度を指定するには

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

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

結果

Find Percentage オペレーションが正常に終了した場合は、トランザクショナル インターフェイスによって、指定したキー値またはレコードの相対位置がデータ バッファーに返されます。この位置は、キー パスまたはファイルにおけるオフセットのパーセンテージとして表され、0(0 %)から 10,000(100.00%)までの範囲の値になります。これは、物理位置でも論理位置でもないので注意してください。

パーセンテージ値は、下位バイト、上位バイトの順の 2 バイト整数として返されます。たとえば、次のようになります。

16 進数の戻り値
10 進数の戻り値
キー パスまたはファイル内でのパーセンテージ
88h 13h
00 50
50%

また、オペレーションが正常に終了した場合には、トランザクショナル インターフェイスからデータ バッファー長に 4 が返されます。

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

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

ポジショニング

Find Percentage オペレーションを実行しても、カレンシー情報は変更されません。


End Transaction(20)

Get By Percentage(44)