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 生成的游标标识符。 游标 是 handle 必须在涉及游标的所有后续过程中提供的值，例如 sp_cursorfetch。 游标参数为 int，不能NULL为 。
游标 允许多个游标在单个数据库连接上处于活动状态。
stmt
定义游标结果集的必需参数。 任何字符串类型（无论 Unicode、size 等）的任何有效查询字符串（语法和绑定）都可以用作有效的 stmt 值类型。
scrollopt
滚动选项。 scrollopt 参数为 int，默认值NULL为 ，可以是下列值之一。
| 值 | 说明 |
|---|---|
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 |
OPTIMISTIC （以前称为 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 |
此游标已解除分配且不可用。 |
引发错误时，返回值可能不一致，无法保证准确性。
将 rowcount 参数指定为返回值时，将发生以下结果集。
| 值 | 说明 |
|---|---|
-1 |
如果行数未知或不适用，则返回此值。 |
-n |
当异步填充生效时，返回此值。 表示指定 scrollopt AUTO_FETCH 值时放置在提取缓冲区中的行数。 |
如果使用 RPC，则返回值如下所示。
| 值 | 说明 |
|---|---|
0 |
过程成功。 |
1 |
过程失败。 |
2 |
正在异步生成键集游标。 |
16 |
快进游标自动关闭。 |
sp_cursoropen如果过程成功执行，则发送具有 TDS 列格式信息（0xa0和消息）的 RPC 返回参数和0xa1结果集。 如果不成功，则发送一条或多条 TDS 错误消息。 在任一情况下，都未返回行数据，消息 DONE 计数为 0。 0x81 返回 standard for SELECT 语句0xa5 > 和 0xa4 标记流。
注解
stmt 参数
如果 stmt 指定存储过程的执行，则输入参数可以定义为常量作为 stmt 字符串的一部分，或指定为 boundparam 参数。 通过此方法，可以将声明的变量作为绑定参数传递。
stmt 参数的允许内容取决于 ccopt ALLOW_DIRECT 返回值是否链接到 OR ccopt 值的其余部分：
ALLOW_DIRECT如果未指定，则必须使用对包含单个SELECT语句的存储过程调用的 Transact-SQLSELECT或EXECUTE语句。 此外，语句SELECT必须限定为游标;也就是说，它不能包含关键字SELECT INTO或FOR BROWSE。如果
ALLOW_DIRECT已指定，则可能会导致一个或多个 Transact-SQL 语句，包括使用多个语句执行其他存储过程的语句。SELECT非语句或任何SELECT包含关键字SELECT INTO或FOR BROWSE执行的语句，并且不会导致创建游标。 对于包含在一批多个语句中的任何SELECT语句也是如此。SELECT如果语句包含仅适用于游标的子句，则忽略这些子句。 例如，当 ccopt 的值为0x2002时，这是请求：如果只有一个
SELECT语句限定为游标，则具有滚动锁的游标，或者如果有多个语句、单个非
SELECT语句或SELECT不限定为游标的语句，则直接执行语句。
scrollopt 参数
前五个滚动值（KEYSEY、、DYNAMICFORWARD_ONLY、STATIC和FAST_FORWARD）互斥。
PARAMETERIZED_STMT 可以 CHECK_ACCEPTED_TYPES 链接到 OR 前五个值中的任何一个。
AUTO_FETCH 和 AUTO_CLOSE 可链接到 OR FAST_FORWARD。
ON如果是CHECK_ACCEPTED_TYPES，则最后五个滚动值（KEYSET_ACCEPTABLE、、FORWARD_ONLY_ACCEPTABLEDYNAMIC_ACCEPTABLE或STATIC_ACCEPTABLEFAST_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可以链接到ORREAD_ONLY值SCROLL_LOCKS之一或值之OPTIMISTIC一。
ON如果是CHECK_ACCEPTED_TYPES，则最后四个 ccopt 值（READ_ONLY_ACCEPTABLESCROLL_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 流中返回游标选择列表元数据。
示例
A. bound_param参数
第五个参数之后的任何参数都将作为输入参数传递到语句计划。 第一个此类参数必须是以下形式的字符串：
<parameter_name> <data_type> [ ,... n ]
后续参数用于传递要替换为 <parameter_name> 语句中的值。