SQLGetData －从列中获取数据

用途

规范：

DB2 CLI 1.1

ODBC 1.0

ISO CLI

SQLGetData() 在结果集的当前行中检索单一列的数据。这是 SQLBindCol() 的替代函数，用来在进行每个 SQLFetch() 调用时将数据直接传送到应用程序变量中。

必须在调用 SQLGetData() 之前调用 SQLFetch()。

在对每个需要的列调用 SQLGetData() 之后，调用 SQLFetch() 来检索下一行。

语法

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

函数自变量

表 66. SQLGetData 自变量

数据类型	自变量	使用	描述
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`	输出	指向存储所检索到列数据的缓冲区的指针。输出缓冲区需要字对齐（平行）。许多处理器（如 Motorola 68000）有字对齐的规则，对于非字符数据类型，应用程序应正确地将缓冲区对齐。
SQLINTEGER	`BufferLength`	输入	`TargetValuePtr` 指向的缓冲区的最大大小。如果 TargetType 指示二进制或字符串，则 BufferLength 必须大于 0，不然会返回错误。否则，此自变量被忽略。
SQLINTEGER *	`StrLen_or_IndPtr`	输出	指向一个值的指针，该值指示 DB2 CLI 可以在 `TargetValuePtr` 缓冲区中返回的字节数。如果发生数据截断的情况，它会包含检索整列所需的总字节数。对于二进制和字符数据类型，应用程序可选择逐块检索方式来一段一段地检索庞大数据。在此方式下，`StrLen_or_IndPtr` 自变量包含列中余下的字节数。如果列的数据值为空，则值是 SQL_NULL_DATA。如果此指针是 NULL，而 `SQLFetch()` 获取到包含空数据的列，则此函数会失败，原因是没有办法报告这种情况。如果 `SQLFetch()` 取装到包含二进制数据的列，则指向 `StrLen_or_IndPtr` 的指针不得是 NULL，否则此函数会失败，原因是它没有其它办法通知应用程序在 `TargetValuePtr` 缓冲区中检索到的数据的长度。

用法

如果使用 SQLFetch()，则可以对同一结果集配合使用 SQLGetData() 和 SQLBindCol()。一般的步骤是：

SQLFetch() 进至第一行，检索该第一行，并传送绑定列的数据。
SQLGetData() 传送指定列的数据。
SQLGetData() 对所需的每个列重复步骤 2。
SQLFetch() 进至下一行，检索该下一行，并传送绑定列的数据。
对结果集中的每一行重复步骤 2、3 和 4，或者重复至不再需要该结果集为止。

要废弃通过检索所得的列数据部分，应用程序可以调用 SQLGetData()，并将 ColumnNumber 设置为感兴趣的下一个列位置。要废弃尚未对整行检索的数据，应用程序应调用 SQLFetch() 来进至下一行；或者，如果不再需要结果集中的数据，则调用 SQLFreeStmt()。

TargetType 输入自变量确定在将列数据放入由 TargetValuePtr 指向的存储区之前所需的数据转换（如果有的话）的类型。

除非要检索的列数据是二进制数据，否则 TargetValuePtr 中返回的值以空结束。

截断数字数据类型时，如果截断小数点右面的位，则会将此截断报告为警告。如果截断在小数点左边发生，则会返回错误。

返回码

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE
SQL_NO_DATA_FOUND

如果 SQLGetData() 检索到长度为零的字符串，则返回 SQL_SUCCESS。如果出现这种情况，则 StrLen_or_IndPtr 包含 0，TargetValuePtr 包含 null 终止符。

如果先前的 SQLFetch() 调用失败，则不要调用 SQLGetData()，原因是未定义结果。

诊断

表 67. SQLGetData SQLSTATE

SQLSTATE	描述	解释
01004	数据被截断。	对指定列（`ColumnNumber`）返回的数据被截断。字符串或数值在右端被截断。返回 SQL_SUCCESS_WITH_INFO。
07006	转换无效。	不能将数据值转换为自变量 `TargetType` 指定的 C 数据类型。先前对同一 `ColumnNumber` 值调用了此函数，但 `TargetType` 值不同。
22002	指定的输出或指示符缓冲区无效。	对 `StrLen_or_IndPtr` 自变量指定的指针值是空指针，列的值为空。报告 SQL_NULL_DATA 是没有意义的。
22005	赋值出错。	返回值与 `TargetType` 自变量指示的数据类型不兼容。
40003 08S01	通信链路故障。	函数尚未完成，应用程序与数据源间的通信链路就失效了。
58004	意外系统故障。	不可恢复的系统错误。
HY001	内存分配失败。	DB2 CLI 无法分配支持函数的执行或完成所需的内存。
HY002	列号无效。	指定的列小于 0 或大于结果列的数目。
HY003	程序类型超出范围。	`TargetType` 不是有效的数据类型或 SQL_C_DEFAULT。
HY010	函数顺序错误。	调用该函数之前未首先调用 `SQLFetch()`。
HY013	发生意外的内存处理错误。	DB2 CLI 无法访问支持函数的执行或完成所需的内存。
HY090	字符串或缓冲区长度无效。	`BufferLength` 自变量的值小于 0，`TargetType` 自变量是 SQL_C_CHAR 或 SQL_C_BINARY，或者 `TargetType` 是 SQL_C_DEFAULT，而缺省类型是 SQL_C_CHAR、SQL_C_BINARY 或 SQL_C_DBCHAR 之一。
HYC00	驱动程序不起作用。	DB2 CLI 识别但不支持指定数据类型的 SQL 数据类型。 DB2 CLI 或数据源不能执行所请求的从 SQL 数据类型到应用程序数据 `TargetType` 的转换。

限制

无。

相关参考

SQLGetData － 从列中获取数据

SQLGetData －从列中获取数据