sp_describe_cursor (Transact-SQL)

Si applica a: SQL Server

Crea un report degli attributi di un cursore del server.

Convenzioni relative alla sintassi Transact-SQL

Sintassi

sp_describe_cursor
    [ @cursor_return = ] cursor_return OUTPUT
    , [ @cursor_source = ] { N'local' | N'global' | N'*cursor_source*' }
    , [ @cursor_identity = ] N'cursor_identity'
[ ; ]

Argomenti

[ @cursor_return = ] cursor_return OUTPUT

Nome di una variabile di cursore dichiarata per ricevere l'output del cursore. @cursor_return è un parametro OUTPUT di tipo int, senza impostazione predefinita e non deve essere associato ad alcun cursore al momento sp_describe_cursor della chiamata. Il cursore restituito è di tipo scorrevole, dinamico e di sola lettura.

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

Specifica se il cursore segnalato su viene specificato utilizzando il nome di un cursore locale , un cursore globale o una variabile di cursore. @cursor_source è nvarchar(30), senza impostazione predefinita.

[ @cursor_identity = ] N'cursor_identity'

Nome di un cursore creato da un'istruzione DECLARE CURSOR . @cursor_identity è nvarchar(128), senza impostazione predefinita.

  • Se il cursore ha la LOCAL parola chiave o è impostato su LOCAL, @cursor_identity è local.

  • Se il cursore ha la GLOBAL parola chiave o è impostato su GLOBAL, @cursor_identity è global. @cursor_identity può anche essere il nome di un cursore del server API aperto da un'applicazione ODBC e quindi denominato chiamando SQLSetCursorName.

  • In caso contrario, @cursor_identity è il nome di una variabile di cursore associata a un cursore aperto.

Valori del codice restituito

Nessuno.

Cursori restituiti

sp_describe_cursor incapsula il set di risultati in un parametro di output Transact-SQL cursor . In questo modo, i batch Transact-SQL, le stored procedure e i trigger possono funzionare con l'output di una riga alla volta. Ciò significa anche che la procedura non può essere chiamata direttamente dalle funzioni API del database. Il cursor parametro di output deve essere associato a una variabile di programma, ma le API di database non supportano parametri o variabili di associazione cursor .

Nella tabella seguente viene illustrato il formato del cursore restituito tramite sp_describe_cursor. Il formato del cursore è uguale al formato restituito tramite sp_cursor_list.

Nome colonna Tipo di dati Descrizione
reference_name sysname Nome utilizzato per fare riferimento al cursore. Se il riferimento al cursore è stato eseguito tramite il nome specificato in un'istruzione DECLARE CURSOR , il nome del riferimento corrisponde al nome del cursore. Se il riferimento al cursore è stato impostato tramite una variabile, il nome di riferimento corrisponde al nome della variabile.
cursor_name sysname Nome del cursore da un'istruzione DECLARE CURSOR . Se il cursore è stato creato impostando una variabile di cursore su un cursore, cursor_name restituisce il nome della variabile di cursore. Nelle versioni precedenti di SQL Server, questa colonna di output restituisce un nome generato dal sistema.
cursor_scope tinyint 1 = LOCAL
2 = GLOBAL
status int Stessi valori segnalati dalla funzione di CURSOR_STATUS sistema:

1 = Il cursore a cui fa riferimento il nome del cursore o la variabile è aperto. Se il cursore non fa distinzione, statica o keyset, è almeno una riga. Se invece è dinamico, contiene zero o più righe.
0 = Il cursore a cui fa riferimento il nome del cursore o la variabile è aperto ma non contiene righe. I cursori dinamici non restituiscono mai questo valore.
-1 = Il cursore a cui fa riferimento il nome del cursore o la variabile è chiuso.
-2 = Si applica solo alle variabili di cursore. Alla variabile non è assegnato alcun cursore. Possibilmente, un OUTPUT parametro ha assegnato un cursore alla variabile, ma la stored procedure ha chiuso il cursore prima di restituire.
-3 = Non esiste una variabile cursore o cursore con il nome specificato oppure la variabile del cursore non dispone di un cursore allocato.
model tinyint 1 = Senza distinzione (o statico)
2 = Keyset
3 = Dinamico
4 = Avanzamento rapido
concurrency tinyint 1 = Sola lettura
2 = Blocchi di scorrimento
3 = Ottimistica
scrollable tinyint 0 = Solo inoltro
1 = Scorrevole
open_status tinyint 0 = Chiuso
1 = Apri
cursor_rows decimal(10,0) Numero di righe risultanti nel set dei risultati. Per altre informazioni, vedere @@CURSOR_ROWS.
fetch_status smallint Stato dell'ultimo recupero sul cursore. Per altre informazioni, vedere @@FETCH_STATUS.

0 = Recupero riuscito.
-1 = Recupero non riuscito o oltre i limiti del cursore.
-2 = La riga richiesta è mancante.
-9 = Non si è verificato alcun recupero sul cursore.
column_count smallint Numero di colonne nel set dei risultati del cursore.
row_count decimal(10,0) Numero di righe modificate dall'ultima operazione eseguita sul cursore. Per altre informazioni, vedere @@ROWCOUNT.
last_operation tinyint Ultima operazione eseguita sul cursore:

0 = Nessuna operazione eseguita sul cursore.
1 = OPEN
2 = FETCH
3 = INSERT
4 = UPDATE
5 = DELETE
6 = CLOSE
7 = DEALLOCATE
cursor_handle int Valore univoco che identifica il cursore nell'ambito del server.

Osservazioni:

sp_describe_cursor descrive gli attributi globali di un cursore del server, ad esempio la possibilità di scorrere e aggiornare. Utilizzare sp_describe_cursor_columns per una descrizione degli attributi del set di risultati restituito dal cursore. Utilizzare sp_describe_cursor_tables per un report delle tabelle di base a cui fa riferimento il cursore. Per ottenere un report dei cursori transact-SQL server visibili nella connessione, usare sp_cursor_list.

Un'istruzione DECLARE CURSOR potrebbe richiedere un tipo di cursore che SQL Server non può supportare usando l'istruzione SELECT contenuta in DECLARE CURSOR. SQL Server converte in modo implicito il cursore in un tipo che può supportare l'uso dell'istruzione SELECT . Se TYPE_WARNING è specificato nell'istruzione , SQL Server invia all'applicazione DECLARE CURSOR un messaggio informativo che indica che è stata completata una conversione. sp_describe_cursor può quindi essere chiamato per determinare il tipo di cursore implementato.

Autorizzazioni

È richiesta l'appartenenza al ruolo public .

Esempi

Nell'esempio seguente viene aperto un cursore globale e viene utilizzata la stored procedure sp_describe_cursor per creare un report degli attributi del cursore.

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