CLI の手引きおよび解説書

SQLColumns - 表の列の情報を入手する

目的


仕様: 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 */

関数引き数


表 38. SQLColumns 引き数
データ・タイプ 引き数 使用法 説明
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() 戻り値の変更を参照してください。

SQL 列のキーワードと属性の最適化

以下のどちらかを使用して、 SQLColumns() への呼び出しを最適化するよう DB2 CLI/ODBC ドライバーを設定できます。

上記のどちらかの値を設定すると、以下の列は情報を戻さなくなります。

SQLColumns で戻される列

列 1 TABLE_CAT (VARCHAR(128))
これは常に NULL です。

列 2 TABLE_SCHEM (VARCHAR(128))
TABLE_NAME を含むスキーマの名前。

列 3 TABLE_NAME (VARCHAR(128) 非 NULL)
表、視点、別名、または同義語の名前。

列 4 COLUMN_NAME (VARCHAR(128) 非 NULL)
列の識別子。指定された表、視点、別名、または同義語の列の名前。

列 5 DATA_TYPE (SMALLINT 非 NULL)
COLUMN_NAME によって識別される列の SQL データ・タイプ。これは、表 2 の記号 SQL データ・タイプ列にある値の 1 つです。

列 6 TYPE_NAME (VARCHAR(128) 非 NULL)
DATA_TYPE に対応するデータ・タイプの名前を表す文字ストリング。

列 7 COLUMN_SIZE (INTEGER)
DATA_TYPE 列の値が文字ストリングまたは 2 進ストリングを示す場合、この列には列の最大文字数の長さが入ります。

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

数値データ・タイプの場合、これは結果表の NUM_PREC_RADIX 列の値に基づいて、列に許可されている合計桁数または合計ビット数のいずれかです。

表 194 も参照してください。

列 8 BUFFER_LENGTH (INTEGER)
SQL_C_DEFAULT が SQLBindCol()SQLGetData() および SQLBindParameter() 呼び出しで指定された場合に、この列からのデータを保管するための関連 C バッファーの最大バイト。この長さには、ヌル終止符は含まれていません。正確な数値データ・タイプを出すには、長さとして小数部や符号も考慮されます。

表 196 も参照してください。

列 9 DECIMAL_DIGITS (SMALLINT)
列のスケール。位取りが適用できないデータ・タイプの場合は NULL が戻されます。

表 195 も参照してください。

列 10 NUM_PREC_RADIX (SMALLINT)
10、2、または NULL のどれか。 DATA_TYPE が近似値データ・タイプである場合、この列には値 2 が含まれており、 COLUMN_SIZE 列にはその列に許可されているビット数が入ります。

DATA_TYPE が正確な数値データ・タイプの場合、この列には値 10 が入り、 COLUMN_SIZE にはそのパラメーターに許可されている小数桁数が入ります。

数値データ・タイプの場合、DBMS は 10 または 2 の NUM_PREC_RADIX を戻すことができます。

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

列 11 NULLABLE (SMALLINT 非 NULL)
列が NULL を受け入れない場合は SQL_NO_NULLS。

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

列 12 REMARKS (VARCHAR(254))
列に関する記述情報を入れることができます。この列には、情報が戻されない場合があります。詳しくは、『SQL 列のキーワードと属性の最適化』を参照してください。

列 13 COLUMN_DEF (VARCHAR(254))
列の省略時値。省略時値が数値リテラルの場合、この列には単一引用符で囲まれていない数値リテラルの文字表示が含まれています。省略時値が文字ストリングの場合、この列は単一引用符で囲まれたストリングです。省略時値が DATE、TIME、および TIMESTAMP 列の場合などの疑似リテラル の場合、この列には引用符で囲まれていない疑似リテラル (CURRENT DATE など) のキーワードが入ります。

NULL を省略時値として指定した場合、この列は引用符で囲まれていない語 NULL を返します。切り捨てを行わずに省略時値を表すことができない場合、この列には単一引用符で囲まれていない TRUNCATED が含まれています。省略時値を指定しなかった場合、この列は NULL です。

この列には、情報が戻されない場合があります。詳しくは、『SQL 列のキーワードと属性の最適化』を参照してください。

列 14 SQL_DATA_TYPE (SMALLINT 非 NULL)
IRD の SQL_DESC_TYPE レコード・フィールドに現れる SQL データ・タイプ。この列は、DATA_TYPE 列と同じです。

列 15 SQL_DATETIME_SUB (SMALLINT)
日時データ・タイプのサブタイプ・コード。

他のすべてのデータ・タイプの場合、この列は NULL を戻します。

列 16 CHAR_OCTET_LENGTH (INTEGER)
文字データ・タイプ列の場合はオクテット単位の最大長が含まれています。 1 バイト文字セットの場合、これは COLUMN_SIZE と同じです。他のすべてのデータ・タイプの場合は NULL です。

列 17 ORDINAL_POSITION (INTEGER 非 NULL)
表中の列の順序を示す位置。表の最初の列は 1 です。

列 18 IS_NULLABLE (VARCHAR(254))
列がヌル可でないことがわかっている場合は文字列「NO」が含まれており、それ以外の場合は「YES」が含まれています。

注:この結果セットは X/Open CLI の Columns() 結果セット仕様と同じであり、 ODBC V2 に指定されている SQLColumns() 結果セットの拡張版です。 ODBC SQLColumns() 結果セットには、同じ位置にあるすべての列が含まれています。

戻りコード

診断


表 39. SQLColumns SQLSTATE
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 属性を使用して設定することができます。

制約

なし。

CLI サンプル tbinfo.c

(ここで完全サンプル 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);
 
 

参照


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]