SQLFetchScroll Function(SQLFetchScroll 函数)SQLFetchScroll Function

Conformance
引入的版本:ODBC 3.0 标准符合性:ISO 92Version Introduced: ODBC 3.0 Standards Compliance: ISO 92

摘要Summary
SQLFetchScroll从结果集中提取指定的数据行集, 并返回所有绑定列的数据。SQLFetchScroll fetches the specified rowset of data from the result set and returns data for all bound columns. 可在绝对或相对位置或按书签指定行集。Rowsets can be specified at an absolute or relative position or by bookmark.

使用 ODBC 2.x 驱动程序时, 驱动程序管理器将此函数映射到SQLExtendedFetchWhen working with an ODBC 2.x driver, the Driver Manager maps this function to SQLExtendedFetch. 有关详细信息, 请参阅映射替换函数以实现应用程序的向后兼容性For more information, see Mapping Replacement Functions for Backward Compatibility of Applications.

语法Syntax

  
SQLRETURN SQLFetchScroll(  
      SQLHSTMT      StatementHandle,  
      SQLSMALLINT   FetchOrientation,  
      SQLLEN        FetchOffset);  

参数Arguments

StatementHandleStatementHandle
送语句句柄。[Input] Statement handle.

FetchOrientationFetchOrientation
[Input]

提取类型:Type of fetch:

SQL_FETCH_NEXTSQL_FETCH_NEXT

SQL_FETCH_PRIORSQL_FETCH_PRIOR

SQL_FETCH_FIRSTSQL_FETCH_FIRST

SQL_FETCH_LASTSQL_FETCH_LAST

SQL_FETCH_ABSOLUTESQL_FETCH_ABSOLUTE

SQL_FETCH_RELATIVESQL_FETCH_RELATIVE

SQL_FETCH_BOOKMARKSQL_FETCH_BOOKMARK

有关详细信息, 请参阅 "注释" 部分中的 "定位光标"。For more information, see "Positioning the Cursor" in the "Comments" section.

FetchOffsetFetchOffset
[Input]

要提取的行数。Number of the row to fetch. 此参数的解释取决于FetchOrientation参数的值。The interpretation of this argument depends on the value of the FetchOrientation argument. 有关详细信息, 请参阅 "注释" 部分中的 "定位光标"。For more information, see "Positioning the Cursor" in the "Comments" section.

返回Returns

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_STILL_EXECUTING、SQL_ERROR 或 SQL_INVALID_HANDLE。SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.

诊断Diagnostics

SQLFetchScroll返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时, 可以通过使用 SQLGetDiagRec 的 HandleType 和 SQL_HANDLE_STMT 的句柄调用StatementHandle来获取关联的 SQLSTATE 值。When SQLFetchScroll returns either SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value can be obtained by calling SQLGetDiagRec with a HandleType of SQL_HANDLE_STMT and a Handle of StatementHandle. 下表列出了通常由SQLFetchScroll返回的 SQLSTATE 值, 并对该函数的上下文中的每个值进行了说明:"(DM)" 表示法位于驱动程序管理器返回的 SQLSTATEs 的说明之前。The following table lists the SQLSTATE values commonly returned by SQLFetchScroll and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. 除非另有说明, 否则与每个 SQLSTATE 值相关联的返回代码为 SQL_ERROR。The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise. 如果对单个列发生错误, 则可以使用 SQL_DIAG_COLUMN_NUMBER 的 DiagIdentifier 调用SQLGetDiagField , 以确定发生错误的列;可以使用 SQL_DIAG_ROW_NUMBER 的 DiagIdentifier 调用和SQLGetDiagField来确定包含该列的行。If an error occurs on a single column, SQLGetDiagField can be called with a DiagIdentifier of SQL_DIAG_COLUMN_NUMBER to determine the column the error occurred on; and SQLGetDiagField can be called with a DiagIdentifier of SQL_DIAG_ROW_NUMBER to determine the row containing that column.

对于可以返回 SQL_SUCCESS_WITH_INFO 或 SQL_ERROR 的所有 SQLSTATEs (除了 01xxx SQLSTATEs), 如果在一个或多个 (但不是全部) 行上发生错误, 则将返回 SQL_SUCCESS_WITH_INFO; 如果发生错误, 则返回多行单行操作。For all those SQLSTATEs that can return SQL_SUCCESS_WITH_INFO or SQL_ERROR (except 01xxx SQLSTATEs), SQL_SUCCESS_WITH_INFO is returned if an error occurs on one or more, but not all, rows of a multirow operation, and SQL_ERROR is returned if an error occurs on a single-row operation.

SQLSTATESQLSTATE ErrorError 描述Description
0100001000 一般警告General warning 驱动程序特定的信息性消息。Driver-specific informational message. (函数返回 SQL_SUCCESS_WITH_INFO。)(Function returns SQL_SUCCESS_WITH_INFO.)
0100401004 字符串数据, 右截断String data, right truncated 为列返回的字符串或二进制数据导致截断非空白字符或非空的二进制数据。String or binary data returned for a column resulted in the truncation of nonblank character or non-NULL binary data. 如果它是一个字符串值, 则它将被右截断。If it was a string value, it was right-truncated.
01S0101S01 行中的错误Error in row 提取一行或多行时出错。An error occurred while fetching one or more rows.

(如果在 ODBC3.x 应用程序使用 odbc2.x 驱动程序时返回此 SQLSTATE, 则可以将其忽略。)(If this SQLSTATE is returned when an ODBC 3 .x application is working with an ODBC 2 .x driver, it can be ignored.)
01S0601S06 尝试在结果集返回第一个行集之前提取Attempt to fetch before the result set returned the first rowset 当 FetchOrientation 为 SQL_FETCH_PRIOR 时, 请求的行集与结果集的开头重叠, 当前位置超出第一行, 当前行的行号小于或等于行集大小。The requested rowset overlapped the start of the result set when FetchOrientation was SQL_FETCH_PRIOR, the current position was beyond the first row, and the number of the current row is less than or equal to the rowset size.

当 FetchOrientation 为 SQL_FETCH_PRIOR 时, 请求的行集与结果集的开头重叠, 当前位置超出了结果集的末尾, 并且行集的大小大于结果集的大小。The requested rowset overlapped the start of the result set when FetchOrientation was SQL_FETCH_PRIOR, the current position was beyond the end of the result set, and the rowset size was greater than the result set size.

当 FetchOrientation 为 SQL_FETCH_RELATIVE 时, 请求的行集与结果集的开头重叠, FetchOffset 为负值, 而 FetchOffset 的绝对值小于或等于行集大小。The requested rowset overlapped the start of the result set when FetchOrientation was SQL_FETCH_RELATIVE, FetchOffset was negative, and the absolute value of FetchOffset was less than or equal to the rowset size.

当 FetchOrientation 为 SQL_FETCH_ABSOLUTE 时, 请求的行集与结果集的开头重叠, FetchOffset 为负值, 而 FetchOffset 的绝对值大于结果集大小但小于或等于行集大小。The requested rowset overlapped the start of the result set when FetchOrientation was SQL_FETCH_ABSOLUTE, FetchOffset was negative, and the absolute value of FetchOffset was greater than the result set size but less than or equal to the rowset size.

