DESCRIBE INPUT ステートメント

DESCRIBE INPUT ステートメントでは、準備済みステートメントの入力パラメーター・マーカーについての情報を取得します。

呼び出し

このステートメントは、アプリケーション・プログラムに組み込む方法のみ可能です。これは、動的に作成できない実行可能ステートメントです。

許可

必要ありません。

構文

説明

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

CALL ステートメントの場合は、プロシージャーの入力パラメーター (IN または INOUT として定義されているパラメーター) に関する情報が戻されます。入力パラメーター・マーカーは、使用法に関係なく常に NULL 可能と見なされます。

INTO 記述子名

SQL 記述子域 (SQLDA) を指定します。 DESCRIBE INPUT ステートメントを実行する前に、SQLDA 内の以下の変数を設定しておく必要があります。

SQLN: SQLDA に用意する SQLVAR のオカレンス数を指定します。 DESCRIBE INPUT ステートメントを実行する前に、SQLN にゼロ以上の値を設定する必要があります。

DESCRIBE INPUT ステートメントを実行すると、データベース・マネージャーは、以下のように SQLDA の変数に値を割り当てます。

SQLDAID

最初の 6 バイトは 'SQLDA ' に設定されます (5 文字の英字の後、6 文字目はスペース文字です)。

7 番目のバイト (SQLDOUBLED として定義されているバイト) は、記述されているパラメーター・マーカーに基づいて設定されます。

SQLDA に各入力パラメーターの SQLVAR 項目が 2 つ含まれている場合は、7 番目のバイトが '2' に設定されます。この技法によって、LOB または構造化タイプの入力パラメーターに対応できます。
それ以外の場合、7 番目のバイトはスペース文字に設定されます。

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

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

SQLDABC

SQLDA の長さ (バイト単位)。

SQLD

プロシージャーの IN パラメーターと INOUT パラメーターの数。

SQLVAR

SQLD の値が 0 の場合、または SQLD の値が SQLN の値より大きい場合は、 SQLVAR のエレメントには値は割り当てられません。

SQLD の値が n (n は 0 より大きく SQLN の値以下) の場合は、SQLVAR の最初の n 個のオカレンスに値が割り当てられます。これらの値では、プロシージャーの入力パラメーターのパラメーター・マーカーを記述します。 SQLVAR の最初のオカレンスでは、最初の入力パラメーター・マーカーを記述し、SQLVAR の 2 番目のオカレンスでは、2 番目の入力パラメーター・マーカーを記述する、といった具合になります。

基本 SQLVAR

SQLTYPE

パラメーターのデータ・タイプと、その列に NULL 値が入るかどうかを示すコード。

SQLLEN

パラメーターのデータ・タイプによって決まる長さを示す値。 LOB データ・タイプの場合、SQLLEN は 0 になります。

SQLNAME

sqlname は、以下のように導き出されます。

SQLVAR が、プロシージャーのパラメーター・リスト内にあり式の一部ではないパラメーター・マーカーに対応する場合は、CREATE PROCEDURE ステートメントでパラメーターが指定されていれば、sqlname にはそのパラメーターの名前が含まれます。
SQLVAR が、指定されたパラメーター・マーカーに対応する場合は、 sqlname にはそのパラメーター・マーカーの名前が含まれます。
CREATE PROCEDURE でパラメーターが指定されていなければ、 sqlname には SQLDA 内の SQLVAR の位置を表す ASCII 数値リテラル値が含まれます。

2 次 SQLVAR

これらの変数は、LOB、特殊タイプ、構造化タイプ、または参照タイプのパラメーターを含めることができるよう、SQLVAR の項目の数が 2 倍にされた場合にのみ使用されます。

SQLLONGLEN: BLOB、CLOB、または DBCLOB のパラメーターの長さ属性。
SQLDATATYPE_NAME: データベース・マネージャーは、すべてのユーザー定義タイプ (特殊タイプまたは構造化タイプ) のパラメーターで、この名前を完全修飾ユーザー定義タイプ名に設定します。また、参照タイプのパラメーターでは、データベース・マネージャーは、この名前を参照のターゲット・タイプの完全修飾ユーザー定義タイプ名に設定します。それ以外の場合、スキーマ名は SYSIBM となり、タイプ名は SYSCAT.DATATYPES カタログ・ビューの TYPENAME 列に含まれている名前になります。

注

SQLDA の準備: DESCRIBE INPUT ステートメントを実行する前に、SQLDA を割り振り、SQLN の値をゼロ以上の値に設定して、SQLDA の中の SQLVAR のオカレンスの数を示す必要があります。 SQLN のオカレンスを格納するために、十分なストレージを割り振る必要があります。準備済みステートメントの入力パラメーター・マーカーの説明を取得するには、SQLVAR のオカレンス数が入力パラメーター・マーカーの数を下回っていてはなりません。さらに、入力パラメーター・マーカーに LOB または構造化タイプが含まれている場合は、SQLVAR のオカレンス数が入力パラメーター・マーカーの数の 2 倍になっている必要があります。
拡張 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 INPUT ステートメントを実行します。 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 ステートメントをもう一度実行します。
この方式では、方式 1 よりもストレージを効率的に管理できます。しかし、DESCRIBE INPUT ステートメントの数は 2 倍になります。

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

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

例

準備済みステートメントに組み込める最大数の入力パラメーターを記述できるように、十分な数の SQLVAR オカレンスを設定した SQLDA を指定して、DESCRIBE INPUT ステートメントを実行します。最大で 5 つのパラメーター・マーカーを記述する必要があり、入力データに LOB が含まれていないと想定すると、次のようになります。

       /* STMT1_STR contains INSERT statement with VALUES clause */
   EXEC SQL PREPARE STMT1_NAME FROM :STMT1_STR;
   ... /* code to set SQLN to 5 and to allocate the SQLDA        */
   EXEC SQL DESCRIBE INPUT STMT1_NAME INTO :SQLDA;
   .
   .
   .

この例では、『DESCRIBE OUTPUT』の『SQLDA の割り振り』にある方式 1 を使用しています。