sp_cursorfetch (Transact-SQL)

项目
07/05/2024

从数据库中提取由一行或多行组成的缓冲区。此缓冲区中的行组称为游标的 提取缓冲区。通过在表格数据流（TDS）数据包中指定 ID = 7 来调用sp_cursorfetch。

语法

  
sp_cursorfetch cursor  
    [ , fetchtype[ , rownum [ , nrows] ]]

参数

cursor
SQL Server 生成的句柄值，由sp_cursoropen返回。 cursor 是调用 int 输入值的必需参数。有关详细信息，请参阅本主题后面的“备注”部分。

fetchtype
指定要提取的游标缓冲区。 fetchtype 是一个可选参数，需要以下整数输入值之一。

值	名称	描述
0x0001	FIRST	提取 nrows 行的第一个缓冲区。如果 nrows 等于 0，则游标位于结果集之前，不返回任何行。
0x0002	NEXT	提取 nrows 行的下一个缓冲区。
0x0004	PREV	提取 nrows 行的上一个缓冲区。注意：对FORWARD_ONLY游标使用 PREV 将返回错误消息，因为FORWARD_ONLY仅支持向一个方向滚动。
0x0008	LAST	提取 nrows 行的最后一个缓冲区。如果 nrows 等于 0，则游标位于结果集之后，不返回任何行。注意：对FORWARD_ONLY游标使用 LAST 将返回错误消息，因为FORWARD_ONLY仅支持向一个方向滚动。
0x10	ABSOLUTE	提取以行号行开头的 nrows* 行的*缓冲区。注意：对动态游标或FORWARD_ONLY游标使用 ABSOLUTE 将返回错误消息，因为FORWARD_ONLY仅支持向一个方向滚动。
0x20	RELATIVE	从指定为当前块中第一行的行的行数值开始提取 nrows 行的缓冲区。在这种情况下，rownum 可以是负数。注意：对FORWARD_ONLY游标使用 RELATIVE 将返回错误消息，因为FORWARD_ONLY仅支持向一个方向滚动。
0x80	REFRESH	重新填充基础表中的缓冲区。
0x100	INFO	检索有关游标的信息。此信息是使用 rownum 和 nrows 参数返回的。因此，当指定 INFO 时， rownum 和 nrows 将成为输出参数。
0x200	PREV_NOADJUST	用法类似于 PREV。但是，如果过早遇到结果集顶部，结果可能有所不同。
0x400	SKIP_UPDT_CNCY	必须与 INFO 以外的其他提取类型值之一一一起使用。

注意

不支持值 0x40。

有关详细信息，请参阅本主题后面的“备注”部分。

rownum
是一个可选参数，用于仅对输入或输出使用整数值来指定 ABSOLUTE 和 INFO 提取类型 值的行位置。 rownum 用作 fetchtype 位值 RELATIVE 的行偏移量。 对于所有其他值，将忽略 rownum 。有关详细信息，请参阅本主题后面的“备注”部分。

nrows
一个可选参数，用于指定要提取的行数。如果未 指定 nrows ，则默认值为 20 行。若要在不返回数据的情况下设置位置，请指定值 0。当 nrows 应用于 fetchtype INFO 查询时，它将返回该查询中的行总数。

注意

REFRESH fetchtype 位值忽略 nrows。

有关详细信息，请参阅本主题后面的“备注”部分。

返回代码值

当指定位值 INFO 时，以下各表显示可能返回的值。

注意

：如果未返回任何行，则缓冲区内容将保持不变。

<rownum>	设置为
如果未打开	0
如果定位在结果集前面	0
如果定位在结果集后面	-1
对于 KEYSET 游标和 STATIC 游标	结果集中当前位置的绝对行号
对于 DYNAMIC 游标	1
对于 ABSOLUTE	-1 返回集中的最后一行。 -2 返回集中的倒数第二行，依此类推。注意：如果在这种情况下请求提取多个行，则返回结果集的最后两行。

<nrows>	设置为
如果未打开	0
对于 KEYSET 游标和 STATIC 游标	通常为当前键集大小。 -m 如果游标处于异步创建状态，但此时找到 m 行。
对于 DYNAMIC 游标	-1

注解

cursor 参数

在执行任何提取操作之前，游标的默认位置位于结果集第一行的前面。

fetchtype 参数

除SKIP_UPD_CNCY外， fetchtype 值是互斥的。

如果指定 SKIP_UPDT_CNCY，则在提取或刷新行时，时间戳列的值不会写入到键集表中。如果正在更新键集行，则时间戳列的值保持为先前的值。如果正在插入键集行，则时间戳列的值不确定。