(函数返回 SQL_SUCCESS_WITH_INFO。)(Function returns SQL_SUCCESS_WITH_INFO.)
01S0701S07 小数截断Fractional truncation 为列返回的数据被截断。The data returned for a column was truncated. 对于数值数据类型, 数值的小数部分被截断。For numeric data types, the fractional part of the number was truncated. 对于包含时间部分的时间、时间戳和间隔数据类型, 时间的小数部分将被截断。For time, timestamp, and interval data types containing a time component, the fractional portion of the time was truncated.

(函数返回 SQL_SUCCESS_WITH_INFO。)(Function returns SQL_SUCCESS_WITH_INFO.)
0700607006 受限制的数据类型属性冲突Restricted data type attribute violation 结果集中列的数据值无法转换为SQLBindColTargetType指定的数据类型。The data value of a column in the result set could not be converted to the data type specified by TargetType in SQLBindCol.

列0与 SQL_C_BOOKMARK 的数据类型绑定, SQL_ATTR_USE_BOOKMARKS 语句特性设置为 SQL_UB_VARIABLE。Column 0 was bound with a data type of SQL_C_BOOKMARK, and the SQL_ATTR_USE_BOOKMARKS statement attribute was set to SQL_UB_VARIABLE.

列0与数据类型 SQL_C_VARBOOKMARK 绑定, 而 SQL_ATTR_USE_BOOKMARKS 语句特性未设置为 SQL_UB_VARIABLE。Column 0 was bound with a data type of SQL_C_VARBOOKMARK, and the SQL_ATTR_USE_BOOKMARKS statement attribute was not set to SQL_UB_VARIABLE.
0700907009 描述符索引无效Invalid descriptor index 驱动程序是不支持SQLExtendedFetch的 ODBC2.x 驱动程序, 并且在绑定中为列指定的列号为0。The driver was an ODBC 2 .x driver that does not support SQLExtendedFetch, and a column number specified in the binding for a column was 0.

已绑定列 0, 并且 SQL_ATTR_USE_BOOKMARKS 语句属性设置为 SQL_UB_OFF。Column 0 was bound, and the SQL_ATTR_USE_BOOKMARKS statement attribute was set to SQL_UB_OFF.
08S0108S01 通信链接失败Communication link failure 在函数完成处理之前, 驱动程序与连接到的数据源之间的通信链接失败。The communication link between the driver and the data source to which the driver was connected failed before the function completed processing.
2200122001 字符串数据, 右截断String data, right truncated 为列返回的可变长度书签已截断。A variable-length bookmark returned for a column was truncated.
2200222002 需要指示器变量, 但未提供Indicator variable required but not supplied NULL 数据提取到StrLen_or_IndPtr设置的列中, SQLBINDCOL (或 SQL_DESC_INDICATOR_PTR 通过SQLSetDescFieldSQLSetDescRec设置) 为 null 指针。NULL data was fetched into a column whose StrLen_or_IndPtr set by SQLBindCol (or SQL_DESC_INDICATOR_PTR set by SQLSetDescField or SQLSetDescRec) was a null pointer.
2200322003 数值超出范围Numeric value out of range 返回一个或多个绑定列的数值 (作为数字或字符串) 将导致截断数字的整个部分 (而不是小数部分)。Returning the numeric value (as numeric or string) for one or more bound columns would have caused the whole (as opposed to fractional) part of the number to be truncated.

有关详细信息, 请参阅附录 D:数据类型For more information, see Converting Data from SQL to C Data Types in Appendix D: Data Types.
2200722007 Datetime 格式无效Invalid datetime format 结果集中的字符列已绑定到日期、时间或时间戳 C 结构, 列中的值分别为无效的日期、时间或时间戳。A character column in the result set was bound to a date, time, or timestamp C structure, and a value in the column was, respectively, an invalid date, time, or timestamp.
2201222012 被零除Division by zero 返回了算术表达式中的值, 从而导致被零除。A value from an arithmetic expression was returned, which resulted in division by zero.
2201522015 间隔字段溢出Interval field overflow 从精确数值或间隔 SQL 类型赋值到 interval C 类型会导致前导字段的有效位丢失。Assigning from an exact numeric or interval SQL type to an interval C type caused a loss of significant digits in the leading field.

将数据提取到 interval C 类型时, interval C 类型中没有 SQL 类型的值的表示形式。When fetching data to an interval C type, there was no representation of the value of the SQL type in the interval C type.
2201822018 转换规范的字符值无效Invalid character value for cast specification 结果集中的字符列已绑定到字符 C 缓冲区, 列包含的字符在缓冲区的字符集中没有表示形式。A character column in the result set was bound to a character C buffer, and the column contained a character for which there was no representation in the character set of the buffer.

C 类型是精确或近似数字、日期时间或间隔数据类型;列的 SQL 类型是字符数据类型;列中的值不是绑定 C 类型的有效文本。The C type was an exact or approximate numeric, a datetime, or an interval data type; the SQL type of the column was a character data type; and the value in the column was not a valid literal of the bound C type.
2400024000 无效的游标状态Invalid cursor state StatementHandle处于已执行状态, 但没有与StatementHandle关联的结果集。The StatementHandle was in an executed state but no result set was associated with the StatementHandle.
4000140001 序列化失败Serialization failure 执行提取的事务已终止, 以防止死锁。The transaction in which the fetch was executed was terminated to prevent deadlock.
4000340003 语句完成情况未知Statement completion unknown 在执行此函数的过程中关联的连接失败, 无法确定事务的状态。The associated connection failed during the execution of this function, and the state of the transaction cannot be determined.
HY000HY000 一般错误General error 发生了一个错误, 该错误没有特定的 SQLSTATE, 没有为其定义实现特定的 SQLSTATE。An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. MessageText 缓冲区中的 SQLGetDiagRec返回的错误消息描述了错误及其原因。 *The error message returned by SQLGetDiagRec in the *MessageText buffer describes the error and its cause.
HY001HY001 内存分配错误Memory allocation error 驱动程序无法分配支持执行或完成此函数所需的内存。The driver was unable to allocate memory required to support execution or completion of the function.
HY008HY008 操作已取消Operation canceled 已为StatementHandle启用异步处理。Asynchronous processing was enabled for the StatementHandle. 函数被调用, 在完成执行之前, 在StatementHandle上调用了SQLCancelSQLCancelHandleThe function was called, and before it completed execution, SQLCancel or SQLCancelHandle was called on the StatementHandle. 然后, 在StatementHandle上再次调用该函数。Then the function was called again on the StatementHandle.

函数被调用, 在完成执行之前, 从多线程应用程序中的另一个线程调用StatementHandle上的SQLCancelSQLCancelHandleThe function was called, and before it completed execution, SQLCancel or SQLCancelHandle was called on the StatementHandle from a different thread in a multithread application.
HY010HY010 函数序列错误Function sequence error (DM) 为与StatementHandle关联的连接句柄调用了异步执行的函数。(DM) An asynchronously executing function was called for the connection handle that is associated with the StatementHandle. 调用SQLFetchScroll函数时, 此异步函数仍在执行。This asynchronous function was still executing when the SQLFetchScroll function was called.

