OPEN ステートメント

OPEN ステートメントは、カーソルをオープンして、 そのカーソルを結果表からの行の取り出しに使用できるようにします。

呼び出し

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

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

許可

グローバル変数が参照される場合、ステートメントの許可 ID に、以下のいずれかの権限が含まれている必要があります。
  • モジュールで定義されていないグローバル変数に対する READ 特権
  • モジュールで定義されているグローバル変数のモジュールに対する EXECUTE 特権

このステートメントは動的に準備できないので、グループ特権は考慮されません。

構文

構文図を読む構文図をスキップする OPEN cursor-namecursor-variable-name(expression) USING,variableexpression1USING DESCRIPTORdescriptor-name
注:
  • 1 変数以外の式は、コンパイル済みのコンパウンド・ステートメントでのみ使用できます。

説明

cursor-name
プログラムのそれ以前の個所にある DECLARE CURSOR ステートメントで定義されているカーソルの名前を指定します。 cursor-name が SQL プロシージャー内の WITH RETURN TO CLIENT と宣言されているカーソルを指定したときに、そのカーソルが既にオープン状態だった場合、既存のオープン・カーソルは結果セット・カーソルになって cursor-name を使用してアクセスすることができなくなり、新しいカーソルがオープンして cursor-name を使用してアクセスできるようになります。これ以外の場合は、この OPEN ステートメントが実行される時点で、cursor-name で指定されたカーソルはクローズ状態でなければなりません。
DECLARE CURSOR ステートメントは、次のいずれかの方法で、 SELECT ステートメントを指定しなければなりません。
  • その DECLARE CURSOR ステートメントに SELECT ステートメントを組み込む。
  • 準備済み SELECT ステートメントを指定する statement-name を組み込む。

カーソルの結果表は、その SELECT ステートメントを評価することによって得られます。 評価の際には、その SELECT ステートメントで指定されている特殊レジスター、グローバル変数、または PREVIOUS VALUE 式の現行値と、SELECT ステートメントまたは OPEN ステートメントの USING 節で指定されたホスト変数の現行値が使用されます。 結果表の行は、OPEN ステートメントの実行中に得られ、それらを入れる一時表が作成されるか、あるいは後続の FETCH ステートメントの実行中に得られます。 いずれの場合でも、カーソルはオープン状態になり、その位置はその結果表の最初の行の前になります。 表が空の場合、カーソルの状態は事実上「最終行の後」になります。

cursor-variable-name

カーソル変数の名前を指定します。カーソル変数の値は、NULL であってはなりません (SQLSTATE 34000)。カーソルの値コンストラクターが直接または間接的に割り当てられたカーソル変数は、その割り当てと同じ有効範囲にある OPEN ステートメントでのみ使用できます (SQLSTATE 51044)。 カーソル変数に割り当てられたカーソルの値コンストラクターで、statement-name を指定した場合、OPEN ステートメントは、その statement-name が明示的または暗黙的に宣言された有効範囲と同じ有効範囲内にある必要があります (SQLSTATE 51044)。

この OPEN ステートメントが実行される時点で、カーソル変数の基礎となるカーソルはクローズ状態でなければなりません。 基礎となるカーソルの結果表は、その SELECT ステートメントまたはカーソル変数に関連付けられた動的ステートメントを評価することによって得られます。 評価の際には、その SELECT ステートメントで指定されている特殊レジスター、グローバル変数、または PREVIOUS VALUE 式の現行値と、SELECT ステートメントまたは OPEN ステートメントの USING 節で指定された変数の現行値が使用されます。 結果表の行は、OPEN ステートメントの実行中に得られ、それらを入れる一時表が作成されるか、あるいは後続の FETCH ステートメントの実行中に得られます。 いずれの場合でも、カーソルはオープン状態になり、その位置はその結果表の最初の行の前になります。 表が空の場合、カーソルの状態は事実上「最終行の後」になります。

cursor-variable-name を使用する OPEN ステートメントは、コンパウンド SQL (コンパイル済み) ステートメント内でのみ使用できます。

