DESCRIBE INPUT

DESCRIBE INPUT ステートメントは、準備済みステートメントの IN および INOUT パラメーター・マーカーに関する情報を取得します。

準備済みステートメントの説明については、PREPAREを参照してください。

呼び出し

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

権限

権限は不要です。準備済みステートメントを作成するために必要な権限については、PREPAREを参照してください。

構文

構文図を読む構文図をスキップする
>>-DESCRIBE INPUT--statement-name------------------------------->

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

説明

statement-name
準備済みステートメントを識別します。DESCRIBE INPUT ステートメントが実行される時点で、この名前は、現行サーバー側で準備済みステートメントを識別していなければなりません。
USING
SQL 記述子を識別します。
LOCAL
記述子の名前の有効範囲はプログラム呼び出しのローカルであることを指定します。
GLOBAL
記述子の名前の有効範囲は SQL セッション全体であることを指定します。
SQL-descriptor-name
SQL 記述子の名前を指定します。名前は、指定の有効範囲を持つ既存の記述子を識別するものでなければなりません。

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

INTO descriptor-name
SQL 記述子域 (SQLDA) を指定します。これについては、SQLDA (SQL 記述子域)で説明しています。DESCRIBE INPUT ステートメントを実行する前に、SQLDA の以下の変数をセットしておく必要があります。
SQLN
SQLDA で用意される SQLVAR オカレンスの数を指定します。 DESCRIBE INPUT ステートメントを実行する前に、SQLN をゼロ以上の値にセットしておく必要があります。 必要なオカレンスの数を決定する手法については、必要な SQLVAR オカレンスの数の決定を参照してください。
DESCRIBE INPUT ステートメントが実行されると、データベース・マネージャーでは、SQLDA の各変数に次のような値を割り当てます。
SQLDAID
最初の 6 バイトは 'SQLDA ' (つまり、5 文字の後にスペース文字) に設定 されます。

7 番目のバイトは、記述されたパラメーター・マーカーに基づいて次のように設定されます。

  • SQLDA に入力パラメーター・マーカーごとに 2 つの SQLVAR 項目が含まれる場合、7 番目のバイトは '2' に設定されます。この技法は、LOB 入力パラメーターに対応するために使用されています。
  • それ以外の場合、7 番目のバイトはスペース文字に設定されます。

SQLDA 内にすべての入力パラメーター・マーカーの記述を含める余地がない場合、7 番目のバイトはスペース文字に設定されます。

8 番目のバイトはスペース文字に設定されます。

SQLDABC
SQLDA の長さ (バイト)。
SQLD
準備済みステートメント内の入力パラメーター・マーカーの数。
SQLVAR
SQLD の値が 0 の場合、または SQLD の値が SQLN の値より大きい場合は、SQLVAR のオカレンスには値が割り当てられません。

SQLD の値が n (ただし、n は 0 より大きいが、SQLN の値より小さいか、または等しい値) の場合は、値が SQLVAR の最初の n 個のオカレンスに割り当てられ、その結果、SQLVAR の最初のオカレンスには最初の入力パラメーター・マーカーの記述が入り、SQLVAR の 2 番目のオカレンスには 2 番目の入力パラメーター・マーカーの記述が入ります。以下同様です。SQLVAR オカレンスに割り当てられる値については、SQLVAR のオカレンスのフィールドの説明を参照してください。

注

SQL 記述子の割り振り: DESCRIBE INPUT ステートメントを実行する前に、ALLOCATE DESCRIPTOR ステートメントを使用して SQL 記述子を割り振らなければなりません。 割り振る記述子項目の数は、入力パラメーター・マーカーの数以上でなければなりません。そうしないとエラーが戻されます。

SQLDA の割り振り: DESCRIBE INPUT ステートメントを実行する前に、SQLVAR の出現回数を想定して十分な量のストレージを割り振っておく必要があります。SQLN は、割り当てられた SQLVAR オカレンスの数に設定されなければなりません。 準備済みステートメント内の入力パラメーター・マーカーの記述を取得するためには、SQLVAR のオカレンスの数が入力パラメーター・マーカーの数以上でなければなりません。 さらに、入力パラメーター・マーカーに LOB または特殊タイプが含まれる場合は、SQLVAR のオカレンス数を入力パラメーター・マーカーの数の 2 倍にする必要があります。詳しくは、必要な SQLVAR オカレンスの数の決定を参照してください。