(DM) 为StatementHandle调用了SQLExecuteSQLExecDirectSQLMoreResults , 并返回了 SQL_PARAM_DATA_AVAILABLE。(DM) SQLExecute, SQLExecDirect, or SQLMoreResults was called for the StatementHandle and returned SQL_PARAM_DATA_AVAILABLE. 在检索所有流式处理参数的数据之前调用此函数。This function was called before data was retrieved for all streamed parameters.

(DM) 指定的StatementHandle未处于执行状态。(DM) The specified StatementHandle was not in an executed state. 调用函数时, 无需先调用SQLExecDirectSQLExecute或 catalog 函数。The function was called without first calling SQLExecDirect, SQLExecute or a catalog function.

(DM) 为StatementHandle调用了异步执行的函数 (而不是此函数), 并且在调用此函数时仍在执行。(DM) An asynchronously executing function (not this one) was called for the StatementHandle and was still executing when this function was called.

(DM) SQLExecuteSQLExecDirectSQLBulkOperationsSQLSETPOS调用了StatementHandle并返回了 SQL_NEED_DATA。(DM) SQLExecute, SQLExecDirect, SQLBulkOperations, or SQLSetPos was called for the StatementHandle and returned SQL_NEED_DATA. 在为所有执行时数据参数或列发送数据之前, 将调用此函数。This function was called before data was sent for all data-at-execution parameters or columns.

(DM) 在调用SQLExtendedFetch后, 调用了StatementHandle SQLFETCH , 并调用了 SQL_CLOSE 选项SQLFreeStmt(DM) SQLFetch was called for the StatementHandle after SQLExtendedFetch was called and before SQLFreeStmt with the SQL_CLOSE option was called.
HY013HY013 内存管理错误Memory management error 未能处理函数调用, 原因可能是由于内存不足而无法访问基础内存对象。The function call could not be processed because the underlying memory objects could not be accessed, possibly because of low memory conditions.
HY090HY090 字符串或缓冲区长度无效Invalid string or buffer length SQL_ATTR_USE_BOOKMARK 语句特性设置为 SQL_UB_VARIABLE, 而列0绑定到的缓冲区的长度不等于此结果集的书签的最大长度。The SQL_ATTR_USE_BOOKMARK statement attribute was set to SQL_UB_VARIABLE, and column 0 was bound to a buffer whose length was not equal to the maximum length for the bookmark for this result set. (此长度在 IRD 的 SQL_DESC_OCTET_LENGTH 字段中提供, 可以通过调用SQLDescribeColSQLColAttributeSQLGetDescField获取。)(This length is available in the SQL_DESC_OCTET_LENGTH field of the IRD and can be obtained by calling SQLDescribeCol, SQLColAttribute, or SQLGetDescField.)
HY106HY106 提取类型超出范围Fetch type out of range DM) 为参数 FetchOrientation 指定的值无效。DM) The value specified for the argument FetchOrientation was invalid.

(DM) 参数 FetchOrientation 是 SQL_FETCH_BOOKMARK, SQL_ATTR_USE_BOOKMARKS 语句特性设置为 SQL_UB_OFF。(DM) The argument FetchOrientation was SQL_FETCH_BOOKMARK, and the SQL_ATTR_USE_BOOKMARKS statement attribute was set to SQL_UB_OFF.

SQL_ATTR_CURSOR_TYPE 语句特性的值为 SQL_CURSOR_FORWARD_ONLY, 而 FetchOrientation 参数的值不为 SQL_FETCH_NEXT。The value of the SQL_ATTR_CURSOR_TYPE statement attribute was SQL_CURSOR_FORWARD_ONLY, and the value of argument FetchOrientation was not SQL_FETCH_NEXT.

SQL_ATTR_CURSOR_SCROLLABLE 语句特性的值为 SQL_NONSCROLLABLE, 而 FetchOrientation 参数的值不为 SQL_FETCH_NEXT。The value of the SQL_ATTR_CURSOR_SCROLLABLE statement attribute was SQL_NONSCROLLABLE, and the value of argument FetchOrientation was not SQL_FETCH_NEXT.
HY107HY107 行值超出范围Row value out of range 用 SQL_ATTR_CURSOR_TYPE 语句特性指定的值为 SQL_CURSOR_KEYSET_DRIVEN, 但通过 SQL_ATTR_KEYSET_SIZE 语句特性指定的值大于0且小于用 SQL_ATTR_ROW_ARRAY_ 指定的值SIZE 语句特性。The value specified with the SQL_ATTR_CURSOR_TYPE statement attribute was SQL_CURSOR_KEYSET_DRIVEN, but the value specified with the SQL_ATTR_KEYSET_SIZE statement attribute was greater than 0 and less than the value specified with the SQL_ATTR_ROW_ARRAY_SIZE statement attribute.
HY111HY111 书签值无效Invalid bookmark value 参数 FetchOrientation 为 SQL_FETCH_BOOKMARK, 由 SQL_ATTR_FETCH_BOOKMARK_PTR 语句特性中的值指向的书签无效或为 null 指针。The argument FetchOrientation was SQL_FETCH_BOOKMARK, and the bookmark pointed to by the value in the SQL_ATTR_FETCH_BOOKMARK_PTR statement attribute was not valid or was a null pointer.
HY117HY117 由于未知的事务状态, 连接被挂起。Connection is suspended due to unknown transaction state. 仅允许断开连接和只读函数。Only disconnect and read-only functions are allowed. (DM) 有关挂起状态的详细信息, 请参阅SQLEndTran 函数(DM) For more information about suspended state, see SQLEndTran Function.
HYC00HYC00 未实现的可选功能Optional feature not implemented 驱动程序或数据源不支持SQLBindColTargetType的组合指定的转换和相应列的 SQL 数据类型。The driver or data source does not support the conversion specified by the combination of the TargetType in SQLBindCol and the SQL data type of the corresponding column.
HYT00HYT00 超时时间已到Timeout expired 在数据源返回请求的结果集之前, 查询超时期限已过期。The query timeout period expired before the data source returned the requested result set. 超时期限通过 SQLSetStmtAttr、SQL_ATTR_QUERY_TIMEOUT 设置。The timeout period is set through SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT.
HYT01HYT01 连接超时已过期Connection timeout expired 连接超时期限在数据源响应请求之前过期。The connection timeout period expired before the data source responded to the request. 连接超时期限通过SQLSetConnectAttr、SQL_ATTR_CONNECTION_TIMEOUT 设置。The connection timeout period is set through SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001IM001 驱动程序不支持此功能Driver does not support this function (DM) 与StatementHandle关联的驱动程序不支持该函数。(DM) The driver associated with the StatementHandle does not support the function.
IM017IM017 在异步通知模式下禁用轮询Polling is disabled in asynchronous notification mode 无论何时使用通知模型, 都将禁用轮询。Whenever the notification model is used, polling is disabled.
IM018IM018 尚未调用SQLCompleteAsync来完成此句柄上先前的异步操作。SQLCompleteAsync has not been called to complete the previous asynchronous operation on this handle. 如果句柄上的上一个函数调用返回 SQL_STILL_EXECUTING, 并且如果启用了通知模式, 则必须在句柄上调用SQLCompleteAsync , 才能执行后处理并完成操作。If the previous function call on the handle returns SQL_STILL_EXECUTING and if notification mode is enabled, SQLCompleteAsync must be called on the handle to do post-processing and complete the operation.

