DESCRIBE OUTPUT ステートメント

DESCRIBE OUTPUT ステートメントは、準備されたステートメントについての情報を入手します。

呼び出し

このステートメントは、アプリケーション・プログラムに組み込む方法のみ可能です。 これは実行可能ステートメントですが、動的に準備することはできません。

許可

必要ありません。

構文

構文図を読む構文図をスキップするDESCRIBEOUTPUTstatement-name INTOdescriptor-name

説明

statement-name
準備済みステートメントを指定します。DESCRIBE OUTPUT ステートメントを実行する時点で、この名前は現行のサーバーでアプリケーション・プロセスにより準備されたステートメントを指定していなければなりません。

準備済みステートメントが SELECT または VALUES INTO ステートメントである場合、戻される情報は、その結果表の中の列数を示します。 準備済みステートメントが CALL ステートメントである場合、戻される情報は、プロシージャーの OUT または INOUT として定義される出力パラメーターを示します。

INTO descriptor-name
SQL 記述子域 (SQLDA) を指定します。 DESCRIBE OUTPUT ステートメントを実行する前に、SQLDA 内の以下の変数を設定しておく必要があります。
SQLN
SQLDA に用意する SQLVAR のオカレンス数を指定します。 DESCRIBE OUTPUT ステートメントを実行する前に、SQLN にゼロ以上の値を設定する必要があります。
DESCRIBE OUTPUT ステートメントを実行すると、データベース・マネージャーは、 以下のように SQLDA の変数に値を割り当てます。
SQLDAID
最初の 6 バイトは 'SQLDA ' に設定されます (5 文字の英字の後、6 文字目はスペース文字です)。
SQLDOUBLED として定義される 7 番目のバイトは、示された結果列またはパラメーター・マーカーに基づいて設定されます。
  • すべての列または出力パラメーターに対して SQLDA に 2 つの SQLVAR 項目が含まれている場合、7 番目のバイトは '2' に設定されます。 LOB、特殊タイプ、構造化タイプ、参照タイプの列、または出力パラメーターを可能にするために、このようになっています。
  • それ以外の場合、7 番目のバイトはスペース文字に設定されます。

SQLDA の中にすべての結果列または出力パラメーター・マーカーの記述が入るだけの十分なスペースがない場合、7 番目のバイトはスペース文字に設定されます。

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

SQLDABC
SQLDA の長さ (バイト単位)。
SQLD
準備済みステートメントが SELECT である場合は、SQLD は結果表の中の列数に設定されます。 準備済みステートメントが CALL ステートメントである場合は、SQLD はプロシージャーの OUT および INOUT パラメーターの数に設定されます。 それ以外の場合、SQLD は 0 に設定されます。
SQLVAR
SQLD の値が 0 の場合、または SQLD の値が SQLN の値より大きい場合は、 SQLVAR のエレメントには値は割り当てられません。

SQLD の値が n (n は 0 より大きく、SQLN の値以下) の場合、SQLVAR の先頭の n オカレンスに対して、値は SQLTYPE、SQLLEN、SQLNAME、SQLLONGLEN、および SQLDATATYPE_NAME に割り当てられます。 これらの値は、結果表の列、またはプロシージャーの出力パラメーターのパラメーター・マーカーのいずれかを示します。 SQLVAR の最初のオカレンスは最初の列または出力パラメーター・マーカーを示し、SQLVAR の 2 番目のオカレンスは 2 番目の列または出力パラメーター・マーカーを示し、というように続きます。

