DESCRIBE TABLE
DESCRIBE TABLE ステートメントは、表またはビューに関する情報を入手します。
呼び出し
このステートメントは、アプリケーション・プログラム、SQL 関数、 SQL プロシージャー、またはトリガー内にのみ組み込むことができます。 これは実行可能ステートメントですが、動的に準備することはできません。Java™ では指定できません。
権限
このステートメントの権限 ID が保持する特権には、少なくとも以下の 1 つ が含まれていなければなりません。
- ステートメントに指定された表またはビューに対して、
- その表またはビューに対する *OBJOPR システム権限
- 表やビューが入っているライブラリーに対する *EXECUTE システム権限
- データベース管理者権限
構文
>>-DESCRIBE TABLE--variable-------------------------------------> .-INCLUDING IMPLICITLY HIDDEN COLUMNS-. >--+-------------------------------------+----------------------> '-EXCLUDING IMPLICITLY HIDDEN COLUMNS-' .-SQL-. .-LOCAL--. >--+-USING--+-----+--DESCRIPTOR--+--------+--SQL-descriptor-name-+->< | '-GLOBAL-' | '-INTO----descriptor-name----+-------------------------+------' '-USING--+-NAMES--------+-' +-SYSTEM NAMES-+ +-LABELS-------+ +-ANY----------+ +-BOTH---------+ '-ALL----------'
説明
- variable
- 説明する表またはビューを指定します。
DESCRIBE TABLE ステートメントを実行する時点で、
- この名前は、アプリケーション・サーバーにある表またはビューを識別するものでなければなりません。
- 変数 は文字ストリング変数または Unicode グラフィック・ストリング変数でなければならず、標識変数を含んでいてはなりません。この変数は、グローバル変数にすることはできません。
- 変数 内に含まれる表名は左寄せでなければならず、その長さが変数 の長さより短い場合は、右側にブランクを埋め込まなければなりません。
- 表の名前は、区切り文字付の名前でない限り、大文字にしなければなりません。
- INCLUDING IMPLICITLY HIDDEN COLUMNS または EXCLUDING IMPLICITLY HIDDEN COLUMNS
- 表の中の暗黙的隠し列に関する情報を戻すべきかどうかを指定します。
- INCLUDING IMPLICITLY HIDDEN COLUMNS
- 暗黙的隠し列として定義された列に関する情報を戻すことを指定します。これはデフォルトです。
- EXCLUDING IMPLICITLY HIDDEN COLUMNS
- 暗黙的隠し列として定義された列に関する情報を戻さないことを指定します。
DESCRIBE TABLE ステートメントを実行すると、データベース・マネージャーによって、SQL 記述子または SQLDA の各変数には次のような値が割り当てられます。
- USING
- SQL 記述子を識別します。
- LOCAL
- 記述子の名前の有効範囲はプログラム呼び出しのローカルであることを指定します。
- GLOBAL
- 記述子の名前の有効範囲は SQL セッション全体であることを指定します。
- SQL-descriptor-name
- SQL 記述子の名前を指定します。名前は、指定の有効範囲を持つ既存の記述子を識別するものでなければなりません。
SQL 記述子に入る情報の説明については、GET DESCRIPTORを参照してください。
- INTO descriptor-name
- SQL 記述子域 (SQLDA) を指定します。これについては、SQLDA (SQL 記述子域)で説明しています。DESCRIBE TABLE ステートメントを実行する前に、SQLDA の以下の変数をセットしておく必要があります。
- SQLN
- SQLDA で用意される SQLVAR オカレンスの数を指定します。 DESCRIBE TABLE ステートメントを実行する前に、SQLN をゼロ以上の値にセットしておく必要があります。 必要なオカレンスの数を決定する手法については、必要な SQLVAR オカレンスの数の決定を参照してください。
DESCRIBE ステートメントが実行されると、データベース・マネージャーでは、SQLDA の各変数に次のような値を割り当てます。
- SQLDAID
- 最初の 6 バイトは 'SQLDA ' (つまり、5 文字の後にスペース文字) に設定
されます。
7 番目のバイトは、記述された列に基づいて設定されます。
- SQLDA に表の列ごとに 2 つ、3 つ、または 4 つの SQLVAR 項目が含まれる場合、この 7 番目のバイトはそれぞれ '2'、'3'、または '4' に設定されます。 この技法は、LOB または特殊タイプ結果列、ラベル、およびシステム名に対応するために 使用されています。
- それ以外の場合、7 番目のバイトはスペース文字に設定されます。
SQLDA 内にすべての列の記述を含める余地がない場合、7 番目のバイトはスペース文字に設定されます。
8 番目のバイトはスペース文字に設定されます。
- 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 のオカレンスのフィールドの説明を参照してください。
- USING
- SQLDA のそれぞれの SQLNAME 変数に、どのような値を割り当てるかを
指定します。要求した値が存在しない場合、または名前の長さが 30 より大きい場合は、SQLNAME の長さは 0 にセットされます。
- NAMES
- 列の名前を割り当てます。戻される列名は大/小文字の区別があり、区切り文字はありません。 これはデフォルトです。
- SYSTEM NAMES
- 列のシステム列名を割り当てます。
- LABELS
- 列のラベルを割り当てます。(列のラベルは、LABEL ステートメントによって定義されます。) ラベルの最初の 20 バイトだけが戻されます。
- ANY
- 列のラベルを割り当てます。列にラベルがない場合は、代わりに列の名前が割り当てられます。
- BOTH
- 列のラベルと名前の両方を割り当てます。この場合、追加情報に応じ るために、1 つの列ごとに SQLVAR の 2 つから 3 つのオカレンスが必要になり ますが、その数は、表に特殊タイプが入っているか否かによって決まります。この拡張の SQLVAR 配列を指定するには、SQLN を 2*n か 3*n (この場合の n は、表やビュー内の列数) に設定します。 列名がシステム列名とは異なる場合、列名は SQLVAR の最初の n オカレンスに含まれます。 2 番目または 3 番目の n オカレンスには、列のラベルが含まれます。 特殊タイプがない場合、SQLVAR 項目の 2 番目のセットにそのラベルが戻されます。 それ以外の場合、ラベルは、SQLVAR 項目の 3 番目のセット内に戻されます。
- ALL
- ラベル、列名、およびシステム列名を割り当てます。この場合、追加情報に応じるために、 1 つの列ごとに SQLVAR の 3 つから 4 つのオカレンスが必要になりますが、その数は、 表に特殊タイプが入っているか否かによって決まります。この拡張の SQLVAR 配列を指定するには、SQLN を 3*n か 4*n (この場合の n は、表内の列数) に設定します。 SQLVAR の最初の n オカレンスには、システム列名が入ります。 2 番目または 3 番目の n オカレンスには、列のラベルが含まれます。 3 番目または 4 番目の n オカレンスには、列名が含まれます。 特殊タイプが指定されていない場合、ラベルは、SQLVAR 記入項目の 2 番目のセット内に戻され、 列名は、SQLVAR 記入項目の 3 番目のセット内に戻されます。 それ以外の場合、ラベルは、SQLVAR 記入項目の 3 番目のセット内に戻され、列名は、 SQLVAR 記入項目の 4 番目のセット内に戻されます。
注
SQL 記述子の割り振り: DESCRIBE TABLE ステートメントを実行する前に、ALLOCATE DESCRIPTOR ステートメントを使用して SQL 記述子を割り振らなければなりません。 割り振られた記述子項目の数が表またはビューの列の数より小さい場合は、警告 (SQLSTATE 01005) が戻されます。
SQLDA の割り振り: DESCRIBE TABLE ステートメントを実行する前に、SQLN にゼロ以上の値をセットして、SQLDA に用意する SQLVAR のオカレンスの数を指示するとともに、SQLN の各オカレンスを収容するのに十分な記憶域を割り振っておく必要があります。 表またはビューの列の記述を取得するには、SQLVAR のオカレンスの数が列の数以上でなければなりません。 さらに、USING BOTH や USING ALL を指定している場合、あるいは、列に LOB や特殊タイプを指定している場合は、SQLVAR のオカレンス数として、列数の 2、3、または 4 倍の数値を指定する必要があります。詳しくは、必要な SQLVAR オカレンスの数の決定を参照してください。
提供されるオカレンスが不足していて、オカレンスのすべてのセットを戻せるとは限らない場合、SQLN は、すべての情報を戻すのに必要なオカレンスの合計数に設定されます。 それ以外の場合、SQLN は、列数に設定されます。
SQLDA の割り振りのために使用する方法については、SQLDA (SQL 記述子域)を参照してください。
例
C プログラムの中で、SQLVAR のオカレンスなしの SQLDA を使用して DESCRIBE ステートメントを実行します。SQLD がゼロより大きければ、その値を使用して、SQLVAR に必要なオカレンス数を指定した SQLDA を割り振ります。その後で、新しい SQLDA を使用して DESCRIBE ステートメントを実行します。
EXEC SQL BEGIN DECLARE SECTION;
char table_name[201];
EXEC SQL END DECLARE SECTION;
EXEC SQL INCLUDE SQLDA;
EXEC SQL DECLARE DYN_CURSOR CURSOR FOR STMT1_NAME;
.../*code to prompt user for a table or view */
.../*code to set SQLN to zero and to allocate the SQLDA */
EXEC SQL DESCRIBE TABLE :table_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 TABLE :table_name INTO :sqlda;
.
.
.