注释Comments

SQLFetchScroll从结果集中返回指定的行集。SQLFetchScroll returns a specified rowset from the result set. 可以按绝对或相对位置或按书签指定行集。Rowsets can be specified by absolute or relative position or by bookmark. SQLFetchScroll只能在结果集存在时调用, 也就是说, 在创建结果集的调用之后, 在该结果集上的游标结束之前。SQLFetchScroll can be called only while a result set exists - that is, after a call that creates a result set and before the cursor over that result set is closed. 如果绑定了任何列, 则它会返回这些列中的数据。If any columns are bound, it returns the data in those columns. 如果应用程序已指定一个指向行状态数组或缓冲区的指针 (在其中返回提取的行数), SQLFetchScroll也将返回此信息。If the application has specified a pointer to a row status array or a buffer in which to return the number of rows fetched, SQLFetchScroll returns this information as well. SQLFetchScroll的调用可以与对SQLFetch的调用混合, 但不能与对SQLExtendedFetch的调用混合。Calls to SQLFetchScroll can be mixed with calls to SQLFetch but cannot be mixed with calls to SQLExtendedFetch.

有关详细信息, 请参阅使用块游标使用可滚动游标For more information, see Using Block Cursors and Using Scrollable Cursors.

定位光标Positioning the Cursor

创建结果集时, 游标将定位在结果集的开始位置之前。When the result set is created, the cursor is positioned before the start of the result set. SQLFetchScroll根据FetchOrientationFetchOffset参数的值定位块游标, 如下表所示。SQLFetchScroll positions the block cursor based on the values of the FetchOrientation and FetchOffset arguments as shown in the following table. 确定新行集开头的确切规则如下一节所示。The exact rules for determining the start of the new rowset are shown in the next section.

FetchOrientationFetchOrientation 含义Meaning
SQL_FETCH_NEXTSQL_FETCH_NEXT 返回下一个行集。Return the next rowset. 这等效于调用SQLFetchThis is equivalent to calling SQLFetch.

SQLFetchScroll忽略FetchOffset的值。SQLFetchScroll ignores the value of FetchOffset.
SQL_FETCH_PRIORSQL_FETCH_PRIOR 返回前面的行集。Return the prior rowset.

SQLFetchScroll忽略FetchOffset的值。SQLFetchScroll ignores the value of FetchOffset.
SQL_FETCH_RELATIVESQL_FETCH_RELATIVE 从当前行集的开头返回行集FetchOffsetReturn the rowset FetchOffset from the start of the current rowset.
SQL_FETCH_ABSOLUTESQL_FETCH_ABSOLUTE 返回从行FetchOffset开始的行集。Return the rowset starting at row FetchOffset.
SQL_FETCH_FIRSTSQL_FETCH_FIRST 返回结果集中的第一个行集。Return the first rowset in the result set.

SQLFetchScroll忽略FetchOffset的值。SQLFetchScroll ignores the value of FetchOffset.
SQL_FETCH_LASTSQL_FETCH_LAST 返回结果集中的最后一个完整行集。Return the last complete rowset in the result set.

SQLFetchScroll忽略FetchOffset的值。SQLFetchScroll ignores the value of FetchOffset.
SQL_FETCH_BOOKMARKSQL_FETCH_BOOKMARK 从 SQL_ATTR_FETCH_BOOKMARK_PTR 语句特性指定的书签返回行集 FetchOffset 行。Return the rowset FetchOffset rows from the bookmark specified by the SQL_ATTR_FETCH_BOOKMARK_PTR statement attribute.

驱动程序无需支持所有提取方向;应用程序调用SQLGetInfo , 其信息类型为 SQL_DYNAMIC_CURSOR_ATTRIBUTES1、SQL_KEYSET_CURSOR_ATTRIBUTES1 或 SQL_STATIC_CURSOR_ATTRIBUTES1 (具体取决于游标的类型), 以确定哪些提取方向是受驱动程序支持。Drivers are not required to support all fetch orientations; an application calls SQLGetInfo with an information type of SQL_DYNAMIC_CURSOR_ATTRIBUTES1, SQL_KEYSET_CURSOR_ATTRIBUTES1, or SQL_STATIC_CURSOR_ATTRIBUTES1 (depending on the type of the cursor) to determine which fetch orientations are supported by the driver. 应用程序应查看这些信息类型中的 SQL_CA1_NEXT、SQL_CA1_RELATIVE、SQL_CA1_ABSOLUTE 和 WQL_CA1_BOOKMARK 位掩码。The application should look at the SQL_CA1_NEXT, SQL_CA1_RELATIVE, SQL_CA1_ABSOLUTE, and WQL_CA1_BOOKMARK bitmasks in these information types. 此外, 如果游标是只进的并且 FetchOrientation 不是 SQL_FETCH_NEXT, 则SQLFetchScroll将返回 SQLSTATE HY106 (提取类型超出范围)。Furthermore, if the cursor is forward-only and FetchOrientation is not SQL_FETCH_NEXT, SQLFetchScroll returns SQLSTATE HY106 (Fetch type out of range).

SQL_ATTR_ROW_ARRAY_SIZE 语句特性指定行集中的行数。The SQL_ATTR_ROW_ARRAY_SIZE statement attribute specifies the number of rows in the rowset. 如果SQLFetchScroll提取的行集与结果集的末尾重叠, 则SQLFetchScroll将返回部分行集。If the rowset being fetched by SQLFetchScroll overlaps the end of the result set, SQLFetchScroll returns a partial rowset. 也就是说, 如果 S + R-1 大于 L, 其中 S 是要提取的行集的起始行, 则 R 是行集的大小, L 是结果集中的最后一行, 则仅行集的第一 L + 1 行是有效的。That is, if S + R - 1 is greater than L, where S is the starting row of the rowset being fetched, R is the rowset size, and L is the last row in the result set, then only the first L - S + 1 rows of the rowset are valid. 其余行为空, 状态为 "SQL_ROW_NOROW"。The remaining rows are empty and have a status of SQL_ROW_NOROW.

SQLFetchScroll返回后, 当前行是行集的第一行。After SQLFetchScroll returns, the current row is the first row of the rowset.

游标定位规则Cursor Positioning Rules

以下部分介绍 FetchOrientation 的每个值的确切规则。The following sections describe the exact rules for each value of FetchOrientation. 这些规则使用以下表示法。These rules use the following notation.

