FETCH ステートメント

FETCH ステートメントは、カーソルの位置を結果表の次の行に移し、その行の値をターゲット変数に割り当てます。

呼び出し

対話式 SQL 機能には外見上対話式の実行に見えるインターフェースが用意されている場合がありますが、 このステートメントはアプリケーション・プログラムに組み込むことだけが可能です。 これは、動的に作成できない実行可能ステートメントです。 コマンド行プロセッサーを使用して呼び出した場合は、cursor-name に続く構文は、オプションで SQL 構文とは異なります。

詳しくは、 コマンド行 SQL ステートメントおよび XQuery ステートメントの使用 を参照してください。

許可

cursor-variable-name として使用される、または array-index の式で使用されるグローバル変数ごとに、以下のいずれかの特権がステートメントの許可 ID によって保持されている必要があります。
  • モジュールで定義されていないグローバル変数に対する READ 特権
  • モジュールで定義されているグローバル変数のモジュールに対する EXECUTE 特権
  • モジュールで定義されているグローバル変数のモジュールが含まれているスキーマに対する EXECUTEIN 特権
  • モジュールで定義されているグローバル変数のモジュールが含まれているスキーマに対する DATAACCESS 権限
assignment-target として使用されるグローバル変数ごとに、以下のいずれかの特権がステートメントの許可 ID によって保持されている必要があります。
  • モジュールで定義されていないグローバル変数に対する WRITE 特権
  • モジュールで定義されているグローバル変数のモジュールに対する EXECUTE 特権
  • モジュールで定義されているグローバル変数のモジュールが含まれているスキーマに対する EXECUTEIN 特権
  • モジュールで定義されているグローバル変数のモジュールが含まれているスキーマに対する DATAACCESS 権限

カーソルの使用に必要な許可については、 DECLARE CURSOR を参照してください。

構文

Read syntax diagramSkip visual syntax diagramFETCH FROM cursor-namecursor-variable-name INTO,assignment-targetUSING DESCRIPTORdescriptor-name

assignment-target

Read syntax diagramSkip visual syntax diagram global-variable-namehost-variable-nameSQL-parameter-nameSQL-variable-nametransition-variable-namearray-variable-name[array-index]field-reference

説明

カーソル変数名 (cursor-variable-name)
フェッチ操作で使用するカーソルを指定します。 cursor-variable-name は、有効範囲にあるカーソル変数を指定する必要があります。 FETCH ステートメントを実行する場合、cursor-variable-name の基礎となるカーソルはオープン状態でなければなりません。 cursor-variable-name を使用する FETCH ステートメントは、コンパウンド SQL (コンパイル済み) ステートメント内でのみ使用できます。
INTO 割り当て-ターゲット

出力値の割り当てのための 1 つ以上のターゲットを示します。 結果行の最初の値はリスト中の最初のターゲット、その次の値は 2 番目のターゲット、以下同様に割り当てられます。 assignment-target への個々の割り当ては、リストに指定された順序で行われます。 割り当てでエラーが発生すると、値はターゲットに割り当てられず、 値はそれ以上ターゲットに割り当てられません。 それまでに既にターゲットに割り当てられていた値はそのままになります。

すべての assignment-target のデータ・タイプが行タイプではない場合、assignment-targets の数が結果列の値の数より少ないと、SQLCA の SQLWARN3 フィールドに値「W」が割り当てられます。

assignment-target のデータ・タイプが行タイプの場合は、assignment-target を 1 つだけ指定し (SQLSTATE 428HR)、列の数が行タイプ内のフィールドの数に一致し、またフェッチされる行の列のデータ・タイプが行タイプの対応するフィールドに割り当て可能である必要があります (SQLSTATE 42821)。

assignment-target のデータ・タイプが配列エレメントの場合は、assignment-target を正確に 1 つだけ指定する必要があります。