基本 SQLVAR
SQLTYPE
列またはパラメーターのデータ・タイプと、その列に NULL 値が入るかどうかを示すコード。
SQLLEN
列またはパラメーターのデータ・タイプによって決まる長さを示す値。 LOB データ・タイプの場合、SQLLEN は 0 になります。
SQLNAME
sqlname は、以下のように導き出されます。
  • SQLVAR が、SELECT ステートメントの選択リスト内の単純な列参照用の派生列に対応する場合は、 sqlname はその列の名前です。
  • SQLVAR が、プロシージャーのパラメーター・リストにはあるが式の一部ではないパラメーター・マーカーに対応する場合は、CREATE PROCEDURE でパラメーターが指定されていれば、sqlname にはそのパラメーターの名前が含まれます。
  • CREATE PROCEDURE でパラメーターが指定されていなければ、 sqlname には SQLDA 内の SQLVAR の位置を表す ASCII 数値リテラル値が含まれます。
2 次 SQLVAR
これらの変数は、LOB、特殊タイプ、構造化タイプ、または参照タイプの列またはパラメーターを含めることができるよう、SQLVAR の項目の数が 2 倍にされた場合にのみ使用されます。
SQLLONGLEN
BLOB、CLOB、または DBCLOB の列またはパラメーターの長さ属性。
SQLDATATYPE_NAME
データベース・マネージャーは、すべてのユーザー定義タイプ (特殊タイプまたは構造化タイプ) の列またはパラメーターで、この名前を完全修飾ユーザー定義タイプ名に設定します。 また、参照タイプの列またはパラメーターでは、データベース・マネージャーは、 この名前を参照のターゲット・タイプの完全修飾ユーザー定義タイプ名に設定します。 それ以外の場合、スキーマ名は SYSIBM となり、 タイプ名は SYSCAT.DATATYPES カタログ・ビューの TYPENAME 列に含まれている名前になります。

