Btrieve API Guide (v11)

Get Next Extended(36)

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

Get Next Extended オペレーションでは、レコードから指定した部分だけを抽出し、その部分だけをアプリケーションに返すこともできます。

パラメーター

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

戻り値
 

 

前提条件

手順

  1. オペレーション コードに 36 を設定します。オプションで、ロック バイアスも指定できます。
  2. ファイルのポジション ブロックを渡します。
  3. 入力データ バッファーと戻りデータ バッファーのどちらか大きい方を格納できるように、十分な長さのデータ バッファーを指定します。表 21 に示す構造体に従って、データ バッファーを初期化します。
  4. データ バッファー長に、入力構造体(表 21)と戻り構造体(表 22)のどちらか大きい方の長さを指定します。
  5. キー バッファーに前のオペレーションで取得したキー値を指定します。キー バッファーには、前の呼び出しでトランザクショナル インターフェイスから返されたキー値とまったく同じものを渡します。トランザクショナル インターフェイスでは、ファイル内の現在の位置を決定するために、直前にキー バッファーに格納された情報が必要となるからです。
  6. キー番号パラメーターに、前の呼び出しで使用したキー パスを設定します。Get Next Extended オペレーションを使ってキー パスを変更することはできません。

詳細

次の表は、入力データ バッファーの構造体を示しています。

表 21 Extended Get / Step オペレーションの入力データ バッファー構造体
要素
長さ(バイト単位)
説明
ヘッダー
2
データ バッファー全体の長さ。
2
2 つの文字列定数値のいずれかを指定します(固定長で、ヌル終端にしてはいけません)。
"EG" - ポジショニングされているレコードの次のレコードから検索を開始します。
"UC" - ポジショニングされているレコードから検索を開始します。
Step Next Extended オペレーションの場合は、この値には常に "EG" を設定してください。
フィルター(固定部分)
2
リジェクト カウントの最大数。これは、トランザクショナル インターフェイスでレコードの検索中に、フィルター条件を満たさないものとしてスキップできるレコードの件数です。0 から 65,535 までの範囲の値を指定できます(0 を指定すると、トランザクショナル インターフェイスではシステム定義の最大リジェクト カウント、4,095 が使用されます)。
2
フィルター条件として使用する論理式の項の数。(0 指定すると、トランザクショナル インターフェイスではフィルター処理が実行されません)。項の数はデータ バッファーのサイズによってのみ制限されます。Pervasive.SQL 2000i SP3 でのみ、項の数が 119 に制限されています。
フィルター(論理式の各項について、このセグメントを 1 回繰り返す)
1
フィールドのデータ型。表 11 に記載されているコードのいずれかを使用します。
2
フィールド長。
2
フィールドのオフセット(ゼロを基準にした相対的なオフセット)。
1
比較演算子のコードを指定します。
1  等しい
2  より大きい
3  より小さい
4  等しくない
5  以上
6  以下
ファイルの既存の ACS のいずれかを使って文字列を比較するには、+8 バイアスを加算します。
ファイルのデフォルトの ACS を使って文字列を比較するには、+32 バイアスを加算します。デフォルトの ACS とは、ファイルで定義されている先頭の ACS のことです。+8 バイアスと +32 バイアスの両方を使用すると、+32 バイアスは無視されます。
 
2 番目のオペランドが定数ではなく、レコード内の別のフィールドの場合は、+64 バイアスを加算します。
大文字と小文字を区別しないで文字列を比較するには、+128 バイアスを加算します。
1
AND/OR 論理演算子を指定します。
0 - 最後の項を示します。
1 - 次の項を AND で結合します。
2 - 次の項を OR で結合します。
2 または n
2 つのフィールドを比較する場合は、2 バイトの、2 番目のフィールドに対するゼロ基準の相対的なオフセットを指定します(2 番目のフィールドは、同じデータ型かつ同じ長さでなければなりません)。
または
フィールドを定数と比較する場合は、定数の実際の値を指定します。定数の長さ(n)は、フィールドの長さと等しくなければなりません。
0、5、9、17
名前によって ACS を指定(バイアス +8)するときは、表 12 に示されている名前の形式のいずれかを使って、ACS 識別子を指定します。
ディスクリプター(固定部分)
2
取得するレコード数。レコードのセットではなく 1 つのレコードだけを取得するには、1 を指定します。
2
各レコードから抽出するフィールド数。
ディスクリプター(抽出される各フィールドについて、このセグメントを繰り返す)
2
抽出するフィールド長。
2
フィールドのオフセット(ゼロを基準にした相対的なオフセット)。

トランザクショナル インターフェイスでは Extended Get および Step オペレーションのフィルターで使用されている AND および OR 演算子は、厳密に左から右へ向かって解釈されます。トランザクショナル インターフェイスは、次の規則に従ってフィルター内の式の評価を続けていきます。

次のいずれかの条件が成立すると、レコードの検索は中止されます。