对于 KEYSET 游标，这意味着在执行最后一个非跳过 FETCH 的过程中（如果已执行一个），键集表设置了值。否则，将在填充过程中设置值。

对于 DYNAMIC 游标，这意味着如果使用刷新来执行跳过，则它生成与 KEYSET 相同的结果。对于任何其他提取类型，键集表会被截断。这意味着正在插入行，且时间戳列的值不确定。因此，当您针对 DYNAMIC 游标运行 sp_cursorfetch 时，对于除 REFRESH 之外的任何操作应避免使用 SKIP_UPDT_CNCY。

如果由于所请求的游标位置超出结果集而导致提取操作失败，则应将游标位置设置为恰好在最后一行的后面。如果由于所请求的游标位置位于结果集的前面而导致提取操作失败，则应将游标位置设置在第一行的前面。

rownum 参数

使用 rownum 时，缓冲区从指定的行开始填充。

fetchtype 值 ABSOLUTE 是指整个结果集中行号的位置。具有 ABSOLUTE 的负数指定该操作从结果集的末尾开始对行进行计数。

fetchtype 值 RELATIVE 是指行数相对于游标在当前缓冲区开头的位置。具有 RELATIVE 的负数指定该游标从当前游标位置向后计数。

nrows 参数

fetchtype 值 REFRESH 和 INFO 忽略此参数。

当指定具有 nrow 值为 0 的 FIRST 的 fetchtype 值时，游标将定位在提取缓冲区中没有行的结果集之前。

指定 LAST 的 fetchtype 值时，游标位于当前提取缓冲区中没有行的结果集之后。

对于 NEXT、PREV、ABSOLUTE、RELATIVE 和 PREV_NOADJUST 的 fetchtype 值，nrow 值 0 无效。

RPC 注意事项

RPC 返回状态指示键集大小参数是否为最终的（也即，键集表或临时表是否异步填充）。

RPC 状态参数设置为下表中显示的值之一。

值	说明
0	过程已成功执行。
0x0001	过程失败。
0x0002	当处于负方向中的提取在逻辑上应位于结果集前面时，该提取可能导致将游标位置设置在结果集的开头。
0x10	快进游标自动关闭。

这些行将作为典型的结果集返回，也即：列格式 (0x2a)、行 (0xd1)，后跟完成 (0xfd)。元数据标记使用与为 sp_cursoropen 指定的相同格式发送，也即：对于 SQL Server 7.0 用户为 0x81、0xa5 和 0xa4 等。行状态指示器在具有列名称 rowstat 和数据类型 INT4 的每一行的末尾作为隐藏列发送（类似于 BROWSE 模式）。此 rowstat 列具有下表中显示的值之一。

值	说明
0x0001	FETCH_SUCCEEDED
0x0002	FETCH_MISSING

因为 TDS 协议不提供发送尾随状态列而不发送先前列的方法，所以为缺少的行发送虚数据（根据需要，将可以为 Null 的字段设置为 Null，将固定长度的字段设置为 0、空白或该列的默认值）。

DONE 行计数将始终为零。 DONE 消息包含实际结果集行计数，在任何 TDS 消息之间可能出现错误消息或信息性消息。

若要请求在 TDS 流中返回有关游标选择列表的元数据，请将 RPC RETURN_METADATA 输入标志设置为 1。

示例

A. 使用 PREV 更改游标位置

假定游标 h2 将生成具有以下内容的结果集，且当前位置如下所示：

row 1 contents      
row 2 contents  
row 3 contents  
row 4 contents  <-- current position  
row 5 contents   
row 6 contents

接下来，一个sp_cursorfetch PREV，其 nrows 值为 5 会在结果集的第一行之前逻辑定位游标两行。在此类情况下，游标将调整为从第一行开始，并返回请求的行数。这通常意味着它将返回位于 PRIOR 提取缓冲区中的行。

注意

这是 RPC 状态参数设置为 2 时的确切情况。

B. 使用 PREV_NOADJUST 返回少于 PREV 的行

PREV_NOADJUST 从不包括任何位于它返回的行块中当前游标位置或在其之后的行。如果 PREV 在当前位置后返回行，PREV_NOADJUST返回的行数少于在 nrows 中 请求的行数。假设在前面的示例 A 中的位置，应用 PREV 时，sp_cursorfetch（h2、4、1、5）提取以下行：

row1 contents   
row2 contents  
row3 contents  
row4 contents  
row5 contents

但是，应用PREV_NOADJUST时，sp_cursorfetch（h2、512、6、5）仅提取以下行：

row1 contents   
row2 contents  
row3 contents

另请参阅

sp_cursoropen （Transact-SQL）
系统存储过程 (Transact-SQL)

通过