sp_cursorfetch (Transact-SQL)
适用范围：
SQL Server
从数据库中提取由一行或多行组成的缓冲区。 此缓冲区中的行组称为游标的 提取缓冲区。 sp_cursorfetch 通过在表格数据流（TDS）数据包中指定 ID = 7 来调用。
语法
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 行的上一个缓冲区。 注意：用于 PREVFORWARD_ONLY游标会返回错误消息，因为FORWARD_ONLY仅支持在一个方向滚动。 |
0x0008 |
LAST |
提取 nrows 行的最后一个缓冲区。 如果 nrows 等于 0，则游标位于结果集之后，不返回任何行。 注意：用于 LASTFORWARD_ONLY游标会返回错误消息，因为FORWARD_ONLY仅支持在一个方向滚动。 |
0x10 |
ABSOLUTE |
提取以行号行开头的 nrows 行的缓冲区。 注意：对 DYNAMIC游标或FORWARD_ONLY游标使用ABSOLUTE会返回错误消息，因为FORWARD_ONLY仅支持在一个方向滚动。 |
0x20 |
RELATIVE |
从指定为当前块中第一行的行的行数值开始提取 nrows 行的缓冲区。 在这种情况下， rownum 可以是负数。 注意：用于 RELATIVEFORWARD_ONLY游标会返回错误消息，因为FORWARD_ONLY仅支持在一个方向滚动。 |
0x80 |
REFRESH |
重新填充基础表中的缓冲区。 |
0x100 |
INFO |
检索有关游标的信息。 此信息是使用 rownum 和 nrows 参数返回的 。 因此，指定时 INFO ， rownum 和 nrows 将成为输出参数。 |
0x200 |
PREV_NOADJUST |
使用方式如下 PREV。 但是，如果过早遇到结果集顶部，结果可能有所不同。 |
0x400 |
SKIP_UPDT_CNCY |
必须与另 一个 fetchtype 值一起使用，但除外 INFO。 |
注意
不支持该值 0x40。
有关详细信息，请参阅备注部分。
rownum
一个可选参数，用于仅对输入或输出使用整数值来指定和INFO/或提取类型值的行位置ABSOLUTE。 rownum 用作 fetchtype 位值的RELATIVE行偏移量。 对于所有其他值，将忽略 rownum 。 有关详细信息，请参阅备注部分。
nrows
一个可选参数，用于指定要提取的行数。 如果未 指定 nrows ，则默认值为 20 行。 若要在不返回数据的情况下设置位置，请指定值 0。 当 nrows 应用于 fetchtype INFO 查询时，它将返回该查询中的行总数。
fetchtype 位值忽略 REFRESH nrows。 有关详细信息，请参阅备注部分。
返回代码值
指定位值 INFO时，可能会返回的值显示在下表中。
如果未返回任何行，则缓冲区内容将保持不变。
| <rownum> | 设置为 |
|---|---|
| 如果未打开 | 0 |
| 如果定位在结果集前面 | 0 |
| 如果定位在结果集后面 | -1 |
For KEYSET 和 STATIC cursors |
结果集中当前位置的绝对行号 |
对于 DYNAMIC 游标 |
1 |
对于 ABSOLUTE |
-1 返回集中的最后一行。 -2 返回集中的倒数第二行，依此类推。 注意： 如果在此示例中请求了多个行进行提取，则返回结果集的最后两行。 |
<nrows> |
设置为 |
|---|---|
| 如果未打开 | 0 |
For KEYSET 和 STATIC cursors |
通常为当前键集大小。-m 如果游标处于异步创建状态，但 此时找到 m 行。 |
对于 DYNAMIC 游标 |
-1 |
注解
游标参数
在任何提取操作之前，游标的默认位置位于结果集的第一行之前。
fetchtype 参数
SKIP_UPD_CNCY除提取类型值外，提取类型值是互斥的。
指定时 SKIP_UPDT_CNCY ，提取或刷新行时，时间戳列值不会写入键集表。 如果正在更新键集行，则时间戳列的值保持为先前的值。 如果正在插入键集行，则时间戳列的值不确定。
对于 KEYSET 游标，这意味着键集表在最后一个非skip FETCH期间设置了值（如果已执行）。 否则，它是填充期间设置的值。
对于 DYNAMIC 游标，这意味着如果通过刷新执行跳过，它将生成与 KEYSET相同的结果。 对于任何其他提取类型，键集表会被截断。 这意味着要插入行，时间戳列的值是未定义的。 因此，为游标运行sp_cursorfetchDYNAMIC时，请避免对除任何操作以外的REFRESH任何操作使用SKIP_UPDT_CNCY。
如果由于所请求的游标位置超出结果集而导致提取操作失败，则应将游标位置设置为恰好在最后一行的后面。 如果由于所请求的游标位置位于结果集的前面而导致提取操作失败，则应将游标位置设置在第一行的前面。
rownum 参数
使用 rownum 时，缓冲区从指定的行开始填充。
fetchtype 值ABSOLUTE是指整个结果集中行号的位置。 一个负数， ABSOLUTE 指定操作对结果集末尾的行进行计数。
fetchtype 值RELATIVE是指行数相对于游标在当前缓冲区开头的位置的位置。 一个负数， RELATIVE 指定游标从当前游标位置向后移动。
nrows 参数
fetchtype 值REFRESH并INFO忽略此参数。
当指定该值为 0 的 FIRST fetchtype 值时，游标位于提取缓冲区中没有行的结果集之前。
当指定为 nrow 值为 0 的 LAST fetchtype 值时，游标位于当前提取缓冲区中没有行的结果集之后。
对于 fetchtype 值，、PREVABSOLUTE、RELATIVE和 PREV_NOADJUSTnrow 类型的值NEXT0无效。
RPC 注意事项
RPC 返回状态指示密钥集大小参数是否为最终参数;也就是说，如果以异步方式填充键集或临时表。
RPC 状态参数设置为下表中显示的值之一。
| 值 | 说明 |
|---|---|
0 |
过程已成功执行。 |
0x0001 |
过程失败。 |
0x0002 |
当处于负方向中的提取在逻辑上应位于结果集前面时，该提取可能导致将游标位置设置在结果集的开头。 |
0x10 |
快进游标自动关闭。 |
这些行作为典型的结果集返回：列格式（0x2a）、行（0xd1），后跟 DONE （0xfd）。 元数据令牌的发送格式与为 sp_cursoropen： 0x81、 0xa5 0xa4 SQL Server 用户等指定的格式相同。 行状态指示器作为隐藏列（类似于 BROWSE 模式）发送到每行末尾，其中包含列名称行统计信息和数据类型 int。此行统计信息列包含下表中显示的值之一。
| 值 | 说明 |
|---|---|
0x0001 |
FETCH_SUCCEEDED |
0x0002 |
FETCH_MISSING |
由于 TDS 协议无法发送尾随状态列而不发送上一列，因此会针对缺失行发送虚拟数据。 可以为 null 的字段设置为 null，固定长度字段设置为 0、空白或该列的默认值（视情况而定）。
行 DONE 计数始终 0为 。 该 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