9.2 構文と使用法
9.2.7 SQL カーソル
複数の行を返すクエリを実行するための埋め込み SQL を使用したい場合は、SQL カーソルを使用 する必要があります。SQL カーソルを使用するには、まず DECLARE で名前を設定します。この名 前は、カーソルの OPEN、FETCH (データの取り出し)、CLOSE の際に使用します。
カーソル名は、クラスまたはルーチンの中で一意である必要があります。また、DECLARE 文は、そ のカーソルを使用する文より 前 のルーチンにある必要があります。
以下の例では、カーソルを使用してクエリを実行し、主デバイスへ結果を表示します。
構文と使用法
&sql(DECLARE C1 CURSOR FOR SELECT %ID,Name
INTO :id, :name FROM Sample.Person ORDER BY Name )
&sql(OPEN C1) &sql(FETCH C1)
While (SQLCODE = 0) {
Write id, ": ", name,!
&sql(FETCH C1) }
&sql(CLOSE C1)
この例は、以下を実行します。
1. これは、カーソル C1 を宣言し、Nameの順に並べられた一連のPerson行を返します。
2. カーソルをオープンします。
3. データの最後に達するまで、カーソルの FETCH を呼び出します。FETCH 呼び出しの後、さら にフェッチするデータがある場合は SQLCODE 変数は 0 に設定されます。FETCH への各呼 び出しの後、返り値は DECLARE 文の INTO 節により指定されたホスト変数にコピーされます。
4. カーソルをクローズします。
9.2.7.1 DECLARE カーソル文
DECLARE 文は、名前と、カーソルを定義する SQL SELECT 文の両方を指定します。例えば、以 下の文は MyCursor と呼ばれるカーソルを宣言します。
&sql(DECLARE MyCursor CURSOR FOR SELECT Name, DOB
FROM Sample.Person
WHERE Home_State = :state ORDER BY Name
)
DECLARE 文は、オプションの INTO 節を含む場合もあります。INTO 節は、カーソルが走査された ときにデータを受け取るローカル・ホスト変数の名前を指定します。例えば、上記の例に INTO 節を 追加すると、以下のようになります。
&sql(DECLARE MyCursor CURSOR FOR SELECT Name, DOB
INTO :name, :dob FROM Sample.Person
WHERE Home_State = :state ORDER BY Name
)
INTO 節のホスト変数の数は、カーソルの SELECT リストの中の列数と正確に一致している必要が あります。一致していない場合、文がコンパイルされたときに “カーディナリティ・ミスマッチ・エラー”
が生成されます。
DECLARE 文に INTO 節が含まれない場合、INTO 節は FETCH 文の中に表す必要があります。
9.2.7.2 OPEN カーソル文
OPEN 文は、カーソルより後の部分を実行するために、カーソルを作成します。
&sql(OPEN MyCursor)
OPEN 呼び出しに成功すると、SQLCODE 変数が 0 に設定されます。
最初に OPEN 呼び出しを実行せずに、カーソルからデータを FETCH することはできません。
カーソルに使用された実際のクエリによっては、OPEN 文はほとんど何も実行しない場合や、クエリ のための初期化作業を実行する場合もあります。
9.2.7.3 FETCH カーソル文
FETCH 文は、(カーソル・クエリで定義されているように) カーソルの次の行のデータをフェッチしま す。
&sql(FETCH MyCursor)
FETCH 呼び出しの前に、カーソルの DECLARE と OPEN を実行する必要があります。
FETCH 文は、INTO 節を含む場合があります。INTO 節は、カーソルが走査されたときにデータを 受け取るローカル・ホスト変数の名前を指定します。例えば、上記の例に INTO 節を追加すると、以 下のようになります。
&sql(FETCH MyCursor INTO :a, :b)
DECLARE 文と FETCH 文の両方に INTO 節が含まれる場合、FETCH 文により指定されたホスト 変数を使用します。
INTO 節のホスト変数の数は、カーソルの SELECT リストの中の列数と正確に一致している必要が あります。一致していない場合、文がコンパイルされたときに “カーディナリティ・ミスマッチ・エラー”
が生成されます。
FETCH の呼び出しに成功すると、SQLCODE 変数は 0 に設定されます。それ以上フェッチする データがない場合は、SQLCODE は 100 に設定されます (これ以上データがないことを意味しま す)。
クエリによっては、最初の FETCH 呼び出しが別のタスク (一時的なデータ構造内の値の並べ替え など) を実行する場合もあります。
9.2.7.4 CLOSE カーソル文
CLOSE 文は、カーソルの実行を終了します。
&sql(CLOSE MyCursor)
構文と使用法
CLOSE 文は、クエリの実行に使用したテンポラリ･ストレージをクリーンアップします。CLOSE 呼び 出しに失敗したプログラムでは、リソース・リークが起こる可能性があります (テンポラリ･データベー スの CACHETEMP の不必要な増加など)。
CLOSE の呼び出しに成功すると、SQLCODE 変数が 0 に設定されます。