表示法Notation 含义Meaning
开始之前Before start 块游标位于结果集的开头位置之前。The block cursor is positioned before the start of the result set. 如果新行集的第一行在结果集的开头之前, 则SQLFetchScroll将返回 SQL_NO_DATA。If the first row of the new rowset is before the start of the result set, SQLFetchScroll returns SQL_NO_DATA.
结束后After end 块游标位于结果集的结尾之后。The block cursor is positioned after the end of the result set. 如果新行集的第一行在结果集的末尾之后, 则SQLFetchScroll将返回 SQL_NO_DATA。If the first row of the new rowset is after the end of the result set, SQLFetchScroll returns SQL_NO_DATA.
CurrRowsetStartCurrRowsetStart 当前行集中第一行的编号。The number of the first row in the current rowset.
LastResultRowLastResultRow 结果集中的最后一行的行号。The number of the last row in the result set.
RowsetSizeRowsetSize 行集大小。The rowset size.
FetchOffsetFetchOffset FetchOffset参数的值。The value of the FetchOffset argument.
BookmarkRowBookmarkRow 对应于 SQL_ATTR_FETCH_BOOKMARK_PTR 语句特性指定的书签的行。The row corresponding to the bookmark specified by the SQL_ATTR_FETCH_BOOKMARK_PTR statement attribute.

SQL_FETCH_NEXTSQL_FETCH_NEXT

下面的规则适用。The following rules apply.

条件Condition 新行集的第一行First row of new rowset
开始之前Before start 11
CurrRowsetStart + RowsetSize[1] <= LastResultRowCurrRowsetStart + RowsetSize[1] <= LastResultRow CurrRowsetStart + RowsetSize[1]CurrRowsetStart + RowsetSize[1]
CurrRowsetStart + RowsetSize2 > LastResultRowCurrRowsetStart + RowsetSize[1]> LastResultRow 结束后After end
结束后After end 结束后After end

[1] 如果行集大小自上次调用提取行后发生了更改, 则这是与上一调用一起使用的行集大小。[1] If the rowset size has been changed since the previous call to fetch rows, this is the rowset size that was used with the previous call.

SQL_FETCH_PRIORSQL_FETCH_PRIOR

下面的规则适用。The following rules apply.

条件Condition 新行集的第一行First row of new rowset
开始之前Before start 开始之前Before start
CurrRowsetStart = 1CurrRowsetStart = 1 开始之前Before start
1 < CurrRowsetStart <= RowsetSize [2]1 < CurrRowsetStart <= RowsetSize [2] 1 [1]1 [1]
CurrRowsetStart > RowsetSize [2]CurrRowsetStart > RowsetSize [2] CurrRowsetStart - RowsetSize [2]CurrRowsetStart - RowsetSize [2]
结束后, LastResultRow < RowsetSize[2]After end AND LastResultRow < RowsetSize [2] 1 [1]1 [1]
结束和 LastResultRow 之后 > = RowsetSize[2]After end AND LastResultRow >= RowsetSize [2] LastResultRow-RowsetSize + 1[2]LastResultRow - RowsetSize + 1 [2]

[1] SQLFetchScroll返回 SQLSTATE 01S06 (尝试在结果集返回第一个行集之前提取) 和 SQL_SUCCESS_WITH_INFO。[1] SQLFetchScroll returns SQLSTATE 01S06 (Attempt to fetch before the result set returned the first rowset) and SQL_SUCCESS_WITH_INFO.

[2] 如果行集大小自上次调用提取行后发生了更改, 则这是新的行集大小。[2] If the rowset size has been changed since the previous call to fetch rows, this is the new rowset size.

SQL_FETCH_RELATIVESQL_FETCH_RELATIVE

下面的规则适用。The following rules apply.

条件Condition 新行集的第一行First row of new rowset
(开始之前, FetchOffset > 0)或 (结束后 FetchOffset < 0)(Before start AND FetchOffset > 0) OR (After end AND FetchOffset < 0) -- [1]-- [1]
BeforeStart 和 FetchOffset < = 0BeforeStart AND FetchOffset <= 0 开始之前Before start
CurrRowsetStart = 1, FetchOffset < 0CurrRowsetStart = 1 AND FetchOffset < 0 开始之前Before start
CurrRowsetStart > 1 和 CurrRowsetStart + FetchOffset < 1 和| FetchOffset | > RowsetSize[3]CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND | FetchOffset | > RowsetSize [3] 开始之前Before start
CurrRowsetStart > 1 和 CurrRowsetStart + FetchOffset < 1 和| FetchOffset | < = RowsetSize[3]CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND | FetchOffset | <= RowsetSize [3] 1 [2]1 [2]
1 < = CurrRowsetStart + FetchOffset <= LastResultRow1 <= CurrRowsetStart + FetchOffset <= LastResultRow CurrRowsetStart + FetchOffsetCurrRowsetStart + FetchOffset
CurrRowsetStart + FetchOffset > LastResultRowCurrRowsetStart + FetchOffset > LastResultRow 结束后After end
结束和 FetchOffset 之后 > = 0After end AND FetchOffset >= 0 结束后After end

[1] SQLFetchScroll返回的行集与将 FetchOrientation 设置为 SQL_FETCH_ABSOLUTE 时调用的行集相同。[1] SQLFetchScroll returns the same rowset as if it was called with FetchOrientation set to SQL_FETCH_ABSOLUTE. 有关详细信息, 请参阅 "SQL_FETCH_ABSOLUTE" 部分。For more information, see the "SQL_FETCH_ABSOLUTE" section.

[2] SQLFetchScroll返回 SQLSTATE 01S06 (尝试在结果集返回第一个行集之前提取) 和 SQL_SUCCESS_WITH_INFO。[2] SQLFetchScroll returns SQLSTATE 01S06 (Attempt to fetch before the result set returned the first rowset) and SQL_SUCCESS_WITH_INFO.

[3] 如果行集大小自上次调用提取行后发生了更改, 则这是新的行集大小。[3] If the rowset size has been changed since the previous call to fetch rows, this is the new rowset size.

SQL_FETCH_ABSOLUTESQL_FETCH_ABSOLUTE

下面的规则适用。The following rules apply.

条件Condition 新行集的第一行First row of new rowset
FetchOffset < 0 和| FetchOffset | < = LastResultRowFetchOffset < 0 AND | FetchOffset | <= LastResultRow LastResultRow + FetchOffset + 1LastResultRow + FetchOffset + 1
FetchOffset < 0 和| FETCHOFFSET | > LastResultRow 和| FetchOffset | > RowsetSize[2]FetchOffset < 0 AND | FetchOffset | > LastResultRow AND | FetchOffset | > RowsetSize [2] 开始之前Before start
FetchOffset < 0 和| FETCHOFFSET | > LastResultRow 和| FetchOffset | < = RowsetSize[2]FetchOffset < 0 AND | FetchOffset | > LastResultRow AND | FetchOffset | <= RowsetSize [2] 1 [1]1 [1]
FetchOffset = 0FetchOffset = 0 开始之前Before start
1 < = FetchOffset <= LastResultRow1 <= FetchOffset <= LastResultRow FetchOffsetFetchOffset
FetchOffset > LastResultRowFetchOffset > LastResultRow 结束后After end

[1] SQLFetchScroll返回 SQLSTATE 01S06 (尝试在结果集返回第一个行集之前提取) 和 SQL_SUCCESS_WITH_INFO。[1] SQLFetchScroll returns SQLSTATE 01S06 (Attempt to fetch before the result set returned the first rowset) and SQL_SUCCESS_WITH_INFO.

