SQLColumns() - 列情報を取得する
SQLColumns() は、指定された表の中の列のリストを戻します。この情報は SQL 結果セットに戻されます。これは、 照会で作成された結果セットをフェッチするのと同じ関数を使用して、フェッチすることができます。
SQLColumns() の ODBC 仕様
| 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);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| 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() を頻繁に呼び出すと、結果として複雑で高価なカタログ照会になるため、この呼び出しは慎重に使用し、呼び出しを繰り返すよりも結果を保管するようにしてください。
- 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() が戻す結果セット の列を示しています。
| 列番号 | 列名 | データ・タイプ | 説明 |
|---|---|---|---|
| 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 | 日時データ・タイプのサブタイプ・コードは次のいずれかの値が可能です。
|
| 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 にリストされた 結果セット列を得ることになります。
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 08S01 | 通信リンクに障害が起きました。 | 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。 |
| 24000 | カーソル状態が無効です。 | ステートメント・ハンドルでカーソルがオープン状態です。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
| HY010 | 関数シーケンス・エラーが発生しました。 | この関数は、実行時データの操作時に呼び出されました。(すなわち、SQLParamData() または SQLPutData() 関数を使用するプロシージャー実行中に関数が呼び出されました。) |
| HY014 | これ以上ハンドルがありません。 | Db2 ODBC は、内部リソースが少ないためにハンドルを割り振ることができません。 |
| HY090 | ストリングまたはバッファーの長さが無効です。 | 名前の長さ引数のうちの 1 つの値は 0 より小さい値ですが、SQL_NTS と等しくありません。 |
| HYC00 | ドライバーは使用できません。 | Db2 ODBC は、表名の修飾子として 'catalog' はサポートしていません。 |
例
/* ... */
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 */
/* ... */