sp_cursoropen (Transact-SQL)
适用于：
SQL Server
打开游标。 sp_cursoropen 定义与游标和游标选项相关联的 SQL 语句，然后填充游标。 sp_cursoropen等效于 Transact-SQL 语句DECLARE_CURSOR和 OPEN 的组合。 此过程通过在表格格式数据流 (TDS) 数据包中指定 ID = 2 来调用。
语法
sp_cursoropen cursor OUTPUT, stmt
[, scrollopt[ OUTPUT ] [ , ccopt[ OUTPUT ]
[ ,rowcount OUTPUT [ ,boundparam][,...n]]] ]]
参数
cursor
SQL Server 生成的游标标识符。 游标 是 必须针对涉及游标的所有后续过程（例如sp_cursorfetch）提供的句柄 值。 cursor 是具有 int 返回值的必需参数。
游标 允许多个游标在单个数据库连接上处于活动状态。
stmt
定义游标结果集的必需参数。 任何字符串类型（无论 Unicode、size 等）的任何有效查询字符串（语法和绑定）都可以用作有效的 stmt 值类型。
scrollopt
滚动选项。 scrollopt 是一个可选参数，需要以下 int 输入值之一。
| 值 | 说明 |
|---|---|
| 0x0001 | KEYSET |
| 0x0002 | DYNAMIC |
| 0x0004 | FORWARD_ONLY |
| 0x0008 | STATIC |
| 0x10 | FAST_FORWARD |
| 0x1000 | PARAMETERIZED_STMT |
| 0x2000 | AUTO_FETCH |
| 0x4000 | AUTO_CLOSE |
| 0x8000 | CHECK_ACCEPTED_TYPES |
| 0x10000 | KEYSET_ACCEPTABLE |
| 0x20000 | DYNAMIC_ACCEPTABLE |
| 0x40000 | FORWARD_ONLY_ACCEPTABLE |
| 0x80000 | STATIC_ACCEPTABLE |
| 0x100000 | FAST_FORWARD_ACCEPTABLE |
由于请求的值可能不适合 stmt 定义的游标，因此此参数同时充当输入和输出。 在此类情况下，SQL Server 分配一个适当的值。
ccopt
并发控制选项。 ccopt 是一个可选参数，需要以下 int 输入值之一。
| 值 | 说明 |
|---|---|
| 0x0001 | READ_ONLY |
| 0x0002 | SCROLL_LOCKS（以前称为 LOCKCC） |
| 0x0004 | 乐观 （以前称为 OPTCC） |
| 0x0008 | OPTIMISTIC（以前称为 OPTCCVAL） |
| 0x2000 | ALLOW_DIRECT |
| 0x4000 | UPDT_IN_PLACE |
| 0x8000 | CHECK_ACCEPTED_OPTS |
| 0x10000 | READ_ONLY_ACCEPTABLE |
| 0x20000 | SCROLL_LOCKS_ACCEPTABLE |
| 0x40000 | OPTIMISTIC_ACCEPTABLE |
| 0x80000 | OPTIMISITC_ACCEPTABLE |
与 scrollopt 一样，SQL Server 可以替代请求 的 ccopt 值。
rowcount
要用于 AUTO_FETCH 的提取缓冲区行数。 默认值为 20 行。 当分配为输入值与返回值时，rowcount 的行为方式不同。
| 作为输入值 | 作为返回值 |
|---|---|
| 如果指定了AUTO_FETCH scrollopt 值，则表示要放入提取缓冲区的行数。 注意： >0 是指定AUTO_FETCH但被忽略的有效值。 |
表示结果集中的行数，但指定 scrollopt AUTO_FETCH 值时除外。 |
-
boundparam
指示使用其他参数。 boundparam 是一个可选参数，如果 scrollopt PARAMETERIZED_STMT 值设置为 ON，则应指定此参数。
返回代码值
如果未引发错误，则 sp_cursoropen 返回以下值之一。
0
成功执行的过程。
0x0001
在执行过程中发生了错误（次要错误，严重程度不足以在操作中引发错误）。
0x0002
正在执行异步操作。
0x0002
正在执行 FETCH 操作。
A
此游标已由 SQL Server 解除分配，不可用。
当引发错误时，返回值可能不一致，无法确保准确性。
将 rowcount 参数指定为返回值时，将发生以下结果集。
-1
如果行数未知或不适用，则返回此值。
-n
当异步填充生效时，返回此值。 表示指定 scrollopt AUTO_FETCH 值时放置在提取缓冲区中的行数。
如果使用 RPC，则返回值如下所示。
0
过程成功。
1
过程失败。
2
正在异步生成键集游标。
16
快进游标已自动关闭。
注意
如果sp_cursoropen过程成功执行，则发送具有 TDS 列格式信息（0xa0和0xa1消息）的 RPC 返回参数和结果集。 如果不成功，则发送一条或多条 TDS 错误消息。 在任一情况下，都不会返回任何行数据，完成的消息计数将为零。 如果使用的 SQL Server 版本早于 7.0,0xa0，则返回0xa1（标准版LECT 语句的标准）以及0xa5和0xa4令牌流。 如果使用 SQL Server 7.0，则返回0x81（标准版LECT 语句的标准），以及0xa5和0xa4令牌流。
注解
stmt 参数
如果 stmt 指定存储过程的执行，则输入参数可以定义为常量作为 stmt 字符串的一部分，或指定为 boundparam 参数。 通过此方法，可以将声明的变量作为绑定参数传递。
stmt 参数的允许内容取决于 ccopt ALLOW_DIRECT 返回值是否已由 ccopt 值的其余部分链接，即：
如果未指定ALLOW_DIRECT，则必须使用对包含单个 标准版LECT 语句的存储过程调用 Transact-SQL 标准版LECT 或 EXECUTE 语句。 此外，标准版LECT 语句必须限定为游标;也就是说，它不能包含 标准版LECT INTO 或 FOR BROW 关键字 (keyword)标准版。
如果指定了ALLOW_DIRECT，这可能会导致一个或多个 Transact-SQL 语句，包括反过来使用多个语句执行其他存储过程。 将只执行非 SELECT 语句或包含关键字 SELECT INTO 或 FOR BROWSE 的任何 SELECT 语句，而不会导致创建游标。 这同样适用于在一批多个语句中包含的任何 SELECT 语句。 在 SELECT 语句包含只与游标相关的子句的情况下，将忽略这些子句。 例如，当 ccopt 的值0x2002时，这是请求：
具有滚动锁的游标（如果只有一个 SELECT 语句限定为游标），或者
一个直接的语句执行（如果有多个语句、一个非 SELECT 语句或不限定为游标的 SELECT 语句）。
scrollopt 参数
前五个滚动值（KEY标准版Y、DYNAMIC、FORWARD_ONLY、STATIC 和 FAST_FORWARD）互斥。
PARAMETERIZED_STMT 和 CHECK_ACCEPTED_TYPES 可以由 OR 链接到前五个值中的任何一个。
AUTO_FETCH 和 AUTO_CLOSE 可以由 OR 链接到 FAST_FORWARD。
如果CHECK_ACCEPTED_TYPES为 ON，则最后五个滚动值（KEY标准版T_ACCEPTABLE DYNAMIC_ACCEPTABLE、FORWARD_ONLY_ACCEPTABLE,、STATIC_ACCEPTABLE 或 FAST_FORWARD_ACCEPTABLE） 中至少必须为 ON。
STATIC 游标始终打开为 READ_ONLY。 这意味着无法通过此游标更新基础表。
ccopt 参数
前四 个 ccopt 值（READ_ONLY、SCROLL_LOCKS 和两个 OPTIMISTIC 值）互斥。
注意
选择前四 个 ccopt 值之一决定了游标是只读的，还是使用锁定或乐观方法来防止更新丢失。 如果未指定 ccopt 值，则默认值为 OPTIMISTIC。
ALLOW_DIRECT 和 CHECK_ACCEPTED_TYPES 可以由 OR 链接到前四个值中的任何一个。
UPDT_IN_PLACE 可以由 OR 链接到 READ_ONLY、SCROLL_LOCKS 或任一 OPTIMISTIC 值。
如果CHECK_ACCEPTED_TYPES为 ON，则最后四 个 ccopt 值（READ_ONLY_ACCEPTABLE、SCROLL_LOCKS_ACCEPTABLE和任一OPTIMISTIC_ACCEPTABLE值）中至少必须是 ON。
定位 UPDATE 和 DELETE 函数只能在提取缓冲区内执行，并且仅当 ccopt 值等于 SCROLL_LOCKS 或 OPTIMISTIC 时。 如果 SCROLL_LOCKS 是指定的值，则此操作可确保成功。 如果 OPTIMISTIC 是指定的值，则当自上次提取该行后行已发生变化时，操作将失败。
此失败的原因是，当 OPTIMISTIC 是指定值时，通过比较时间戳或检查和值（由 SQL Server 确定）来执行乐观货币控制函数。 如果任何行不匹配，则操作失败。
将 UPDT_IN_PLACE 指定为返回值可控制以下结果：
如果未设置，则当对某个表使用唯一索引执行定位更新时，游标将从其工作表中删除该行，并将其插入到游标使用的任何键列的末尾，从而更改这些列。
如果设置为 ON，游标将只更新工作表的原始行中的键列。
bound_param 参数
根据代码中的错误消息，在指定PARAMETERIZED_STMT时，参数名称应 为 paramdef 。 当未指定 PARAMETERIZED_STMT 时，在错误消息将不指定任何名称。
RPC 注意事项
RPC RETURN_METADATA 输入标志可设置为 0x0001，以请求在 TDS 流中返回游标选择列表元数据。
示例
bound_param 参数
第五个参数之后的任何参数都将作为输入参数传递到语句计划。 第一个此类参数必须为以下格式的字符串：
{ 本地变量名称数据类型 }[,...n]
后续参数用于传递要替换为 语句中局部变量名称 的值。
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