| 规范： | DB2 CLI 5.0 | ODBC 3.0 |
|
SQLFetchScroll() 从结果集取装指定的数据行集，并返回所有已绑定列的数据。可以使用绝对位置或相对位置指定行集。
语法
SQLRETURN SQLFetchScroll (
SQLHSTMT StatementHandle,
SQLSMALLINT FetchOrientation,
SQLINTEGER FetchOffset);
函数自变量
| 数据类型 | 自变量 | 使用 | 描述 |
|---|---|---|---|
| SQLHSTMT | StatementHandle | 输入 | 语句句柄 |
| SQLSMALLINT | FetchOrientation | 输入 | 取装类型：
|
| SQLINTEGER | FetchOffset | 输入 | 要取装的行数。此自变量的解释取决于 FetchOrientation 自变量的值。 |
用法
SQLFetchScroll() 从结果集返回指定的行集。可用绝对位置或相对位置指定行集。仅当结果集存在时，才能调用 SQLFetchScroll() － 即， 在创建结果集的调用之后，而在该结果集上的游标关闭之前，才能调用。如果绑定了任何列，则返回这些列中的数据。如果应用程序指定了指向行状态数组或要在其中返回所取装行数的缓冲区的指针，则 SQLFetchScroll() 还返回此信息。对 SQLFetchScroll() 调用可以与对 SQLFetch() 调用混合在一起。
定位游标
当创建结果集时，游标定位在结果集开头的前面。SQLFetchScroll() 根据 FetchOrientation 和 FetchOffset 自变量的值定位块游标，如以下列表所示。确定新行集开头的精确规则在下一节中说明。
SQL_ATTR_ROW_ARRAY_SIZE 语句属性指定行集中的行数。如果 SQLFetchScroll() 取装的行集与结果集的末尾重叠，则 SQLFetchScroll() 返回部分行集。也就是说，如果 S + R - 1 大于 L，其中 S 是正在取装的行集的起始行，R 是行集大小，而 L 是结果集中的最后一行，则只有行集的前 L - S + 1 行有效。其余各行是空的，状态为 SQL_ROW_NOROW。
SQLFetchScroll() 返回后，行集游标定位在结果集的第一行。
游标定位规则
下列各节描述 FetchOrientation 的每个值的精确规则。这些规则使用下列表示法：
SQL_FETCH_NEXT 规则
| 条件 | 新行集的第一行 |
|---|---|
| Before start | 1 |
| CurrRowsetStart + RowsetSize <= LastResultRow | CurrRowsetStart + RowsetSize |
| CurrRowsetStart + RowsetSize > LastResultRow | 在末尾之后 |
| After end | 在末尾之后 |
SQL_FETCH_PRIOR 规则
| 条件 | 新行集的第一行 |
|---|---|
| Before start | 在起始点之前 |
| CurrRowsetStart = 1 | 在起始点之前 |
| 1 < CurrRowsetStart <= RowsetSize | 1a |
| CurrRowsetStart > RowsetSize | CurrRowsetStart - RowsetSize |
| After end AND LastResultRow < RowsetSize | 1a |
| After end AND LastResultRow >= RowsetSize | LastResult - RowRowsetSize + 1 |
SQL_FETCH_RELATIVE 规则
| 条件 | 新行集的第一行 |
|---|---|
| (Before start AND FetchOffset > 0) OR (After end AND FetchOffset < 0) | --a |
| Before start AND FetchOffset <= 0 | 在起始点之前 |
| CurrRowsetStart = 1 AND FetchOffset < 0 | 在起始点之前 |
| CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND |FetchOffset| > RowsetSize | 在起始点之前 |
| CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND |FetchOffset| <= RowsetSize | 1b |
| 1 <= CurrRowsetStart + FetchOffset <= LastResultRow | CurrRowsetStart + FetchOffset |
| CurrRowsetStart + FetchOffset > LastResultRow | 在末尾之后 |
| After end AND FetchOffset >= 0 | 在末尾之后 |
SQL_FETCH_ABSOLUTE 规则
| 条件 | 新行集的第一行 |
|---|---|
| FetchOffset < 0 AND |FetchOffset| <= LastResultRow | LastResultRow + FetchOffset + 1 |
| FetchOffset < 0 AND |FetchOffset| > LastResultRow AND |FetchOffset| > RowsetSize | 在起始点之前 |
| FetchOffset < 0 AND |FetchOffset| > LastResultRow AND |FetchOffset| <= RowsetSize | 1a |
| FetchOffset = 0 | 在起始点之前 |
| 1 <= FetchOffset <= LastResultRow | FetchOffset |
| FetchOffset > LastResultRow | 在末尾之后 |
SQL_FETCH_FIRST 规则
| 条件 | 新行集的第一行 |
|---|---|
| 任何 | 1 |
SQL_FETCH_LAST 规则
| 条件 | 新行集的第一行 |
|---|---|
| RowsetSize <= LastResultRow | LastResultRow - RowsetSize + 1 |
| RowsetSize > LastResultRow | 1 |
返回绑定列中的数据
SQLFetchScroll() 返回绑定列中数据的方式与 SQLFetch() 相同。有关更多信息，请参阅SQLFetch － 取装下一行。
如果未绑定任何列，则 SQLFetchScroll() 不返回数据，但将块游标移至指定的位置。对于 SQLFetch()，在这种情况下可以使用 SQLGetData() 来检索信息。
缓冲区地址
SQLFetchScroll() 使用 SQLFetch() 所使用的公式来确定数据的地址和长度／指示符缓冲区。有关更多信息，请参阅SQLBindCol － 将列绑定至应用程序变量。
行状态数组
行状态数组用来返回行集中每一行的状态。此数组的地址使用 SQL_ATTR_ROW_STATUS_PTR 语句属性指定。此数组由应用程序分配，且必须具有 SQL_ATTR_ROW_ARRAY_SIZE 语句属性所指定的元素数目。它的值由 SQLFetch() 和 SQLFetchScroll() 设置。如果 SQL_ATTR_ROW_STATUS_PTR 语句属性的值是空指针，则这些函数不返回行状态。
如果 SQLFetch() 或 SQLFetchScroll() 未返回 SQL_SUCCESS 或 SQL_SUCCESS_WITH_INFO，则行状态数组缓冲区的内容未定义。
下列值在行状态数组中返回。
“取装的行”缓冲区
“取装的行”缓冲区用来返回取装的行数，包括那些因为在取装行时出错而未返回数据的行。这是在行状态数组中其值不是 SQL_ROW_NOROW 的那些行的数目。此缓冲区的地址使用 SQL_ATTR_ROWS_FETCHED_PTR 语句属性指定。此缓冲区由应用程序分配。它由 SQLFetch() 和 SQLFetchScroll() 设置。如果 SQL_ATTR_ROWS_FETCHED_PTR 语句属性的值是空指针，则这些函数不返回取装的行数。要确定结果集中的当前行数，应用程序可以调用 SQLGetStmtAttr()，并指定 SQL_ATTR_ROW_NUMBER 属性。
如果 SQLFetch() 或 SQLFetchScroll() 未返回 SQL_SUCCESS 或 SQL_SUCCESS_WITH_INFO，则“取装的行”缓冲区的内容未定义，返回 SQL_NO_DATA 时是一个例外，在这种情况下，“取装的行”缓冲区中的值设置为 0。
返回码
诊断
| SQLSTATE | 描述 | 解释 |
|---|---|---|
| 01000 | 警告 | 参考消息。（函数返回 SQL_SUCCESS_WITH_INFO。） |
| 01004 | 数据被截断。 | 对一个或多个列返回的数据被截断。字符串值或数值在右端被截断。（如果不出错，则返回 SQL_SUCCESS_WITH_INFO。） |
| 01S06 | 试图在结果集返回第一个行集之前进行取装。 | 在当前位置在第一行之外，且 FetchOrientation 是 SQL_PRIOR，或 FetchOrientation 是 SQL_RELATIVE，而 FetchOffset 是负数时（其绝对值小于或等于当前 SQL_ATTR_ROW_ARRAY_SIZE），则请求的行集与结果集的起始点重叠。（函数返回 SQL_SUCCESS_WITH_INFO。） |
| 07006 | 转换无效。 | 未能将数据值以有意义的方式转换为 SQLBindCol() 中的 fCType 所指定的数据类型。 |
| 22002 | 指定的输出或指示符缓冲区无效。 | 对 SQLBindCol() 中 pcbValue 自变量指定的指针值是空指针，且相应列的值为空。报告 SQL_NULL_DATA 是没有意义的。 |
| 22003 | 数值超出范围。 | 对一个或多个绑定列返回数字值 （作为数字或字符串）会导致数字的整个部分（并非分数部分）被截断。 |
| 24000 | 游标状态无效。 | StatementHandle 处于已执行状态，但没有任何结果集与 StatementHandle 相关联。 |
| HY000 | 一般错误。 | 出错，该错误没有特定的 SQLSTATE。*MessageText 缓冲区中由 SQLGetDiagRec() 返回的错误消息描述该错误及其原因。 |
| HY001 | 内存分配失败。 | DB2 CLI 无法分配支持函数的执行或完成所需的内存。 |
| HY010 | 函数顺序错误。 | 在对 StatementHandle 调用 SQLPrepare() 或 SQLExecDirect() 之前调用了该函数。 |
| HY106 | 取装类型超出范围。 | 对自变量 FetchOrientation
指定的值无效。
SQL_CURSOR_TYPE 语句属性的值是 SQL_CURSOR_FORWARD_ONLY，而 FetchOrientation 自变量的值不是 SQL_FETCH_NEXT。 |
| HY107 | 行值超出范围。 | 用 SQL_ATTR_CURSOR_TYPE 语句属性指定的值是 SQL_CURSOR_KEYSET_DRIVEN，但用 SQL_ATTR_KEYSET_SIZE 语句属性指定的值大于 0 且小于用 SQL_ATTR_ROW_ARRAY_SIZE 语句属性指定的值。 |
限制
无。
相关参考