[2] 如果行集大小自上次调用提取行后发生了更改, 则这是新的行集大小。[2] If the rowset size has been changed since the previous call to fetch rows, this is the new rowset size.

对动态游标执行的绝对提取无法提供所需的结果, 因为动态游标中的行位置不确定。An absolute fetch performed against a dynamic cursor cannot provide the required result because row positions in a dynamic cursor are undetermined. 此类操作等效于首先提取, 然后是提取相对;这不是原子操作, 这与静态游标上的绝对提取相同。Such an operation is equivalent to a fetch first followed by a fetch relative; it is not an atomic operation, as is an absolute fetch on a static cursor.

SQL_FETCH_FIRSTSQL_FETCH_FIRST

下面的规则适用。The following rules apply.

条件Condition 新行集的第一行First row of new rowset
随时Any 11

SQL_FETCH_LASTSQL_FETCH_LAST

下面的规则适用。The following rules apply.

条件Condition 新行集的第一行First row of new rowset
RowsetSize[1] < = LastResultRowRowsetSize [1] <= LastResultRow LastResultRow-RowsetSize + 1[1]LastResultRow - RowsetSize + 1 [1]
RowsetSize[1] > LastResultRowRowsetSize [1] > LastResultRow 11

[1] 如果行集大小自上次调用提取行后发生了更改, 则这是新的行集大小。[1] If the rowset size has been changed since the previous call to fetch rows, this is the new rowset size.

SQL_FETCH_BOOKMARKSQL_FETCH_BOOKMARK

下面的规则适用。The following rules apply.

条件Condition 新行集的第一行First row of new rowset
BookmarkRow + FetchOffset < 1BookmarkRow + FetchOffset < 1 开始之前Before start
1 < = BookmarkRow + FetchOffset <= LastResultRow1 <= BookmarkRow + FetchOffset <= LastResultRow BookmarkRow + FetchOffsetBookmarkRow + FetchOffset
BookmarkRow + FetchOffset > LastResultRowBookmarkRow + FetchOffset > LastResultRow 结束后After end

有关书签的信息, 请参阅书签 (ODBC)For information about bookmarks, see Bookmarks (ODBC).

游标移动上已删除、添加和错误行的效果Effect of Deleted, Added, and Error Rows on Cursor Movement

静态游标和由键集驱动的游标有时会检测添加到结果集中的行并删除从结果集中删除的行。Static and keyset-driven cursors sometimes detect rows added to the result set and remove rows deleted from the result set. 通过使用 SQL_STATIC_CURSOR_ATTRIBUTES2 和 SQL_KEYSET_CURSOR_ATTRIBUTES2 选项调用SQLGetInfo , 并查看 SQL_CA2_SENSITIVITY_ADDITIONS、SQL_CA2_SENSITIVITY_DELETIONS 和 SQL_CA2_SENSITIVITY_UPDATES 位屏蔽,应用程序确定由特定驱动程序实现的游标是否执行此操作。By calling SQLGetInfo with the SQL_STATIC_CURSOR_ATTRIBUTES2 and SQL_KEYSET_CURSOR_ATTRIBUTES2 options and looking at the SQL_CA2_SENSITIVITY_ADDITIONS, SQL_CA2_SENSITIVITY_DELETIONS, and SQL_CA2_SENSITIVITY_UPDATES bitmasks, an application determines whether the cursors implemented by a particular driver do this. 对于可以检测已删除的行并将其删除的驱动程序, 以下各段说明了此行为的影响。For drivers that can detect deleted rows and remove them, the following paragraphs describe the effects of this behavior. 对于可以检测已删除的行但不能删除它们的驱动程序, 删除对游标移动没有影响, 并且以下段落不适用。For drivers that can detect deleted rows but cannot remove them, deletions have no effect on cursor movements, and the following paragraphs do not apply.

如果游标检测到添加到结果集中的行, 或删除从结果集中删除的行, 则其似乎仅在提取数据时才检测这些更改。If the cursor detects rows added to the result set or removes rows deleted from the result set, it appears as if it detects these changes only when it fetches data. 这包括以下情况: 调用SQLFetchScroll时, FetchOrientation 设置为 SQL_FETCH_RELATIVE, FetchOffset 设置为 0, 以重新提取同一行集, 但在将 SQLSetPos 设置为 fOption 的情况下调用 SQL_REFRESH 时不包括大小写。This includes the case when SQLFetchScroll is called with FetchOrientation set to SQL_FETCH_RELATIVE and FetchOffset set to 0 to refetch the same rowset, but does not include the case when SQLSetPos is called with fOption set to SQL_REFRESH. 在后一种情况下, 行集缓冲区中的数据将被刷新, 而不是制约, 并且删除的行不会从结果集中删除。In the latter case, the data in the rowset buffers is refreshed, but not refetched, and deleted rows are not removed from the result set. 因此, 在将行从当前行集中删除或插入行时, 游标不会修改行集缓冲区。Thus, when a row is deleted from or inserted into the current rowset, the cursor does not modify the rowset buffers. 相反, 它会在提取之前包含已删除行的任何行集时检测更改, 或者现在包含插入的行。Instead, it detects the change when it fetches any rowset that previously included the deleted row or now includes the inserted row.

例如:For example:

// 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) 的新行集时, 在计算新行集的起始位置。When SQLFetchScroll returns a new rowset that has a position relative to the current rowset - that is, FetchOrientation is SQL_FETCH_NEXT, SQL_FETCH_PRIOR, or SQL_FETCH_RELATIVE - it does not include changes to the current rowset when calculating the starting position of the new rowset. 但是, 如果在当前行集的外部进行了更改, 它就会包含这些更改。However, it does include changes outside the current rowset if it is capable of detecting them. 此外, 当SQLFetchScroll返回一个新行集, 它具有独立于当前行集的位置 (即, FETCHORIENTATION 为 SQL_FETCH_FIRST、SQL_FETCH_LAST、SQL_FETCH_ABSOLUTE 或 SQL_FETCH_BOOKMARK) 时, 它将包含所有更改可以检测, 即使它们位于当前行集中。Furthermore, when SQLFetchScroll returns a new rowset that has a position independent of the current rowset - that is, FetchOrientation is SQL_FETCH_FIRST, SQL_FETCH_LAST, SQL_FETCH_ABSOLUTE, or SQL_FETCH_BOOKMARK - it includes all changes it is capable of detecting, even if they are in the current rowset.

在确定新添加的行是位于当前行集的内部还是外部时, 会将部分行集视为结束于最后一个有效行;即, 行状态为 "不 SQL_ROW_NOROW" 的最后一行。When determining whether newly added rows are inside or outside the current rowset, a partial rowset is considered to end at the last valid row; that is, the last row for which the row status is not SQL_ROW_NOROW. 例如, 假设游标能够检测新添加的行, 当前行集是部分行集, 应用程序添加新行, 并且游标将这些行添加到结果集的末尾。For example, suppose the cursor is capable of detecting newly added rows, the current rowset is a partial rowset, the application adds new rows, and the cursor adds these rows to the end of the result set. 如果应用程序调用SQLFetchScroll , 并将 FetchOrientation 设置为 SQL_FETCH_NEXT, 则SQLFetchScroll将从第一个新添加的行开始返回行集。If the application calls SQLFetchScroll with FetchOrientation set to SQL_FETCH_NEXT, SQLFetchScroll returns the rowset starting with the first newly added row.

