sp_describe_cursor (Transact-SQL)

Articolo
08/21/2023

Si applica a:SQL Server

Crea un report degli attributi di un cursore del server.

Sintassi

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

Argomenti

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

[ @cursor_source= ] { N'local' | N'global' | N'variable' }
Specifica se il cursore di cui viene generato il report viene specificato utilizzando il nome di un cursore locale, di un cursore globale o di una variabile di cursore. Il parametro è nvarchar(30).

[ @cursor_identity= ] N'local_cursor_name' ]
Nome di un cursore creato da un'istruzione DECLARE CURSOR con la parola chiave LOCAL o impostato sul valore predefinito LOCAL. local_cursor_name è nvarchar(128).

[ @cursor_identity= ] N'global_cursor_name' ]
Nome di un cursore creato da un'istruzione DECLARE CURSOR con la parola chiave GLOBAL o impostato sul valore predefinito GLOBAL. global_cursor_name è nvarchar(128).

global_cursor_name può anche essere il nome di un cursore del server API aperto da un'applicazione ODBC che viene quindi denominata chiamando SQLSetCursorName.

[ @cursor_identity= ] N'input_cursor_variable' ]
Nome di una variabile di cursore associata a un cursore aperto. input_cursor_variable è nvarchar(128).

Valori del codice restituito

Nessuno

Cursori restituiti

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

Nella tabella seguente viene descritto il formato del cursore restituito da sp_describe_cursor. Tale formato corrisponde a quello restituito da 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 impostato tramite il nome specificato in un'istruzione DECLARE CURSOR, il nome di 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 che deriva da un'istruzione DECLARE CURSOR. In SQL Server, 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
stato	int	Stessi valori restituiti dalla funzione di sistema CURSOR_STATUS: 1 = Il cursore a cui si fa riferimento tramite il nome o la variabile è aperto. Se il cursore è di tipo insensitive, statico o keyset, il set di risultati contiene almeno una riga. Se invece è dinamico, contiene zero o più righe. 0 = Il cursore a cui si fa riferimento tramite il nome o la variabile è aperto, ma non contiene righe. I cursori dinamici non restituiscono mai questo valore. -1 = Il cursore a cui si fa riferimento tramite il nome o la variabile è chiuso. -2 = Si applica solo alle variabili di cursore. Alla variabile non è assegnato alcun cursore. È possibile che un parametro OUTPUT abbia assegnato un cursore alla variabile, ma la stored procedure ha chiuso il cursore prima di completare l'operazione. -3 = Non esiste alcun cursore o variabile di cursore con il nome specificato oppure alla variabile non è stato assegnato alcun cursore.
modello	tinyint	1 = Insensitive (o statico) 2 = Keyset 3 = Dinamico 4 = Fast forward-only
concurrency	tinyint	1 = Di sola lettura. 2 = Blocchi di scorrimento. 3 = Ottimistica.
scrollable	tinyint	0 = Forward-only 1 = Scorrevole
open_status	tinyint	0 = Chiuso 1 = Aperto
cursor_rows	decimal(10,0)	Numero di righe risultanti nel set dei risultati. Per altre informazioni, vedere @@CURSOR_ROWS (Transact-SQL).
fetch_status	smallint	Stato dell'ultimo recupero sul cursore. Per ulteriori informazioni, vedere @@FETCH_STATUS (Transact-SQL). 0 = Recupero corretto. -1 = Recupero non riuscito o non compreso entro i limiti del cursore. -2 = La riga richiesta è mancante. -9 = Nessun recupero eseguito 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 (Transact-SQL).
last_operation	tinyint	Ultima operazione eseguita sul cursore: 0 = Non è stata eseguita alcuna operazione. 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:

La stored procedure sp_describe_cursor descrive gli attributi globali per un cursore del server, ad esempio la possibilità di scorrimento o aggiornamento. Utilizzare sp_describe_cursor_columns per ottenere una descrizione degli attributi del set dei risultati restituito dal cursore. Utilizzare sp_describe_cursor_tables per ottenere 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 può richiedere un tipo di cursore che SQL Server non può supportare tramite l'istruzione SELECT contenuta in DECLARE CURSOR. SQL Server converte in modo implicito il cursore in un tipo che può supportare tramite l'istruzione SELECT. Se TYPE_WARNING viene specificato nell'istruzione DECLARE CURSOR, SQL Server invia all'applicazione 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

Vedi anche

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