( expression, ... )
パラメーター化されたカーソル変数の名前付きパラメーターに関連付けられている引数を指定します。 カーソル変数に割り当てられた cursor-value-constructor は、指定された引数の数と同数のパラメーターを持つパラメーターのリストが含まれている必要があります (SQLSTATE 07006 または 07004)。n 番目の式のデータ・タイプと値は、n 番目のパラメーターに割り当て可能でなければなりません (SQLSTATE 07006 または 22018)。
USING

この後に、カーソルのステートメント内のパラメーター・マーカーまたは変数に代入する値を指定します。パラメーター・マーカーの説明については、『PREPARE』を参照してください。

statement-name を DECLARE CURSOR ステートメント、またはパラメーター・マーカーを含むカーソル変数に関連付けられたカーソルの値コンストラクターで指定した場合、USING の使用が必須です。 準備済みステートメントにパラメーター・マーカーが含まれていない場合、USING は無視されます。

select-statement を DECLARE CURSOR ステートメント、またはカーソル変数に関連付けられた非パラメーター化カーソルの値コンストラクターで指定した場合、USING を変数値のオーバーライドに使用できます。

variable

変数とホスト変数の宣言規則に従って、該当プログラムで宣言されている変数またはホスト構造体を指定します。 変数の数は、準備済みステートメントのパラメーター・マーカーの数と同じでなければなりません。 n 番目の変数は、 準備済みステートメントの n 番目のパラメーター・マーカーに対応します。 場合によっては、ロケーター変数とファイル参照変数も、パラメーター・マーカーの値のソースとして指定できます。

expression
式を使用してパラメーター・マーカーに関連付ける値を指定します。 式を USING 節に指定する OPEN ステートメントは、コンパウンド SQL (コンパイル済み) ステートメント内でのみ使用できます (SQLSTATE 42601)。式の数は、準備済みステートメントのパラメーター・マーカーの数と同じでなければなりません (SQLSTATE 07001)。n 番目の式は、準備済みステートメントの n 番目のパラメーター・マーカーに対応します。n 番目の式のデータ・タイプと値は、n 番目のパラメーター・マーカーに関連付けられたタイプに割り当て可能でなければなりません (SQLSTATE 07006)。

規則

  • カーソルの SELECT ステートメントが評価される場合に、 そのステートメント中の各パラメーター・マーカーは、対応するホスト変数によって置き換えられます。 型付きパラメーター・マーカーの場合、ターゲット変数の属性は CAST 指定によって指定されます。 タイプなしパラメーター・マーカーの場合、 ターゲット変数の属性はパラメーター・マーカーのコンテキストに従って決定されます。
  • V は、パラメーター・マーカー P に対応するホスト変数を表します。 V の値は、列への値の割り振り規則に従って、P のターゲット変数に割り当てられます。 したがって、
    • V はターゲットと互換でなければなりません。
    • V がストリングの場合、その長さ (ただし、 LONG ストリングでないストリングの末尾ブランクは含まない) はターゲットの長さ属性を超えることはできません。
    • V が数値の場合、 V の整数部分の絶対値はターゲットの整数部分の絶対値の最大を超えることはできません。
    • V の属性がターゲットの属性と同一でない場合、 その値はターゲットの属性に合うように変換されます。

    カーソルの SELECT ステートメントが評価されると、 P の代わりに使用される値は P のターゲット変数になります。 例えば、V が CHAR(6) でターゲットが CHAR(8) の場合、 P の代わりに使用される値は V の値にブランクを 2 個付加したものになります。

  • USING 節は、パラメーター・マーカーを含む準備済み SELECT ステートメントのために用意されています。 ただし、これは、カーソルの SELECT ステートメントが DECLARE CURSOR ステートメント、またはカーソル変数に関連付けられた非パラメーター化カーソルの値コンストラクターの一部である場合にも使用できます。 このような場合、OPEN ステートメントは、 あたかも SELECT ステートメントの各ホスト変数がパラメーター・マーカーであるかのように実行されます。 ただし、ターゲット変数の属性は SELECT ステートメントのホスト変数と同じになります。 その結果、USING 節に指定するホスト変数の値によって、 カーソルの SELECT ステートメントの中のホスト変数の値がオーバーライドされることになります。変数値のオーバーライドは、SELECT ステートメントでは他の変数をなにも組み込まないため、パラメーター化されたカーソル変数をオープンする際には使用しないでください。
  • カーソル定義に組み込まれている SQL データを変更する SQL データ変更ステートメントとルーチンは完全に実行され、 結果セットは、カーソルのオープン時に一時表に保管されます。 ステートメントの実行が正常に完了すると、SQLERRD(3) フィールドには、挿入、更新、 および削除操作が可能な行の数の合計が入ります。 全選択内にデータ変更ステートメントを含むカーソルが関係する OPEN ステートメントの実行中にエラーが発生した場合は、 そのデータ変更ステートメントがロールバックされます。

    OPEN ステートメントの明示的なロールバック、 つまり OPEN ステートメント以前のセーブポイントまでのロールバックにより、カーソルはクローズします。 カーソルの定義で、全選択の FROM 節内にデータ変更ステートメントが含まれている場合、 データ変更ステートメントの結果はロールバックされます。

    SELECT ステートメントや SELECT INTO ステートメントにネストされていたデータ変更ステートメントで、 ターゲット表の行に対して行われた変更は、カーソルがオープンされるときに処理されるため、 カーソルに対するフェッチ操作の途中でエラーが発生しても、変更が元に戻ることはありません。

