SQLDescribeCol － 返回列的一组属性

用途

规范： DB2 CLI 1.1 ODBC 1.0 ISO CLI

SQLDescribeCol() 返回查询所生成的结果集中指示列的 一组常用描述符信息（列名、类型、精度、小数位和可空性）。

在调用此函数之前，必须调用 SQLPrepare() 或 SQLExecDirect()。

通常在调用绑定列函数（SQLBindCol()）之前调用此函数，以便在将一个列与应用程序变量绑定之前确定它的属性。

语法 

SQLRETURN   SQLDescribeCol   (
                  SQLHSTMT          StatementHandle,  /* hstmt */
                SQLUSMALLINT      ColumnNumber,      /* icol */
                SQLCHAR      *FAR ColumnName,        /* szColName */
                SQLSMALLINT       BufferLength,      /* cbColNameMax */
                SQLSMALLINT  *FAR NameLengthPtr,     /* pcbColName */
                SQLSMALLINT  *FAR DataTypePtr,       /* pfSqlType */
                SQLUINTEGER  *FAR ColumnSizePtr,     /* pcbColDef */
                SQLSMALLINT  *FAR DecimalDigitsPtr,  /* pibScale */
                SQLSMALLINT  *FAR NullablePtr);      /* pfNullable */

函数自变量

表 38. SQLDescribeCol 自变量

数据类型 自变量 使用 描述
SQLHSTMT StatementHandle 输入 语句句柄。
SQLUSMALLINT ColumnNumber 输入 要描述的列号。列从 1 开始按顺序从左到右编号。
SQLCHAR * ColumnName 输出 指向列名缓冲区的指针。如果不能确定列名，则此自变量设置为 NULL。
SQLSMALLINT BufferLength 输入 ColumnName 缓冲区的大小。
SQLSMALLINT * NameLengthPtr 输出 可为 ColumnName 自变量返回的字节数。如果 NameLengthPtr 大于或等于 BufferLength，则将列名 (ColumnName) 截断为 BufferLength - 1 个字节。
SQLSMALLINT * DataTypePtr 输出 列的基本 SQL 数据类型。
SQLUINTEGER * ColumnSizePtr 输出 在数据库中所定义的列精度。
SQLSMALLINT * DecimalDigitsPtr 输出 在数据库中所定义的列的小数位（仅适用于 SQL_DECIMAL）。
SQLSMALLINT * NullablePtr 输出 指示此列是否允许 NULL。下列两项中的任意一项：

SQL_NO_NULLS

SQL_NULLABLE

用法

各个列由一个号码标识，并从左到右按顺序编号，且可以任何顺序进行描述。列号从 1 开始。

如果对任何指针自变量指定空指针，则 DB2 CLI 假定应用程序不需要该信息， 且不返回任何信息。

返回码

诊断

如果 SQLDescribeCol() 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO，则通过调用 SQLError() 函数可能会获得下列其中一个 SQLSTATE。

表 39. SQLDescribeCol SQLSTATE

SQLSTATE 描述 解释
01004 数据被截断。 ColumnName 自变量中返回的列名比 BufferLength 自变量中指定的值要长。NameLengthPtr 自变量包含完整列名的长度。（函数返回 SQL_SUCCESS_WITH_INFO。）
07005 语句未返回结果集。 与 StatementHandle 相关联的语句未返回结果集。没有要描述的列。（首先调用 SQLNumResultCols() 以确定结果集中是否有任何行。）
07009 描述符索引无效 对 ColumnNumber 指定的值等于或小于 0。对 ColumnNumber 自变量指定的值大于结果集中的列数。
40003 08S01 通信链路故障。 函数尚未完成，应用程序与数据源间的通信链路就失效了。
58004 意外系统故障。 不可恢复的系统错误。
HY001 内存分配失败。 DB2 CLI 无法分配支持函数的执行或完成所需的内存。
HY002 列号无效。 对自变量 ColumnNumber 指定的值小于 1，或者对自变量 ColumnNumber 指定的值大于结果集中的列数。
HY090 字符串或缓冲区长度无效。 自变量 BufferLength 中指定的长度小于 1。
HY010 函数顺序错误。 在对 StatementHandle 调用 SQLPrepare() 或 SQLExecDirect() 之前调用了该函数。
HY013 发生意外的内存处理错误。 DB2 CLI 无法访问支持函数的执行或完成所需的内存。
HYC00 驱动程序不起作用。 DB2 CLI 不识别 ColumnNumber 列的 SQL 数据类型。

限制

DB2 Everyplace 只支持 ODBC 定义的下列数据类型：

相关参考