注

  • DESCRIBE OUTPUT ステートメントを実行する前に、SQLN の値を SQLDA の中の SQLVAR のオカレンスの数に設定し、 SQLN 個のオカレンスが入るだけの十分なストレージを割り振っておく必要があります。 例えば、準備済み SELECT ステートメントの結果表の列の記述を入手するには、 SQLVAR のオカレンス数は列数以上でなければなりません。
  • 大きいサイズの LOB が予想される場合、 このラージ・オブジェクトの処理がアプリケーション・メモリーに与える影響について考慮してください。 そのような状況では、ロケーターまたはファイル参照変数を使用することを考えてください。 DESCRIBE OUTPUT ステートメントを実行してからストレージを割り振るまでの間に、 SQLDA を修正して、SQLLEN などの他のフィールドへ対応する変更を使用して、SQL_TYP_xLOB の SQLTYPE を SQL_TYP_xLOB_LOCATOR または SQL_TYP_xLOB_FILE に変更してください。 その後、SQLTYPE に基づいてストレージを割り振ってから、処理を継続します。
  • 拡張 UNIX コード (EUC) コード・ページと DBCS コード・ページとの間、または Unicode と非 Unicode コード・ページとの間でコード・ページ変換を行うと、結果の文字長が変化する場合があります。
  • 構造化タイプが選択されているのに、 FROM SQL トランスフォームが定義されていない (CURRENT DEFAULT TRANSFORM GROUP 特殊レジスターで指定された TRANSFORM GROUP がない (SQLSTATE 428EM) か、 あるいは指定されたグループに FROM SQL 変換機能が定義されていないため (SQLSTATE 42744) 場合は、エラーが戻されます。
  • SQLDA の割り振り: SQLDA を割り振る方式としては、以下の 3 とおりがあります。

    方式 1: アプリケーションで処理する必要のある選択リストが入るだけの十分な数の SQLVAR のオカレンスを含む SQLDA を割り振ります。 表に LOB、特殊タイプ、構造化タイプ、または参照タイプの列が含まれている場合には、 SQLVAR の数を最大列数の 2 倍にしてください。 それ以外の場合は、その数を最大列数と同じにします。 割り振りを行ったなら、アプリケーションでこの SQLDA を繰り返し使用できるようになります。

    このテクニックでは、大量のストレージを使用し、 そのストレージのほとんどが特定の選択リストで使用されるわけではない場合でも決して割り振り解除されることがありません。

    方式 2: 選択リストを処理するたびに、以下の 2 つのステップを繰り返し実行します。
    1. SQLVAR のオカレンスのない SQLDA (SQLN を 0 にした SQLDA) を指定した DESCRIBE OUTPUT ステートメントを実行します。 SQLD の戻り値は、結果表の列数となります。 これは、必要な SQLVAR のオカレンス数か、またはその数の半分のいずれかになります。 SQLVAR 項目がないので、SQLSTATE 01005 の警告が出されます。 その警告の SQLCODE が +237、+238、または +239 のいずれかである場合、 SQLVAR 項目の数は SQLD の戻り値の 2 倍でなければなりません。 (上記の正の SQLCODE の戻り値は、 SQLWARN BIND オプションが YES (正の SQLCODE を戻す) に設定されていることが前提となっています。 SQLWARN が NO に設定されている場合でも +238 が戻されて、 SQLVAR 項目の数が SQLD の戻り値の 2 倍でなければならないことを示します。)
    2. SQLVAR のオカレンス数として十分大きい数を指定した SQLDA を割り振ります。 この新しい SQLDA を使用して、DESCRIBE OUTPUT ステートメントをもう一度実行します。

    この方式では、方式 1 よりもストレージを効率的に管理できます。 しかし、DESCRIBE OUTPUT ステートメントの数は 2 倍になります。

    方式 3: 選択リストのほとんど (そしておそらくは全部) を処理できるほどの大きさではあるが、適度に小さい SQLDA を割り振ります。 DESCRIBE を実行して SQLD 値を調べます。 必要なら、SQLVAR のオカレンス数として SQLD 値を使用することにより、 もっと大きな SQLDA を割り振ります。

    この方式は、最初の 2 つの方式の折衷方式です。 その効果は、元の SQLDA サイズを適切に選択することに依存しています。

  • 暗黙的な隠し列についての考慮事項: DESCRIBE OUTPUT ステートメントで暗黙的な隠し列についての情報が戻されるのは、記述対象の照会の最終的な結果表の SELECT リスト内にその列が明示的に指定されている場合のみです。 暗黙的な隠し列が照会の結果表に含まれない場合、DESCRIBE OUTPUT ステートメントによって戻されるその照会に関する情報には、暗黙的な隠し列の情報が含まれません。

例

C プログラムの中で、SQLVAR オカレンスのない SQLDA を指定して DESCRIBE OUTPUT ステートメントを実行します。 SQLD が 0 より大きい場合、 その値を使って必要な数の SQLVAR のオカレンスを含む SQLDA を割り振り、 その SQLDA を使って DESCRIBE ステートメントを実行します。 
   EXEC SQL  BEGIN DECLARE SECTION;
     char  stmt1_str[200];
   EXEC SQL  END DECLARE SECTION;
   EXEC SQL  INCLUDE SQLDA;
   EXEC SQL  DECLARE DYN_CURSOR CURSOR FOR STMT1_NAME;

   ... /* code to prompt user for a query, then to generate */
       /* a select-statement in the stmt1_str            */
   EXEC SQL  PREPARE STMT1_NAME FROM :stmt1_str;
   
   ... /* code to set SQLN to zero and to allocate the SQLDA */
   EXEC SQL  DESCRIBE STMT1_NAME INTO :sqlda;

   ... /* code to check that SQLD is greater than zero, to set */
       /* SQLN to SQLD, then to re-allocate the SQLDA          */
   EXEC SQL  DESCRIBE STMT1_NAME INTO :sqlda;

   ... /* code to prepare for the use of the SQLDA             */
       /* and allocate buffers to receive the data             */
   EXEC SQL  OPEN DYN_CURSOR;

   ... /* loop to fetch rows from result table                 */
   EXEC SQL  FETCH DYN_CURSOR USING DESCRIPTOR :sqlda;
   .
   .
   .