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 函数

另请参阅

ODBC API 参考
ODBC 头文件