sp_describe_cursor (Transact-SQL)

适用于：SQL Server

报告服务器游标的属性。

Transact-SQL 语法约定

语法

  
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_cursor_variable 是 游标，没有默认值，在调用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 游标 输出参数中。 这使 Transact-SQL 批处理、存储过程和触发器能够一次处理一行输出。 这也意味着无法直接从数据库 API 函数调用该过程。 游标输出参数必须绑定到程序变量，但数据库 API 不支持绑定游标参数或变量。

下表显示了使用 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
状态	int	与 CURSOR_STATUS 系统函数报告的值相同的值： 1 = 游标名称或游标变量引用的游标为打开状态。 如果游标是不敏感的、静态的或是键集，则至少具有一行。 如果游标是动态的，则结果集具有零行或多行。 0 = 游标名称或游标变量引用的游标为打开状态，但不包含任何行。 动态游标从不返回此值。 -1 = 游标名称或游标变量引用的游标为关闭状态。 -2 = 仅适用于游标变量。 没有为该变量分配任何游标。 这可能是由于某个 OUTPUT 参数为该变量分配了游标，但存储过程在返回前关闭了游标。 -3 = 指定名称的游标或游标变量不存在，或没有为该游标变量分配游标。
模型	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 语句可以使用 DECLARE CURSOR 中包含的 SELECT 语句请求SQL Server不支持的游标类型。 SQL Server使用 SELECT 语句将游标隐式转换为它可以支持的类型。 如果在 DECLARE CURSOR 语句中指定了TYPE_WARNING，SQL Server向应用程序发送一条信息性消息，指出转换已完成。 然后，可以调用sp_describe_cursor来确定已实现的游标的类型。

权限

要求具有 public 角色的成员身份。

示例

下面的示例将打开一个全局游标，并使用 sp_describe_cursor 报告该游标的属性。

USE AdventureWorks2022;  
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  

另请参阅

光标
CURSOR_STATUS (Transact-SQL)
DECLARE CURSOR (Transact-SQL)
sp_cursor_list (Transact-SQL)
sp_describe_cursor_columns (Transact-SQL)
sp_describe_cursor_tables (Transact-SQL)