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 自变量

用法

将调用此函数以检索有关一个表或一组表的列的信息。典型应用程序可能希望在调用 SQLTables() 后调用此函数以确定表的各列。应用程序应使用 SQLTables() 结果集的 TABLE_NAME 中返回的字符串作为此函数的输入。

SQLColumns() 返回标准结果集，按 TABLE_NAME 和 ORDINAL_POSITION 排序。*** 列示结果集中的各列。

TableName 和 ColumnName 自变量将接受搜索模式。

此函数不返回有关结果集中的各列的信息。应使用 SQLDescribeCol() 或 SQLColAttribute() 代替。

最好不要经常调用 SQLColumns()，原因是在许多情况下它们都映射至对系统目录的复杂且高成本的查询。应保存结果而不是重复调用。

已使用最大长度属性 128 声明目录函数结果集的 VARCHAR 列，以便与 SQL92 限制一致。因为 DB2 名称少于 128 个字符，所以应用程序可选择总是为输出缓冲区保留 128 个字符（加上 null 终止符），或者使用 SQL_MAX_TABLE_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) not NULL)

表名。

第 4 列 COLUMN_NAME (VARCHAR(128) not NULL)

列标识。指定表、视图、别名或同义词的列的名称。

第 5 列 DATA_TYPE (SMALLINT not NULL)

由 COLUMN_NAME 标识的列的 SQL 数据类型。这是SQL 符号和缺省数据类型中的“符号 SQL 数据类型”列的值之一。

第 6 列 TYPE_NAME (VARCHAR(128) not NULL)

表示与 DATA_TYPE 对应的数据类型的名称的字符串。

第 7 列 COLUMN_SIZE (INTEGER)

如果 DATA_TYPE 列值表示字符或二进制字符串，则此列包含该列的最大长度（以字符计）。

对于 DATE、TIME 或 TIMESTAMP 数据类型，这是在转换为字符时显示该值所需的总字符数。

对于数字数据类型，这是该列中允许的总位数。

另请参阅数据类型属性。

第 8 列 BUFFER_LENGTH (INTEGER)

如果在 SQLBindCol()、SQLGetData() 和 SQLBindParameter() 调用上指定了 SQL_C_DEFAULT，则为要存储此列中的数据的相关 C 缓冲区的最大字节数。此长度不包括任何 null 终止符。对于确切数字数据类型，在长度上需要考虑小数点和符号。另请参阅数据类型属性

第 9 列 DECIMAL_DIGITS (SMALLINT)

列的小数位。对于小数位不适用的数据类型，将返回 NULL。另请参阅数据类型属性

第 10 列 NUM_PREC_RADIX (SMALLINT)

10 或 NULL。

如果 DATA_TYPE 是确切的数字数据类型，则此列包含值 10， 而 COLUMN_SIZE 包含该列允许的小数位数。

对于数字数据类型，DBMS 返回 NUM_PREC_RADIX 为 10。

对于基不适用的数据类型，将返回 NULL。

第 11 列 NULLABLE (SMALLINT not NULL)

如果该列不接受 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 not NULL)

此列与 DATA_TYPE 列相同。

第 15 列 SQL_DATETIME_SUB (SMALLINT)

此列始终是 NULL。

第 16 列 CHAR_OCTET_LENGTH (INTEGER)

包含字符数据类型列的最大长度（以八位字节计）。 对于“单字节”字符集，它与 COLUMN_SIZE 相同。对于所有其它数据类型，它为 NULL。

第 17 列 ORDINAL_POSITION (INTEGER not NULL)

列在表中的顺序位置。表中的第一列编号为 1。

第 18 列 IS_NULLABLE (VARCHAR(254))

如果该列已知是不可空的，则包含字符串“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 － 获取表信息