2012-04-01

sp_cursorfetch (Transact-SQL)

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

主题链接图标 Transact-SQL 语法约定

语法

        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 行组成的上一个缓冲区。注意将 PREV 用于 FORWARD_ONLY 游标将返回一条错误消息，因为 FORWARD_ONLY 仅支持单向滚动。
0x0008	LAST	提取由 nrows 行组成的最后一个缓冲区。如果 nrows 等于 0，则游标位于结果集的后面且不返回行。注意将 LAST 用于 FORWARD_ONLY 游标将返回一条错误消息，因为 FORWARD_ONLY 仅支持单向滚动。
0x10	ABSOLUTE	提取由 nrows 行组成的缓冲区（从 rownum 行开始）。注意将 ABSOLUTE 用于 DYNAMIC 游标或 FORWARD_ONLY 游标将返回一条错误消息，因为 FORWARD_ONLY 仅支持单向滚动。
0x20	RELATIVE	提取由 nrows 行组成的缓冲区（在当前块中的第一行中，从指定作为各行的 rownum 值的行开始）。在这种情况下，rownum 可为负数。注意将 RELATIVE 用于 FORWARD_ONLY 游标将返回一条错误消息，因为 FORWARD_ONLY 仅支持单向滚动。
0x80	REFRESH	重新填充基础表中的缓冲区。
0x100	INFO	检索有关游标的信息。通过使用 rownum 和 nrows 参数返回该信息。因此，如果指定 INFO，则 rownum 和 nrows 将成为输出参数。
0x200	PREV_NOADJUST	用法类似于 PREV。但是，如果过早遇到结果集顶部，结果可能有所不同。
0x400	SKIP_UPDT_CNCY	必须与其他 fetchtype 值之一一起使用，INFO 除外。

注意
不支持值 0x40。

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

rownum
一个可选参数，用于通过只将整数值用于输入或输出或同时用于两者，为 ABSOLUTE 和 INFO fetchtype 值指定行位置。rownum 用作 fetchtype 位值 RELATIVE 的行偏移。对于所有其他值，将忽略 rownum。有关详细信息，请参阅本主题后面的“备注”部分。
nrows
一个可选参数，用于指定要提取的行数。如果没有指定 nrows，则默认值为 20 行。若要设置位置而不返回数据，则指定值为 0。当 nrows 应用于 fetchtype INFO 查询时，它将返回该查询中的总行数。

注意

REFRESH fetchtype 位值将忽略 nrows。

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

注意
REFRESH fetchtype 位值将忽略 nrows。有关详细信息，请参阅本主题后面的“备注”部分。

返回代码值

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

注意
：如果不返回行，则缓冲区内容保持不变。

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

如果未打开

对于 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 表示 rownum 在整个结果集内的位置。具有 ABSOLUTE 的负数指定该操作从结果集的末尾开始对行进行计数。

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

nrows 参数

fetchtype 值 REFRESH 和 INFO 忽略该参数。

当您指定 FIRST（具有 nrow 值 0）的 fetchtype 值时，游标定位在提取缓冲区中不包含行的结果集的前面。

当您指定 LAST（具有 nrow 值 0）的 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

接下来，具有 nrows 值 5 的 sp_cursorfetch PREV 在逻辑上将游标定位于结果集第一行的前两行。在此类情况下，游标将调整为从第一行开始，并返回请求的行数。这通常意味着它将返回位于 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

通过