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 时,可以通过调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值,该 SQLGetDiagRec 的 HandleType 为 SQL_HANDLE_STMT 和 Handle of StatementHandle。 下表列出了 SQLFetchScroll 通常返回的 SQLSTATE 值,并说明了此函数上下文中的每个值;表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATEs 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR,除非另有说明。 如果单个列发生错误,则可以使用 diagIdentifier SQL_DIAG_COLUMN_NUMBER 调用 SQLGetDiagField ,以确定发生错误的列;可以使用 diagIdentifier SQL_DIAG_ROW_NUMBER 调用 SQLGetDiagField ,以确定包含该列的行。
对于除 01xxx SQLSTATEs) 以外的所有可返回SQL_SUCCESS_WITH_INFO或SQL_ERROR (的 SQLSTATE,如果多行操作的一行或多行发生错误,则返回SQL_SUCCESS_WITH_INFO;如果单行操作发生错误,则返回SQL_ERROR。
SQLSTATE | 错误 | 说明 |
---|---|---|
01000 | 常规警告 | 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
01004 | 字符串数据,右截断 | 为列返回的字符串或二进制数据导致截断非空字符或非 NULL 二进制数据。 如果是字符串值,则将其右截。 |
01S01 | 行中出现错误 | 提取一行或多行时出错。 (如果在 ODBC 3*.x* 应用程序使用 ODBC 2*.x* 驱动程序时返回此 SQLSTATE,则可以忽略它。) |
01S06 | 尝试在结果集返回第一个行集之前提取 | SQL_FETCH_PRIOR FetchOrientation 时,请求的行集与结果集的开头重叠,当前位置超出第一行,并且当前行的数目小于或等于行集大小。 SQL_FETCH_PRIOR FetchOrientation 时,请求的行集与结果集的开头重叠,当前位置超出结果集的末尾,并且行集大小大于结果集大小。 当 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为 null 指针的列中。 |
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。 SQLGetDiagRec 在 *MessageText 缓冲区中返回的错误消息描述了错误及其原因。 |
HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
HY008 | 操作已取消 | 已为 StatementHandle 启用异步处理。 调用了函数,在它完成执行之前,在 StatementHandle 上调用了 SQLCancel 或 SQLCancelHandle。 然后,在 StatementHandle 上再次调用函数。 函数已调用,在它完成执行之前,在 StatementHandle 上从多线程应用程序中的不同线程调用 SQLCancel 或 SQLCancelHandle。 |
HY010 | 函数序列错误 | (DM) 为与 StatementHandle 关联的连接句柄调用了异步执行的函数。 调用 SQLFetchScroll 函数时,此异步函数仍在执行。 (DM) SQLExecute、 SQLExecDirect 或 SQLMoreResults 已为 StatementHandle 调用并返回SQL_PARAM_DATA_AVAILABLE。 此函数是在检索所有流参数的数据之前调用的。 (DM) 指定的 StatementHandle 未处于执行状态。 该函数是在未首先调用 SQLExecDirect、 SQLExecute 或目录函数的情况下调用的。 (DM) 为 StatementHandle 调用了异步执行的函数, (不是此函数) ,在调用此函数时仍在执行。 (DM) SQLExecute、 SQLExecDirect、 SQLBulkOperations 或 SQLSetPos 已为 StatementHandle 调用,并返回SQL_NEED_DATA。 在针对所有数据执行参数或列发送数据之前调用了此函数。 (DM) 调用 SQLExtendedFetch 之后,在调用具有 SQL_CLOSE 选项的 SQLFreeStmt 之前,为 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] |
After end AND LastResultRow < RowsetSize[2] | 1[1] |
After end AND LastResultRow >= RowsetSize[2] | LastResultRow - RowsetSize + 1[2] |
[1] SQLFetchScroll 返回 SQLSTATE 01S06 (尝试提取结果集) 并SQL_SUCCESS_WITH_INFO。
[2] 如果自上次调用提取行以来,行集大小已更改,则这是新的行集大小。
SQL_FETCH_RELATIVE
以下规则适用。
条件 | 新行集的第一行 |
---|---|
(开始之前和 FetchOffset > 0) 或 (结束后和 FetchOffset < 0) | --[1] |
BeforeStart 和 FetchOffset <= 0 | 开始前 |
CurrRowsetStart = 1 AND FetchOffset < 0 | 开始前 |
CurrRowsetStart > 1 和 CurrRowsetStart + FetchOffset < 1 AND |FetchOffset | > RowsetSize[3] | 开始前 |
CurrRowsetStart > 1 和 CurrRowsetStart + FetchOffset < 1 AND |FetchOffset | <= RowsetSize[3] | 1[2] |
1 <= CurrRowsetStart + FetchOffset <= LastResultRow | CurrRowsetStart + FetchOffset |
CurrRowsetStart + FetchOffset > LastResultRow | 结束之后 |
After end 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位掩码,应用程序可确定特定驱动程序实现的游标是否执行此操作。 对于可以检测已删除行并将其删除的驱动程序,以下段落介绍了此行为的影响。 对于可以检测已删除行但无法删除它们的驱动程序,删除操作不会影响游标移动,并且以下段落不适用。
如果游标检测到添加到结果集中的行或删除了从结果集中删除的行,则它看起来就像仅在提取数据时才检测到这些更改一样。 这包括调用 SQLFetchScroll 并将 FetchOrientation 设置为 SQL_FETCH_RELATIVE,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行状态的最后一行。 例如,假设游标能够检测新添加的行,当前行集是部分行集,应用程序会添加新行,游标将这些行添加到结果集的末尾。 如果应用程序调用 SQLFetchScroll 并将 FetchOrientation 设置为 SQL_FETCH_NEXT, 则 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,则调用 SQLFetchScroll 并将 FetchOrientation 设置为 SQL_FETCH_RELATIVE 并且 FetchOffset 设置为 5 将返回从第 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 参数的值。 如果SQL_FETCH_BOOKMARK FetchOrientation,则使用存储在 SQL_ATTR_FETCH_BOOKMARK_PTR 语句属性指定的地址上的值。 |
RowCountPtr | SQL_ATTR_ROWS_FETCHED_PTR 语句属性指定的地址。 |
RowStatusArray | SQL_ATTR_ROW_STATUS_PTR 语句属性指定的地址。 |
有关详细信息,请参阅附录 G: 向后兼容性驱动程序指南中的块游标、可滚动游标和 向后兼容性。
描述符和 SQLFetchScroll
SQLFetchScroll 以与 SQLFetch 相同的方式与描述符交互。 有关详细信息,请参阅 SQLFetch 函数中的“描述符和 SQLFetchScroll”部分。
代码示例
请参阅 列式绑定、 按行绑定、 定位更新和删除语句以及 使用 SQLSetPos 更新行集中的行。
相关函数
有关以下方面的信息 | 请参阅 |
---|---|
将缓冲区绑定到结果集中的列 | SQLBindCol 函数 |
执行批量插入、更新或删除操作 | SQLBulkOperations 函数 |
取消语句处理 | SQLCancel 函数 |
返回有关结果集中列的信息 | SQLDescribeCol 函数 |
执行 SQL 语句 | SQLExecDirect 函数 |
执行准备好的 SQL 语句 | SQLExecute 函数 |
以仅向前方向提取单行或数据块 | SQLFetch 函数 |
关闭语句上的游标 | SQLFreeStmt 函数 |
返回结果集列数 | SQLNumResultCols 函数 |
定位游标、刷新行集中的数据,或者更新或删除结果集中的数据 | SQLSetPos 函数 |
设置语句属性 | SQLSetStmtAttr 函数 |
另请参阅
反馈
https://aka.ms/ContentUserFeedback。
即将发布:在整个 2024 年,我们将逐步淘汰作为内容反馈机制的“GitHub 问题”,并将其取代为新的反馈系统。 有关详细信息,请参阅:提交和查看相关反馈