FETCH
FETCH ステートメントは、カーソルを結果表の行に位置付けます。FETCH ステートメントは、 ゼロ、1 つ、または複数の行を戻すこともでき、戻された行の値を変数に割り当てます。
呼び出し
このステートメントは、アプリケーション・プログラムに組み込んで使用します。それ以外の使用法はありません。 これは実行可能ステートメントですが、動的に準備することはできません。REXX プロシージャーでは、複数行の取り出しはできません。
権限
カーソルの使用に必要な許可については、DECLARE CURSORを参照してください。
INTO 変数リスト内にグローバル変数が指定されている 場合、ステートメントの権限 ID が保持する特権に、 少なくとも次のいずれか 1 つが含まれていなければなりません。
- グローバル変数に対する WRITE 特権
- データベース管理者権限
構文
.-FROM-. >>-FETCH--+------------------------+--+------+--cursor-name-----> +-NEXT-------------------+ +-PRIOR------------------+ +-FIRST------------------+ +-LAST-------------------+ | (1) | +-BEFORE-----------------+ | (2) | +-AFTER------------------+ +-CURRENT----------------+ '-RELATIVE--+-variable-+-' '-integer--' >--+--------------------+-------------------------------------->< +-single-fetch-------+ '-multiple-row-fetch-' single-fetch .-,--------. V | |--+-INTO----variable-+-------------------------------------+---| | .-LOCAL--. | +-INTO--SQL--DESCRIPTOR--+--------+--SQL-descriptor-name-+ | '-GLOBAL-' | '-INTO DESCRIPTOR--descriptor-name-----------------------' multiple-row-fetch |--FOR--+-variable-+--ROWS--------------------------------------> '-integer--' >--+-INTO--host-structure-array----------------------------------------------------------+--| | .-LOCAL--. | '-+-USING--SQL--DESCRIPTOR--+--------+--SQL-descriptor-name-+--INTO--row-storage-area-' | '-GLOBAL-' | '-USING DESCRIPTOR--descriptor-name-----------------------' row-storage-area |--:--host-identifier-1--+-------------------------------------+--| | .-INDICATOR-. | '-+-----------+--:--host-identifier-2-'
- BEFORE が指定されている場合には、単一取り出し、または複数行取り出し を指定することはできません。
- AFTER が指定されている場合には、単一取り出し、または複数行取り出し を指定することはできません。
説明
- NEXT
- 現行カーソル位置から見て、結果表の次の行にカーソルを位置付けます。 他のカーソルの方向付けが指定されていない場合には、NEXT がデフォルト値になります。
- PRIOR
- 現行カーソル位置から見て、結果表の前の行にカーソルを位置付けます。
- FIRST
- 結果表の先頭の行にカーソルを位置付けます。
- LAST
- 結果表の最終行にカーソルを位置付けます。
- BEFORE
- 結果表の先頭行の前にカーソルを位置付けます。
- AFTER
- 結果表の最終行の後にカーソルを位置付けます。
- CURRENT
- カーソルの位置は変えずに、現行カーソル位置を維持します。カーソ ルが DYNAMIC SCROLL として宣言されている場合、現在行が変更された結果 、結果表のソート順序の中での位置が変化していると、エラーが戻されます。
- RELATIVE
- 変数 または整数 が、整数値 k に割り当てられます。RELATIVE によって決められるカーソルの結果表内の行の位置は、k>0 の場合は現在行の k 行後、k<0 の場合は現在行の k 行前になります。変数 を指定する場合には、位取りがゼロの数値変数を指定しなければならず、
また標識変数を入れることはできません。
表 1. 同義のスクロール指定 指定 代替 RELATIVE +1 NEXT RELATIVE -1 PRIOR RELATIVE 0 CURRENT - FROM
- このキーワードは、文脈を分かりやすくするために使用するものです。 スクロール位置オプションを指定する場合には、このキーワードが必要です。 スクロール・オプションを指定しない場合には、FROM キーワードはオプショナルです。
- cursor-name
- 取り出し操作で使用するカーソルを識別します。
cursor-name では、宣言済みカーソルを指定する必要があります (DECLARE CURSOR ステートメントの 説明を参照してください)。Java™ で使用する場合は、SQLJ イテレーターのインスタンスを指定しなければなりません。FETCH ステートメントの実行時点で、指定したカーソルはオープン状態でなければなりません。
単一行取り出し 文節または複数行取り出し 文節が指定されていない場合、データはユーザーに戻されません。 ただし、カーソルは位置付けられ、行ロックが掛けられます。 ロックの詳細については、分離レベルを参照してくだ さい。
single-fetch
- INTO variable,...
- 1 つ以上のホスト構造体または変数を識別しますが、
それらはホスト構造体および変数の宣言に関する規則に従って宣言されているものでなければなりません。
INTO の操作形式では、ホスト構造体は、その個々の変数に対する参照に置き換えられます。
結果の行の最初の値がリストの最初の変数に割り当てられ、2 番目の値が 2 番目の変数に割り当てられます。
以下同様です。
現在の接続がローカル接続である (DRDA® 接続ではない) 場合のみ、グローバル変数が使用できます。
- INTO SQL DESCRIPTOR SQL-descriptor-name
- FETCH ステートメントで使用される出力変数の有効な記述子を含む SQL 記述子を識別します。
FETCH ステートメントを実行する前に、ALLOCATE DESCRIPTOR ステートメントを使用して記述子を割り振らなければなりません。
- LOCAL
- 記述子の名前の有効範囲はプログラム呼び出しのローカルであることを指定します。
- GLOBAL
- 記述子の名前の有効範囲は SQL セッション全体であることを指定します。
- SQL-descriptor-name
- SQL 記述子の名前を指定します。名前は、指定の有効範囲を持つ既存の記述子を識別するものでなければなりません。
SQL 記述子内の情報の説明については、SET DESCRIPTORを参照してください。
- INTO DESCRIPTOR descriptor-name
- ゼロ個または 1 つ以上の変数の有効な記述が入っている SQLDA を識別します。
ユーザーは、FETCH ステートメントを処理する前に、SQLDA の以下のフィールドをセットしておく必要があります。(REXX の場合は、規則が異なります。 詳しくは、「組み込み SQL プログラミング」のトピック集を参照してください。)
- SQLN (SQLDA に用意する SQLVAR のオカレンスの数を示します。)
- SQLDABC (SQLDA 用に割り振る記憶域のバイト数を示します。)
- SQLD (ステートメントを処理するときに、SQLDA で使用する変数の個数を指示します。)
- SQLVAR の各オカレンス (変数の属性を指示します。)
SQLDA の記憶域は、SQLVAR のオカレンスをすべて収容するのに十分な大きさで割り振らなければなりません。 したがって、SQLDABC の値は、16 + SQLN*(80) よりも大きいか、または等しくなければなりません。ここで、80 は SQLVAR の 1 つのオカレンスの長さです。LOB が指定された場合には、各パラメーター・マーカーご とに 2 つの SQLVAR 項目が必要であり、SQLN はパラメーター・マーカー数 の 2 倍をセットしなければなりません。
SQLD には、ゼロ以上で SQLN 以下の値をセットしなければなりません。 詳しくは、SQLDA (SQL 記述子域)を参照してください。
Java プログラムでは、FETCH ステートメントで USING DESCRIPTOR 文節を使用できません。
multiple-row-fetch
- FOR variable または integer ROWS
- 取り出す行の数を表す整数値に対して変数 または整数 を評価します。
変数 を指定する場合には、位取りがゼロの数値変数を指定しなければならず、
また標識変数を入れることはできません。
変数をグローバル変数にすることはできません。値は 1 から 32767 の
範囲内でなければならず、行の合計サイズ (LOB を除く) は 16 M 未満
でなければなりません。カーソルは、方向付けキーワード (例えば NEXT) の指定する行に置かれ、その行が取り出されます。
それから、次の行が取り出され (表内で順方向に移動)、指定された行数が取り出されるかカーソルの終わりに達するまでこれが繰り返されます。
取り出し操作の後、カーソルは最後に取り出された行に置かれます。
例えば、FETCH PRIOR FROM C1 FOR 3 ROWS を実行すると、前の行、現在行、および次の行が、この順序で戻されます。 カーソルは次の行に置かれます。FETCH RELATIVE -1 FROM C1 FOR 3 ROWS でも、同じ結果が戻されます。 これに対して FETCH FIRST FROM C1 FOR :x ROWS では、先頭の x 行が戻され、 カーソルは番号 x の行に置かれたままとなります。
複数行取り出し が正しく実行されると、 次の 3 つのステートメント情報項目が SQL 診断領域 (または SQLCA) で使用可能になります。
- ROW_COUNT (または SQLCA の SQLERRD(3)) には、取り出された行の数を示す値が設定されます。
- DB2_ROW_LENGTH (または SQLCA の SQLERRD(4)) には、取り出された行の長さが入ります。
- DB2_LAST_ROW (または SQLCA の SQLERRD(5)) には、取り出された行が最後の行である場合、+100 が設定されます。 1
- INTO host-structure-array
- ホスト構造体配列 は、ホスト構造体の宣言に関する
規則に従って定義されているホスト構造体の配列を識別します。
すなわち、配列の最初の構造は最初の行に対応し、配列の 2 番目の構造は 2 行目に対応しています。以下も同じです。 さらに、行の最初の値が構造体内の最初の項目に対応し、行の 2 番目の値が構造体の 2 番目の項目に対応するというように、 これも順番に対応しています。取り出す行数は、ホスト構造体配列の次元以下でなければなりません。
- USING SQL DESCRIPTOR SQL-descriptor-name
- SQL 記述子を識別します。
- LOCAL
- 記述子の名前の有効範囲はプログラム呼び出しのローカルであることを指定します。
- GLOBAL
- 記述子の名前の有効範囲は SQL セッション全体であることを指定します。
- SQL-descriptor-name
- SQL 記述子の名前を指定します。名前は、指定の有効範囲を持つ既存の記述子を識別するものでなければなりません。
記述子ヘッダーの COUNT フィールドは、結果セットの列の数を反映するように設定しなければなりません。 結果セットのそれぞれの列ごとに TYPE および DATETIME_INTERVAL_CODE (適用可能な場合) を設定しなければなりません。
- USING DESCRIPTOR descriptor-name
- SQLDA を識別しますが、行記憶域 の中の行の形式を記述するゼロまたはそれ以上の変数の有効な記述が入っているものでなければなりません。
ユーザーは、FETCH ステートメントを処理する前に、SQLDA の以下のフィールドをセットしておく必要があります。
- SQLN (SQLDA に用意する SQLVAR のオカレンスの数を示します。)
- SQLDABC (SQLDA 用に割り振る記憶域のバイト数を示します。)
- SQLD (ステートメントを処理するときに SQLDA で使用する変数の個数を指示します。)
- SQLVAR の各オカレンス (変数の属性を指示します。)
SQLDA の他のフィールド (SQLNAME など) の値は、FETCH ステートメントを実行した後に定義することはできず、 また、使用するべきではありません。
SQLDA の記憶域は、SQLVAR のオカレンスをすべて収容するのに十分な大きさで割り振らなければなりません。 したがって、SQLDABC の値は、16 + SQLN*(80) よりも大きいか、または等しくなければなりません。ここで、80 は SQLVAR の 1 つのオカレンスの長さです。LOB または特殊タイプが指定された場合には、各パラメーター・マーカーご とに 2 つの SQLVAR 項目が必要であり、SQLN はパラメーター・マーカー数 の 2 倍にセットしなければなりません。
SQLD には、ゼロ以上で SQLN 以下の値をセットしなければなりません。 詳しくは、SQLDA (SQL 記述子域)を参照してください。
FETCH が完了すると、最初の SQLVAR 項目の SQLDATA ポインターは、 最初の行の割り振り済み記憶域内の最初の列に対して戻された値をアドレス指定し、 2 番目の SQLVAR 項目の SQLDATA ポインターは、最初の行の割り振り済み記憶域内の 2 番目の列に対して戻された値を、 というように順にアドレス指定します。NULL 可能な最初の SQLVAR 項目の SQLIND ポインターは最初の標識値をアドレス指定し、 2 番目のNULL 可能な SQLVAR 項目の SQLIND ポインターは 2 番目の標識値を、というように順にアドレス指定します。 SQLDA は、16 バイト境界上に割り振らなければなりません。
- INTO row-storage-area
- 変数を使用して指定されたホスト ID -1 は、行を戻す記憶域の割り振りを指定します。
行は、SQLDA または SQL 記述子によって記述された形式でその記憶域に戻されます。
ホスト ID -1 は、
要求された行をすべて保持できるだけの十分な大きさが必要です。
ホスト ID -2 は、 オプショナルの標識区域を識別します。戻されるデータ・タイプのいずれかがNULL 可能な場合にこれを指定する必要があります。 この標識は、短整数として戻されます。 ホスト ID -2 は、戻される各行についてNULL 可能な各値ごとに標識を入れられるだけの十分な大きさが必要です。
GET DIAGNOSTICS ステートメントは、行記憶域 に戻される各行の長さを示す DB2_ROW_LENGTH を戻すために使用できます。
INTO 文節によって識別されているか、または SQLDA で記述されている n 番目 の変数は、 カーソルの結果表の n 番目 の列に対応します。各変数のデータ・タイプは、 それぞれに対応する列と互換性がなければなりません。
変数への割り当てはそれぞれ、検索割り当てで説明されている検索割り当て規則に従って行われます。2変数の数が行の中の値の数より少ない場合、SQLSTATE は「01503」に設定 (または SQLCA の SQLWARN3 フィールドに「W」が設定) されます。結果の列の数よりも変数の数が多い場合には、警告は出されない点に注意してください。 値が NULL の場合は、標識変数が用意されている必要があります。 割り当てでエラーが起こった場合、その値は変数に割り当てられず、 それ以後の変数への値の割り当ては行われません。変数にすで に割り当てられている値はすべて、割り当てられたままとなります。
外側の SELECT ステートメントの SELECT リストの算術式の結果として エラーが起こった場合 (ゼロによる除算、オーバーフロー、その他など)、 または文字変換エラーが起こった場合には、結果は NULL 値になります。 他の NULL 値の場合と同様に、標識変数を用意しなければなりません。 該当の変数の値は、未定義になります。しかし、この場合、標識変数が -2 に設定されます。ステートメントの処理は、エラーが発生しなかった場合と同様に継続されます。 (ただし、警告が戻されます。) 標識変数を用意していない場合は、エラーが戻されます。 エラーが生じた時点で、既にいくつかの値が変数に割り当てられていることがあり、 それらの値は割り当てられたままになります。
結果列に LOB が含まれている場合、または現行接続がリモート・サーバ ーへの接続の場合、複数行取り出し は許されません。
注
カーソル位置: オープン状態のカーソルの位置として、 次の 3 つの位置が考えられます。
- 行の前
- 行
- 最終行の後
カーソルがある行に位置付けられている場合、その行をカーソルの現在行と呼びます。 UPDATE または DELETE ステートメントで参照するカーソルは、行に位置付けられていなければなりません。 カーソルは、FETCH ステートメントの結果としてのみ、行に位置付けることができます。
エラーの発生によって、カーソルの状態が予期できないものになることがあります。
変数の割り当て: INTO 文節によって識別されているか、または SQLDA で記述されている n 番目の変数は、カーソルの結果表の n 番目の列に対応します。各変数のデータ・タイプは、 それぞれに対応する列と互換性がなければなりません。
変数への割り当てはそれぞれ、割り当ておよび比較で説明されている検索割り当て規則に従って行われます。変数の数が行の中の値の数より少ない場合、SQLCA の SQLWARN3 フィールドに 'W' が設定されます。結果の列の数よりも変数の数が多い場合には、警告は出されない点に注意してください。 値が NULL の場合は、標識変数が用意されている必要があります。 割り当てエラーが発生すると、変数の値は予測不能になります。
ストリング変数を指定した場合に、その変数が結果を収容できるほどの大きさでなければ、警告 (SQLSTATE 01004) が返されます (さらに、SQLCA で SQLWARN1 に「W」が割り当てられます)。標識変数が用意されている場合、結果の実際の長さは、その変数 に関連する標識変数に戻されます。
変数として C の NUL で終了する変数を指定し、その変数が、 結果および NUL 終了文字を入れられるだけの十分な大きさを持っていない場合は、以下のようになります。
- CRTSQLCI コマンドまたは CRTSQLCPPI コマンドに *CNULRQD オプションを
指定した場合 (または SET OPTION ステートメントに CNULRQD(*YES) を指定した場合)、以下のようになります。
- 結果が切り捨てられます。
- 最後の文字は NUL 終了文字になります。
- 警告 (SQLSTATE 01004) が戻されます (そして、SQLCA の SQLWARN1 に「W」が割り当てられます)。
- CRTSQLCI コマンドまたは CRTSQLCPPI コマンドに *NOCNULRQD オプションを
指定した場合 (または SET OPTION ステートメントに CNULRQD(*NO) を指定した場合)、以下のようになります。
- NUL 終了文字は戻されません。
- 警告 (SQLSTATE 01004) が戻されます (そして、SQLCA の SQLWARN1 に「N」が割り当てられます)。
代替構文: 以下のキーワードは、旧リリースとの互換性を維持するためにサポートされている同義語です。 これらのキーワードは標準キーワードではないので、原則として使用しないようにしてください。
- USING DESCRIPTOR は、単一取り出し文節で INTO DESCRIPTOR の同義語として使用することができます。
例
例 1: この C の例では、FETCH ステートメントが SELECT ステートメントの結果を取り出してプログラム変数 dnum、dname、および mnum に入れます。取り出す行がなくなったとき、不検出条件が戻されます。
EXEC SQL DECLARE C1 CURSOR FOR
SELECT DEPTNO, DEPTNAME, MGRNO FROM TDEPT
WHERE ADMRDEPT = 'A00';
EXEC SQL OPEN C1;
while (SQLCODE==0) {
EXEC SQL FETCH C1 INTO :dnum, :dname, :mnum;
}
EXEC SQL CLOSE C1;例 2: この FETCH ステートメントは、SQLDA を使用します。
FETCH CURS USING DESCRIPTOR :sqlda3