SQLColumns() - 列情報を取得する

SQLColumns() は、指定された表の中の列のリストを戻します。この情報は SQL 結果セットに戻されます。これは、 照会で作成された結果セットをフェッチするのと同じ関数を使用して、フェッチすることができます。

SQLColumns() の ODBC 仕様

表 1. SQLColumns() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
1.0 あり なし

構文

SQLRETURN   SQLColumns       (SQLHSTMT          hstmt,
                              SQLCHAR     FAR   *szCatalogName,
                              SQLSMALLINT       cbCatalogName,
                              SQLCHAR     FAR   *szSchemaName,
                              SQLSMALLINT       cbSchemaName,
                              SQLCHAR     FAR   *szTableName,
                              SQLSMALLINT       cbTableName,
                              SQLCHAR     FAR   *szColumnName,
                              SQLSMALLINT       cbColumnName);

関数の引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLColumns() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 ステートメント・ハンドルを示します。
SQLCHAR * szCatalogName 入力 結果セットを修飾するためのパターン値 を入れることが できるバッファーを示します。 カタログ は、3 部構成の表名の最初の部分です。

これは、NULL ポインターまたは長さゼロのストリングでなければなりません。

SQLSMALLINT cbCatalogName 入力 szCatalogName の長さ (バイト) を指定します。これは、0 に設定する必要があります。
SQLCHAR * szSchemaName 入力 結果セットをスキーマ名で修飾するパターン値 を入れることが できるバッファーを示します。
SQLSMALLINT cbSchemaName 入力 szSchemaName の長さ (バイト) を指定します。
SQLCHAR * szTableName 入力 表名によって結果セットを修飾するパターン値を入れることが できるバッファーを示します。
SQLSMALLINT cbTableName 入力 szTableName の長さ (バイト) を指定します。
SQLCHAR * szColumnName 入力 列名によって結果セットを修飾するパターン値を入れる ことができるバッファーを示します。
SQLSMALLINT cbColumnName 入力 szColumnName の長さ (バイト) を指定します。

使用法

この関数は、表または表集合の列についての情報を取り出します。 一般には、SQLTables() を呼び出して表の列を判別してから、この関数を呼び出し ます。SQLTables() 結果セットの TABLE_SCHEM および TABLE_NAME 列に 戻される文字ストリングを、この関数への入力として使用します。

SQLColumns() は、TABLE_CAT、TABLE_SCHEM、TABLE_NAME、 および ORDINAL_POSITION の順序で標準結果セットを戻します。表 3 には、結 果セットにある列の一覧を記載してあります。

szSchemaName、szTableName、およ び szColumnName 引数は検索パターンを受け入れます。

SQLColumns() を頻繁に呼び出すと、結果として複雑で高価なカタログ照会になるため、この呼び出しは慎重に使用し、呼び出しを繰り返すよりも結果を保管するようにしてください。

カタログ関数の結果セットの VARCHAR 列は、128 バイトの最大長属性で 宣言されています (ANSI/ISO SQL 規格 (1992) の制限と整合性あり)。Db2® 名は 128 文字より短いため、アプリケーション では常に 128 文字 (NUL 終止符をプラス) を 出力バッファー用に取っておくように選択できます。 あるいは、引数 InfoType を以下のそれぞれの値に 設定して、SQLGetInfo() を呼び出すことができます。
  • SQL_MAX_CATALOG_NAME_LEN -- 接続されたデータベース管理システムがサポートする TABLE_CAT 列の長さを判別
  • SQL_MAX_SCHEMA_NAME_LEN -- 接続されたデータベース管理システムがサポートする TABLE_SCHEM 列の長さを判別
  • SQL_MAX_TABLE_NAME_LEN -- 接続されたデータベース管理システムがサポートする TABLE_NAME 列の長さを判別
  • SQL_MAX_COLUMN_NAME_LEN -- 接続されたデータベース管理システムがサポートする COLUMN_NAME 列の長さを判別

将来のリリースでは、列が新たに追加されたり、既存の列の名前が 変更される可能性はありますが、現行の列の位置が変更されることはありま せん。次の表は、現在、SQLColumns() が戻す結果セット の列を示しています。

