sp_describe_cursor (Transact-SQL)

Informa de 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 de tipo cursor, no tiene valor predeterminado y no debe estar asociada a ningún cursor en el momento en el que se llama a sp_describe_cursor. El cursor devuelto es un cursor desplazable, dinámico y de sólo 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 de tipo 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 de tipo 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 u obtuvo el valor predeterminado GLOBAL. global_cursor_name es de tipo nvarchar(128).

  global_cursor_name también puede ser el nombre de un cursor de servidor API que se abrió con una aplicación ODBC que, a continuación, se denominó al llamar 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 de tipo nvarchar(128).

Valores de código de retorno

Ninguno

Cursores devueltos

sp_describe_cursor encapsula su conjunto de resultados en un parámetro de salida de tipo cursor de Transact-SQL. Esto permite a los lotes, procedimientos almacenados y desencadenadores de Transact-SQL trabajar con la salida de fila en fila. 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 cursor debe estar enlazado a una variable del programa, pero las API de base de datos no admiten el enlace de parámetros o variables 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 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ó al establecer 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 de los que informó 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 sólo 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 = Que no distingue (o estático) 2 = Conjunto de claves 3 = Dinámico 4 = Avance rápido
concurrency	tinyint	1 = Sólo lectura 2 = Bloqueos de desplazamiento 3 = Optimista
scrollable	tinyint	0 = De sólo 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 recuperación de este cursor. Para obtener más información, vea @@FETCH_STATUS (Transact-SQL). 0 = Recuperación correcta. -1 = Error en la recuperación o se sobrepasaron los límites del cursor. -2 = Falta la fila solicitada. -9 = No se registró ninguna recuperación 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, vea @@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.

Notas

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 pedir un tipo de cursor no compatible con la instrucción SELECT de SQL Server dentro de DECLARE CURSOR. SQL Server convierte implícitamente el cursor a un tipo de datos compatible con la instrucción SELECT. Si se especifica TYPE_WARNING en la instrucción DECLARE CURSOR, SQL Server envía a la aplicación un mensaje notificando que se ha realizado una conversión. Entonces es posible llamar a sp_describe_cursor para determinar el tipo de cursor implementado.

Permisos

Debe pertenecer a la función 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 AdventureWorks;
GO
-- Declare and open a global cursor.
DECLARE abc CURSOR STATIC FOR
SELECT LastName
FROM Person.Contact

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

Referencia

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)

Conceptos

Cursores (motor de base de datos)