例如, 假设当前行集的行数为21到 30, 行集大小为 10, 游标将删除从结果集中删除的行, 并且游标检测添加到结果集中的行。For example, suppose the current rowset comprises rows 21 to 30, the rowset size is 10, the cursor removes rows deleted from the result set, and the cursor detects rows added to the result set. 下表显示了在各种情况下SQLFetchScroll返回的行。The following table shows the rows SQLFetchScroll returns in various situations.

更改Change 提取类型Fetch type FetchOffsetFetchOffset 新行集 [1]New rowset[1]
删除第21行Delete row 21 NEXTNEXT 00 31到4031 to 40
删除第31行Delete row 31 NEXTNEXT 00 32至4132 to 41
在第21行和第22行之间插入行Insert row between rows 21 and 22 NEXTNEXT 00 31到4031 to 40
在行30和31之间插入行Insert row between rows 30 and 31 NEXTNEXT 00 插入的行, 31 到39Inserted row, 31 to 39
删除第21行Delete row 21 PRIORPRIOR 00 11到2011 to 20
删除第20行Delete row 20 PRIORPRIOR 00 10到1910 to 19
在第21行和第22行之间插入行Insert row between rows 21 and 22 PRIORPRIOR 00 11到2011 to 20
在行20和21之间插入行Insert row between rows 20 and 21 PRIORPRIOR 00 12到20个, 插入的行12 to 20, inserted row
删除第21行Delete row 21 RELATIVERELATIVE 00 22到 31[2]22 to 31[2]
删除第21行Delete row 21 RELATIVERELATIVE 11 22到3122 to 31
在第21行和第22行之间插入行Insert row between rows 21 and 22 RELATIVERELATIVE 00 21, 插入行, 22 到2921, inserted row, 22 to 29
在第21行和第22行之间插入行Insert row between rows 21 and 22 RELATIVERELATIVE 11 22到3122 to 31
删除第21行Delete row 21 ABSOLUTEABSOLUTE 2121 22到 31[2]22 to 31[2]
删除第22行Delete row 22 ABSOLUTEABSOLUTE 2121 21、23到3121, 23 to 31
在第21行和第22行之间插入行Insert row between rows 21 and 22 ABSOLUTEABSOLUTE 2222 插入的行, 22 到29Inserted row, 22 to 29

[1] 在插入或删除任何行之前, 此列使用行号。[1] This column uses the row numbers before any rows were inserted or deleted.

[2] 在本例中, 游标尝试返回第21行开始的行。[2] In this case, the cursor attempts to return rows starting with row 21. 由于已删除第21行, 因此它返回的第一行是第22行。Because row 21 has been deleted, the first row it returns is row 22.

错误行 (即状态为 SQL_ROW_ERROR 的行) 不会影响游标移动。Error rows (that is, rows with a status of SQL_ROW_ERROR) do not affect cursor movement. 例如, 如果当前行集从第11行开始, 而第11行的状态为 SQL_ROW_ERROR, 则调用SQLFetchScroll并将 FetchOrientation 设置为 SQL_FETCH_RELATIVE, 并将 FetchOffset 设置为5将返回第16行开始的行集, 就像第11行的状态为 SQL_SUCCESS。For example, if the current rowset starts with row 11 and the status of row 11 is SQL_ROW_ERROR, calling SQLFetchScroll with FetchOrientation set to SQL_FETCH_RELATIVE and FetchOffset set to 5 returns the rowset starting with row 16, just as it would if the status for row 11 was SQL_SUCCESS.

返回绑定列中的数据Returning Data in Bound Columns

SQLFetchScroll以与SQLFetch相同的方式返回绑定列中的数据。SQLFetchScroll returns data in bound columns in the same way as SQLFetch. 有关详细信息, 请参阅SQLFetch 函数中的 "返回绑定列中的数据"。For more information, see "Returning Data in Bound Columns" in SQLFetch Function.

如果未绑定列, 则SQLFetchScroll不返回数据, 而是将块光标移至指定位置。If no columns are bound, SQLFetchScroll does not return data but does move the block cursor to the specified position. 是否可以使用SQLGetData从块游标的未绑定列检索数据取决于驱动程序。Whether data can be retrieved from unbound columns of a block cursor with SQLGetData depends on the driver. 如果对SQLGetInfo的调用返回 SQL_GETDATA_EXTENSIONS 信息类型的 SQL_GD_BLOCK 位, 则支持此功能。This capability is supported if a call to SQLGetInfo returns the SQL_GD_BLOCK bit for the SQL_GETDATA_EXTENSIONS information type.

缓冲区地址Buffer Addresses

SQLFetchScroll使用相同的公式来确定数据和长度/指示器缓冲区为SQLFetch的地址。SQLFetchScroll uses the same formula to determine the address of data and length/indicator buffers as SQLFetch. 有关详细信息, 请参阅SQLBindCol 函数中的 "缓冲区地址"。For more information, see "Buffer Addresses" in SQLBindCol Function.

行状态数组Row Status Array

SQLFetchScroll以与 SQLFetch 相同的方式设置行状态数组中的值。SQLFetchScroll sets values in the row status array in the same manner as SQLFetch. 有关详细信息, 请参阅SQLFetch 函数中的 "行状态数组"。For more information, see "Row Status Array" in SQLFetch Function.

提取的行缓冲区Rows Fetched Buffer

SQLFetchScroll以与SQLFetch相同的方式返回在提取的行中提取的行数。SQLFetchScroll returns the number of rows fetched in the rows fetched buffer in the same manner as SQLFetch. 有关详细信息, 请参阅SQLFetch 函数中的 "提取的行数"。For more information, see "Rows Fetched Buffer" in SQLFetch Function.

错误处理Error Handling

当应用程序在 ODBC 1.x 驱动程序中调用SQLFetchScroll时, 驱动程序管理器将在驱动程序中调用SQLFetchScrollWhen an application calls SQLFetchScroll in an ODBC 3.x driver, the Driver Manager calls SQLFetchScroll in the driver. 当应用程序在 ODBC 2.x 驱动程序中调用SQLFetchScroll时, 驱动程序管理器将在驱动程序中调用 SQLExtendedFetch。When an application calls SQLFetchScroll in an ODBC 2.x driver, the Driver Manager calls SQLExtendedFetch in the driver. 由于SQLFetchScroll和 SQLExtendedFetch 以略有不同的方式处理错误, 因此当应用程序在 odbc 2.X 和 odbc 2.x 驱动程序中调用SQLFetchScroll时, 会看到略微不同的错误行为。Because SQLFetchScroll and SQLExtendedFetch handle errors in a slightly different manner, the application sees slightly different error behavior when it calls SQLFetchScroll in ODBC 2.x and ODBC 3.x drivers.

