SQLColumns - 表の列情報の取得

目的

SQLColumns() は指定された表の列のリストを戻します。 この情報は SQL 結果セットに入れて戻され、照会で生成された結果セットを取り出すのに使用される関数と同じ関数を使用して検索できます。

構文

SQLRETURN   SQLColumns       (
               SQLHSTMT          StatementHandle,   /* hstmt */
               SQLCHAR      FAR  *CatalogName,      /* szCatalogName */
               SQLSMALLINT       NameLength1,       /* cbCatalogName */
               SQLCHAR      FAR  *SchemaName,       /* szSchemaName */
               SQLSMALLINT       NameLength2,       /* cbSchemaName */
               SQLCHAR      FAR  *TableName,        /* szTableName */
               SQLSMALLINT       NameLength3,       /* cbTableName */
               SQLCHAR      FAR  *ColumnName,       /* szColumnName */
               SQLSMALLINT       NameLength4);      /* cbColumnName */

関数の引き数

表 92. SQLColumns の引き数

使用法

この関数は、1 つの表または 1 組の表の列についての情報を検索するときに呼び出します。 一般的なアプリケーションでこの関数を呼び出すのは、SQLTables() を呼び出した後、表の列を判別するときです。 アプリケーションでは、SQLTables() 結果セットの TABLE_NAME に戻された文字ストリングをこの関数の入力として使用する必要があります。

SQLColumns() は、TABLE_NAME と ORDINAL_POSITION の順に配列された標準の結果セットを戻します。SQLColumns が戻す列に結果セットの列をリストしてあります。

TableName 引き数と ColumnName 引き数は検索パターンを受け入れます。

この関数は結果セット内の列についての情報は戻しません。代わりに、SQLDescribeCol() または SQLColAttribute() を使用してください。

SQLColumns() の呼び出しは、多くの場合システム・カタログに対する複雑で時間のかかる照会となるため、控えめに行うようにしてください。 呼び出しを繰り返さず、結果を保管するようにしてください。

カタログ関数の結果セットの VARCHAR 列は、SQL92 の制限と一貫性を持たせるために最大長の属性は 128 で宣言されています。 DB2 の名前は 128 より短いため、128 文字 (NULL 終止符を含む) を常に出力バッファー用にとっておくか、または SQL_MAX_TABLE_NAME_LEN と SQL_MAX_COLUMN_NAME_LEN とを指定した SQLGetInfo() を呼び出して、接続されている DBMS がサポートする TABLE_NAME 列と COLUMN_NAME 列の実際の長さを判別することができます。

将来のリリースで新規の列が追加されたり、既存の列の名前が変更されても、現在の列の位置は変わりません。

SQLColumns が戻す列

列 1 TABLE_CAT (VARCHAR(128))

これは常に NULL です。

列 2 TABLE_SCHEM (VARCHAR(128))

これは常に NULL です。

列 3 TABLE_NAME (VARCHAR(128) 非ヌル)

表の名前。

列 4 COLUMN_NAME (VARCHAR(128) 非ヌル)

列 ID。指定された表の列の名前、ビュー、別名、または同義語。

列 5 DATA_TYPE (SMALLINT 非ヌル)

COLUMN_NAME で識別された列の SQL データ・タイプ。これは、SQL のシンボリックおよびデフォルトのデータ・タイプの「シンボリック SQL データ・タイプ」の欄の値の 1 つです。

列 6 TYPE_NAME (VARCHAR(128) 非ヌル)

DATA_TYPE に対応するデータ・タイプの名前を表す文字ストリング。

列 7 COLUMN_SIZE (INTEGER)

DATA_TYPE 列の値が文字ストリングかバイナリー・ストリングを表す場合、この列には列の最大長 (文字数) が入ります。

DATE、TIME、または TIMESTAMP のデータ・タイプの場合、これは、文字に変換された値を表示するのに必要な文字の合計数になります。

数値データ・タイプの場合、これは、列内で許可される合計の桁数になります。

データ・タイプ属性も参照してください。

列 8 BUFFER_LENGTH (INTEGER)

SQL_C_DEFAULT が SQLBindCol()、SQLGetData()、および SQLBindParameter() の呼び出しで指定された場合、この列からのデータを関連した C バッファーに格納するときのバイトの最大数。この長さは NULL 終止符を含んでいません。また、厳密な数値データ・タイプの場合、長さには 10 進数と符号が含まれます。データ・タイプ属性も参照してください。

列 9 DECIMAL_DIGITS (SMALLINT)

列の位取り。位取りが適用されないデータ・タイプの場合は、NULL が戻されます。データ・タイプ属性も参照してください。

列 10 NUM_PREC_RADIX (SMALLINT)

10 または NULL のいずれか。

DATA_TYPE が厳密な数値データ・タイプである場合、この列には値 10 が入り、COLUMN_SIZE には列に許可されている 10 進数の桁数が入ります。

数値データ・タイプの場合、DBMS は 10 の NUM_PREC_RADIX を戻します。

基数が適用されないデータ・タイプの場合は、NULL が戻されます。

列 11 NULLABLE (SMALLINT 非ヌル)

列が NULL 値を受け入れない場合、SQL_NO_NULLS。

列が NULL 値を受け入れる場合、SQL_NULLABLE。

列 12 REMARKS (VARCHAR(254))

これは常に NULL です。

列 13 COLUMN_DEF (VARCHAR(254))

列のデフォルト値。デフォルト値が数値リテラルである場合は、 この列には単一引用符で囲まれていない数値リテラルの文字表現が入ります。デフォルト値が文字ストリングである場合は、この列には単一引用符で囲まれたそのストリングが入ります。デフォルト値が DATE、TIME、および TIMESTAMP といった列の疑似リテラルである場合は、引用符で囲まれていない疑似リテラルのキーワード (例えば、CURRENT DATE) が入ります。

NULL がデフォルト値として指定された場合は、 この列には引用符で囲まれていない「NULL」という単語が戻されます。デフォルト値が指定されなかった場合は、 この列は NULL となります。

列 14 SQL_DATA_TYPE (SMALLINT 非ヌル)

この列は DATA_TYPE 列と同じです。

列 15 SQL_DATETIME_SUB (SMALLINT)

この列は常に NULL です。

列 16 CHAR_OCTET_LENGTH (INTEGER)

文字データ・タイプ列のオクテット単位での最大長が入ります。 1 バイト文字セットの場合、これは COLUMN_SIZE と同じです。その他のデータ・タイプの場合は、NULL です。

列 17 ORDINAL_POSITION (INTEGER 非ヌル)

表内の列の順序を示す位置。表の第 1 列は番号 1 です。

列 18 IS_NULLABLE (VARCHAR(254))

列が NULL 可能でないことが既知である場合はストリング「NO」が入り、それ以外の場合は、「YES」が入ります。

この結果セットは X/Open CLI の Columns() 結果セット仕様と同一です。この仕様は、ODBC V2 で規定されている SQLColumns() 結果セットの拡張バージョンです。ODBC の SQLColumns() 結果セットには同じ位置に各列が含まれます。

注: この結果セットは X/Open CLI の Columns() 結果セット仕様と同一です。この仕様は、ODBC V2 に規定されている SQLColumns() 結果セットの拡張バージョンです。ODBC の SQLColumns() 結果セットには同じ位置に各列が含まれます。

戻りコード

• SQL_SUCCESS
• SQL_SUCCESS_WITH_INFO
• SQL_ERROR
• SQL_INVALID_HANDLE

診断

表 93. SQLColumns の SQLSTATE

制約事項

なし。

関連した解説

• SQLTables - 表情報の取得