FETCH 文 [ESQL] [SP]

FETCH [ cursor-position ] cursor-name
INTO variable-list [ FOR UPDATE ]

FETCH [ cursor-position ] cursor-name
[ INTO { hostvar-list  } | USING [ SQL ] DESCRIPTOR sqlda-name ]
[ PURGE ]
[ BLOCK n ]
[ FOR UPDATE ]
[ ARRAY fetch-count ]

cursor-position :
    NEXT | PRIOR | FIRST | LAST
| { ABSOLUTE | RELATIVE } row-count

row-count : number | hostvar

cursor-name : identifier | hostvar

hostvar-list : インジケータ変数を含めることができる

variable-list :  ストアドプロシージャ変数

sqlda-name :  identifier

fetch-count :  integer | hostvar

INTO 句 INTO 句はオプションです。この句が指定されていない場合、FETCH 文はカーソルのみを配置します。hostvar-list は Embedded SQL でのみ使用されます。
カーソル位置 オプションの位置パラメータを指定して、カーソルを移動してからローをフェッチできます。指定しない場合、NEXT が使用されます。FETCH 文に配置パラメータがあり、その場所が許可されたカーソルの範囲の外側である場合、SQLE_NOTFOUND の警告が表示され、SQLCOUNT フィールドには有効な位置からのオフセットが設定されます。
OPEN 文は、まず、先頭のローの前にカーソルを配置します。
NEXT 句 デフォルトの位置付けは NEXT です。これはローをフェッチする前に、カーソルを次のローに進めます。
PRIOR 句 ローをフェッチする前に、カーソルを 1 つ前のローに戻します。
RELATIVE 句 RELATIVE 配置を使用すると、フェッチする前にいずれかの方向へ指定した数のローだけカーソルを移動できます。正の数は前進を示し、負の数は後退を示します。そのため、NEXT は RELATIVE 1 と等しく、PRIOR は RELATIVE -1 と等しくなります。RELATIVE 0 は、このカーソル上の最後の FETCH 文と同じローを取り出します。
ABSOLUTE 句 ABSOLUTE 配置パラメータを使用すると、特定のローに移動できます。0 は先頭のローの前の位置を示します。
1 は先頭のローを示し、残りのローがそれに続きます。負の数を使ってカーソルの最後からの絶対位置を指定します。-1 はカーソルの最後のローを示します。
FIRST 句 ABSOLUTE 1 の省略形。
LAST 句 ABSOLUTE -1 の省略形。

注意

DYNAMIC SCROLL カーソルに挿入や更新をいくつか行うと、カーソルの位置の問題が生じます。SELECT 文に ORDER BY 句を指定しないかぎり、データベースサーバはカーソル内の予測可能な位置にはローを挿入しません。場合によっては、カーソルを閉じてもう一度開かないと、挿入したローが表示されないことがあります。

この動作は、カーソルを開くためにテンポラリテーブルを作成する必要がある場合に起こります。

UPDATE 文は、カーソル内でローを移動させることがあります。これは、既存のインデックスを使用する ORDER BY 句がカーソルに指定されている場合に発生します (テンポラリテーブルは作成されません)。
BLOCK 句 クライアントアプリケーションは一度に複数のローをフェッチできます。これはブロックフェッチ、プリフェッチ、またはマルチローフェッチと呼ばれます。最初のフェッチによって、いくつかのローがデータベースサーバから送り返されます。クライアントはこれらのローをバッファに格納します。後に続くフェッチは、データベースサーバへ新しい要求を行わないで、これらのバッファからローを取り出します。
BLOCK 句は Embedded SQL でのみ使用されます。この句は、クライアントとサーバに、アプリケーションがフェッチできるローの個数に関する情報を与えます。0 という特別値は、要求をデータベースサーバに送信し、シングルローを返すことを示します (ローブロックはありません)。BLOCK 句を指定すると、BLOCK 値を次にプリフェッチするときに含められるローの数が削減されます。プリフェッチされるローの数を増やすには、PrefetchRows 接続パラメータを使用します。

BLOCK 句を指定しない場合は、OPEN に指定した値が使用されます。

FETCH RELATIVE 0 は常にローを再フェッチします。