例

例 1: COBOL プログラムで、以下を行う組み込みステートメントを作成します。
  1. カーソル C1 を定義します。このカーソルは、DEPARTMENT 表から管理部門 (ADMRDEPT) 'A00' によって管理される部門の行すべてを検索するために使用します。
  2. 最初に取り出す行の前に、カーソル C1 を置きます。 
       EXEC SQL  DECLARE C1 CURSOR FOR
                  SELECT DEPTNO, DEPTNAME, MGRNO
                    FROM DEPARTMENT
                    WHERE ADMRDEPT = 'A00'
   END-EXEC.


   EXEC SQL  OPEN C1
   END-EXEC.
例 2: C プログラムで動的に定義される選択ステートメントに カーソル DYN_CURSOR を関連付ける OPEN ステートメントをコーディングします。 選択ステートメントの述部には 2 つのパラメーター・マーカーが使用されており、 2 つのホスト参照変数をその OPEN ステートメントに指定して、 アプリケーションとデータベースとの間で整数と VARCHAR(64) の値を渡すために使用します。 (関連するホスト変数の定義、PREPARE ステートメント、 および DECLARE CURSOR ステートメントもこの例に示しています。) 
   EXEC SQL  BEGIN DECLARE SECTION;
     static short    hv_int;
     char            hv_vchar64[65];
     char            stmt1_str[200];
   EXEC SQL  END DECLARE SECTION;

   EXEC SQL  PREPARE STMT1_NAME FROM :stmt1_str;
   EXEC SQL  DECLARE DYN_CURSOR CURSOR FOR STMT1_NAME;

   EXEC SQL  OPEN DYN_CURSOR USING :hv_int, :hv_vchar64;
例 3: 例 2 と同様に OPEN ステートメントをコーディングしますが、 この例では WHERE 節のパラメーター・マーカーの数とデータ・タイプは不明です。 
   EXEC SQL  BEGIN DECLARE SECTION;
     char    stmt1_str[200];
   EXEC SQL  END DECLARE SECTION;
   EXEC SQL  INCLUDE SQLDA;

   EXEC SQL  PREPARE STMT1_NAME FROM :stmt1_str;
   EXEC SQL  DECLARE DYN_CURSOR CURSOR FOR STMT1_NAME;

   EXEC SQL  OPEN DYN_CURSOR USING DESCRIPTOR :sqlda;
例 4: 以下の操作を行うプロシージャーを作成します。
  1. カーソルを出力カーソル変数に割り当てます。
  2. カーソルをオープンします。
CREATE PROCEDURE PROC1 (OUT P1 CURSOR)LANGUAGE SQL
BEGIN
SET P1=CURSOR FOR SELECT DEPTNO, DEPTNAME, MGRNO FROM DEPARTMENT WHERE ADMRDEPT='A00'; --
OPEN P1; --
END;