| 规范： | DB2 CLI 1.1 | ODBC 1.0 |
|
SQLFetch() 使游标进至结果集的下一行，并检索任何绑定的列。
列可以与应用程序存储器绑定。
当调用 SQLFetch() 时，会执行适当的数据传输和任何数据转换（如果绑定列时指示了转换的话）。在取装之后，还可以通过调用 SQLGetData() 分别地接收到列。
仅当通过执行查询生成了结果集之后（使用同一语句句柄），才能调用 SQLFetch()。
语法
SQLRETURN SQLFetch (SQLHSTMT StatementHandle); /* hstmt */
函数自变量
| 数据类型 | 自变量 | 使用 | 描述 |
|---|---|---|---|
| SQLHSTMT | StatementHandle | 输入 | 语句句柄。 |
用法
仅当对同一语句句柄生成了结果集之后，才能调用 SQLFetch()。在首次调用 SQLFetch() 之前，游标定位在结果集开头的前面。
与 SQLBindCol() 绑定的应用程序变量的数目不得超过结果集中的列数，否则 SQLFetch() 会失败。
如果未调用 SQLBindCol() 来绑定任何列，则 SQLFetch() 不将任何数据返回至应用程序，而是仅仅使游标前进。在这种情况下，可以调用 SQLGetData() 来分别获取所有的列。当 SQLFetch() 时游标进至下一行时，未绑定列中的数据被废弃。
列可以与应用程序存储器绑定。SQLBindCol() 用来将应用程序存储器绑定至列。在取装时，会将数据从数据库传送至应用程序。还会设置要返回的可用数据的长度。
如果任何绑定的存储器缓冲区不够大，无法存放 SQLFetch() 返回的数据，则会截断该数据将。如果字符数据被截断，则返回 SQL_SUCCESS_WITH_INFO，且生成指示此截断的 SQLSTATE。SQLBindCol() 延迟输出自变量 pcbValue 包含从服务器检索的列数据的实际长度。 应用程序应将实际输出长度与输入缓冲区长度（来自 SQLBindCol() 的 pcbValue 和 cbValueMax 自变量）作比较，以确定截断了哪些字符列。
截断数字数据类型时，如果截断小数点右面的位，则会将此截断报告为警告。如果截断在小数点左边发生，则会返回错误（参阅『诊断』一节）。
在从结果集中检索了所有行，或者不需要剩余的行时，调用 SQLFreeStmt() 来关闭游标并废弃剩余的数据和相关联的资源。
DB2 Everyplace 每次至多取装一行，而不是使用行集。DB2 Everyplace 不支持语句描述符。
SQLFetch() 确定应用程序是否指定了单独的长度和指示符缓冲区。在这种情况下，当数据不是 NULL 时，SQLFetch() 将指示符缓冲区设置为 0，并在长度缓冲区中返回长度。当数据为 NULL 时，SQLFetch() 将指示符缓冲区设置为 SQL_NULL_DATA，而不修改长度缓冲区。
定位游标
当创建结果集时，游标定位在结果集开头的前面。SQLFetch() 取装下一行。
返回码
如果结果集中没有任何行，或先前的 SQLFetch() 调用已从结果集中取装了所有的行，则返回 SQL_NO_DATA_FOUND。
如果已取装所有的行，则游标定位在结果集末尾之后。
诊断
| SQLSTATE | 描述 | 解释 |
|---|---|---|
| 01004 | 数据被截断。 | 对一个或多个列返回的数据被截断。字符串值或数值在右端被截断。（如果不出错，则返回 SQL_SUCCESS_WITH_INFO。） |
| 07006 | 转换无效。 | 未能将数据值以有意义的方式转换为 SQLBindCol() 中的 fCType 所指定的数据类型。 |
| 22002 | 指定的输出或指示符缓冲区无效。 | 对 SQLBindCol() 中 pcbValue 自变量指定的指针值是空指针，且相应列的值为空。报告 SQL_NULL_DATA 是没有意义的。 |
| 58004 | 意外系统故障。 | 不可恢复的系统错误。 |
| HY001 | 内存分配失败。 | DB2 CLI 无法分配支持函数的执行或完成所需的内存。 |
| HY010 | 函数顺序错误。 | 在对 StatementHandle 调用 SQLPrepare() 或 SQLExecDirect() 之前调用了该函数。 |
| HY013 | 发生意外的内存处理错误。 | DB2 CLI 无法访问支持函数的执行或完成所需的内存。 |
限制
无。
相关参考