SQLFetchScroll返回错误和警告的方式与SQLFetch相同;有关详细信息, 请参阅SQLFetch中的 "错误处理"。SQLFetchScroll returns errors and warnings in the same manner as SQLFetch; for more information, see "Error Handling" in SQLFetch. SQLExtendedFetch返回错误的方式与SQLFetch相同, 但以下情况除外:SQLExtendedFetch returns errors in the same manner as SQLFetch, with the following exceptions:

当发生适用于行集中特定行的警告时, SQLExtendedFetch 会将行状态数组中的相应条目设置为 SQL_ROW_SUCCESS, 而不是 SQL_ROW_SUCCESS_WITH_INFO。When a warning occurs that applies to a particular row in the rowset, SQLExtendedFetch sets the corresponding entry in the row status array to SQL_ROW_SUCCESS, not SQL_ROW_SUCCESS_WITH_INFO.

如果行集中的每一行发生错误, 则 SQLExtendedFetch 将返回 SQL_SUCCESS_WITH_INFO, 而不是 SQL_ERROR。If errors occur in every row in the rowset, SQLExtendedFetch returns SQL_SUCCESS_WITH_INFO, not SQL_ERROR.

在适用于单个行的每一组状态记录中, SQLExtendedFetch 返回的第一个状态记录必须包含 SQLSTATE 01S01 (行中的错误);SQLFetchScroll不会返回此 SQLSTATE。In each group of status records that applies to an individual row, the first status record returned by SQLExtendedFetch must contain SQLSTATE 01S01 (Error in row); SQLFetchScroll does not return this SQLSTATE. 如果 SQLExtendedFetch 无法返回其他 SQLSTATEs, 它仍必须返回此 SQLSTATE。If SQLExtendedFetch is unable to return additional SQLSTATEs, it still must return this SQLSTATE.

SQLFetchScroll 和开放式并发SQLFetchScroll and Optimistic Concurrency

如果游标使用乐观并发, 即 SQL_ATTR_CONCURRENCY 语句特性的值为 SQL_CONCUR_VALUES 或 SQL_CONCUR_ROWVER, 则会更新数据源使用的开放式并发值, 以检测是否行已更改。If a cursor uses optimistic concurrency - that is, the SQL_ATTR_CONCURRENCY statement attribute has a value of SQL_CONCUR_VALUES or SQL_CONCUR_ROWVER - SQLFetchScroll updates the optimistic concurrency values used by the data source to detect whether a row has changed. 只要SQLFetchScroll提取新行集, 就会发生这种情况, 包括 refetches 当前行集。This happens whenever SQLFetchScroll fetches a new rowset, including when it refetches the current rowset. (将 FetchOrientation 设置为 SQL_FETCH_RELATIVE, 并将 FetchOffset 设置为0。)(It is called with FetchOrientation set to SQL_FETCH_RELATIVE and FetchOffset set to 0.)

SQLFetchScroll 和 ODBC 2.x 驱动程序SQLFetchScroll and ODBC 2.x Drivers

当应用程序在 ODBC 2.x 驱动程序中调用SQLFetchScroll时, 驱动程序管理器会将此调用映射到SQLExtendedFetchWhen an application calls SQLFetchScroll in an ODBC 2.x driver, the Driver Manager maps this call to SQLExtendedFetch. 它为SQLExtendedFetch的参数传递以下值。It passes the following values for the arguments of SQLExtendedFetch.

SQLExtendedFetch 参数SQLExtendedFetch argument Value
StatementHandleStatementHandle SQLFetchScroll中的 StatementHandle。StatementHandle in SQLFetchScroll.
FetchOrientationFetchOrientation SQLFetchScroll中的 FetchOrientation。FetchOrientation in SQLFetchScroll.
FetchOffsetFetchOffset 如果 FetchOrientation 不是 SQL_FETCH_BOOKMARK, 则使用SQLFetchScroll中的 FetchOffset 参数的值。If FetchOrientation is not SQL_FETCH_BOOKMARK, the value of the FetchOffset argument in SQLFetchScroll is used.

如果 FetchOrientation 为 SQL_FETCH_BOOKMARK, 则使用存储在由 SQL_ATTR_FETCH_BOOKMARK_PTR 语句特性指定的地址的值。If FetchOrientation is SQL_FETCH_BOOKMARK, the value stored at the address specified by the SQL_ATTR_FETCH_BOOKMARK_PTR statement attribute is used.
RowCountPtrRowCountPtr SQL_ATTR_ROWS_FETCHED_PTR 语句特性指定的地址。The address specified by the SQL_ATTR_ROWS_FETCHED_PTR statement attribute.
RowStatusArrayRowStatusArray SQL_ATTR_ROW_STATUS_PTR 语句特性指定的地址。The address specified by the SQL_ATTR_ROW_STATUS_PTR statement attribute.

有关详细信息, 请参阅附录 G 中的块游标、可滚动游标和后向兼容性:向后兼容的驱动程序准则。For more information, see Block Cursors, Scrollable Cursors, and Backward Compatibility in Appendix G: Driver Guidelines for Backward Compatibility.

描述符和 SQLFetchScrollDescriptors and SQLFetchScroll

SQLFetchScroll与描述符的交互方式与SQLFetch相同。SQLFetchScroll interacts with descriptors in the same manner as SQLFetch. 有关详细信息, 请参阅SQLFetch 函数中的 "描述符和 SQLFetchScroll" 部分。For more information, see the "Descriptors and SQLFetchScroll" section in SQLFetch Function.

代码示例Code Example

请参阅按列绑定、按行绑定定位更新和删除语句, 并通过 SQLSetPos 更新行集中的行See Column-Wise Binding, Row-Wise Binding, Positioned Update and Delete Statements, and Updating Rows in the Rowset with SQLSetPos.

有关信息For information about 请参阅See
将缓冲区绑定到结果集中的列Binding a buffer to a column in a result set SQLBindCol 函数SQLBindCol Function
执行 bulk insert、update 或 delete 操作Performing bulk insert, update, or delete operations SQLBulkOperations 函数SQLBulkOperations Function
正在取消语句处理Canceling statement processing SQLCancel 函数SQLCancel Function
返回有关结果集中的列的信息Returning information about a column in a result set SQLDescribeCol 函数SQLDescribeCol Function
执行 SQL 语句Executing an SQL statement SQLExecDirect 函数SQLExecDirect Function
执行已准备的 SQL 语句Executing a prepared SQL statement SQLExecute 函数SQLExecute Function
按只进方向提取单个行或数据块Fetching a single row or a block of data in a forward-only direction SQLFetch 函数SQLFetch Function
在语句上关闭游标Closing the cursor on the statement SQLFreeStmt 函数SQLFreeStmt Function
返回结果集列的数目Returning the number of result set columns SQLNumResultCols 函数SQLNumResultCols Function
定位游标, 刷新行集中的数据, 或更新或删除结果集中的数据Positioning the cursor, refreshing data in the rowset, or updating or deleting data in the result set SQLSetPos 函数SQLSetPos Function
设置语句特性Setting a statement attribute SQLSetStmtAttr 函数SQLSetStmtAttr Function

请参阅See Also

ODBC API 参考 ODBC API Reference
ODBC 头文件ODBC Header Files