カーソルを応答セットの次の行(デフォルト)または任意指定の行に置き、その行の値をホスト変数に割り当てます。
ANSI準拠
ANSI/ISO SQL:2011準拠。
必要な権限
なし。
呼び出し
実行可能形式。
埋め込みSQLのみ。
構文
FETCH [ NEXT | PRIOR | FIRST | LAST | ABSOLUTE n | RELATIVE n ] cursor_name [ INTO [,...] | USING DESCRIPTOR [:] descriptor_area ]
構文要素
- into_spec
[:] host_variable_name [ [INDICATOR] :host_indicator_name ]
- NEXT
- 現在のカーソル位置から見て次の行を応答セットから取り出す。
- PRIOR
- 現在のカーソル位置から見て前の行を応答セットから取り出す。
- FIRST
- 応答セットの最初の行を取り出す。
- LAST
- 応答セットの最後の行を取り出す。
- ABSOLUTE n
- 以下を基準として、応答セットのn番目の行を取り出す。
- nが正の数であれば、セットの最初の行から数える。
- nが負の数であれば、セットの最後の行から数える。
- RELATIVE n
- 以下のようにして、応答セットのn番目の行を取り出す。
- nが正の数であれば、nの値だけ前方に移動する。
- nが負の数であれば、nの値だけ後方に移動する。
- cursor_name
- 1つ以上の行が取り出されるオープンしている選択カーソルの名前。
- host_variable_name
- 現在行の列値が割り当てられる変数。
- host_indicator_variable
- 標識変数。
- descriptor_area
- SQL記述領域(SQLDA)
使用上の注意
- スクロール可能カーソル
スクロール可能カーソルを開くと、カーソルは応答セットの最初の行の前に置かれます。いずれかのFETCH指向キーワードを使って取り出すことができます。
アクセスのパフォーマンスを向上するために、マルチセッション接続でスクロール可能カーソルを開くことができます。アプリケーションが順序どおりに行にアクセスしない場合、応答バッファ サイズを行の取り出しサイズと等しく設定すると、パフォーマンスが向上することがあります。最適なパフォーマンスを得るために、プログラマはさまざまな応答バッファのサイズを試行することができます。
- SQLDAを定義する必要があります。
- FETCHを動的SQL文として実行することはできません。
- スクロール可能カーソルFETCHでは、複文リクエストを使用できません。
- PP2 COMMITTEDモードではスクロール可能カーソルFETCHを使用できません。
- cursor_nameで特定されるカーソルは、事前に宣言しておく必要があります。
- INTO句は、静的または動的SQL文で宣言したカーソルと一緒に使用します。
USING DESCRIPTOR句は、動的SQL文で宣言した選択カーソルと一緒に使用することを意図したものです。
- リクエストによって返される列の数は、ホスト変数指定の数、あるいはSQLDAのSQLVAR配列の要素数と一致していなければなりません。つまり、結果セットに返される列の数は、SQLDフィールドの値と等しくなければなりません。
- ホスト変数指定によって、あるいはSQLDAのSQLVAR配列で指定した主なホスト変数と、返されるデータの対応する列は、同じデータ型のグループに属していなければなりません。
ただし、唯一の有効な例外として、主なホスト変数が近似数値データ型の場合、スプール テーブルの列は、近似数値データ型か絶対数値データ型のどちらかにすることができます。
- USING DESCRIPTOR句を指定した場合は、SQLDAのSQLDATAおよびSQLINDポインタ フィールドが、適切なホスト変数をポイントするように設定されていることを検証しなければなりません。
COBOL言語にはポインタ値を設定するためのサポートが用意されていないので、データベースではこのタスクを行なうために呼び出せるサービス ルーチンを提供しています。
IBMのVS COBOL IIには、ポインタ値を設定するために変更されたSET文が用意されています。COBOLでコーディングしているプログラマの方は、適宜この機能を使用することを考慮してください。
- cursor_nameで識別されるカーソルが開いていなければなりません。
- cursor_nameで識別されるカーソルは次行に置かれ、次のルールに従ってホスト変数に値が割り当てられます。
カーソルの状態 結果 配置されたばかり FETCHは以下を戻します。 - 要求されたデータ(正常にデータを戻す文の場合)。
- SQLCODE +100およびSQLSTATE '02xxx'(データがない場合)。
- エラー(ロールバックを引き起こさないSQL < O and SQLSTATE > '02xxx'の場合)。
- 最終行またはそれ以降に置かれている
または
- データを返さない
- カーソルは最終行より後に置かれます。
- システムは、SQLCODEに+100を割り当てます。
- システムは、SQLSTATEに'02xxx'を割り当てます。
- ホスト変数は未変更のままになります。
行より前に置かれている - カーソルはその行上に置かれます。
- システムは、INTO句または出力SQLDAで指定したホスト変数に、行にある値を割り当てます。
最終行以外の行上に置かれている - カーソルは、その行の直後の行上に置かれます。
- システムは、INTO句または出力SQLDAで指定したホスト変数に、新しい現在行にある値を割り当てます。
- システムは、INTO句またはSQLDAのSQLVAR配列で指定したホスト変数に、ホスト変数を指定した順に値を割り当てます。システムは、最後にSQLSTATEとSQLCODEに値を割り当てます。
- ホスト変数に値を割り当てるときにエラーが発生した場合、システムはホスト変数への値の割り当てを停止し、以下の値を結果コード変数に割り当てます。
SQLCODE SQLSTATE -303 ‘22509’ -304 ‘22003’ -413 ‘22003’ - 以下の表では、返されるデータのフィールドがNULLの場合、対応するホスト変数を指定したかどうかに応じて、システムが何を割り当てるかを示しています。
対応するホスト変数 システムの実行内容 指定する場合 ホスト標識変数に-1が割り当てられます。 指定しない場合 - SQLCODEに-305が割り当てられます。
- SQLSTATEに‘22002’が割り当てられます。
どちらの場合も、ホスト変数は未変更のままになります。- 以下の表では、一時テーブルの行の列値がNOT NULLで、対応する標識ホスト変数を指定していた場合に、システムが設定するホスト標識変数を示しています。
条件 システムが設定するホスト標識変数の内容 列および主なホスト変数にCHARACTERと入力した場合に、列値がその主ホスト変数より長い。 列値の長さ その他 0。 - システムは、ホスト変数のルールに従って、対応する主なホスト変数に列値を設定します。
関連情報
- descriptor_areaについては、<Teradata® Preprocessor2 for Embedded SQLプログラマ ガイド、B035-2446>を参照してください。
- NEXT以外のFETCH指向を使用し、スクロール可能カーソルをあらかじめ宣言しておく必要があります。DECLARE CURSOR (選択形式)を参照してください。
- スクロール可能カーソルについては、SET BUFFERSIZEを参照してください。