提供されるオカレンスが不足していて、オカレンスのすべてのセットを戻せるとは限らない場合、SQLN は、すべての情報を戻すのに必要なオカレンスの合計数に設定されます。 それ以外の場合、SQLN は、入力パラメーター・マーカーの数に設定されます。

SQLDA を割り振るための可能な方法としては、 以下の 3 通りがあります。

最初の技法
アプリケーションで処理する必要があるどの入力パラメーター・マーカーの数にも対応できるように、SQLVAR 項目のオカレンス数を十分にとって SQLDA を割り振ります。極端なことをいえば、SQLVAR の数を、準備済みステートメントで許容されているパラメーター・マーカーの最大数の 2 倍にすることも可能です。いったん割り振りが終了すれば、アプリケーションでは、この SQLDA を繰り返し使用することができます。

この方法は、大量の記憶域を使用します。また、ある特定の準備済みステートメントで、その記憶域のごく一部しか使用しないとしても、記憶域の割り振りが解除されることはありません。

2 番目の技法
準備済みステートメントを処理するたびに、以下の 3 つのステップを繰り返し実行します。
  1. SQLVAR 項目のオカレンスがない SQLDA、つまり SQLN がゼロの SQLDA を使用して、DESCRIBE INPUT ステートメントを実行します。SQLD で返される値は、準備済みステートメントの入力パラメーター・マーカーの数です。その値は、SQLVAR 項目の必要出現回数か、その回数の半分になります。SQLVAR 項目がないので、警告が出されます。1
  2. その警告を伴う SQLSTATE が 01005 と等しい場合は、SQLDA に 2 * SQLD の出現回数を割り振り、その新しい SQLDA の SQLN を 2 * SQLD に設定します。そうでない場合、SQLDA を SQLD オカレンスで割り振り、新規の SQLDA の SQLN を SQLD の値に設定します。
  3. 次に、この新しい SQLDA を使用して、再び DESCRIBE INPUT ステートメントを実行します。

この方法をとると、方法 1 より記憶域管理が向上しますが、DESCRIBE INPUT ステートメントの数が 2 倍になります。

3 番目の技法
準備済みステートメント内のパラメーター・マーカーの大半 (ほとんど全部) を扱うのに十分な範囲で、なるべく小さな SQLDA を割り振ります。SQLDA が小さ過ぎることが原因で、DESCRIBE INPUT ステートメントの実行に失敗した場合は、より大きな SQLDA を割り振って、再び DESCRIBE INPUT ステートメントを実行します。新しい SQLDA では、最初の DESCRIBE INPUT の実行で SQLD に戻された値 (または SQLD の 2 倍の値) を使用して、SQLVAR 項目のオカレンス数を指定してください。

この方法は、方法 1 と方法 2 を組み合わせたものです。方法 3 の効果は、最初の SQLDA のサイズを適切に選定できるかどうかによって左右されます。

例

例 1: C プログラムで DESCRIBE INPUT ステートメントを実行します。準備済みステートメントの入力パラメーター・マーカーの数を想定し、その数の入力パラメーター・マーカーを記述するための十分な SQLDA を割り振ります。多くても 5 つのパラメーター・マーカーを記述すればよく、入力データに LOB が含まれないものとします。

  EXEC SQL  BEGIN DECLARE SECTION;
    char stmt1_str [200];
  EXEC SQL  END DECLARE SECTION;
  EXEC SQL  INCLUDE SQLDA;
  struct sqlda initialsqlda;
  struct sqlda *sqldaPtr;

  … /* stmt1_str contains INSERT statement with VALUES     */
      /* clause                                              */
  EXEC SQL  PREPARE STMT1_NAME   FROM :stmt1_str;

  … /* code to set SQLN to five and to allocate the SQLDA */
  EXEC SQL  DESCRIBE INPUT  STMT1_NAME INTO  :SQLDA;

   …

例 2: 20 項目の記述子域を保持できる大きさの 'NEWDA' という記述子を割り振り、それを DESCRIBE INPUT で使用します。

  EXEC SQL ALLOCATE DESCRIPTOR 'NEWDA'
    WITH MAX 20;

  EXEC SQL DESCRIBE INPUT STMT1
    USING SQL DESCRIPTOR 'NEWDA';

1 LOB または UDT が結果セットに入っていない場合、この警告が戻されるのは、標準オプションが指定されている場合のみです。 標準オプションについては、標準への準拠を参照してください。