SQLExtendedFetch 函数
一致性
引入的版本：ODBC 1.0 标准符合性：已弃用
摘要
SQLExtendedFetch 从结果集中提取指定的数据行集，并返回所有绑定列的数据。 行集可以在绝对位置或相对位置指定，也可以按书签指定。
注意
在 ODBC 3*.x* 中， SQLExtendedFetch 已替换为 SQLFetchScroll。 ODBC 3*.x* 应用程序不应调用 SQLExtendedFetch;相反，它们应调用 SQLFetchScroll。 使用 ODBC 2*.x* 驱动程序时，驱动程序管理器会将 SQLFetchScroll 映射到 SQLExtendedFetch 。 如果 ODBC 3*.x* 驱动程序想要使用调用它的 ODBC 2*.x* 应用程序，则它们应支持 SQLExtendedFetch 。 有关详细信息，请参阅附录 G：向后兼容性驱动程序指南中的“注释” 和块游标、可滚动游标和向 后兼容性。
语法
SQLRETURN SQLExtendedFetch(
SQLHSTMT StatementHandle,
SQLUSMALLINT FetchOrientation,
SQLLEN FetchOffset,
SQLULEN * RowCountPtr,
SQLUSMALLINT * RowStatusArray);
自变量
StatementHandle
[输入]语句句柄。
FetchOrientation
[输入]提取类型。 这与 SQLFetchScroll 中的 FetchOrientation 相同。
FetchOffset
[输入]要提取的行数。 这与 SQLFetchScroll 中的 FetchOffset 相同，但有一个例外。 SQL_FETCH_BOOKMARK FetchOrientation 时， FetchOffset 是固定长度的书签，而不是书签的偏移量。 换句话说， SQLExtendedFetch 从此参数检索书签，而不是从 SQL_ATTR_FETCH_BOOKMARK_PTR 语句属性检索书签。 它不支持长度可变的书签，并且不支持从书签中提取偏移量 (0) 以外的行集。
RowCountPtr
[输出]指向缓冲区的指针，该缓冲区将返回实际提取的行数。 此缓冲区的使用方式与 SQL_ATTR_ROWS_FETCHED_PTR 语句属性指定的缓冲区相同。 此缓冲区仅由 SQLExtendedFetch 使用。 SQLFetch 或 SQLFetchScroll 不使用它。
RowStatusArray
[输出]指向要在其中返回每行状态的数组的指针。 此数组的使用方式与 SQL_ATTR_ROW_STATUS_PTR 语句属性指定的数组相同。
但是，此数组的地址不存储在 IRD 的SQL_DESC_STATUS_ARRAY_PTR字段中。 此外，在 SQLExtendedFetch 之后调用此数组时，只有 SQLExtendedFetch 和 SQLBulkOperations 使用 SQL_ADD 或 SQLSetPos操作。 SQLFetch 或 SQLFetchScroll 不使用它，SQLBulkOperations 或 SQLSetPos 在 SQLFetch 或 SQLFetchScroll 之后调用它们时也不使用它。 在调用任何提取函数之前调用操作为 SQL_ADD 的 SQLBulkOperations 时，也不会使用它。 换句话说，它仅在语句状态 S7 中使用。 语句状态 S5 或 S6 中不使用它。 有关详细信息，请参阅附录 B：ODBC 状态转换表中的 语句 转换。
应用程序应在 RowStatusArray 参数中提供有效的指针;如果不是，则未定义 SQLExtendedFetch 的行为以及 SQLExtendedFetch 定位游标后对 SQLBulkOperations 或 SQLSetPos 的调用的行为。
返回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
诊断
当 SQLExtendedFetch 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过调用 SQLError 获取关联的 SQLSTATE 值。 下表列出了通常由 SQLExtendedFetch 返回的 SQLSTATE 值，并说明了此函数上下文中的每个值;表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATEs 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。 如果单个列发生错误，则可以使用 diagIdentifier SQL_DIAG_COLUMN_NUMBER 调用 SQLGetDiagField，以确定发生错误的列;可以使用 diagIdentifier SQL_DIAG_ROW_NUMBER 调用 SQLGetDiagField，以确定包含该列的行。
| SQLSTATE | 错误 | 说明 |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 01004 | 字符串数据，右截断 | 为列返回的字符串或二进制数据导致截断非空字符或非 NULL 二进制数据。 如果是字符串值，则将其右截。 如果是数值，则数字的小数部分将被截断。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 01S01 | 行中出现错误 | 提取一行或多行时出错。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 01S06 | 尝试在结果集返回第一个行集之前提取 | 当当前位置超出第一行时，请求的行集与结果集的开头重叠，并且 FetchOrientation SQL_PRIOR或 FetchOrientation 被SQL_RELATIVE为负 FetchOffset ，其绝对值小于或等于当前SQL_ROWSET_SIZE。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 01S07 | 小数截断 | 为列返回的数据被截断。 对于数值数据类型，数字的小数部分被截断。 对于包含时间分量的时间、时间戳和间隔数据类型，时间的小数部分将被截断。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 07006 | 受限数据类型属性冲突 | 无法将数据值转换为 SQLBindCol 中 TargetType 指定的 C 数据类型。 |
| 07009 | 描述符索引无效 | 列 0 与 SQLBindCol 绑定，SQL_ATTR_USE_BOOKMARKS 语句属性设置为 SQL_UB_OFF。 |
| 08S01 | 通信链接失败 | 在函数完成处理之前，驱动程序与驱动程序连接到的数据源之间的通信链接失败。 |
| 22002 | 需要指示器变量，但未提供 | NULL 数据被提取到 SQLBindCol 设置的StrLen_or_IndPtr为空指针的列中。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 22003 | 数值范围外 | 将数值 (返回为一列或多列的数值或字符串) 会导致整个 (而不是小数部分) 部分被截断。 (函数返回 SQL_SUCCESS_WITH_INFO.) 有关详细信息，请参阅附录 D： 数据类型中的间隔和数值数据类型指南 。 |
| 22007 | 日期/时间格式无效 | 结果集中的字符列绑定到日期、时间或时间戳 C 结构，列中的值分别为无效的日期、时间或时间戳。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 22012 | 被零除 | 返回算术表达式中的值，导致被零除。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 22015 | 间隔字段溢出 | 从确切的数字或间隔 SQL 类型分配给间隔 C 类型会导致前导字段中丢失有效位数。 将数据提取到间隔 C 类型时，间隔 C 类型中没有 SQL 类型的值表示形式。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 22018 | 强制转换规范的字符值无效 | C 类型为精确或近似数值、datetime 或 interval 数据类型;列的 SQL 类型为字符数据类型;列中的值不是绑定 C 类型的有效文本。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 24000 | 游标状态无效 | StatementHandle 处于已执行状态，但没有结果集与 StatementHandle 相关联。 |
| HY000 | 常规错误 | 发生错误，其中没有特定的 SQLSTATE，并且没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLError 返回的错误消息描述了错误及其原因。 |
| HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY008 | 操作已取消 | 已为 StatementHandle 启用异步处理。 调用了函数，在它完成执行之前，在 StatementHandle 上调用了 SQLCancel 或 SQLCancelHandle，然后在 StatementHandle 上再次调用该函数。 函数已调用，在它完成执行之前， SQLCancel 或 SQLCancelHandle 是从多线程应用程序中的不同线程在 StatementHandle 上调用的。 |
| HY010 | 函数序列错误 | (DM) 为 与 StatementHandle 关联的连接句柄调用了异步执行的函数。 调用 SQLExtendedFetch 函数时，此异步函数仍在执行。 (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 是在调用 SQLFetch 或 SQLFetchScroll 之后为 StatementHandle 调用的，在使用 SQL_CLOSE 选项调用 SQLFreeStmt 之前。 (DM) SQLBulkOperations 是在调用 SQLFetch、SQLFetchScroll 或 SQLExtendedFetch 之前为语句调用的，然后在使用 SQL_CLOSE 选项调用 SQLFreeStmt 之前调用 SQLExtendedFetch。 |
| HY013 | 内存管理错误 | 无法处理函数调用，因为无法访问基础内存对象，可能是因为内存不足。 |
| HY106 | 提取范围外的类型 | (DM) 为参数 FetchOrientation 指定的值无效。 (请参阅“注释”。) 参数 FetchOrientation 已SQL_FETCH_BOOKMARK，SQL_ATTR_USE_BOOKMARKS 语句属性设置为 SQL_UB_OFF。 SQL_CURSOR_TYPE 语句选项的值已SQL_CURSOR_FORWARD_ONLY，并且未SQL_FETCH_NEXT 参数 FetchOrientation 的值。 参数 FetchOrientation 已SQL_FETCH_RESUME。 |
| HY107 | 行值范围外 | 使用 SQL_CURSOR_TYPE 语句选项指定的值已SQL_CURSOR_KEYSET_DRIVEN，但使用 SQL_KEYSET_SIZE 语句属性指定的值大于 0 且小于使用 SQL_ROWSET_SIZE 语句属性指定的值。 |
| HY111 | 书签值无效 | 参数 FetchOrientation 已SQL_FETCH_BOOKMARK， FetchOffset 参数中指定的书签无效。 |
| HY117 | 由于未知的事务状态，连接已挂起。 仅允许断开连接和只读函数。 | (DM) 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。 |
| HYC00 | 未实现可选功能 | 驱动程序或数据源不支持指定的提取类型。 驱动程序或数据源不支持由 SQLBindCol 中的 TargetType 和相应列的 SQL 数据类型的组合指定的转换。 仅当列的 SQL 数据类型映射到特定于驱动程序的 SQL 数据类型时，此错误才适用。 |
| HYT00 | 超时时间已到 | 查询超时期限在数据源返回结果集之前过期。 超时期限通过 SQLSetStmtOption 设置，SQL_QUERY_TIMEOUT。 |
| HYT01 | 超过连接超时时间 | 在数据源响应请求之前，连接超时期限已过期。 连接超时期限是通过 SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT设置的。 |
| IM001 | 驱动程序不支持此函数 | (DM) 与 StatementHandle 关联的驱动程序不支持 函数。 |
注释
SQLExtendedFetch 的行为与 SQLFetchScroll 的行为相同，但有以下例外情况：
SQLExtendedFetch 和 SQLFetchScroll 使用不同的方法来返回提取的行数。 SQLExtendedFetch 返回 *RowCountPtr; 中提取的行数 SQLFetchScroll 返回直接提取到SQL_ATTR_ROWS_FETCHED_PTR指向的缓冲区的行数。 有关详细信息，请参阅 RowCountPtr 参数。
SQLExtendedFetch 和 SQLFetchScroll 返回不同数组中每一行的状态。 有关详细信息，请参阅 RowStatusArray 参数。
SQL_FETCH_BOOKMARK FetchOrientation 时，SQLExtendedFetch 和 SQLFetchScroll 使用不同的方法来检索书签。 SQLExtendedFetch 不支持可变长度书签，也不支持从书签中提取偏移量为 0 的行集。 有关详细信息，请参阅 FetchOffset 参数。
SQLExtendedFetch 和 SQLFetchScroll 使用不同的行集大小。 SQLExtendedFetch 使用 SQL_ROWSET_SIZE 语句属性的值， SQLFetchScroll 使用 SQL_ATTR_ROW_ARRAY_SIZE 语句属性的值。
SQLExtendedFetch 的错误处理语义与 SQLFetchScroll 略有不同。 有关详细信息，请参阅 SQLFetchScroll 的“注释”部分中的“错误处理”。
SQLExtendedFetch 不支持绑定偏移量 (SQL_ATTR_ROW_BIND_OFFSET_PTR语句属性) 。
对 SQLExtendedFetch 的调用不能与对 SQLFetch 或 SQLFetchScroll 的调用混合，如果在调用任何提取函数之前调用 SQLBulkOperations ，则在关闭并重新打开游标之前，无法调用 SQLExtendedFetch 。 也就是说，只能在语句状态 S7 中调用 SQLExtendedFetch 。 有关详细信息，请参阅附录 B：ODBC 状态转换表中的 语句 转换。
当应用程序在使用 ODBC 2*.x* 驱动程序时调用 SQLFetchScroll 时，驱动程序管理器会将此调用映射到 SQLExtendedFetch。 有关详细信息，请参阅 SQLFetchScroll 中的“ SQLFetchScroll 和 ODBC 2*.x* 驱动程序”。
在 ODBC 2*.x* 中，调用 SQLExtendedFetch 来提取多行，调用 SQLFetch 来提取单个行。 另一方面，在 ODBC 3*.x* 中，可以调用 SQLFetch 来提取多行。
相关函数
| 有关以下方面的信息 | 请参阅 |
|---|---|
| 将缓冲区绑定到结果集中的列 | SQLBindCol 函数 |
| 执行批量插入、更新或删除操作 | SQLBulkOperations 函数 |
| 取消语句处理 | SQLCancel 函数 |
| 返回有关结果集中列的信息 | SQLDescribeCol 函数 |
| 执行 SQL 语句 | SQLExecDirect 函数 |
| 执行准备好的 SQL 语句 | SQLExecute 函数 |
| 返回结果集列数 | SQLNumResultCols 函数 |
| 定位游标、刷新行集中的数据，或者更新或删除结果集中的数据 | SQLSetPos 函数 |
| 设置语句属性 | SQLSetStmtAttr 函数 |