sp_cursoropen (Transact-SQL)

适用范围:SQL Server

打开游标。 sp_cursoropen 定义与游标和游标选项关联的 SQL 语句,然后填充游标。 sp_cursoropen 等效于 Transact-SQL 语句 DECLARE_CURSOROPEN. 此过程通过在表格数据流 (TDS) 数据包中指定 ID = 2 来调用。

Transact-SQL 语法约定

语法

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 计数为 00x81 返回 standard for SELECT 语句0xa5 > 和 0xa4 标记流。

注解

stmt 参数

如果 stmt 指定存储过程的执行,则输入参数可以定义为常量作为 stmt 字符串的一部分,或指定为 boundparam 参数。 通过此方法,可以将声明的变量作为绑定参数传递。

stmt 参数的允许内容取决于 ccopt ALLOW_DIRECT 返回值是否链接到 OR ccopt 值的其余部分:

  • ALLOW_DIRECT如果未指定,则必须使用对包含单个SELECT语句的存储过程调用的 Transact-SQL SELECTEXECUTE语句。 此外,语句 SELECT 必须限定为游标;也就是说,它不能包含关键字 SELECT INTOFOR BROWSE

  • 如果 ALLOW_DIRECT 已指定,则可能会导致一个或多个 Transact-SQL 语句,包括使用多个语句执行其他存储过程的语句。 SELECT非语句或任何SELECT包含关键字SELECT INTOFOR BROWSE执行的语句,并且不会导致创建游标。 对于包含在一批多个语句中的任何 SELECT 语句也是如此。 SELECT如果语句包含仅适用于游标的子句,则忽略这些子句。 例如,当 ccopt 的值0x2002时,这是请求:

    • 如果只有一个 SELECT 语句限定为游标,则具有滚动锁的游标,或者

    • 如果有多个语句、单个非SELECT 语句或 SELECT 不限定为游标的语句,则直接执行语句。

scrollopt 参数

前五个滚动值(KEYSEY、、DYNAMICFORWARD_ONLYSTATICFAST_FORWARD)互斥。

PARAMETERIZED_STMT 可以 CHECK_ACCEPTED_TYPES 链接到 OR 前五个值中的任何一个。

AUTO_FETCHAUTO_CLOSE 可链接到 OR FAST_FORWARD

ON如果是CHECK_ACCEPTED_TYPES,则最后五个滚动值(KEYSET_ACCEPTABLE、、FORWARD_ONLY_ACCEPTABLEDYNAMIC_ACCEPTABLESTATIC_ACCEPTABLEFAST_FORWARD_ACCEPTABLE)中至少必须有ON一个。

STATIC 游标始终以 READ_ONLY. 这意味着无法通过此游标更新基础表。

ccopt 参数

前四 个 ccopt 值(READ_ONLYSCROLL_LOCKS两个 OPTIMISTIC 值)互斥。

注意

选择前四 个 ccopt 值之一决定了游标是只读的,还是使用锁定或乐观方法来防止更新丢失。 如果未指定 ccopt 值,则默认值为 OPTIMISTIC

ALLOW_DIRECT 可以通过 CHECK_ACCEPTED_TYPES 前四个值中的任何一个链接 OR

UPDT_IN_PLACE可以链接到ORREAD_ONLYSCROLL_LOCKS之一或值之OPTIMISTIC一。

ON如果是CHECK_ACCEPTED_TYPES,则最后四个 ccopt 值(READ_ONLY_ACCEPTABLESCROLL_LOCKS_ACCEPTABLE和其中一个OPTIMISTIC_ACCEPTABLE值)中至少有一个也必须为 ON。

UPDATE定位和DELETE函数只能在提取缓冲区内执行,并且仅当 ccopt 值等于SCROLL_LOCKSOPTIMISTIC。 如果 SCROLL_LOCKS 为指定值,则保证操作成功。 如果 OPTIMISTIC 为指定值,则如果自上次提取以来行发生更改,则操作将失败。

此失败的原因是,当指定值时 OPTIMISTIC ,通过比较时间戳或校验和值(由 SQL Server 确定)来执行乐观货币控制函数。 如果这些行中的任何一行不匹配,操作将失败。

指定 UPDT_IN_PLACE 为返回值可控制以下结果:

  • 如果在对具有唯一索引的表执行定位更新时未设置,游标会从其工作表中删除该行,并将其插入游标使用的任何键列的末尾,这会更改这些列。

  • 如果设置 ON,游标将更新工作表中原始行中的键列。

bound_param参数

根据代码中的错误消息,参数名称在指定时PARAMETERIZED_STMT为 paramdefPARAMETERIZED_STMT如果未指定,错误消息中未指定任何名称。

RPC 注意事项

RPC RETURN_METADATA 输入标志可以设置为 0x0001 请求在 TDS 流中返回游标选择列表元数据。

示例

A. bound_param参数

第五个参数之后的任何参数都将作为输入参数传递到语句计划。 第一个此类参数必须是以下形式的字符串:

<parameter_name> <data_type> [ ,... n ]

后续参数用于传递要替换为 <parameter_name> 语句中的值。