sp_describe_cursor (Transact-SQL)

  • Artículo

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 = ] cursor_return OUTPUT
    , [ @cursor_source = ] { N'local' | N'global' | N'*cursor_source*' }
    , [ @cursor_identity = ] N'cursor_identity'
[ ; ]

Argumentos

[ @cursor_return = ] cursor_return OUTPUT

Nombre de una variable de cursor declarada para recibir la salida del cursor. @cursor_return es un parámetro OUTPUT de tipo int, sin ningún valor predeterminado y no debe asociarse con ningún cursor en el momento sp_describe_cursor en que se llama. El cursor devuelto es un cursor desplazable, dinámico y de solo lectura.

[ @cursor_source = ] { N'local' | N'global' | N'cursor_source' }

Especifica si el cursor en el que se notifica se especifica mediante el nombre de un cursor local , un cursor global o una variable de cursor. @cursor_source es nvarchar(30), sin ningún valor predeterminado.

[ @cursor_identity = ] N'cursor_identity'

Nombre de un cursor creado por una DECLARE CURSOR instrucción . @cursor_identity es nvarchar(128), sin ningún valor predeterminado.

  • Si el cursor tiene la palabra clave o tiene como LOCAL valor predeterminado LOCAL, @cursor_identity es local.

  • Si el cursor tiene la palabra clave o tiene como GLOBAL valor predeterminado GLOBAL, @cursor_identity es global. @cursor_identity también puede ser el nombre de un cursor del servidor de API abierto por una aplicación ODBC y, a continuación, llamar a SQLSetCursorName.

  • De lo contrario, @cursor_identity es el nombre de una variable de cursor asociada a un cursor abierto.

Valores de código de retorno

Ninguno.

Cursores devueltos

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

En la tabla siguiente se muestra el formato del cursor que se devuelve mediante sp_describe_cursor. El formato del cursor es el mismo que el formato devuelto mediante 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ó a través del nombre especificado en una DECLARE CURSOR instrucción , 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 de una DECLARE CURSOR instrucción . 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 CURSOR_STATUS sistema:

1 = El cursor al que hace referencia el nombre del cursor o la variable está abierto. Si el cursor no distingue, estática o conjunto de claves, es al menos una fila. 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 se cierra.
-2 = Solo se aplica a las variables de cursor. No hay ningún cursor asignado a la variable. Posiblemente, un OUTPUT parámetro asignó un cursor a la variable, pero el procedimiento almacenado cerró el cursor antes de devolverlo.
-3 = No existe una variable de cursor o cursor con el nombre especificado o la variable de cursor no tiene asignado un cursor.
model tinyint 1 = No distingue (o estática)
2 = Conjunto de claves
3 = Dinámico
4= Inserción rápida
concurrency tinyint 1 = Solo lectura
2 = Bloqueos de desplazamiento
3 = Optimista
scrollable tinyint 0 = Solo reenvío
1 = Desplazable
open_status tinyint 0 = Cerrado
1 = Abrir
cursor_rows decimal(10,0) Número de filas certificadas en el conjunto de resultados. Para obtener más información, consulte @@CURSOR_ROWS.
fetch_status smallint Estado de la última captura de este cursor. Para obtener más información, consulte @@FETCH_STATUS.

0 = Captura correcta.
-1 = Error de captura o está más allá de los límites del cursor.
-2 = Falta la fila solicitada.
-9 = No se produjo 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.
last_operation tinyint Última operación realizada en el cursor:

0 = No se realizaron operaciones 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 que son globales para un cursor de servidor, como la capacidad de desplazarse y actualizar. Use sp_describe_cursor_columns para obtener una descripción de los atributos del conjunto de resultados devuelto por el cursor. Use sp_describe_cursor_tables para un informe de las tablas base a las que hace referencia el cursor. Para obtener un informe de los cursores de Transact-SQL Server visibles en la conexión, use sp_cursor_list.

Una DECLARE CURSOR instrucción puede solicitar un tipo de cursor que SQL Server no pueda admitir mediante la SELECT instrucción contenida en .DECLARE CURSOR SQL Server convierte implícitamente el cursor en un tipo que puede admitir mediante la SELECT instrucción . Si TYPE_WARNING se especifica en la DECLARE CURSOR instrucción , SQL Server envía a la aplicación un mensaje informativo que se completó una conversión. sp_describe_cursor A continuación, 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

Contenido relacionado