sp_describe_cursor (Transact-SQL)

Se aplica a:SQL Server

Notifica los atributos de un cursor de servidor.

Convenciones de sintaxis de Transact-SQL

Sintaxis

  
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' ]   
     }   
[;]  

Argumentos

[ @cursor_return= ] output_cursor_variable OUTPUT
Es el nombre de una variable de cursor declarada que recibirá la salida del cursor. output_cursor_variable es el cursor, sin ningún valor predeterminado, y no debe estar asociado a ningún cursor en el momento en que se llama a sp_describe_cursor. El cursor devuelto es un cursor desplazable, dinámico y de solo lectura.

[ @cursor_source= ] { N'local' | N'global' | N'variable' }
Especifica si el cursor del que se informa está especificado con el nombre de un cursor local, un cursor global o una variable de cursor. El parámetro es nvarchar(30).

[ @cursor_identity= ] N'local_cursor_name' ]
Es el nombre de un cursor creado por una instrucción DECLARE CURSOR que tiene la palabra clave LOCAL u obtuvo el valor predeterminado LOCAL. local_cursor_name es nvarchar(128).

[ @cursor_identity= ] N'global_cursor_name' ]
Es el nombre de un cursor creado por una instrucción DECLARE CURSOR que tiene la palabra clave GLOBAL o que tiene como valor predeterminado GLOBAL. global_cursor_name es nvarchar(128).

global_cursor_name también puede ser el nombre de un cursor de servidor de API que abre una aplicación ODBC que, a continuación, llama a SQLSetCursorName.

[ @cursor_identity= ] N'input_cursor_variable' ]
Es el nombre de una variable de cursor asociada a un cursor abierto. input_cursor_variable es nvarchar(128).

Valores de código de retorno

None

Cursores devueltos

sp_describe_cursor encapsula su conjunto de resultados en un parámetro de salida de cursor de Transact-SQL. Esto permite que los lotes, los procedimientos almacenados y los desencadenadores de Transact-SQL funcionen con la salida de una fila a la vez. También significa que no se puede llamar al procedimiento directamente desde funciones de una API de base de datos. El parámetro de salida del cursor debe enlazarse a una variable de programa, pero las API de base de datos no admiten el enlace de parámetros o variables del cursor .

En la siguiente tabla se muestra el formato del cursor devuelto por sp_describe_cursor. El formato del cursor es el mismo que el devuelto con sp_cursor_list.

Nombre de la columna	Tipo de datos	Descripción
reference_name	sysname	Nombre que se utiliza para hacer referencia al cursor. Si la referencia al cursor se realizó utilizando el nombre especificado en una instrucción DECLARE CURSOR, el nombre de referencia es el mismo que el nombre del cursor. Si la referencia al cursor se hizo utilizando una variable, el nombre de referencia es el de la variable.
cursor_name	sysname	Nombre del cursor desde una instrucción DECLARE CURSOR. En SQL Server, si el cursor se creó estableciendo una variable de cursor en un cursor, cursor_name devuelve el nombre de la variable de cursor. En versiones anteriores de SQL Server, esta columna de salida devuelve un nombre generado por el sistema.
cursor_scope	tinyint	1 = LOCAL 2 = GLOBAL
status	int	Los mismos valores notificados por la función del sistema CURSOR_STATUS: 1 = El cursor al que hace referencia el nombre del cursor o ?la variable está abierto. Si se trata de un cursor que no distingue, estático o de conjunto de claves, el conjunto de resultados tiene una fila, como mínimo. Si el cursor es dinámico, el conjunto de resultados tiene cero o más filas. 0 = El cursor al que hace referencia el nombre del cursor o la variable está abierto pero no tiene filas. Los cursores dinámicos nunca devuelven este valor. -1 = El cursor al que hace referencia el nombre del cursor o la variable está cerrado. -2 = Se aplica solo a variables de cursor. No hay ningún cursor asignado a la variable. Posiblemente, un parámetro OUTPUT asignó un cursor a la variable pero el procedimiento almacenado cerró el cursor antes de devolver resultados. -3 = No existe un cursor o variable de cursor con el nombre especificado, o la variable del cursor no tiene todavía un cursor asignado.
model	tinyint	1 = Sin distinción (o estático) 2 = Conjunto de claves 3 = Dinámico 4 = Avance rápido
simultaneidad	tinyint	1 = Solo lectura 2 = Bloqueos de desplazamiento 3 = Optimista
scrollable	tinyint	0 = Solo avance 1 = Desplazable
open_status	tinyint	0 = Cerrado 1 = Abierto
cursor_rows	decimal(10,0)	Número de filas certificadas en el conjunto de resultados. Para obtener más información, vea @@CURSOR_ROWS (Transact-SQL).
fetch_status	smallint	Estado de la última captura de este cursor. Para obtener más información, vea @@FETCH_STATUS (Transact-SQL). 0 = Captura correcta. -1 = Error en la captura o se sobrepasaron los límites del cursor -2 = Falta la fila solicitada. -9 = No se registró ninguna captura en el cursor.
column_count	smallint	Número de columnas del conjunto de resultados del cursor.
row_count	decimal(10,0)	Número de filas afectadas por la última operación del cursor. Para obtener más información, consulte @@ROWCOUNT(Transact-SQL).
last_operation	tinyint	Última operación realizada en el cursor: 0 = No se realizó ninguna operación en el cursor. 1 = OPEN 2 = FETCH 3 = INSERT 4 = UPDATE 5 = DELETE 6 = CLOSE 7 = DEALLOCATE
cursor_handle	int	Valor único del cursor dentro del ámbito del servidor.

Comentarios

sp_describe_cursor describe los atributos globales de un cursor de servidor, como la posibilidad de desplazarlo y actualizarlo. Utilice sp_describe_cursor_columns para obtener una descripción de los atributos del conjunto de resultados devuelto por el cursor. Utilice sp_describe_cursor_tables para obtener un informe de las tablas base a las que hace referencia el cursor. Para obtener un informe de los cursores de servidor de Transact-SQL visibles en la conexión, use sp_cursor_list.

Una instrucción DECLARE CURSOR puede solicitar un tipo de cursor que SQL Server no pueda admitir el uso de la instrucción SELECT contenida en declare CURSOR. SQL Server convierte implícitamente el cursor en un tipo que puede admitir mediante la instrucción SELECT. Si TYPE_WARNING se especifica en la instrucción DECLARE CURSOR, SQL Server envía a la aplicación un mensaje informativo que se ha completado una conversión. sp_describe_cursor se puede llamar a para determinar el tipo de cursor que se ha implementado.

Permisos

Debe pertenecer al rol public.

Ejemplos

En el ejemplo siguiente se abre un cursor global y se utiliza sp_describe_cursor para obtener un informe de los atributos del 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  

Vea también

Cursores
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)