sp_describe_cursor (Transact-SQL)

Artikel
05/23/2023

Meldet die Attribute eines Servercursors.

Syntax

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

Argumente

[ @cursor_return= ] output_cursor_variable OUTPUT
Der Name einer deklarierten Cursorvariablen zum Empfangen der Cursorausgabe. output_cursor_variable ist der Cursor ohne Standard und darf zum Zeitpunkt des Aufrufs sp_describe_cursor keinem Cursor zugeordnet werden. Bei dem zurückgegebenen Cursor handelt es sich um einen scrollfähigen, dynamischen, schreibgeschützten Cursor.

[ @cursor_source= ] { N'local' | N'global' | N'variable' }
Gibt an, ob der Cursor, für den der Bericht erstellt wird, mithilfe des Namens eines lokalen Cursors, eines globalen Cursors oder einer Cursorvariablen angegeben wird. Der Parameter ist nvarchar(30).

[ @cursor_identity= ] N'local_cursor_name' ]
Der Name eines mit einer DECLARE CURSOR-Anweisung erstellten Cursors, der entweder das LOCAL-Schlüsselwort aufweist oder standardmäßig auf LOCAL festgelegt ist. local_cursor_name ist nvarchar(128).

[ @cursor_identity= ] N'global_cursor_name' ]
Der Name eines mit einer DECLARE CURSOR-Anweisung erstellten Cursors, der entweder das GLOBAL-Schlüsselwort aufweist oder standardmäßig auf GLOBAL festgelegt ist. global_cursor_name ist nvarchar(128).

global_cursor_name kann auch der Name eines API-Servercursors sein, der von einer ODBC-Anwendung geöffnet wird, die dann durch Aufrufen von SQLSetCursorName benannt wurde.

[ @cursor_identity= ] N'input_cursor_variable' ]
Der Name einer Cursorvariablen, die mit einem geöffneten Cursor verknüpft ist. input_cursor_variable ist nvarchar(128).

Rückgabecodewerte

Keine

Zurückgegebene Cursor

sp_describe_cursor kapselt das Resultset in einem Transact-SQL-Cursorausgabeparameter. Dadurch können Transact-SQL-Batches, gespeicherte Prozeduren und Trigger zeilenweise mit der Ausgabe arbeiten. Dies bedeutet auch, dass die Prozedur nicht direkt über Datenbank-API-Funktionen aufgerufen werden kann. Der Cursorausgabeparameter muss an eine Programmvariable gebunden sein, aber die Datenbank-APIs unterstützen keine Bindungscursorparameter oder -variablen.

In der folgenden Tabelle wird das Format des Cursors dargestellt, der mithilfe von sp_describe_cursor zurückgegeben wird. Das Format des Cursors ist mit dem mithilfe von sp_cursor_list zurückgegebenen Format identisch.

