仕様: | DB2 CLI 2.1 | ODBC 1.0 |
|
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 */
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル。 |
SQLCHAR * | CatalogName | 入力 | 結果セットを修飾するためのパターン値 を入れられるバッファー。
カタログ は、3 部分から成る表名の最初の部分です。
これは、NULL ポインターまたは長さゼロのストリングでなければなりません。 |
SQLSMALLINT | NameLength1 | 入力 | CatalogName の長さ。これは、0 に設定する必要があります。 |
SQLCHAR * | SchemaName | 入力 | スキーマ名で結果セットを修飾するためのパターン値 を入れられるバッファー。 |
SQLSMALLINT | NameLength2 | 入力 | SchemaName の長さ。 |
SQLCHAR * | TableName | 入力 | 表名で結果セットを修飾するためのパターン値 を入れられるバッファー。 |
SQLSMALLINT | NameLength3 | 入力 | TableName の長さ。 |
SQLCHAR * | ColumnName | 入力 | 列名で結果セットを修飾するためのパターン値 を入れられるバッファー。 |
SQLSMALLINT | NameLength4 | 入力 | ColumnName の長さ。 |
使用法
表および表の集まりの列に関する情報を検索するには、この関数を呼び出します。通常のアプリケーションでは、 SQLTables() を呼び出して表の列を判別してからこの関数を呼び出すこともできます。アプリケーションは、SQLTables() 結果セットの TABLE_SCHEMA、 TABLE_NAME 列に返される文字ストリングを、この関数の入力として使用することになります。
SQLColumns() は、TABLE_CAT、TABLE_SCHEM、TABLE_NAME、および ORDINAL_POSITION の順序で標準の結果セットを返します。 『SQLColumns() で戻される列』は、結果セット内の列をリストしています。
SchemaName、TableName、および ColumnName 引き数は、探索パターンを受け入れます。有効な探索パターンについては、カタログ関数での入力引き数を参照してください。
この関数は、結果セット内の列についての情報を返しません。 SQLDescribeCol() または SQLColAttribute() を代わりに使用する必要があります。
SQL_ATTR_LONGDATA_COMPAT 属性が、SQLSetConnectAttr() の呼び出しによって、または DB2 CLI 初期設定ファイル内の LONGDATACOMPAT キーワードの設定によって、 SQL_LD_COMPAT_YES に設定される場合、LOB データ・タイプは、SQL_LONGVARCHAR、SQL_LONGVARBINARY、または SQL_LONGVARGRAPHIC として報告されます。
多くの場合に SQLColumns() の呼び出しはシステム・カタログに対する複雑な (したがってコストのかかる) 照会にマッピングされるため、それらの呼び出しの使用を少なくし、呼び出しを繰り返すのではなく結果を保管するようにしてください。
カタログ関数の結果セットの VARCHAR 列は、 SQL92 の制限に従うように、128 の最大長属性で宣言されています。 DB2 名は 128 文字未満なので、アプリケーションは、出力バッファー用に 128 文字 (およびヌル終止符) を常にとっておくか、あるいは、接続している DBMS がサポートしている TABLE_CAT、TABLE_SCHEM、TABLE_NAME、および COLUMN_NAME 列の実際の長さを判別するために、 SQL_MAX_CATALOG_NAME_LEN、 SQL_MAX_OWNER_SCHEMA_LEN、 SQL_MAX_TABLE_NAME_LEN、および SQL_MAX_COLUMN_NAME_LEN を使用して選択的に SQLGetInfo() を呼び出すようにすることができます。
将来のリリースでは、列が新たに追加されたり、既存の列の名前が変更されたりする可能性はありますが、現行の列の位置が変更されることはありません。これらの列は、バージョン 2 からバージョン 5 までの間に変更が加えられました。バージョン 5 またはそれ以降のサーバーに対して、バージョン 2 の DB2 CLI アプリケーション (SQLColumns() を使用するもの) を実行している場合は、詳細について、SQLColumns() 戻り値の変更を参照してください。
以下のどちらかを使用して、 SQLColumns() への呼び出しを最適化するよう DB2 CLI/ODBC ドライバーを設定できます。
上記のどちらかの値を設定すると、以下の列は情報を戻さなくなります。
日付、時刻、タイム・スタンプ・データ・タイプの場合、これは文字に変換されたときに値を表示するために必要となる文字数の合計です。
数値データ・タイプの場合、これは結果表の NUM_PREC_RADIX 列の値に基づいて、列に許可されている合計桁数または合計ビット数のいずれかです。
表 194 も参照してください。
表 196 も参照してください。
表 195 も参照してください。
DATA_TYPE が正確な数値データ・タイプの場合、この列には値 10 が入り、 COLUMN_SIZE にはそのパラメーターに許可されている小数桁数が入ります。
数値データ・タイプの場合、DBMS は 10 または 2 の NUM_PREC_RADIX を戻すことができます。
基数が適用できないデータ・タイプの場合は NULL が戻されます。
列が NULL 値を受け入れる場合は SQL_NULLABLE。
NULL を省略時値として指定した場合、この列は引用符で囲まれていない語 NULL を返します。切り捨てを行わずに省略時値を表すことができない場合、この列には単一引用符で囲まれていない TRUNCATED が含まれています。省略時値を指定しなかった場合、この列は NULL です。
この列には、情報が戻されない場合があります。詳しくは、『SQL 列のキーワードと属性の最適化』を参照してください。
注: | この結果セットは X/Open CLI の Columns() 結果セット仕様と同じであり、 ODBC V2 に指定されている SQLColumns() 結果セットの拡張版です。 ODBC SQLColumns() 結果セットには、同じ位置にあるすべての列が含まれています。 |
戻りコード
診断
SQLSTATE | 説明 | 解説 |
---|---|---|
24000 | カーソル状態が無効です。 | カーソルはすでに、ステートメント・ハンドル上にオープンされています。 |
40003 08S01 | 通信リンクに障害が起きました。 | アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。 |
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
HY008 | 操作が取り消しになりました。 |
非同期処理が StatementHandle に対して使用可能になりました。関数が呼び出され、その実行が完了する前に、 SQLCancel() が StatementHandle で呼び出されました。そして、関数が再び StatementHandle で呼び出されました。 関数が呼び出され、その実行が完了する前に、
SQLCancel() が複数スレッドのアプリケーション内の別のスレッドから、
StatementHandle で呼び出されました。
|
HY010 | 関数の順序エラーです。 |
実行時データ (SQLParamData()、SQLPutData()) 操作中に、関数が呼び出されました。 BEGIN COMPOUND と END COMPOUND SQL の操作中に、関数が呼び出されました。 非同期実行関数 (この関数ではない) が StatementHandle で呼び出され、この関数は、呼び出し時に依然実行中でした。
|
HY014 | もはやハンドルはありません。 | DB2 CLI は、内部資源が原因でハンドルを割り当てることができませんでした。 |
HY090 | ストリングまたはバッファー長が無効です。 | 名前の長さ引き数のうちの 1 つの値は 0 より小さい値でしたが、 SQL_NTS と等しくありませんでした。 |
HYC00 | ドライバーが機能していません。 | DB2 CLI は、表名の修飾子としてカタログ をサポートしません。 |
HYT00 | タイムアウトになりました。 | データ・ソースが結果セットを返す前に、タイムアウト期間が満了しました。タイムアウトは、 Windows 3.1 や Macintosh System 7 のようなマルチタスクではないシステム上でのみサポートされています。タイムアウト期間は、 SQLSetConnectAttr() の SQL_ATTR_QUERY_TIMEOUT 属性を使用して設定することができます。 |
制約
なし。
(ここで完全サンプル tbinfo.c を使用することもできます 。)
/* From the CLI sample TBINFO.C */ /* ... */ /* call SQLColumns */ printf("\n Call SQLColumns for:\n"); printf(" tbSchemaPattern = %s\n", tbSchemaPattern); printf(" tbNamePattern = %s\n", tbNamePattern); printf(" colNamePattern = %s\n", colNamePattern); sqlrc = SQLColumns( hstmt, NULL, 0, tbSchemaPattern, SQL_NTS, tbNamePattern, SQL_NTS, colNamePattern, SQL_NTS);
参照