SQLBindCol －将列绑定至应用程序变量

用途

规范：

DB2 CLI 1.1

ODBC 1.0

ISO CLI

对于所有 C 数据类型，SQLBindCol() 用来使结果集中的列与应用程序变量相关联（绑定）。当调用 SQLFetch() 时，数据从 DBMS 被传送至应用程序。传送数据时，可能会发生数据转换。

将对结果集中应用程序需要检索的每一个列调用一次 SQLBindCol()。

通常，在调用此函数之前调用 SQLPrepare() 或 SQLExecDirect()，而在调用此函数之后调用 SQLFetch()。在调用 SQLBindCol() 之前，还可能需要列属性，可以使用 SQLDescribeCol() 来获取列属性。

语法

SQLRETURN   SQLBindCol       (SQLHSTMT          StatementHandle,   /* hstmt */
                SQLUSMALLINT      ColumnNumber,      /* icol */
                SQLSMALLINT       TargetType,        /* fCType */
                SQLPOINTER        TargetValuePtr,    /* rgbValue */
                SQLINTEGER        BufferLength,      /* cbValueMax */
                SQLINTEGER   *FAR StrLen_or_IndPtr); /* pcbValue */

函数自变量

表 32. SQLBindCol 自变量

数据类型	自变量	使用	描述
SQLHSTMT	`StatementHandle`	输入	语句句柄
SQLUSMALLINT	`ColumnNumber`	输入	标识列的数字。列按顺序从左到右编号。列号从 1 开始。
SQLSMALLINT	`TargetType`	输入	结果集中列号 `ColumnNumber` 的 C 数据类型。下列类型受支持： SQL_C_BINARY SQL_C_BIT SQL_C_CHAR SQL_C_DOUBLE SQL_C_FLOAT SQL_C_LONG SQL_C_SHORT SQL_C_TYPE_DATE SQL_C_TYPE_TIME SQL_C_TYPE_TIMESTAMP SQL_C_TINYINT 指定 SQL_C_DEFAULT 会导致将数据转换为其缺省 C 数据类型。
SQLPOINTER	`TargetValuePtr`	输入／输出（延迟）	指向发生取装时 DB2 CLI 将存储列数据的缓冲区的指针。如果 `TargetValuePtr` 为空，则取消绑定列。
SQLINTEGER	`BufferLength`	输入	可用来存储列数据的 `TargetValuePtr` 缓冲区的大小，以字节计。如果 `TargetType` 指示二进制或字符串，或是 SQL_C_DEFAULT，则 `BufferLength` 必须大于 0，不然会返回错误。否则，此自变量被忽略。
SQLINTEGER *	`StrLen_or_IndPtr`	输入／输出（延迟）	指向一个值的指针，该值指示 DB2 CLI 可以在 `TargetValuePtr` 缓冲区中返回的字节数。如果列的数据值为空，则 `SQLFetch()` 在此自变量中返回 SQL_NULL_DATA。也可能返回 SQL_NO_LENGTH。有关信息，参阅『用法』一节。

对于此函数，TargetValuePtr 和 StrLen_or_Ind 都是延迟输出，这表示在取装结果集行之前，不会更新这些指针所指向的存储位置。因此，在调用 SQLFetch() 之前，这些指针所引用的位置必须仍然有效。例如，如果在本地函数中调用 SQLBindCol()，则必须从该函数的相同作用域中调用 SQLFetch()，或者必须将 TargetValuePtr 缓冲区分配或声明为静态缓冲区或全局缓冲区。

用法

应用程序将对结果集中要检索其数据的每一列调用一次 SQLBindCol()。结果集是通过调用 SQLExecute() 或 SQLExecDirect() 生成的。当调用 SQLFetch() 时，这些绑定列的每一列中的数据将放置在指定位置（由指针 TargetValuePtr 和 StrLen_or_Ind 给定）。

各个列均由一个号码标识，此号码是从左到右按顺序指定的。列号从 1 开始。

结果集中的列数可以通过调用 SQLNumResultCols() 确定。

应用程序可以通过首先调用 SQLDescribeCol() 来查询列的属性（如数据类型和长度）。然后，可使用此信息来分配正确数据类型和长度的存储位置，以指示至另一数据类型的数据转换。

应用程序可以选择不绑定每个列，甚至不绑定任何列。在对当前行取装绑定的列之后，还可使用 SQLGetData() 来检索任何列中的数据。

在进行后续取装时，应用程序可以通过调用 SQLBindCol() 来更改这些列的绑定或绑定先前取消了绑定的列。新的绑定不适用于已取装的数据，它将在下次取装时使用。要取消绑定单个列，调用 SQLBindCol()，并将 TargetValuePtr 指针设置为 NULL。要取消绑定所有列，应用程序应调用 SQLFreeStmt()。

应用程序必须确保为要检索的数据分配足够的存储器。如果缓冲区要用来包含变长数据，则应用程序分配的存储器必须与绑定列所需的最大长度一样多，否则，数据可能会被截断。如果缓冲区要用来包含定长数据，则 DB2 CLI 假定缓冲区的大小就是 C 数据类型的长度。如果指定了数据转换，则所需的大小可能会受到影响。

如果发生字符串截断，则返回 SQL_SUCCESS_WITH_INFO，并把 StrLen_or_IndPtr 设置成可返回给应用程序的 TargetValuePtr 的实际大小。

返回码

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

诊断

表 33. SQLBindCol SQLSTATE

SQLSTATE	描述	解释
07009	描述符索引无效。	对 `ColumnNumber` 自变量指定的值超出结果集中的最大列数。
40003 08S01	通信链路错误。	函数尚未完成，应用程序与数据源间的通信链路就失效了。
58004	意外系统故障。	不可恢复的系统错误。
HY001	内存分配失败。	DB2 CLI 无法分配支持函数的执行或完成所需的内存。
HY002	列号无效。	对 `ColumnNumber` 自变量指定的值小于 0。对 `ColumnNumber` 自变量指定的值超过数据源支持的最大列数。
HY003	程序类型超出范围。	`TargetType` 不是有效的数据类型或 SQL_C_DEFAULT。
HY013	发生意外的内存处理错误。	DB2 CLI 无法访问支持函数的执行或完成所需的内存。
HY090	字符串或缓冲区长度无效。	对 `BufferLength` 自变量指定的值小于 1，而 `TargetType` 自变量是 SQL_C_CHAR、SQL_C_BINARY 或 SQL_C_DEFAULT。
HYC00	驱动程序不起作用。	DB2 CLI 识别但不支持 `TargetType` 自变量中指定的数据类型。

取装时可能会报告与绑定列相关的其它诊断消息。

限制

输出缓冲区需要字对齐（平行）。许多处理器（如 Motorola 68000）有字对齐的规则，对于非字符数据类型，应用程序应正确地将缓冲区对齐。

相关参考

SQLBindCol － 将列绑定至应用程序变量

SQLBindCol －将列绑定至应用程序变量