カーソルのプリフェッチが無効な場合、BLOCK 句は無視され、ローは一度に 1 つずつフェッチされます。ARRAY も指定している場合、ARRAY で指定されたロー数がフェッチされます。
PURGE 句 PURGE 句は Embedded SQL でのみ使用されます。この句によって、クライアントはすべてのローのバッファをフラッシュし、次にフェッチ要求をデータベースサーバに送信します。このフェッチ要求はローのブロックを返します。
FOR UPDATE 句 FOR UPDATE 句は、フェッチされたローが続いて UPDATE WHERE CURRENT OF CURSOR 文によって更新されることを示します。この句は、データベースサーバがローに対して意図的なロックを設定するようにします。ロックは、現在のトランザクションの終わりまで保持されます。
ARRAY 句 ARRAY 句は Embedded SQL でのみ使用されます。この句を使うと、いわゆるワイドフェッチができるようになります。これは複数のローを同時に取り出し、パフォーマンスを改善します。
Embedded SQL でワイドフェッチを使用するには、コードに次のような FETCH 文を含めます。
EXEC SQL FETCH ... ARRAY nnn
ARRAY nnn は FETCH 文の最後の項目です。フェッチ回数を示す nnn にはホスト変数も使用できます。SQLDA には nnn * (ローあたりのカラム数) 変数を入れてください。最初のローは SQLDA の変数 0 から (ロー当たりのカラム数) -1 に入り、以後のローも同様です。

FETCH 文は指定したカーソルからローを 1 つ取り出します。事前にカーソルを開いておきます。

Embedded SQL での使用 Embedded SQL の FETCH 文は配列をサポートしていません。
DECLARE CURSOR 文は、C ソースコード内の FETCH 文の前に置きます。また、OPEN 文を実行してから FETCH 文を実行します。ホスト変数をカーソル名の代わりに使用している場合、DECLARE 文は実際にコードを生成するため、FETCH 文の前に実行します。

サーバは SQLCOUNT にフェッチされたレコードの数を返し、エラーがない場合は 0 より大きい SQLCOUNT を常に返します。

フェッチ時に SQLSTATE_NOTFOUND 警告が返される場合、SQLCA (SQLCOUNT) の sqlerrd[2] フィールドには、フェッチの試みが許可されるカーソル位置を超えたときのローの数が含まれます。ローが見つからなくても位置が有効な場合は、値は 0 です。たとえば、カーソル位置が最後のローのときに FETCH RELATIVE 1 を実行した場合です。カーソルの最後を超えてフェッチしようとした場合、値は正の数です。カーソルの先頭を超えてフェッチしようとした場合、値は負の数です。カーソルの最後を超えてフェッチしようとした場合、カーソルの位置は最後のローになります。カーソルの先頭より前をフェッチしようとした場合、カーソルの位置は先頭のローになります。

FETCH 文の実行が成功した後、SQLCA (SQLIOCOUNT) の sqlerrd[1] フィールドはフェッチを実行するのに必要な入出力操作の数だけ増加します。このフィールドは、実際にはデータベース文が発行されるたびに増加します。
シングルローフェッチ SELECT 文の結果からの 1 つのローは、変数リストの変数の中に置かれます。SELECT リスト対ホスト変数リストは、1 対 1 に対応します。
マルチローフェッチ SELECT 文の結果からの 1 つまたは複数のローは、variable-list の変数の中、または指定した sqlda-name が記述するプログラムデータ領域の中のいずれかに置かれます。SELECT リスト対 hostvar-list または対 sqlda-name 記述子配列は、どちらも 1 対 1 で対応します。

カーソルが開いている必要があり、テーブルに対する SELECT 権限を持っているか、カーソルの宣言で参照されているテーブルの所有者であるか、SELECT ANY TABLE システム権限を持っている必要があります。

プリフェッチが有効な場合、FETCH 文によって、複数のローがサーバからクライアントに取得されるようになる場合があります。

SQL/2008 若干の例外がありますが、FETCH 文の構文 1 は SQL/2008 標準のコア機能です。NEXT 以外のスクロールオプションは、オプションの SQL 言語機能 F431、"Read-only scrollable cursors" を構成します。SQL Anywhere では、SQL/2008 標準に記載されているように、FETCH 文のオプションの FROM 句はサポートされていません。
構文 2 はベンダー拡張です。

FOR UPDATE、PURGE、ARRAY、BLOCK、USING [SQL] DESCRIPTOR 句はベンダー拡張です。

次は、Embedded SQL の例です。

EXEC SQL DECLARE cur_employee CURSOR FOR
SELECT EmployeeID, Surname FROM Employees;
EXEC SQL OPEN cur_employee;
EXEC SQL FETCH cur_employee
INTO :emp_number, :emp_name:indicator;

次は、プロシージャの例です。

BEGIN
   DECLARE cur_employee CURSOR FOR
      SELECT Surname
      FROM Employees;
   DECLARE name CHAR(40);
   OPEN cur_employee;
   lp: LOOP
      FETCH NEXT cur_employee into name;
      IF SQLCODE <> 0 THEN LEAVE lp END IF;
       ...
   END LOOP;
   CLOSE cur_employee;
END

FETCH 文 [ESQL] [SP]

構文 1 [SP]

構文 2 [ESQL]

パラメータ

注意

備考

権限

関連する動作

参照

標準と互換性

例