SQLFetchScroll Function（SQLFetchScroll 函数）
一致性
引入的版本：ODBC 3.0 标准符合性：ISO 92
总结
SQLFetchScroll 从结果集中提取指定的数据行集，并返回所有绑定列的数据。 行集可以在绝对位置或相对位置或通过书签指定。
使用 ODBC 2.x 驱动程序时，驱动程序管理器将此函数映射到 SQLExtendedFetch。 有关详细信息，请参阅 映射替换函数以实现应用程序的向后兼容性。
语法
SQLRETURN SQLFetchScroll(
SQLHSTMT StatementHandle,
SQLSMALLINT FetchOrientation,
SQLLEN FetchOffset);
参数
StatementHandle
[输入]语句句柄。
FetchOrientation
[输入]
提取类型：
SQL_FETCH_NEXT
SQL_FETCH_PRIOR
SQL_FETCH_FIRST
SQL_FETCH_LAST
SQL_FETCH_ABSOLUTE
SQL_FETCH_RELATIVE
SQL_FETCH_BOOKMARK
有关详细信息，请参阅“注释”部分中的“定位光标”。
FetchOffset
[输入]
要提取的行数。 此参数的解释取决于 FetchOrientation 参数的值。 有关详细信息，请参阅“注释”部分中的“定位光标”。
返回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
诊断
当 SQLFetchScroll 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过使用 handleType of SQL_HANDLE_STMT 和 StatementHandle 句柄调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。 下表列出了 SQLFetchScroll 通常返回的 SQLSTATE 值，并解释此函数上下文中的每个值;表示法“（DM）”位于驱动程序管理器返回的 SQLSTATE 的说明之前。 除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。 如果在单个列中发生错误， 则可以使用SQL_DIAG_COLUMN_NUMBER的 DiagIdentifier 调用 SQLGetDiagField 以确定发生错误的列; 可以使用SQL_DIAG_ROW_NUMBER的 DiagIdentifier 调用 SQLGetDiagField 以确定包含该列的行。
对于可以返回SQL_SUCCESS_WITH_INFO或SQL_ERROR（01xxx SQLSTATEs 除外）的所有 SQLSTATE，如果一个或多个操作（但不是全部）发生错误，则返回SQL_SUCCESS_WITH_INFO;如果单行操作发生错误，则返回SQL_ERROR。
| SQLSTATE | 错误 | 说明 |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 （函数返回SQL_SUCCESS_WITH_INFO。） |
| 01004 | 字符串数据，右截断 | 为列返回的字符串或二进制数据导致非空字符或非 NULL 二进制数据的截断。 如果它是字符串值，则将其右截断。 |
| 01S01 | 行中的错误 | 提取一行或多行时出错。 （如果 ODBC 3*.x* 应用程序使用 ODBC 2*.x* 驱动程序时返回此 SQLSTATE，则可以忽略它。 |
| 01S06 | 在结果集返回第一个行集之前尝试提取 | 当 FetchOrientation SQL_FETCH_PRIOR时，请求的行集与结果集的开始重叠，当前位置超出第一行，当前行的数目小于或等于行集大小。 当 FetchOrientation SQL_FETCH_PRIOR时，请求的行集与结果集的开始重叠，当前位置超出结果集的末尾，行集大小大于结果集大小。 当 FetchOrientation SQL_FETCH_RELATIVE，FetchOffset 为负时，请求的行集与结果集的开始重叠，FetchOffset 的绝对值小于或等于行集大小。 当 FetchOrientation SQL_FETCH_ABSOLUTE、FetchOffset 为负时，请求的行集与结果集的开始重叠，FetchOffset 的绝对值大于结果集大小，但小于或等于行集大小。 （函数返回SQL_SUCCESS_WITH_INFO。） |
| 01S07 | 小数截断 | 为列返回的数据被截断。 对于数值数据类型，数字的小数部分被截断。 对于包含时间分量的时间、时间戳和间隔数据类型，时间的小数部分被截断。 （函数返回SQL_SUCCESS_WITH_INFO。） |
| 07006 | 受限数据类型属性冲突 | 结果集中列的数据值无法转换为 SQLBindCol 中 TargetType 指定的数据类型。 列 0 与数据类型SQL_C_BOOKMARK绑定，SQL_ATTR_USE_BOOKMARKS语句属性设置为SQL_UB_VARIABLE。 列 0 与数据类型SQL_C_VARBOOKMARK绑定，并且SQL_ATTR_USE_BOOKMARKS语句属性未设置为SQL_UB_VARIABLE。 |
| 07009 | 描述符索引无效 | 驱动程序是不支持 SQLExtendedFetch 的 ODBC 2*.x* 驱动程序，在绑定中指定的列号为 0。 列 0 已绑定，SQL_ATTR_USE_BOOKMARKS语句属性设置为SQL_UB_OFF。 |
| 08S01 | 通信链接失败 | 驱动程序与驱动程序连接到的数据源之间的通信链接在函数完成处理之前失败。 |
| 22001 | 字符串数据，右截断 | 已截断为列返回的可变长度书签。 |
| 22002 | 指示符变量是必需的，但未提供 | NULL 数据被提取到 SQLBindCol 设置StrLen_or_IndPtr列（或 SQLSetDescField 或 SQLSetDescRec 设置的SQL_DESC_INDICATOR_PTR）是空指针。 |
| 22003 | 数值范围之外 | 返回一个或多个绑定列的数值（作为数字或字符串），会导致截断数字的整个（而不是小数部分）。 有关详细信息，请参阅附录 D：数据类型中的将数据从 SQL 转换为 C 数据类型。 |
| 22007 | 日期/时间格式无效 | 结果集中的字符列绑定到日期、时间或时间戳 C 结构，并且列中的值分别是无效的日期、时间或时间戳。 |
| 22012 | 被零除 | 返回算术表达式中的值，这导致除以零。 |
| 22015 | 间隔字段溢出 | 从确切的数字或间隔 SQL 类型分配给间隔 C 类型会导致前导字段中的有效数字丢失。 将数据提取到间隔 C 类型时，间隔 C 类型中没有 SQL 类型的值表示形式。 |
| 22018 | 强制转换规范的字符值无效 | 结果集中的字符列绑定到字符 C 缓冲区，并且该列包含一个字符，该字符集在缓冲区的字符集中没有表示形式。 C 类型是精确或近似数字、日期/时间或间隔数据类型;列的 SQL 类型是字符数据类型;列中的值不是绑定 C 类型的有效文本。 |
| 24000 | 游标状态无效 | StatementHandle 处于执行状态，但没有结果集与 StatementHandle 相关联。 |
| 40001 | 序列化失败 | 执行提取的事务已终止，以防止死锁。 |
| 40003 | 语句完成未知 | 执行此函数期间关联的连接失败，无法确定事务的状态。 |
| HY000 | 常规错误 | 发生错误：没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述错误及其原因。 |
| HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY008 | 操作已取消 | 为 StatementHandle 启用了异步处理。 调用了该函数，在完成执行之前，对 StatementHandle 调用了 SQLCancel 或 SQLCancelHandle。 然后，在 StatementHandle 上再次调用该函数。 调用了函数，在完成执行之前，SQLCancel 或 SQLCancelHandle 从多线程应用程序中的不同线程调用 StatementHandle。 |
| HY010 | 函数序列错误 | （DM） 为与 StatementHandle 关联的连接句柄调用异步执行函数。 调用 SQLFetchScroll 函数时，此异步函数仍在执行。 （DM） 为 StatementHandle 调用了 SQLExecute、SQLExecDirect 或 SQLMoreResults，并返回了SQL_PARAM_DATA_AVAILABLE。 在检索所有流式处理参数的数据之前调用此函数。 （DM） 指定的 StatementHandle 未处于执行状态。 在未首先调用 SQLExecDirect、SQLExecute 或目录函数的情况下调用该函数。 （DM） 为 StatementHandle 调用异步执行函数（而不是此函数），并在调用此函数时仍在执行。 （DM） 为 StatementHandle 调用了 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos，并返回了SQL_NEED_DATA。 在为所有数据执行参数或列发送数据之前调用此函数。 （DM） 在调用 SQLExtendedFetch 并调用 sqlFreeStmt 和调用 SQL_CLOSE 选项之前，为 StatementHandle 调用 SQLFetch。 |
| HY013 | 内存管理错误 | 无法处理函数调用，因为基础内存对象无法访问，可能是因为内存条件低。 |
| HY090 | 字符串或缓冲区长度无效 | SQL_ATTR_USE_BOOKMARK语句属性设置为SQL_UB_VARIABLE，列 0 绑定到长度不等于此结果集书签的最大长度的缓冲区。 （此长度在 IRD 的SQL_DESC_OCTET_LENGTH字段中可用，可通过调用 获取SQLDescribeCol、 SQLColAttribute 或 SQLGetDescField。） |
| HY106 | 从范围中提取类型 | DM） 为参数 FetchOrientation 指定的值无效。 （DM） 参数 FetchOrientation 已SQL_FETCH_BOOKMARK，SQL_ATTR_USE_BOOKMARKS语句属性设置为SQL_UB_OFF。 SQL_ATTR_CURSOR_TYPE语句属性的值SQL_CURSOR_FORWARD_ONLY，参数 FetchOrientation 的值未SQL_FETCH_NEXT。 SQL_ATTR_CURSOR_SCROLLABLE语句属性的值SQL_NONSCROLLABLE，参数 FetchOrientation 的值未SQL_FETCH_NEXT。 |
| HY107 | 行值范围外 | 使用 SQL_ATTR_CURSOR_TYPE 语句属性指定的值SQL_CURSOR_KEYSET_DRIVEN，但使用 SQL_ATTR_KEYSET_SIZE 语句属性指定的值大于 0，小于使用 SQL_ATTR_ROW_ARRAY_SIZE 语句属性指定的值。 |
| HY111 | 书签值无效 | 参数 FetchOrientation SQL_FETCH_BOOKMARK，SQL_ATTR_FETCH_BOOKMARK_PTR 语句属性中的值指向的书签无效或为 null 指针。 |
| HY117 | 连接因未知事务状态而挂起。 仅允许断开连接和只读函数。 | （DM） 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。 |
| HYC00 | 未实现可选功能 | 驱动程序或数据源不支持由 SQLBindCol 中 TargetType 和相应列的 SQL 数据类型组合指定的转换。 |
| HYT00 | 已超时 | 在数据源返回请求的结果集之前，查询超时期限已过期。 超时期限通过 SQLSetStmtAttr 设置，SQL_ATTR_QUERY_TIMEOUT。 |
| HYT01 | 超过连接超时时间 | 在数据源响应请求之前，连接超时期限已过期。 连接超时期限通过 SQLSetConnectAttr 设置，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驱动程序不支持此函数 | （DM） 与 StatementHandle 关联的驱动程序不支持该函数。 |
| IM017 | 在异步通知模式下禁用轮询 | 每当使用通知模型时，轮询将被禁用。 |
| IM018 | 尚未调用 SQLCompleteAsync 来完成此句柄上的上一个异步操作。 | 如果句柄上的上一个函数调用返回SQL_STILL_EXECUTING并且启用通知模式， 则必须在句柄上调用 SQLCompleteAsync 才能执行后期处理并完成操作。 |
评论
SQLFetchScroll 从结果集中返回指定的行集。 行集可以按绝对位置或相对位置或书签指定。 只有在结果集存在时才能调用 SQLFetchScroll ，即在创建结果集的调用之后，以及关闭该结果集上的游标之前。 如果绑定了任何列，它将返回这些列中的数据。 如果应用程序已指定指向行状态数组的指针或要在其中返回提取的行数的缓冲区， SQLFetchScroll 也会返回此信息。 对 SQLFetchScroll 的调用可与对 SQLFetch 的调用混合，但不能与对 SQLExtendedFetch 的调用混合。
定位光标
创建结果集后，光标将定位在结果集的开头。 SQLFetchScroll 根据 FetchOrientation 和 FetchOffset 参数的值定位块游标，如下表所示。 下一部分显示了用于确定新行集开始的确切规则。
| FetchOrientation | 含义 |
|---|---|
| SQL_FETCH_NEXT | 返回下一行集。 这相当于调用 SQLFetch。 SQLFetchScroll 忽略 FetchOffset 的值。 |
| SQL_FETCH_PRIOR | 返回前面的行集。 SQLFetchScroll 忽略 FetchOffset 的值。 |
| SQL_FETCH_RELATIVE | 从当前行集的开头返回行集 FetchOffset 。 |
| SQL_FETCH_ABSOLUTE | 返回从行 FetchOffset 开始的行 集。 |
| SQL_FETCH_FIRST | 返回结果集中的第一个行集。 SQLFetchScroll 忽略 FetchOffset 的值。 |
| SQL_FETCH_LAST | 返回结果集中的最后一个完整行集。 SQLFetchScroll 忽略 FetchOffset 的值。 |
| SQL_FETCH_BOOKMARK | 从SQL_ATTR_FETCH_BOOKMARK_PTR语句属性指定的书签中返回行集 FetchOffset 行。 |
驱动程序不需要支持所有提取方向;应用程序使用信息类型SQL_DYNAMIC_CURSOR_ATTRIBUTES1、SQL_KEYSET_CURSOR_ATTRIBUTES1或SQL_STATIC_CURSOR_ATTRIBUTES1（具体取决于游标的类型）调用 SQLGetInfo ，以确定驱动程序支持哪些提取方向。 应用程序应查看这些信息类型中的SQL_CA1_NEXT、SQL_CA1_RELATIVE、SQL_CA1_ABSOLUTE和WQL_CA1_BOOKMARK位掩码。 此外，如果游标仅向前且 FetchOrientation 不SQL_FETCH_NEXT， 则 SQLFetchScroll 将返回 SQLSTATE HY106（提取范围外的类型）。
SQL_ATTR_ROW_ARRAY_SIZE语句属性指定行集中的行数。 如果 SQLFetchScroll 提取的行集与结果集的末尾重叠，SQLFetchScroll 将返回部分行集。 也就是说，如果 S + R - 1 大于 L，其中 S 是要提取的行集的起始行，则 R 是行集大小，L 是结果集中的最后一行，则只有第一行 L - S + 1 行行集有效。 其余行为空，状态为SQL_ROW_NOROW。
在 SQLFetchScroll 返回后，当前行是行集的第一行。
游标定位规则
以下部分介绍 FetchOrientation 的每个值的确切规则。 这些规则使用以下表示法。
| 表示法 | 含义 |
|---|---|
| 开始之前 | 块游标位于结果集的开头之前。 如果新行集的第一行位于结果集的开头之前， SQLFetchScroll 将返回SQL_NO_DATA。 |
| 结束之后 | 块游标位于结果集末尾之后。 如果新行集的第一行位于结果集末尾之后， SQLFetchScroll 将返回SQL_NO_DATA。 |
| CurrRowsetStart | 当前行集中第一行的数目。 |
| LastResultRow | 结果集中最后一行的数目。 |
| RowsetSize | 行集大小。 |
| FetchOffset | FetchOffset 参数的值。 |
| BookmarkRow | 对应于由 SQL_ATTR_FETCH_BOOKMARK_PTR 语句属性指定的书签的行。 |
SQL_FETCH_NEXT
以下规则适用。
| 条件 | 新行集的第一行 |
|---|---|
| 开始之前 | 1 |
| CurrRowsetStart + RowsetSize[1] <= LastResultRow | CurrRowsetStart + RowsetSize[1] |
| CurrRowsetStart + RowsetSize[1]> LastResultRow | 结束之后 |
| 结束之后 | 结束之后 |
[1] 如果自上一次调用提取行以来已更改行集大小，则这是与上一次调用一起使用的行集大小。
SQL_FETCH_PRIOR
以下规则适用。
| 条件 | 新行集的第一行 |
|---|---|
| 开始之前 | 开始之前 |
| CurrRowsetStart = 1 | 开始之前 |
| 1 < CurrRowsetStart <= RowsetSize [2] | 1 [1] |
| CurrRowsetStart > RowsetSize [2] | CurrRowsetStart - RowsetSize [2] |
| 结束 AND LastResultRow < RowsetSize [2] | 1 [1] |
| 结束 AND LastResultRow >= RowsetSize [2] | LastResultRow - RowsetSize + 1 [2] |
[1] SQLFetchScroll 返回 SQLSTATE 01S06（尝试提取结果集前返回第一行集）并SQL_SUCCESS_WITH_INFO。
[2] 如果自上一次调用提取行以来已更改行集大小，则这是新的行集大小。
SQL_FETCH_RELATIVE
以下规则适用。
| 条件 | 新行集的第一行 |
|---|---|
| （开始之前和 FetchOffset > 0） 或 （结束并提取Offset < 0） | --[1] |
| BeforeStart AND FetchOffset <= 0 | 开始之前 |
| CurrRowsetStart = 1 AND FetchOffset < 0 | 开始之前 |
| CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND |FetchOffset | > RowsetSize [3] | 开始之前 |
| CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND |FetchOffset | <= RowsetSize [3] | 1 [2] |
| 1 <= CurrRowsetStart + FetchOffset <= LastResultRow | CurrRowsetStart + FetchOffset |
| CurrRowsetStart + FetchOffset > LastResultRow | 结束之后 |
| 结束后 AND FetchOffset >= 0 | 结束之后 |
[1] SQLFetchScroll 返回与使用 FetchOrientation 设置为SQL_FETCH_ABSOLUTE调用的行集相同。 有关详细信息，请参阅“SQL_FETCH_ABSOLUTE”部分。
[2] SQLFetchScroll 返回 SQLSTATE 01S06（尝试提取结果集前返回第一行集）并SQL_SUCCESS_WITH_INFO。
[3] 如果自上一次调用提取行以来已更改行集大小，则这是新的行集大小。
SQL_FETCH_ABSOLUTE
以下规则适用。
| 条件 | 新行集的第一行 |
|---|---|
| FetchOffset < 0 AND |FetchOffset | <= LastResultRow | LastResultRow + FetchOffset + 1 |
| FetchOffset < 0 AND |FetchOffset | > LastResultRow AND |FetchOffset | > RowsetSize [2] | 开始之前 |
| FetchOffset < 0 AND |FetchOffset | > LastResultRow AND |FetchOffset | <= RowsetSize [2] | 1 [1] |
| FetchOffset = 0 | 开始之前 |
| 1 <= FetchOffset <= LastResultRow | FetchOffset |
| FetchOffset > LastResultRow | 结束之后 |
[1] SQLFetchScroll 返回 SQLSTATE 01S06（尝试提取结果集前返回第一行集）并SQL_SUCCESS_WITH_INFO。
[2] 如果自上一次调用提取行以来已更改行集大小，则这是新的行集大小。
对动态游标执行的绝对提取无法提供所需的结果，因为动态游标中的行位置不确定。 此类操作等效于先提取后跟提取相对项;它不是原子操作，静态游标的绝对提取也是一种绝对提取。
SQL_FETCH_FIRST
以下规则适用。
| 条件 | 新行集的第一行 |
|---|---|
| 任意 | 1 |
SQL_FETCH_LAST
以下规则适用。
| 条件 | 新行集的第一行 |
|---|---|
| RowsetSize [1]<= LastResultRow | LastResultRow - RowsetSize + 1 [1] |
| RowsetSize [1]> LastResultRow | 1 |
[1] 如果自上一次调用提取行以来已更改行集大小，则这是新的行集大小。
SQL_FETCH_BOOKMARK
以下规则适用。
| 条件 | 新行集的第一行 |
|---|---|
| BookmarkRow + FetchOffset < 1 | 开始之前 |
| 1 <= BookmarkRow + FetchOffset <= LastResultRow | BookmarkRow + FetchOffset |
| BookmarkRow + FetchOffset > LastResultRow | 结束之后 |
有关书签的信息，请参阅书签（ODBC）。
删除、添加和错误行对游标移动的影响
静态和键集驱动的游标有时会检测添加到结果集中的行，并删除从结果集中删除的行。 通过使用SQL_STATIC_CURSOR_ATTRIBUTES2和SQL_KEYSET_CURSOR_ATTRIBUTES2选项调用 SQLGetInfo 并查看SQL_CA2_SENSITIVITY_ADDITIONS、SQL_CA2_SENSITIVITY_DELETIONS和SQL_CA2_SENSITIVITY_UPDATES位掩码，应用程序将确定由特定驱动程序实现的游标是否执行此操作。 对于可以检测已删除行并删除它们的驱动程序，以下段落描述了此行为的影响。 对于可以检测已删除行但无法删除的驱动程序，删除不会影响游标移动，并且以下段落不适用。
如果游标检测到添加到结果集的行或删除从结果集中删除的行，则它似乎仅在提取数据时才检测到这些更改。 这包括在 将 FetchOrientation 设置为 SQL_FETCH_RELATIVE 的情况下调用 SQLFetchScroll ，并将 FetchOffset 设置为 0 以重新调用同一行集，但不包括使用 fOption 设置为SQL_REFRESH调用 SQLSetPos 的情况。 在后一种情况下，将刷新行集缓冲区中的数据，但不重新写入行，并且不会从结果集中删除已删除的行。 因此，当从当前行集中删除或插入行集时，游标不会修改行集缓冲区。 而是在提取以前包含已删除行或现在包含插入行的任何行集时检测更改。
例如：
// Fetch the next rowset.
SQLFetchScroll(hstmt, SQL_FETCH_NEXT, 0);
// Delete third row of the rowset. Does not modify the rowset buffers.
SQLSetPos(hstmt, 3, SQL_DELETE, SQL_LOCK_NO_CHANGE);
// The third row has a status of SQL_ROW_DELETED after this call.
SQLSetPos(hstmt, 3, SQL_REFRESH, SQL_LOCK_NO_CHANGE);
// Refetch the same rowset. The third row is removed, replaced by what
// was previously the fourth row.
SQLFetchScroll(hstmt, SQL_FETCH_RELATIVE, 0);
当 SQLFetchScroll 返回相对于当前行集的位置的新行集（即 FetchOrientation SQL_FETCH_NEXT、SQL_FETCH_PRIOR或SQL_FETCH_RELATIVE）时，在计算新行集的起始位置时，它不包括对当前行集的更改。 但是，如果更改能够检测这些更改，则它确实包括当前行集之外的更改。 此外，当 SQLFetchScroll 返回一个新的行集，该行集的位置独立于当前行集（即 FetchOrientation 是SQL_FETCH_FIRST、SQL_FETCH_LAST、SQL_FETCH_ABSOLUTE或SQL_FETCH_BOOKMARK）时，它包括能够检测的所有更改，即使它们位于当前行集中也是如此。
确定新添加的行位于当前行集内还是外部时，将部分行集视为最后一个有效行结束;即行状态不SQL_ROW_NOROW的最后一行。 例如，假设游标能够检测新添加的行，当前行集是部分行集，应用程序会添加新行，游标会将这些行添加到结果集的末尾。 如果应用程序调用 将 FetchOrientation 设置为SQL_FETCH_NEXT的 SQLFetchScroll ， 则 SQLFetchScroll 将返回从第一个新添加的行开始的行集。
例如，假设当前行集包含行 21 到 30 行，行集大小为 10，游标从结果集中删除的行，游标检测添加到结果集中的行。 下表显示了 SQLFetchScroll 在各种情况下返回的行。
| 更改 | 提取类型 | FetchOffset | 新建行集[1] |
|---|---|---|---|
| 删除行 21 | NEXT | 0 | 31 到 40 |
| 删除行 31 | NEXT | 0 | 32 到 41 |
| 在行 21 和 22 之间插入行 | NEXT | 0 | 31 到 40 |
| 在行 30 和 31 之间插入行 | NEXT | 0 | 插入行，31 到 39 |
| 删除行 21 | PRIOR | 0 | 11 到 20 |
| 删除行 20 | PRIOR | 0 | 10 至 19 人 |
| 在行 21 和 22 之间插入行 | PRIOR | 0 | 11 到 20 |
| 在行 20 和 21 之间插入行 | PRIOR | 0 | 12 到 20，插入行 |
| 删除行 21 | RELATIVE | 0 | 22 到 31[2] |
| 删除行 21 | RELATIVE | 1 | 22 到 31 |
| 在行 21 和 22 之间插入行 | RELATIVE | 0 | 21，插入行，22 到 29 |
| 在行 21 和 22 之间插入行 | RELATIVE | 1 | 22 到 31 |
| 删除行 21 | ABSOLUTE | 21 | 22 到 31[2] |
| 删除第 22 行 | ABSOLUTE | 21 | 21、23 到 31 |
| 在行 21 和 22 之间插入行 | ABSOLUTE | 22 | 插入行，22 到 29 |
[1] 此列在插入或删除任何行之前使用行号。
[2] 在这种情况下，游标尝试返回以第 21 行开头的行。 由于第 21 行已被删除，因此返回的第一行为第 22 行。
错误行（即状态为SQL_ROW_ERROR的行）不会影响游标移动。 例如，如果当前行集以第 11 行开头，并且第 11 行的状态为SQL_ROW_ERROR，则调用 将 FETCHOrientation 设置为 SQL_FETCH_RELATIVE 且 FetchOffset 设置为 5 的 SQLFetchScroll 将返回以第 16 行开头的行集，就像第 11 行的状态SQL_SUCCESS一样。
返回绑定列中的数据
SQLFetchScroll 以与 SQLFetch 相同的方式返回绑定列中的数据。 有关详细信息，请参阅 SQLFetch 函数中的“返回绑定列中的数据”。
如果未绑定任何列， SQLFetchScroll 不会返回数据，但会将块游标移动到指定位置。 是否可以使用 SQLGetData 从块游标的未绑定列中检索数据取决于驱动程序。 如果对 SQLGetInfo 的调用返回SQL_GETDATA_EXTENSIONS信息类型的SQL_GD_BLOCK位，则支持此功能。
缓冲区地址
SQLFetchScroll 使用相同的公式来确定数据地址和长度/指示器缓冲区作为 SQLFetch。 有关详细信息，请参阅 SQLBindCol 函数中的“缓冲区地址”。
行状态数组
SQLFetchScroll 以与 SQLFetch 相同的方式设置行状态数组中的值。 有关详细信息，请参阅 SQLFetch 函数中的“行状态数组”。
提取的行缓冲区
SQLFetchScroll 以与 SQLFetch 相同的方式返回提取的行中提取的行数。 有关详细信息，请参阅 SQLFetch 函数中的“行提取缓冲区”。
错误处理
当应用程序在 ODBC 3.x 驱动程序中调用 SQLFetchScroll 时，驱动程序管理器会在驱动程序中调用 SQLFetchScroll 。 当应用程序在 ODBC 2.x 驱动程序中调用 SQLFetchScroll 时，驱动程序管理器会在驱动程序中调用 SQLExtendedFetch。 由于 SQLFetchScroll 和 SQLExtendedFetch 以略有不同的方式处理错误，因此当应用程序在 ODBC 2.x 和 ODBC 3.x 驱动程序中调用 SQLFetchScroll 时会看到略有不同的错误行为。
SQLFetchScroll 以与 SQLFetch 相同的方式返回错误和警告;有关详细信息，请参阅 SQLFetch 中的“错误处理”。 SQLExtendedFetch 以与 SQLFetch 相同的方式返回错误，但有以下例外：
当发生应用于行集中特定行的警告时，SQLExtendedFetch 会将行状态数组中的相应条目设置为SQL_ROW_SUCCESS，而不是SQL_ROW_SUCCESS_WITH_INFO。
如果行集中的每一行中出现错误，SQLExtendedFetch 将返回SQL_SUCCESS_WITH_INFO，而不是SQL_ERROR。
在每个应用于单个行的状态记录组中，SQLExtendedFetch 返回的第一条状态记录必须包含 SQLSTATE 01S01（行错误）： SQLFetchScroll 不返回此 SQLSTATE。 如果 SQLExtendedFetch 无法返回其他 SQLSTATE，它仍必须返回此 SQLSTATE。
SQLFetchScroll 和乐观并发
如果游标使用乐观并发（即，SQL_ATTR_CONCURRENCY语句属性的值为 SQL_CONCUR_VALUES 或 SQL_CONCUR_ROWVER - SQLFetchScroll 将更新数据源用来检测行是否已更改的乐观并发值。 每当 SQLFetchScroll 提取新的行集（包括重新提取当前行集时）就会发生这种情况。 （调用 FetchOrientation 设置为 SQL_FETCH_RELATIVE，FetchOffset 设置为 0。
SQLFetchScroll 和 ODBC 2.x 驱动程序
当应用程序在 ODBC 2.x 驱动程序中调用 SQLFetchScroll 时，驱动程序管理器会将此调用映射到 SQLExtendedFetch。 它为 SQLExtendedFetch 的参数传递以下值。
| SQLExtendedFetch 参数 | 值 |
|---|---|
| StatementHandle | SQLFetchScroll 中的 StatementHandle。 |
| FetchOrientation | SQLFetchScroll 中的 FetchOrientation。 |
| FetchOffset | 如果未SQL_FETCH_BOOKMARK FetchOrientation，则使用 SQLFetchScroll 中的 FetchOffset 参数的值。 如果 FetchOrientation SQL_FETCH_BOOKMARK，则使用存储在 SQL_ATTR_FETCH_BOOKMARK_PTR 语句属性指定的地址处的值。 |
| RowCountPtr | SQL_ATTR_ROWS_FETCHED_PTR语句属性指定的地址。 |
| RowStatusArray | SQL_ATTR_ROW_STATUS_PTR语句属性指定的地址。 |
有关详细信息，请参阅“附录 G：驱动程序后向兼容性指南”中的块游标、可滚动游标和后向兼容性。
描述符和 SQLFetchScroll
SQLFetchScroll 以与 SQLFetch 相同的方式与描述符交互。 有关详细信息，请参阅 SQLFetch 函数中的“描述符和 SQLFetchScroll”部分。
代码示例
请参阅列明智绑定、行顺序绑定、定位的 Update 和 Delete 语句，以及使用 SQLSetPos 更新行集中的行。
相关函数
| 有关以下内容的信息 | 请参阅 |
|---|---|
| 将缓冲区绑定到结果集中的列 | SQLBindCol 函数 |
| 执行批量插入、更新或删除操作 | SQLBulkOperations 函数 |
| 取消语句处理 | SQLCancel 函数 |
| 返回有关结果集中的列的信息 | SQLDescribeCol 函数 |
| 执行 SQL 语句 | SQLExecDirect 函数 |
| 执行准备的 SQL 语句 | SQLExecute 函数 |
| 提取单行或仅向前方向的数据块 | SQLFetch 函数 |
| 关闭语句上的游标 | SQLFreeStmt 函数 |
| 返回结果集列数 | SQLNumResultCols 函数 |
| 定位游标、刷新行集中的数据或更新或删除结果集中的数据 | SQLSetPos 函数 |
| 设置语句属性 | SQLSetStmtAttr 函数 |