sp_describe_cursor (Transact-SQL)
报告服务器游标的属性。
适用范围:SQL Server(SQL Server 2008 到当前版本)。 |
语法
sp_describe_cursor [ @cursor_return = ] output_cursor_variable OUTPUT
{ [ , [ @cursor_source = ] N'local'
, [ @cursor_identity = ] N'local_cursor_name' ]
| [ , [ @cursor_source = ] N'global'
, [ @cursor_identity = ] N'global_cursor_name' ]
| [ , [ @cursor_source = ] N'variable'
, [ @cursor_identity = ] N'input_cursor_variable' ]
}
[;]
参数
[ @cursor\_return= ] output_cursor_variable OUTPUT
声明的用于接收游标输出的游标变量的名称。 output_cursor_variable 的数据类型为 cursor,无默认值。调用 sp_describe_cursor 时,该参数不得与任何游标关联。 返回的游标是可滚动的动态只读游标。[ @cursor\_source= ] { N'local' | N'global' | N'variable' }
指定使用以下哪一名称来指定所报告的游标:本地游标、全局游标或游标变量的名称。 该参数的数据类型为 nvarchar(30)。[ @cursor\_identity= ] N'local_cursor_name' ]
由具有 LOCAL 关键字或默认设置为 LOCAL 的 DECLARE CURSOR 语句创建的游标名称。 local_cursor_name 的数据类型为 nvarchar(128)。[ @cursor\_identity= ] N'global_cursor_name' ]
由具有 GLOBAL 关键字或默认设置为 GLOBAL 的 DECLARE CURSOR 语句创建的游标名称。 global_cursor_name 的数据类型为 nvarchar(128)。global_cursor_name 也可以是 API 服务器游标(由 ODBC 应用程序打开,然后通过调用 SQLSetCursorName 来命名)的名称。
[ @cursor\_identity= ] N'input_cursor_variable' ]
与打开的游标关联的游标变量的名称。 input_cursor_variable 的数据类型为 nvarchar(128)。
返回代码值
无
返回的游标
sp_describe_cursor 将其结果集封装在 Transact-SQL cursor 输出参数中。 这样,Transact-SQL 批处理、存储过程和触发器就可以逐行处理输出。 这也意味着无法直接从数据库 API 函数调用该过程。 cursor 输出参数必须绑定到程序变量,但是数据库 API 不支持绑定 cursor 参数或变量。
下表显示了使用 sp_describe_cursor 返回的游标的格式。 该游标格式与使用 sp_cursor_list 返回的格式相同。
列名 |
数据类型 |
说明 |
---|---|---|
reference_name |
sysname |
用于引用游标的名称。 如果通过 DECLARE CURSOR 语句中指定的名称引用游标,则引用名称与游标名称相同。 如果通过变量引用游标,则引用名称为变量的名称。 |
cursor_name |
sysname |
来自 DECLARE CURSOR 语句的游标名称。 在 SQL Server 中,如果是通过将游标变量设置为游标来创建游标,则 cursor_name 返回该游标变量的名称。 在 SQL Server 的早期版本中,此输出列可返回一个系统生成的名称。 |
cursor_scope |
tinyint |
1 = LOCAL 2 = GLOBAL |
status |
int |
与 CURSOR_STATUS 系统函数报告的值相同的值: 1 = 游标名称或游标变量引用的游标为打开状态。 如果游标是不敏感的、静态的或是键集,则至少具有一行。 如果游标是动态的,则结果集具有零行或多行。 0 = 游标名称或游标变量引用的游标为打开状态,但不包含任何行。 动态游标从不返回此值。 -1 = 游标名称或游标变量引用的游标为关闭状态。 -2 = 仅适用于游标变量。 没有为该变量分配任何游标。 这可能是由于某个 OUTPUT 参数为该变量分配了游标,但存储过程在返回前关闭了游标。 -3 = 指定名称的游标或游标变量不存在,或没有为该游标变量分配游标。 |
model |
tinyint |
1 = 不敏感(或静态) 2 = 键集 3 = 动态 4 = 快进 |
concurrency |
tinyint |
1 = 只读 2 = 滚动锁 3 = 乐观 |
scrollable |
tinyint |
0 = 只进 1 = 可滚动 |
open_status |
tinyint |
0 = 关闭 1 = 打开 |
cursor_rows |
decimal(10,0) |
结果集中合格的行数。 有关详细信息,请参阅 @@CURSOR_ROWS (Transact-SQL)。 |
fetch_status |
smallint |
此游标上次提取的状态。 有关详细信息,请参阅 @@FETCH_STATUS (Transact-SQL)。 0 = 提取成功。 -1 = 提取失败或超出游标的界限。 -2 = 缺少所请求的行。 -9 = 尚未对游标进行提取。 |
column_count |
smallint |
游标结果集中的列数。 |
row_count |
decimal(10,0) |
受游标的上次操作影响的行数。 有关详细信息,请参阅 @@ROWCOUNT (Transact-SQL)。 |
last_operation |
tinyint |
上次对游标执行的操作: 0 = 没有对游标执行操作。 1 = OPEN 2 = FETCH 3 = INSERT 4 = UPDATE 5 = DELETE 6 = CLOSE 7 = DEALLOCATE |
cursor_handle |
int |
服务器范围内的游标唯一值。 |
注释
sp_describe_cursor 说明服务器游标的全局属性,如滚动和更新的能力。 使用 sp_describe_cursor_columns 对游标返回的结果集的属性进行说明。 使用 sp_describe_cursor_tables 报告游标引用的基表。 若要获取连接中可见的 Transact-SQL 服务器游标的报告,请使用 sp_cursor_list。
DECLARE CURSOR 语句可以请求一个游标类型,SQL Server 无法使用 DECLARE CURSOR 中包含的 SELECT 语句支持该游标类型。 SQL Server 可以将该游标隐式转换为它可用 SELECT 语句支持的类型。 如果在 DECLARE CURSOR 语句中指定了 TYPE_WARNING,则 SQL Server 将向应用程序发送一条信息性消息,说明转换已完成。 然后可调用 sp_describe_cursor 来确定已实现的游标的类型。
权限
要求具有 public 角色的成员身份。
示例
下面的示例将打开一个全局游标,并使用 sp_describe_cursor 报告该游标的属性。
USE AdventureWorks2012;
GO
-- Declare and open a global cursor.
DECLARE abc CURSOR STATIC FOR
SELECT LastName
FROM Person.Person;
OPEN abc;
-- Declare a cursor variable to hold the cursor output variable
-- from sp_describe_cursor.
DECLARE @Report CURSOR;
-- Execute sp_describe_cursor into the cursor variable.
EXEC master.dbo.sp_describe_cursor @cursor_return = @Report OUTPUT,
@cursor_source = N'global', @cursor_identity = N'abc';
-- Fetch all the rows from the sp_describe_cursor output cursor.
FETCH NEXT from @Report;
WHILE (@@FETCH_STATUS <> -1)
BEGIN
FETCH NEXT from @Report;
END
-- Close and deallocate the cursor from sp_describe_cursor.
CLOSE @Report;
DEALLOCATE @Report;
GO
-- Close and deallocate the original cursor.
CLOSE abc;
DEALLOCATE abc;
GO
请参阅
参考
sp_describe_cursor_columns (Transact-SQL)
sp_describe_cursor_tables (Transact-SQL)