表 3. SQLColumns() で戻される列
列番号 列名 データ・タイプ 説明
1 TABLE_CAT VARCHAR(128) これは常に NULL です。
2 TABLE_SCHEM VARCHAR(128) TABLE_NAME を含むスキーマの名前を示します。
3 TABLE_NAME VARCHAR(128) NOT NULL 表、ビュー、別名、または同義語の名前を示します。
4 COLUMN_NAME VARCHAR(128) NOT NULL 記述される列を示します。 この列は、指定された表、ビュー、別名、または同義語の列の名前を含んでいます。
5 DATA_TYPE SMALLINT NOT NULL COLUMN_NAME が示す SQL データ・タイプを示します。
6 TYPE_NAME VARCHAR(128) NOT NULL DATA_TYPE 結果セットの列に対応するデータ・タイプの名前を表す文字ストリングを示します。
7 COLUMN_SIZE INTEGER DATA_TYPE 列の値が文字ストリングまたはバイナリー・ストリングを示す場合、 この列には列の最大文字数が入ります。

日付、時刻、タイム・スタンプのデータ・タイプの場合、 これは文字に変換されたときに値を表示するために必要となる文字数の合計です。

数値データ・タイプの場合、これは、列で許可される桁の総数またはビットの総数のいずれかです。 いずれであるかは、結果セットの NUM_PREC_RADIX 列の値によって決まります。

XML データ・タイプの場合、長さゼロが戻されます。

8 BUFFER_LENGTH INTEGER SQL_C_DEFAULT が SQLBindCol()、SQLGetData()、および SQLBindParameter() 呼び出しで 指定された場合、この列からのデータを保管するための、関連する C バッファーの最大バイト数 を示します。 この長さには、NUL 終止符は含まれていません。 正確な数値データ・タイプの場合、小数点と符号も長さに数えられます。
9 DECIMAL_DIGITS SMALLINT 列の位取りを示します。位取りが適用できないデータ・タイプの場合は NULL が戻されます。
10 NUM_PREC_RADIX SMALLINT 10、2、または NULL のいずれかを指定します。

DATA_TYPE が近似値データ・タイプの場合、この列には 2 の値が入っており、COLUMN_SIZE 列 にはその列に許可されるビットの合計数が入ります。

DATA_TYPE が厳密な数値データ・タイプの場合、 この列には 10 の値が入っており、COLUMN_SIZE にはそのパラメーターに許可される 10 進数の合計桁数が入ります。

数値データ・タイプの場合、データベース管理システムは 10 もしくは 2 の NUM_PREC_RADIX 値を 戻すことができます。

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

11 NULLABLE SMALLINT NOT NULL 列が NULL 値を受け入れない場合は SQL_NO_NULLS が入ります。

列が NULL 値を受け入れる場合は SQL_NULLABLE が入ります。

12 REMARKS VARCHAR(762) 列に関する記述情報が入ります。
13 COLUMN_DEF VARCHAR(254) 列のデフォルト値を示します。

デフォルト値が数値リテラルの場合、 この列には単一引用符で囲まれていない数値リテラルの文字表記が含まれています。

デフォルト値が文字ストリングの場合、この列は単一引用符で囲まれた ストリングです。

デフォルト値が DATE、TIME、および TIMESTAMP 列などの 疑似リテラル の場合、 この列には、引用符で囲まれていない疑似リテラルのキーワード (例えば、CURRENT DATE) が入ります。

NULL をデフォルト値として指定した場合、この列は引用符で囲まれてい ない NULL という語を戻します。

切り捨てを行わずにデフォルト値を表すことができない場合、この列に は単一引用符で囲まれていない TRUNCATED という値が入ります。

デフォルト値が指定されていない場合、この列は NULL です。

14 SQL_DATA_TYPE SMALLINT NOT NULL SQL データ・タイプを示します。 この列は、DATA_TYPE 列と同じです。

日時のデータ・タイプの場合、結果セット内の SQL_DATA_TYPE フィールド は SQL_DATETIME であり、SQL_DATETIME_SUB フィールドは、特定の日時データ・タイプ のサブコード (SQL_CODE_DATE、SQL_CODE_TIME または SQL_CODE_TIMESTAMP) を戻します。

15 SQL_DATETIME_SUB SMALLINT 日時データ・タイプのサブタイプ・コードは次のいずれかの値が可能です。
  • SQL_CODE_DATE
  • SQL_CODE_TIME
  • SQL_CODE_TIMESTAMP
