DESCRIBE CURSOR

DESCRIBE CURSOR ステートメントは、カーソルに関する情報を取得します。列情報などの情報は、記述子に入れられます。

呼び出し

このステートメントは、アプリケーション・プログラム、SQL 関数、 SQL プロシージャー、またはトリガー内にのみ組み込むことができます。これは実行可能ステートメントですが、動的に準備することはできません。Java™ および REXX では指定できません。

権限

権限は不要です。

構文


>>-DESCRIBE CURSOR--+-cursor-name-+----------------------------->
                    '-variable----'   

            .-SQL-.              .-LOCAL--.                          
>--+-USING--+-----+--DESCRIPTOR--+--------+--SQL-descriptor-name-+-><
   |                             '-GLOBAL-'                      |   
   '-INTO----descriptor-name-------------------------------------'

説明

cursor-name or variable

ソース・プログラムで既にオープンしているカーソルまたは割り振られているカーソルを指定します。

変数を指定する場合、

その変数は、文字ストリング変数またはユニコード・グラフィック・ストリングでなければなりません。この変数は、グローバル変数にすることはできません。
標識変数を伴っていてはなりません。
変数内に含まれるカーソル名は左寄せでなければならず、その長さが変数の長さより短い場合は、右側にブランクを埋め込まなければなりません。
カーソルの名前は、区切り文字付きの名前でない限り、大文字でなければなりません。

USING

SQL 記述子を識別します。

LOCAL

記述子の名前の有効範囲はプログラム呼び出しのローカルであることを指定します。

GLOBAL

記述子の名前の有効範囲は SQL セッション全体であることを指定します。

SQL-descriptor-name

SQL 記述子の名前を指定します。名前は、指定の有効範囲を持つ既存の記述子を識別するものでなければなりません。

記述子域に戻される情報は、指定されたカーソルと関連する結果セット内の列を説明します。DESCRIBE CURSOR の実行後の記述子域の内容は、SELECT の DESCRIBE の実行後の内容と同じです。ただし、以下の内容が追加されます。

GET DESCRIPTOR ステートメントから、プロシージャーでカーソルが WITH HOLD で宣言されているかどうかを示す標識として DB2_CURSOR_HOLD を返すことができます。

SQL 記述子に入る情報の説明については、GET DESCRIPTORを参照してください。

INTO descriptor-name

SQL 記述子域 (SQLDA) を指定します。これについては、SQLDA (SQL 記述子域)で説明しています。DESCRIBE CURSOR ステートメントを実行する前に、SQLDA の以下の変数をセットしておく必要があります。

SQLN: SQLDA で用意される SQLVAR オカレンスの数を指定します。 DESCRIBE CURSOR ステートメントを実行する前に、SQLN にゼロ以上の値をセットしておく必要があります。必要なオカレンスの数を決定する手法については、必要な SQLVAR オカレンスの数の決定を参照してください。

DESCRIBE ステートメントが実行されると、データベース・マネージャーでは、SQLDA の各変数に次のような値を割り当てます。

SQLDAID: 最初の 5 バイトは「SQLRS」に設定される。6 から 8 バイトは予約されている。プロシージャー内でカーソルが WITH HOLD に宣言されると、8 バイト目の高位ビットは 1 に設定される。
SQLDABC: SQLDA の長さ (バイト)。
SQLD: 結果表内の列数に拡張 SQLVAR 項目数を加えたものです。拡張 SQLVAR 項目については、SQLVAR のオカレンスのフィールドの説明を参照してください。
SQLVAR: SQLD の値が 0 の場合、または SQLD の値が SQLN の値より大きい場合は、SQLVAR のオカレンスには値が割り当てられません。
SQLD の値が n (ただし、n は 0 より大きいが、SQLN の値より小さいか、または等しい値) の場合は、値が SQLVAR の最初の n 個のオカレンスに割り当てられ、その結果、SQLVAR の最初のオカレンスには結果表の最初の列の記述が入り、SQLVAR の 2 番目のオカレンスには結果表の 2 番目の列の記述が入ります。以下同様です。SQLVAR オカレンスに割り当てられる値については、SQLVAR のオカレンスのフィールドの説明を参照してください。

注

SQL 記述子の割り振り: DESCRIBE CURSOR ステートメントを実行する前に、ALLOCATE DESCRIPTOR ステートメントを使用して SQL 記述子を割り振らなければなりません。割り振られた記述子項目の数がカーソル結果セットの列の数より小さい場合は、警告 (SQLSTATE 01005) が戻されます。

SQLDA の割り振り: DESCRIBE CURSOR ステートメントを実行する前に、SQLN にゼロ以上の値をセットして、SQLDA に用意する SQLVAR のオカレンスの数を指示するとともに、SQLN の各オカレンスを収容するのに十分な記憶域を割り振っておく必要があります。カーソル結果セットの列の記述を取得するには、SQLVAR のオカレンスの数が列の数以上でなければなりません。

SQLDA の割り振りのために使用する方法については、SQLDA (SQL 記述子域)を参照してください。

例

カーソル C1 に関連する結果セットについての情報を記述子に入れます。

  EXEC SQL ALLOCATE DESCRIPTOR 'DESCR1';
  EXEC SQL DESCRIBE CURSOR C1 USING SQL DESCRIPTOR 'DESCR1';