3.46 FETCH文

機能

カーソルを次の行に位置づけ、その行から値を取り出します。

記述形式

構文の構成

参照項番

単純値指定 → “2.3 値指定と相手指定”
相手指定 → “2.3 値指定と相手指定”

権限

FETCH文を実行できるのは、カーソルの処理対象の表に対するSELECT権の保持者です。

一般規則

カーソルは、開かれた状態であることが必要です。
カーソルは、次の行に位置づけられます。
相手指定の変数に値を代入する途中に誤りが起こると、データ例外(代入エラー)になります。
カーソルが、導出された表の最終行に位置づけられている状態でFETCH文を発行すると例外(データなし)となります。

取出し方向

NEXT、PRIOR、FIRST、LAST、ABSOLUTEおよびRELATIVEは、“取出し方向”と呼びます。
取出し方向を指定した場合、カーソル宣言にSCROLLの指定が必要です。ただし、NEXTを指定した場合は、カーソル宣言のSCROLLの指定を省略することができます。
先頭行より前の行を取り出すと例外(データなし)となり、カーソルは先頭行の直前に位置づけられます。
最終行よりうしろの行を取り出すと例外(データなし)となり、カーソルは最終行の直後に位置づけられます。
取出し方向を省略するとNEXTが指定されたものとみなします。

NEXT

取出し方向にNEXTを指定した場合、カーソルが位置づけられている行の次の行を取り出します。

PRIOR

取出し方向にPRIORを指定した場合、カーソルが位置づけられている行の直前の行を取り出します。

FIRST

取出し方向にFIRSTを指定した場合、先頭の行を取り出します。

LAST

取出し方向にLASTを指定した場合、最後の行を取り出します。

ABSOLUTE

取出し方向にABSOLUTEを指定した場合、先頭行から単純値指定で示す値の分だけうしろの行を取り出します。単純値指定に負の値を指定した場合は、最終行から単純値指定で示す値の絶対値分だけ前の行を取り出します。

RELATIVE

取出し方向にRELATIVEを指定すると、カーソルが位置づけられている行に単純値指定で示す値を加算した行を取り出します。

単純値指定

単純値指定はINTEGER型またはSMALLINT型とします。
単純値指定に標識変数は指定できません。

カーソル名

カーソルの名前を指定します。
カーソル名は、同一コンパイル単位に含まれるカーソル宣言で定義されていることが必要です。

相手指定(取出し相手リスト)

取出し相手リストは、相手指定をカンマ(,)で区切って記述します。
カーソル宣言で指定した問合せ指定の選択リストの個数と、取出し相手リストに指定する相手指定の個数は、同じであることが必要です。
カーソル宣言で指定した問合せ指定の選択リストの結果のデータ型に対して、相手指定に指定可能なデータ型の条件を以下に示します。
選択リストのデータ型が文字列型の場合:
相手指定のデータ型は文字列型であることが必要です。
選択リストのデータ型が各国語文字列型の場合:
相手指定のデータ型は各国語文字列型であることが必要です。
選択リストのデータ型が真数型の場合:
相手指定のデータ型は真数型または概数型であることが必要です。
選択リストのデータ型が概数型の場合:
相手指定のデータ型は真数型または概数型であることが必要です。
選択リストのデータ型が日時型の場合:
相手指定のデータ型は文字列型であることが必要です。
選択リストのデータ型が時間隔型の場合:
相手指定のデータ型は文字列型または真数型であることが必要です。ただし、真数型が指定できるのは選択リストのデータ型が単一日時フィールドで指定された時間隔型の場合のみです。
選択リストのデータ型がBLOB型の場合:
相手指定のデータ型はBLOB型であることが必要です。
カーソル宣言で指定した問合せ指定の選択リストにROW_IDを指定した場合、相手指定にはROW_IDと対応する変数を指定することが必要です。データ型と対応する変数定義については、“表6.1 SQLのデータ型と対応するC変数定義”および“表6.3 SQLのデータ型と対応するCOBOL変数定義”を参照してください。
カーソル指定の列がNULL値の場合の扱いは次のとおりです。
- 相手指定に標識変数が指定されていれば、その標識変数には-1が設定されます。
- 相手指定に標識変数が指定されていなければ、データ例外(NULL値、標識なし)となります。
カーソル指定の列がNULL値でなく、相手指定に標識変数が指定されているならば、その標識変数には次の値が入ります。
- 相手指定のデータ型が固定長または可変長の文字列型の場合で、カーソル指定の列の長さが相手指定の文字列の最大長よりも長ければ、カーソル指定の列の文字数が設定されます。
- 固定長または可変長の各国語文字列型の場合も、同様に設定されます。
- そうでなければ、標識変数には0が設定されます。
カーソル指定の列が、相手指定に設定されるときの規則は次のようになります。
文字列型データの場合:
カーソル指定の列のデータ長が相手指定の長さと同じ場合は、文字データがそのまま設定されます。カーソル指定の列のデータ長が相手指定の長さよりも短い場合は、空白が相手指定の右側に設定されます。カーソル指定の列のデータ長が相手指定の長さよりも長い場合は、相手指定の左側から相手指定の長さだけの文字データが設定されます。
各国語文字列型の場合:
文字列型の場合と同じように設定されます。
真数型の場合:
相手指定のデータ型に変換して設定されます。カーソル指定の列の整数部が相手指定の精度と位取りで表現できる場合は、相手指定の精度と位取りに従って設定されます。上位の桁落ちが発生する場合は例外となり、下位の位が落ちる場合は切り捨てられます。
概数型のデータの場合:
相手指定には、カーソル指定の列の概数値が設定されます。
日時型のデータの場合:
相手指定のデータ型に変換して設定されます。
時間隔型のデータの場合:
相手指定のデータ型に変換して設定されます。
BLOB型のデータの場合:
相手指定には、カーソル指定の列のバイナリ値が設定されます。
ROW_IDの場合:
相手指定には、行識別子が設定されます。