その他のデータ・タイプに対してはすべて、この列は NULL を戻します。
16 CHAR_OCTET_LENGTH INTEGER

文字データ列の最大長 (バイト) を含んでいます。 1 バイト文字セットの場合、これ は COLUMN_SIZE と同じです。XML タイプの場合、ゼロが戻されます。 文字データ・タイプまたは XML データ・タイプ以外のデータ・タイプの場合は、NULL です。

17 ORDINAL_POSITION INTEGER NOT NULL 表中の列の順位。 表の最初の列は 1 です。
18 IS_NULLABLE VARCHAR(254) 列が NULL 可能でないことが判明している場合は、ストリング 'NO' が入り、 それ以外の場合は 'YES' が入ります。

前の表で説明している結果セットは、X/Open CLI Columns() 結果セットの仕様と同じであり、ODBC 2.0 が指定する SQLColumns() 結果セットの拡張バージョンです。 ODBC SQLColumns() 結果セットは、同じ位置にあるすべての列を REMARK 列まで組み込みます。

Db2 for z/OS® サーバーに対して SQLColumns() を 出す Db2 ODBC アプリケーションは、表 3 にリストされた 結果セット列を得ることになります。

戻りコード

SQLColumns() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE

診断

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

表 4. SQLColumns() の SQLSTATE
SQLSTATE 説明 説明
08S01 通信リンクに障害が起きました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
24000 カーソル状態が無効です。 ステートメント・ハンドルでカーソルがオープン状態です。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY010 関数シーケンス・エラーが発生しました。

この関数は、実行時データの操作時に呼び出されました。(すなわち、SQLParamData() または SQLPutData() 関数を使用するプロシージャー実行中に関数が呼び出されました。)

HY014 これ以上ハンドルがありません。 Db2 ODBC は、内部リソースが少ないためにハンドルを割り振ることができません。
HY090 ストリングまたはバッファーの長さが無効です。 名前の長さ引数のうちの 1 つの値は 0 より小さい値ですが、SQL_NTS と等しくありません。
HYC00 ドライバーは使用できません。 Db2 ODBC は、表名の修飾子として 'catalog' はサポートしていません。

例

以下の例は、表列の情報について、 システム・カタログを照会するアプリケーションを示しています。
図 1. 表列に関する情報を戻すアプリケーション
/* ... */
SQLRETURN
list_columns(SQLHDBC hdbc, SQLCHAR *schema, SQLCHAR *tablename )
{
/* ... */
    rc = SQLColumns(hstmt, NULL, 0, schema, SQL_NTS,
                    tablename, SQL_NTS, "NTS);
    rc = SQLBindCol(hstmt, 4, SQL_C_CHAR, (SQLPOINTER) column_name.s, 129,
                    &column_name.ind);
    rc = SQLBindCol(hstmt, 6, SQL_C_CHAR, (SQLPOINTER) type_name.s, 129,
                    &type_name.ind);
    rc = SQLBindCol(hstmt, 7, SQL_C_LONG, (SQLPOINTER) &length,
                    sizeof(length), &length_ind);
    rc = SQLBindCol(hstmt, 9, SQL_C_SHORT, (SQLPOINTER) &scale,
                    sizeof(scale), &scale_ind);
    rc = SQLBindCol(hstmt, 12, SQL_C_CHAR, (SQLPOINTER) remarks.s, 129,
                    &remarks.ind);
    rc = SQLBindCol(hstmt, 11, SQL_C_SHORT, (SQLPOINTER) & nullable,
                    sizeof(nullable), &nullable_ind);
printf("Schema: 
    /* Fetch each row, and display */
    while ((rc = SQLFetch(hstmt)) == SQL_SUCCESS) {
        printf("   name.s);
        if (nullable == SQL_NULLABLE) {
            printf(", NULLABLE");
        } else {
            printf(", NOT NULLABLE");
        }
        printf(", name.s);
        if (length_ind != SQL_NULL_DATA) {
            printf(" (
        } else {
            printf("(¥n");
        }
        if (scale_ind != SQL_NULL_DATA) {
            printf(", 
        } else {
            printf(")¥n");
        }
    }                           /* endwhile */
/* ... */