Btrieve API Guide (v11)

Step Next Extended(38)

Step Next Extended オペレーション(B_STEP_NEXT_EXT)では、物理位置の直後からファイルの末尾へ向かって 1 つまたは複数のレコードを検索します。検索したレコードがフィルター条件を満たしているかどうかをチェックした上で、条件を満たすレコードだけを取得します。フィルター条件は論理式の形を取り、キー フィールドのみに制限されません。

Step Next Extended オペレーションでは、既存のレコードの中から指定したフィールドを抽出し、抽出したフィールドだけを含む新しいレコードのセットを返すこともできます。

パラメーター

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

 
 
戻り値
 

 
 

前提条件

手順

  1. オペレーション コードに 38 を設定します。オプションで、ロック バイアスも指定できます。
  2. ファイルのポジション ブロックを渡します。
  3. 入力データ バッファーと戻りデータ バッファーのどちらか大きい方を格納できるように、十分な長さのデータ バッファーを指定します。表 21 に示す構造体に従って、データ バッファーを初期化します。
  4. 上記の手順に従って、データ バッファー長に適切な値を指定します。
    トランザクショナル インターフェイスではバッファーを用意して、Extended オペレーションのワークスペースとして使用できるようにします。このバッファーのサイズは、[拡張オペレーション バッファー サイズ]オプションを使って構成します。データ バッファー構造体、取得される最長のレコード、およびリクエスターのオーバーヘッドの 355 バイト、これらの合計が設定したバッファー サイズを超えることはできません。(リクエスターのオーバーヘッドは、DOS ワークステーションのエンジンには適用できません。)

詳細

Step Next Extended オペレーションの「詳細」の内容は、Get Next Extended オペレーションと同じです。詳しくは詳細をご覧ください。

結果

Step Next Extended オペレーションが正常に終了した場合、トランザクショナル インターフェイスでは表 22 に示すとおり、取得された 1 つまたは複数のレコードに含まれる 1 つまたは複数のフィールドがデータ バッファーに返されます。さらにトランザクショナル インターフェイスから、データ バッファー長パラメーターには、データ バッファーに返されたバイト数が設定されます。

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

3
ファイルが開いていません。
9
オペレーションが EOF(end-of-file)を検出しました。
22
データ バッファー パラメーターが短すぎます。
60
指定されたリジェクト カウントに達しました。
61
作業領域が小さすぎます。
62
ディスクリプターが不正です。
64
フィルター制限に達しました。
65
フィールド オフセットが不正です。
82
トランザクショナル インターフェイスがポジショニングを失いました。
134
トランザクショナル インターフェイスがインターナショナル ソート規則(ISR)を読み取れません。
135
指定されたインターナショナル ソート規則(ISR)テーブルは破損しているか、または不正です。
136
トランザクショナル インターフェイスは、指定されたオルタネート コレーティング シーケンスをファイル内に見つけられません。

トランザクショナル インターフェイスでは、0 以外のステータス コードが返されても、有効なデータがデータ バッファーに返されることがあります。ただしこの場合、返された最後のレコードは不完全なものである可能性があります。データ バッファー長パラメーターに 0 を超える値が返されている場合は、データ バッファーに抽出されたデータを確認してください。

レコードが短すぎてフィールドの一部しか使用されない場合は、トランザクショナル インターフェイスからは、一部のみ使用されたフィールドも含めて、レコードから抽出できたもののみを返します。部分フィールドが抽出される最後のフィールドである場合、トランザクショナル インターフェイスではオペレーションが続行されます。そうでない場合、トランザクショナル インターフェイスではオペレーションは中止され、ステータス コード 22 が返されます。

たとえば、2 件の可変長レコードから 3 つのフィールドを取得する Step Next Extended オペレーションを考えてみましょう。最初のレコードは 55 バイトで、2 番目のレコードは 50 バイトだとします。取得するフィールドは次のように定義されています。

トランザクショナル インターフェイスで Step Next Extended オペレーションが実行されるとき、最初のレコードは問題なく返されます。しかし、2 番目のレコードのフィールド 2 から 10 バイトを抽出しようとすると、トランザクショナル インターフェイスではオフセット 45 とレコードの末尾のオフセット 49 の間では 5 バイトしか取得できないことが検出されます。この時点で、トランザクショナル インターフェイスではフィールド 2 の不足している 5 バイト分は詰め込まれないため、フィールド 3 は抽出できなくなります。その代わりに、トランザクショナル インターフェイスからステータス コード 22 が返され、フィールド 1 全体とフィールド 2 の先頭 5 バイトが戻りデータ バッファーに格納されます。

ポジショニング

Step Next Extended オペレーションを実行しても、論理カレンシーは確立しませんが、検索された最後のレコードが現在の物理レコードになります。なお、このレコードは取得されているとは限りません。このレコードは、フィルター条件を満たして取得されたレコードか、またはフィルター条件を満たさないために拒否されたレコードのいずれかです。


メモ

トランザクショナル インターフェイスでは、Step Next Extended オペレーションの後に Delete または Update オペレーションを実行することはできません。現在のレコードは検索された最後のレコードであるため、アプリケーションには、意図したレコードを適切に削除または更新しているかどうかを確認する方法がありません。



Step Next(24)

Step Previous(35)