グローバル変数名 (global-variable-name)
割り当てのターゲットとなるグローバル変数を指定します。
ホスト変数名 (host-variable-name)
割り当てのターゲットとなるホスト変数を指定します。 LOB 出力値の場合、ターゲットとして可能なのは正規のホスト変数 (十分な大きさの場合)、LOB ロケーター変数、または LOB ファイル参照変数です。
SQL パラメーター名 (SQL-parameter-name)
割り当てのターゲットとなるパラメーターを識別します。
SQL 変数名 (SQL-variable-name)
割り当てターゲットである SQL 変数を識別します。 SQL 変数は、使用する前に宣言しておかなければなりません。
遷移変数名 (transition-variable-name)
遷移行で更新する列を識別します。 transition-variable-name は、新しい値を識別する相関名によってオプションで修飾されている、トリガーのサブジェクト表にある列を識別していなければなりません。
配列変数名 (array-variable-name)
配列タイプの SQL 変数、SQL パラメーター、またはグローバル変数を指定します。
[array-index]
配列のどのエレメントが割り当てのターゲットとなるかを指定する式。 通常配列の場合、array-index 式は INTEGER に割り当て可能でなければならず (SQLSTATE 428H1)、NULL 値にすることはできません。 その値は、1 と、配列に定義された最大カーディナリティーとの間でなければなりません (SQLSTATE 2202E)。 連想配列の場合、array-index 式は連想配列の指標データ・タイプに割り当て可能でなければならず (SQLSTATE 428H1)、NULL 値にすることはできません。
フィールド参照
割り当てのターゲットとなる行タイプ値内のフィールドを指定します。 field-reference は、修飾子がこのフィールドが定義されている行の値を識別する場合、修飾の field-name として指定する必要があります。
USING DESCRIPTOR 記述子名
ゼロ個以上のホスト変数の有効な記述を含む SQLDA を識別します。
FETCH ステートメントが処理される前に、 ユーザーは次に示す SQLDA 内のフィールドを設定する必要があります。
  • SQLDA に用意する SQLVAR のエレメント数を示す SQLN
  • SQLDA に割り振るストレージのバイト数を示す SQLDABC
  • ステートメントの処理時にその SQLDA の使用される変数の数を示す SQLD
  • 変数の属性を示す SQLVAR のオカレンス

SQLDA には、すべての SQLVAR オカレンスが入るだけの十分なストレージがなければなりません。 したがって、SQLDABC の値は 16 + SQLN*(N) 以上でなければなりません (N は 1 つの SQLVAR オカレンスの長さ)。

LOB または構造化タイプの結果列を入れるには、 各選択リスト項目 (または結果表の列) ごとに 2 つの SQLVAR 項目が必要です。

SQLD に設定する値は、ゼロ以上で SQLN 以下でなければなりません。

SQLDA に記述される n 番目の変数は、 カーソルの結果表の n 番目の列に対応します。 各変数のデータ・タイプは、それに対応する列と互換性がなければなりません。

各変数には、特定の規則に従って値が割り当てられます。 変数の数がその行の値の数よりも少ない場合、 SQLDA の SQLWARN3 フィールドが 'W' に設定されます。 変数の数が結果表の列の数よりも多い場合、警告は出されません。 割り当てエラーが発生すると、値は変数に割り当てられず、 値はそれ以上変数に割り当てられません。 それまでに既に変数に割り当てられていた値はそのままになります。

注

  • カーソル位置: オープン・カーソルの位置として、3 つの位置が考えられます。
    • 行の前
    • 行の上
    • 最終行のあと
    カーソルの現在行となるのは、FETCH ステートメントの結果としての行だけです。 そのカーソルの位置が、現在その結果表の最終行またはそれ以降にある場合、
    • SQLCODE は +100 に設定され、SQLSTATE は '02000' に設定されます。
    • カーソルは最終行の後に位置づけられます。
    • 割り当てのターゲットに値は割り当てられません。

    ある行より前に現在カーソルが位置している場合、カーソルはその行に再配置され、INTO または USING 節で指定されたターゲットに値が割り当てられます。

    最終行以外の行に現在カーソルが位置している場合、カーソルは次の行に再配置され、その行の値は INTO または USING 節で指定されたターゲットに割り当てられます。

    カーソル位置が行にある場合、その行はカーソルの現在行と呼ばれます。 UPDATE ステートメントまたは DELETE ステートメントでカーソルを参照する場合、 そのカーソル位置は行でなければなりません。

    エラーが発生したことによって、カーソルの状態が予測できないものになることがあります。

  • 複数の FETCH を通じてロケーターを維持する必要がない場合、 LOB ロケーターへの取り出しを行う場合には、ロケーター・リソースの限度を考慮して、 その次の FETCH ステートメントを発行する前に FREE LOCATOR ステートメントを発行しておくとよいでしょう。
  • 警告が FETCH に戻されなかったり、 以前取り出された行に対する警告が戻されたりする場合があります。 これらの問題は、 システム一時表やプッシュダウン演算子を使用するような最適化によって生じる場合があります。
  • ステートメント・キャッシングは、EXECUTE IMMEDIATE ステートメントの動作に影響します。
  • Db2® CLI は、追加のフェッチ機能をサポートします。 例えば、カーソルの結果表が読み取り専用の場合に、 SQLFetchScroll() 関数を使用してその結果表の中の任意のスポットにカーソルを位置づけることができます。
  • 更新可能カーソルの場合は、行が取り出される時に行でロックが取得されます。
  • カーソル定義に SQL データ変更ステートメントが含まれている場合や、 SQL データを変更するルーチンの呼び出しが関係している場合は、 フェッチ操作中にエラーが発生し、エラーによってカーソルがクローズされることがあっても、 変更された行がロールバックされることはありません。

例

  • 例 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