SQL Server SQLFetch()

{

/*

摘要
SQLFetch从结果集中提取下一个数据行集, 并返回所有绑定列的数据。

语法

  
SQLRETURN SQLFetch(  
     SQLHSTMT     StatementHandle);  

参数

StatementHandle
送语句句柄。

返回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_STILL_EXECUTING、SQL_ERROR 或 SQL_INVALID_HANDLE。

诊断

当SQLFetch返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时, 可以通过使用SQLGetDiagRec 的 HandleType和 SQL_HANDLE_STMT 的句柄调用StatementHandle 函数来获取关联的 SQLSTATE 值。 下表列出了通常由SQLFetch返回的 SQLSTATE 值, 并对该函数的上下文中的每个值进行了说明:"(DM)" 表示法位于驱动程序管理器返回的 SQLSTATEs 的说明之前。 除非另有说明, 否则与每个 SQLSTATE 值相关联的返回代码为 SQL_ERROR。 如果对单个列发生错误, 则可以使用 SQL_DIAG_COLUMN_NUMBER 的DiagIdentifier调用SQLGetDiagField , 以确定发生错误的列;可以使用 SQL_DIAG_ROW_NUMBER 的DiagIdentifier调用和SQLGetDiagField来确定包含该列的行。

对于可以返回 SQL_SUCCESS_WITH_INFO 或 SQL_ERROR 的所有 SQLSTATEs (除了 01xxx SQLSTATEs), 如果在一个或多个 (但不是全部) 行上发生错误, 则将返回 SQL_SUCCESS_WITH_INFO; 如果发生错误, 则返回多行单行操作。

注释

SQLFetch返回结果集中的下一个行集。 它只能在结果集存在时调用: 即, 在创建结果集的调用之后, 在该结果集上的游标结束之前。 如果绑定了任何列, 则它会返回这些列中的数据。 如果应用程序已指定一个指向行状态数组或缓冲区的指针 (在其中返回提取的行数), SQLFetch也将返回此信息。 对SQLFetch的调用可以与对SQLFetchScroll的调用混合, 但不能与对SQLExtendedFetch的调用混合。 有关详细信息, 请参阅提取数据行。

如果 ODBC1.x 应用程序适用于 odbc2.x 驱动程序, 则驱动程序管理器会将SQLFetch调用映射到支持SQLExtendedFetch的 odbc 2.x驱动程序的SQLExtendedFetch 。 如果 ODBC2.x 驱动程序不支持SQLExtendedFetch, 则驱动程序管理器会将SQLFetch调用映射到 ODBC2.x 驱动程序中的SQLFetch , 该驱动程序只能提取一行。

有关详细信息, 请参阅附录 G 中的块游标、可滚动游标和后向兼容性:向后兼容的驱动程序准则。

定位光标

创建结果集时, 游标将定位在结果集的开始位置之前。 SQLFetch提取下一个行集。 它等效于调用SQLFetchScroll , 并将FETCHORIENTATION设置为 SQL_FETCH_NEXT。 有关游标的详细信息, 请参阅游标和块游标。

SQL_ATTR_ROW_ARRAY_SIZE 语句特性指定行集中的行数。 如果SQLFetch提取的行集与结果集的末尾重叠, 则SQLFetch将返回部分行集。 也就是说, 如果 S + R-1 大于 L, 其中 S 是要提取的行集的起始行, 则 R 是行集的大小, L 是结果集中的最后一行, 则仅行集的第一 L + 1 行是有效的。 其余行为空, 状态为 "SQL_ROW_NOROW"。

SQLFetch返回后, 当前行是行集的第一行。

下表中列出的规则根据此部分的第二个表中列出的条件, 描述了调用SQLFetch后的游标定位。

[1] 如果行集大小在提取之间发生更改, 则这是与上一次提取一起使用的行集大小。

[2] 如果行集大小在提取之间发生更改, 则这是用于新提取的行集大小。

例如, 假设有一个结果集包含100行, 行集大小为5。 下表显示了SQLFetch为不同起始位置返回的行集和返回代码。

返回绑定列中的数据

当SQLFetch返回每行时, 它会将绑定到该列的缓冲区中的每个绑定列的数据放入其中。 如果没有绑定列, SQLFetch将不返回任何数据, 而是向前移动块游标。 仍可使用SQLGetData检索数据。 如果游标是多行游标 (即, SQL_ATTR_ROW_ARRAY_SIZE 大于 1), 则只有当使用SQLGetInfo 的 InfoType调用SQL_GETDATA_EXTENSIONS时, 才能调用SQLGetData 。 (有关详细信息, 请参阅SQLGetData。)

对于行中的每个绑定列, SQLFetch执行以下操作:

1. 将长度/指示器缓冲区设置为 SQL_NULL_DATA, 如果数据为 NULL, 则转到下一列。 如果数据为空且未绑定长度/指示器缓冲区, 则SQLFetch将返回行的 SQLSTATE 22002 (需要指示器变量, 但未提供), 并转到下一行。 有关如何确定长度/指示器缓冲区的地址的信息, 请参阅SQLBindCol中的 "缓冲区地址"。

   如果列的数据不为 NULL, 则SQLFetch将继续执行步骤2。

2. 如果 SQL_ATTR_MAX_LENGTH 语句特性设置为非零值, 并且列包含字符或二进制数据, 则数据将被截断为 SQL_ATTR_MAX_LENGTH 字节。

   备注

   SQL_ATTR_MAX_LENGTH 语句特性旨在减少网络流量。 它通常由数据源实现, 该数据源通过网络返回数据之前将其截断。 驱动程序和数据源不需要支持。 因此, 若要保证数据被截断到特定大小, 应用程序应分配该大小的缓冲区, 并在SQLBindCol的cbValueMax参数中指定大小。

3. 将数据转换为SQLBindCol中由TargetType指定的类型。

4. 如果将数据转换为可变长度的数据类型 (如字符或二进制), SQLFetch会检查数据长度是否超过数据缓冲区的长度。 如果字符数据的长度 (包括 null 终止字符) 超过了数据缓冲区的长度, 则SQLFetch会将数据截断到数据缓冲区长度减去 null 终止字符的长度。 然后, 它将终止数据。 如果二进制数据的长度超过数据缓冲区的长度, 则SQLFetch会将其截断为数据缓冲区的长度。 数据缓冲区的长度是通过SQLBindCol中的BufferLength指定的。

   SQLFetch从不截断转换为固定长度数据类型的数据;它始终假定数据缓冲区的长度为数据类型的大小。

5. 将转换后的数据 (可能截断后的数据) 放入数据缓冲区。 有关如何确定数据缓冲区的地址的信息, 请参阅SQLBindCol中的 "缓冲区地址"。

6. 将数据的长度放入长度/指示器缓冲区。 如果指示器指针和长度指针均设置为同一个缓冲区 (作为对SQLBindCol的调用), 则在缓冲区中写入有效数据的长度, 并且在缓冲区中写入 NULL 数据。 如果没有绑定长度/指示器缓冲区, 则SQLFetch不返回长度。

   • 对于字符或二进制数据, 这是转换后的数据长度, 在截断之前, 因为数据缓冲区太小。 如果驱动程序在转换后无法确定数据的长度, 有时会出现长数据的情况, 它会将长度设置为 SQL_NO_TOTAL。 如果由于 SQL_ATTR_MAX_LENGTH 语句特性而导致数据被截断, 则此属性的值将放入长度/指示器缓冲区而不是实际长度中。 这是因为该属性设计为在转换前截断服务器上的数据, 以便驱动程序无法确定实际长度。

   • 对于所有其他数据类型, 这是转换后的数据长度;也就是说, 它是数据转换到的类型的大小。

   有关如何确定长度/指示器缓冲区的地址的信息, 请参阅SQLBindCol中的 "缓冲区地址"。

7. 如果在转换过程中数据被截断 (例如, 在转换时将实数1.234 截断为整数 1), 则SQLFetch将返回 SQLSTATE 01S07 (小数截断) 和 SQL_SUCCESS_WITH_INFO。 如果由于数据缓冲区的长度太小 (例如, 字符串 "abcdef" 放在4字节缓冲区中) 而导致数据被截断, 则SQLFetch将返回 SQLSTATE 01004 (数据截断) 和 SQL_SUCCESS_WITH_INFO。 如果由于 SQL_ATTR_MAX_LENGTH 语句特性而导致数据被截断, 则SQLFetch将返回 SQL_SUCCESS, 而不会返回 SQLSTATE 01S07 (分段截断) 或 SQLSTATE 01004 (数据截断)。 如果在转换过程中数据被截断 (例如, 如果将大于100000的 SQL_INTEGER 值转换为 SQL_C_TINYINT), 则SQLFetch将返回 SQLSTATE 22003 (数值超出范围) 和 SQL_ERROR (如果行集大小为 1) 或 SQL_SUCCESS_WITH_INFO (如果行集大小大于 1)。

如果SQLFetch或SQLFETCHSCROLL未返回 SQL_SUCCESS 或 SQL_SUCCESS_WITH_INFO, 则绑定数据缓冲区和长度/指示器缓冲区的内容不确定。

行状态数组

行状态数组用于返回行集中每行的状态。 此数组的地址是用 SQL_ATTR_ROW_STATUS_PTR 语句特性指定的。 数组由应用程序分配, 并且必须具有与 SQL_ATTR_ROW_ARRAY_SIZE 语句特性指定的数目相同的元素。 它的值由SQLFetch、 SQLFetchScroll和SQLBulkOperations或SQLSetPos设置 (在游标由SQLExtendedFetch定位后调用时除外)。 如果 SQL_ATTR_ROW_STATUS_PTR 语句特性的值为 null 指针, 则这些函数不返回行状态。

如果SQLFetch或SQLFETCHSCROLL未返回 SQL_SUCCESS 或 SQL_SUCCESS_WITH_INFO, 则不定义行状态数组缓冲区的内容。

行状态数组中将返回以下值。

[1] 对于键集、混合和动态游标, 如果更新键值, 则会将数据行视为已被删除并添加新行。

[2] 某些驱动程序无法检测到数据的更新, 因此无法返回此值。 若要确定驱动程序是否可以检测到制约行的更新, 应用程序将使用 SQL_ROW_UPDATES 选项调用SQLGetInfo 。

[3] SQLFetch只能在与对SQLFetchScroll的调用混合时返回此值。 这是因为SQLFetch会在结果集中向前移动, 并在独占使用时, 不重新提取任何行。 由于没有制约的行, SQLFetch不检测对以前提取的行所做的更改。 但是, 如果SQLFetchScroll将游标定位在之前提取的行之前, 并使用SQLFetch提取这些行, 则SQLFetch可以检测对这些行所做的任何更改。

[4] 仅由 SQLBulkOperations 返回。 不是由SQLFetch或SQLFetchScroll设置的。

提取的行缓冲区

"提取的行" 缓冲区用于返回提取的行数, 包括因为在提取数据时出错而未返回数据的行数。 换言之, 它是行状态数组中的值不是 SQL_ROW_NOROW 的行数。 此缓冲区的地址是用 SQL_ATTR_ROWS_FETCHED_PTR 语句特性指定的。 缓冲区由应用程序分配。 它由SQLFetch和SQLFetchScroll设置。 如果 SQL_ATTR_ROWS_FETCHED_PTR 语句特性的值为 null 指针, 则这些函数不返回提取的行数。 若要确定结果集中的当前行数, 应用程序可以使用 SQL_ATTR_ROW_NUMBER 属性调用SQLGetStmtAttr 。

如果SQLFetch或SQLFETCHSCROLL不返回 SQL_SUCCESS 或 SQL_SUCCESS_WITH_INFO (返回 SQL_NO_DATA 时除外), 则提取的行的内容将不确定, 在这种情况下, 提取缓冲区的行中的值将设置为0。

错误处理

错误和警告可应用于单个行或整个函数。 有关诊断记录的详细信息, 请参阅诊断和SQLGetDiagField。

针对整个函数的错误和警告

如果错误适用于整个函数 (如 SQLSTATE HYT00 (超时时间已过期) 或 SQLSTATE 24000 (无效的游标状态), 则SQLFetch返回 SQL_ERROR 和适用的 SQLSTATE。 行集缓冲区的内容未定义, 并且光标位置保持不变。

如果警告适用于整个函数, 则SQLFetch将返回 SQL_SUCCESS_WITH_INFO 和适用的 SQLSTATE。 适用于整个函数的警告的状态记录将在应用于单个行的状态记录之前返回。

各个行中的错误和警告

如果错误 (如 SQLSTATE 22012 (被零除)) 或警告 (例如 SQLSTATE 01004 (数据已截断)) 或警告 (例如, 已截断的数据), 则SQLFetch将执行以下操作:

• 将行状态数组的相应元素设置为 SQL_ROW_ERROR 以查看错误, 或将 SQL_ROW_SUCCESS_WITH_INFO 设置为。

• 添加零个或多个包含 SQLSTATEs 错误或警告的状态记录。

• 设置状态记录中的行号和列号字段。 如果SQLFetch无法确定行号或列号, 则会将该数字分别设置为 SQL_ROW_NUMBER_UNKNOWN 或 SQL_COLUMN_NUMBER_UNKNOWN。 如果状态记录不适用于特定列, 则SQLFetch会将列号设置为 SQL_NO_COLUMN_NUMBER。

SQLFetch在提取行集中的所有行之前继续提取行。 它将返回 SQL_SUCCESS_WITH_INFO, 除非行集的每一行中发生错误 (不包括状态为 SQL_ROW_NOROW 的行), 在这种情况下, 它将返回 SQL_ERROR。 具体而言, 如果行集的大小为 1, 并且该行发生错误, 则SQLFetch将返回 SQL_ERROR。

SQLFetch按行号顺序返回状态记录。 也就是说, 它返回未知行 (如果有) 的所有状态记录;接下来, 它返回第一行 (如果有) 的所有状态记录, 然后返回第二行 (如果有) 的所有状态记录, 依此类推。 每行的状态记录根据排序状态记录的普通规则进行排序;有关详细信息, 请参阅SQLGetDiagField中的 "状态记录序列"。

描述符和 SQLFetch

以下各节介绍了SQLFetch如何与描述符交互。

参数映射

该驱动程序不根据SQLFetch的参数设置任何描述符字段。

其他描述符字段

SQLFetch使用以下描述符字段。

所有描述符字段也可以通过SQLSetDescField设置。

分隔长度和指示器缓冲区

应用程序可以绑定单个缓冲区或两个单独的缓冲区, 这些缓冲区可用于保存长度和指示器值。 当应用程序调用SQLBindCol时, 驱动程序会将 ARD 的 SQL_DESC_OCTET_LENGTH_PTR 和 SQL_DESC_INDICATOR_PTR 字段设置为在StrLen_or_IndPtr参数中传递的同一地址。 当应用程序调用SQLSetDescField或SQLSetDescRec时, 它可以将这两个字段设置为不同地址。

SQLFetch确定应用程序是否指定了单独的长度和指示器缓冲区。 在这种情况下, 当数据不为 NULL 时, SQLFetch会将指示器缓冲区设置为 0, 并返回长度缓冲区中的长度。 当数据为 NULL 时, SQLFetch会将指示器缓冲区设置为 SQL_NULL_DATA, 并且不会修改长度缓冲区。

代码示例

请参阅SQLBindCol、 SQLColumns、 SQLGetData和SQLProcedures。

相关函数

请参阅

ODBC API 参考
ODBC 头文件

*/

}

原文地址：https://www.cnblogs.com/YZFHKMS-X/p/11831372.html