使用例

例1

カーソル宣言およびカーソルを開いてから閉じるまでの一連の流れを、表T1で説明します。

表T1の検索のためにカーソルCSR1を定義します。
```
DECLARE CSR1 CURSOR FOR
    SELECT COL1,COL2,COL3 FROM T1 WHERE COL4 > 10
      ORDER BY COL2 DESC,COL3 ASC
```
カーソル宣言は非実行文です。アプリケーション中でこのカーソルを使用するOPEN文、FETCH文およびCLOSE文よりも前に記述します。実行の順序とは関係ありません。
カーソルを開いた状態にします。
```
OPEN CSR1
```
カーソルは導出された表の先頭行よりも前の(1)に位置づけられます。
カーソルを位置づけます。相手指定のTGT1、TGT2およびTGT3には位置づけられた行の各列の値が取り出されます。
```
FETCH CSR1 INTO :TGT1,:TGT2,:TGT3
```
カーソルを開いてから最初のFETCH文の実行で、カーソルは(2)に位置づけられます。FETCH文を繰り返して実行することにより、カーソルは(3)から(7)に順に位置づけられ、探索条件を満たす行が次々と取り出されます。また、カーソルが最終行を位置づけている状態でFETCH文を実行すると、カーソルは(8)に位置づけられます。このとき、状態変数(SQLSTATE)にデータなしの例外コードが設定されます。SQLSTATEの値については、“付録A SQLSTATE値”を参照してください。
カーソルを閉じた状態にします。
```
CLOSE CSR1
```
カーソルは閉じられ、再び開いた状態にするまで使用できません。なお、カーソルはどの行に位置づけられた状態でも閉じることができます。

例2

カーソルによって位置づけられた行を削除したあと、次のFETCH文で位置づけられる行について説明します。なお、(2)のFETCH文を実行する前は、カーソルは先頭行を位置づけている状態とします。

DECLARE CSR1 SCROLL CURSOR FOR
      SELECT COL1,COL2,COL3 FROM T1 FOR UPDATE
    ：
OPEN CSR1
    ：
FETCH NEXT FROM CSR1 INTO :H1,:H2,:H3                      (1)
DELETE FROM T1 WHERE CURRENT OF CSR1                       (2)
FETCH NEXT FROM CSR1 INTO :H1,:H2,:H3                      (3)
FETCH ABSOLUTE 5 FROM CSR1 INTO :H1,:H2,:H3                (4)

備考． DELETE文:位置づけで削除した行が詰められたあとのカーソル表で、次に位置づける行が決められます。