Spaltenname	Datentyp	BESCHREIBUNG
reference_name	sysname	Name, der zum Verweisen auf den Cursor verwendet wird. Wenn der Verweis auf den Cursor über den Namen in einer DECLARE CURSOR-Anweisung erfolgte, ist der Name des Verweises mit dem Cursornamen identisch. Wenn der Verweis auf den Cursor über eine Variable erfolgte, ist der Variablenname der Name des Verweises.
cursor_name	sysname	Name des Cursors aus einer DECLARE CURSOR-Anweisung. Wenn der Cursor in SQL Server durch Festlegen einer Cursorvariablen auf einen Cursor erstellt wurde, gibt cursor_name den Namen der Cursorvariablen zurück. In früheren Versionen von SQL Server gibt diese Ausgabespalte einen vom System generierten Namen zurück.
cursor_scope	tinyint	1 = LOKAL 2 = GLOBAL
status	int	Einige Werte, die von der CURSOR_STATUS-Systemfunktion gemeldet werden: 1 = Der Cursor, auf den mit dem Cursornamen oder der Variablen verwiesen wird, ist geöffnet. Ein statischer, Keyset- oder Insensitivcursor weist mindestens eine Zeile auf. Bei einem dynamischen Cursor weist das Resultset keine oder mehr Zeilen auf. 0 = Der Cursor, auf den mit dem Cursornamen oder der Variablen verwiesen wird, ist geöffnet, weist aber keine Zeilen auf. Dynamische Cursor geben diesen Wert nie zurück. -1 = Der Cursor, auf den mit dem Cursornamen oder der Variablen verwiesen wird, ist geschlossen. -2 = Gilt nur für Cursorvariablen. Der Variablen ist kein Cursor zugewiesen. Möglicherweise hat ein OUTPUT-Parameter der Variablen einen Cursor zugewiesen, aber die gespeicherte Prozedur hat den Cursor vor der Rückgabe geschlossen. -3 = Ein Cursor oder eine Cursorvariable mit dem angegebenen Namen ist nicht vorhanden, oder für die Cursorvariable wurde kein Cursor reserviert.
model	tinyint	1 = Insensitiv (oder statisch) 2 = Keyset 3 = Dynamisch 4 = Schneller Vorwärtscursor
concurrency	tinyint	1 = Schreibgeschützt 2 = Scrollsperre 3 = Vollständig
scrollable	tinyint	0 = Vorwärts 1 = Scrollfähig
open_status	tinyint	0 = Geschlossen 1 = Geöffnet
cursor_rows	decimal(10,0)	Die Anzahl der kennzeichnenden Zeilen im Resultset. Weitere Informationen finden Sie unter @@CURSOR_ROWS (Transact-SQL).
fetch_status	smallint	Status des letzten Abrufs auf diesem Cursor. Weitere Informationen finden Sie unter @@FETCH_STATUS (Transact-SQL). 0 = Abruf erfolgreich. -1 = Abruf fehlerhaft oder außerhalb des zulässigen Bereichs des Cursors. -2 = Die angeforderte Zeile fehlt. -9 = Kein Abruf für Cursor.
column_count	smallint	Anzahl der Spalten im Resultset des Cursors
row_count	decimal(10,0)	Anzahl der Zeilen, auf die sich den letzten Vorgang für den Cursor auswirkt. Weitere Informationen finden Sie unter @@@ROWCOUNT (Transact-SQL).
last_operation	tinyint	Letzter Vorgang, der auf dem Cursor ausgeführt wurde: 0 = Für den Cursor wurden keine Vorgänge ausgeführt. 1 = OPEN 2 = FETCH 3 = INSERT 4 = UPDATE 5 = DELETE 6 = CLOSE 7 = DEALLOCATE
cursor_handle	int	Ein eindeutiger Wert für den Cursor innerhalb des Serverbereichs

Bemerkungen

sp_describe_cursor beschreibt die für einen Servercursor globalen Attribute, wie z. B. die Optionen zum Durchführen eines Bildlaufs und zum Aktualisieren. Mit sp_describe_cursor_columns zeigen Sie eine Beschreibung der Attribute des vom Cursor zurückgegebenen Resultsets an. Mit sp_describe_cursor_tables zeigen Sie an, auf welche Basistabellen der Cursor verweist. Wenn Sie einen Bericht der in der Verbindung sichtbaren Transact-SQL Servercursor benötigen, verwenden Sie sp_cursor_list.

Eine DECLARE CURSOR-Anweisung kann einen Cursortyp anfordern, der SQL Server nicht unterstützen kann, indem die SELECT-Anweisung verwendet wird, die in DECLARE CURSOR enthalten ist. SQL Server konvertiert den Cursor implizit in einen Typ, den er mithilfe der SELECT-Anweisung unterstützen kann. Wenn TYPE_WARNING in der DECLARE CURSOR-Anweisung angegeben ist, sendet SQL Server der Anwendung eine Informationsmeldung, dass eine Konvertierung abgeschlossen wurde. sp_describe_cursor kann dann aufgerufen werden, um den Typ des implementierten Cursors zu bestimmen.

Berechtigungen

Erfordert die Mitgliedschaft in der public-Rolle.

Beispiele

Im folgenden Beispiel wird ein globaler Cursor geöffnet und mithilfe von sp_describe_cursor ein Bericht der Cursorattribute erstellt.

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

Weitere Informationen

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