フィルター条件を満たす次のレコード全体を取得するには、フィルター部分を希望どおりに設定し、次のようにディスクリプター フィールドを設定します。

  1. レコード数に 1 を設定します。
  2. フィールド数に 1 を設定します。
  3. フィールド長に取得するレコード全体の長さを設定します。
  4. フィールドのオフセットに 0 を設定します。

フィルター条件を使わずに次の 12 件のレコードを取得し、各レコードから 4 つのフィールドを抽出するには、論理式の項の数に 0 を設定し、次のようにディスクリプター フィールドを設定します。

  1. レコード数に 12 を設定します。
  2. フィールド数に 4 を設定します。
  3. 抽出する 4 つのフィールドごとにフィールド長およびフィールドのオフセット パラメーターを設定します。

レコードからのフィールドの取得

Extended オペレーションを使ってレコードのフィールド(レコードの一部)を取得するときは、データ バッファーがオペレーションから返される情報を十分に格納できることを確認しておく必要があります。

22 は、トランザクショナル インターフェイスから返されるデータ バッファーの構造体を示しています。

表 22 Extended Get / Step オペレーションの戻りデータ バッファー構造体
要素
長さ(バイト単位)
説明
レコード数
2
返されたレコード数。
繰り返し部分(取得されたレコードごとに 1 つあります)
長さ 0
2
先頭レコードのイメージ(すべてのフィールドを結合したもの)の長さ。
位置 0
4
先頭レコードの物理カレンシー(アドレス)。
レコード 0
n
先頭レコードのイメージ(すべてのフィールドを結合したもの)。
.
.
.
 
 
長さ x
2
末尾レコードのイメージ(すべてのフィールドを結合したもの)の長さ(バイト単位)。
位置 x
4
末尾レコードの物理カレンシー(アドレス)。
レコード x
n
末尾レコードのイメージ(すべてのフィールドを結合したもの)。

返されたすべてのレコード(またはレコードのフィールド)が固定長である場合、戻りデータ バッファー内のデータの位置は簡単に計算できます。しかし、Extended オペレーションから返されたデータ バッファーからレコードの可変長部分を抽出するには、さらに特別な手順を踏む必要があります。

レコードの可変長部分が返されるとき、トランザクショナル インターフェイスは戻りデータ バッファー内に余分なレコード イメージを詰め込みません。したがって、レコードの可変長部分が占有する最大のバイト数を想定して戻りデータ バッファー内の領域を確保しても、実際に返されたデータがその最大値を下回る場合、トランザクショナル インターフェイスでは次に返されたフィールドのフィールド記述は現在のフィールドのデータの直後から始まることになります。

たとえば、固定レコード長が 100 バイトで、可変長部分は最大 300 バイトになると推定されるときに、5 件のレコードの可変長部分だけを取得したいとします。入力バッファーのディスクリプター要素を使って、フィールド長に 300 を設定し、フィールドのオフセットに 100 を設定します。戻りバッファーについては、次の計算式で示すように、レコード数を示す 2 バイトと、レコード当たり 306 バイト(つまり、長さの 2 バイト、アドレスの 4 バイト、およびデータの 300 バイト)を加算する必要があります。

2 + ((2 バイト + 4 バイト + 300 バイト) * 5) = 1532 バイト 

しかし、返された先頭レコードの可変長部分には 50 バイトのデータしかなかったとします。その結果、2 バイトから成る 2 番目に返されるレコードの長さは、データ バッファーのオフセット 58、つまり先頭レコードのフィールド イメージの直後に格納されることになります。こうした状況でもアプリケーションでは、トランザクショナル インターフェイスからデータ バッファーに返された長さ、位置、およびデータを正確に解析する必要があります。

結果

Get Next Extended オペレーションが正常に終了した場合は、トランザクショナル インターフェイスから次の情報が返されます。

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

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

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

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

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

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

トランザクショナル インターフェイスではフィルター条件で使用するフィールドと演算子によって、要求を最適化できる場合があります。拒否レコードに達すると、ステータス コード 64 が返され、ファイルの未検索の部分にはフィルター条件を満たすレコードがそれ以上ないことが示されます。

ポジショニング

Get Next Extended オペレーションを実行すると、完全な論理カレンシーおよび物理カレンシーが確立されます。検索された最後のレコードが現在のレコードになります。このレコードは、フィルター条件を満たして取得されたレコードか、またはフィルター条件を満たさないために拒否されたが、まだ最適化の範囲を超えていないレコードのいずれかです。たとえば、Extended オペレーションがステータス 9 を返した場合は、ファイルの末尾のレコードが現在のレコードになります。ステータス 60(リジェクト カウントに達しました)が返された場合は、拒否された最後のレコードが現在のレコードです。ステータス 64(フィルター制限に達しました)が返された場合には、最適化条件を満たす最後のレコードが現在のレコードになります。これ以降のレコードは最適化の範囲を超えていることを確認するために、トランザクショナル インターフェイスが次のレコードを検索する必要があったとしても、現在のレコードの設定は条件を満たす前のレコードに戻されます。


メモ

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



Get Next(6)

Get Position(22)