sp_describe_cursor (Transact-SQL)

Article
05/23/2023

S’applique à :SQL Server

Indique les attributs d'un curseur côté serveur.

Syntaxe

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

Arguments

[ @cursor_return= ] output_cursor_variable OUTPUT
Nom d'une variable de curseur déclarée devant recevoir la sortie du curseur. output_cursor_variable est un curseur, sans valeur par défaut, et ne doit pas être associé à des curseurs au moment où sp_describe_cursor est appelé. Le curseur retourné est un curseur en lecture seule, dynamique et permettant les défilements.

[ @cursor_source= ] { N’local' | N’global' | N’variable' }
Indique si le curseur qui fait l'objet du rapport est défini en utilisant le nom d'un curseur local, d'un curseur global ou d'une variable de curseur. Le paramètre est nvarchar(30).

[ @cursor_identity= ] N’local_cursor_name' ]
Nom d'un curseur créé par une instruction DECLARE CURSOR contenant soit le mot clé LOCAL, soit celui défini par défaut pour LOCAL. local_cursor_name est nvarchar(128).

[ @cursor_identity= ] N’global_cursor_name' ]
Nom d’un curseur créé par une instruction DECLARE CURSOR qui a le mot clé GLOBAL ou qui est défini par défaut sur GLOBAL. global_cursor_name est nvarchar(128).

global_cursor_name peut également être le nom d’un curseur de serveur d’API ouvert par une application ODBC qui est ensuite nommée en appelant SQLSetCursorName.

[ @cursor_identity= ] N’input_cursor_variable' ]
Nom d'une variable de curseur associée à un curseur ouvert. input_cursor_variable est nvarchar(128).

Codet de retour

None

Curseurs retournés

sp_describe_cursor encapsule son jeu de résultats dans un paramètre de sortie de curseur Transact-SQL. Cela permet aux lots Transact-SQL, aux procédures stockées et aux déclencheurs d’utiliser la sortie une ligne à la fois. Cela signifie également que la procédure ne peut pas être appelée directement à partir des fonctions d’API de base de données. Le paramètre de sortie du curseur doit être lié à une variable de programme, mais les API de base de données ne prennent pas en charge les variables ou paramètres de curseur de liaison.

La table suivante indique le format du curseur qui est retourné en utilisant sp_describe_cursor. C'est le même format que celui qui est retourné par sp_cursor_list.

Nom de la colonne	Type de données	Description
reference_name	sysname	Nom utilisé pour désigner le curseur. Si la référence du curseur provient du nom spécifié dans une instruction DECLARE CURSOR, le nom de référence est le même que le nom du curseur. Si la référence du curseur provient d'une variable, le nom de référence est celui de la variable.
cursor_name	sysname	Nom du curseur d’une instruction DECLARE CURSOR. Dans SQL Server, si le curseur a été créé en définissant une variable de curseur sur un curseur, cursor_name retourne le nom de la variable de curseur. Dans les versions antérieures de SQL Server, cette colonne de sortie retourne un nom généré par le système.
cursor_scope	tinyint	1 = LOCAL 2 = GLOBAL
status	int	Mêmes valeurs que celles signalées par la fonction système CURSOR_STATUS : 1 = Le curseur référencé par le nom de curseur ou la variable est ouvert. Si le curseur est non sensitif, statique ou contrôlé par clés, il comporte au moins une ligne. Si le curseur est dynamique, l'ensemble de résultats comporte zéro ou plusieurs lignes. 0 = Le curseur référencé par le nom de curseur ou la variable est ouvert mais ne comporte pas de lignes. Les curseurs dynamiques ne renvoient jamais cette valeur. -1 = Le curseur référencé par le nom de curseur ou la variable est fermé. -2 = S'applique uniquement aux variables de curseur. Aucun curseur n'est affecté à la variable. Il se peut qu'un paramètre OUTPUT ait affecté un curseur à la variable, mais la procédure stockée a fermé le curseur avant de sortir. -3 = Aucun curseur ou variable de curseur portant le nom spécifié n'existe, ou aucun curseur n'a été alloué à la variable de curseur.
model	tinyint	1 = Non sensitif (ou statique) 2 = Jeu de clés 3 = Dynamique 4 = Avance rapide
accès concurrentiel	tinyint	1 = Lecture seule 2 = Verrous de défilement 3 = Optimiste
scrollable	tinyint	0 = Avant uniquement 1 = À défilement
open_status	tinyint	0 = Fermé 1 = Ouvert
cursor_rows	décimal(10,0)	Nombre de lignes correspondantes dans le jeu de résultats. Pour plus d’informations, consultez @@CURSOR_ROWS (Transact-SQL).
fetch_status	smallint	État de la dernière extraction sur ce curseur. Pour plus d'informations, consultez @@FETCH_STATUS (Transact-SQL). 0 = Opération d'extraction réussie. -1 = L'opération d'extraction a échoué ou est hors des limites du curseur. -2 = La ligne demandée est manquante. -9 = Il n'y a pas eu d'opération d'extraction sur le curseur.
column_count	smallint	Nombre de colonnes dans le jeu de résultats du curseur
row_count	décimal(10,0)	Nombre de lignes affectées par la dernière opération sur le curseur. Pour plus d’informations, consultez @@ROWCOUNT (Transact-SQL).
last_operation	tinyint	Dernière opération effectuée sur le curseur : 0 = Aucune opération n'a été effectuée sur le curseur. 1 = OPEN 2 = FETCH 3 = INSERT 4 = UPDATE 5 = DELETE 6 = CLOSE 7 = DEALLOCATE
cursor_handle	int	Valeur unique pour le curseur dans l'étendue du serveur.

Remarques

sp_describe_cursor décrit les attributs globaux d'un curseur de serveur, comme la possibilité de défiler ou d'être mis à jour. Utilisez sp_describe_cursor_columns pour obtenir une description des attributs de l'ensemble de résultats renvoyé par le curseur. Utilisez sp_describe_cursor_tables pour générer un rapport sur les tables de base référencées par le curseur. Utilisez sp_cursor_list pour obtenir un rapport sur les curseurs de serveur Transact-SQL visibles lors de la connexion.

Une instruction DECLARE CURSOR peut demander un type de curseur que SQL Server ne peut pas prendre en charge à l’aide de l’instruction SELECT contenue dans le DECLARE CURSOR. SQL Server convertit implicitement le curseur en un type qu’il peut prendre en charge à l’aide de l’instruction SELECT. Si TYPE_WARNING est spécifié dans l’instruction DECLARE CURSOR, SQL Server envoie à l’application un message d’information indiquant qu’une conversion a été effectuée. sp_describe_cursor pouvez ensuite être appelé pour déterminer le type de curseur implémenté.

Autorisations

Nécessite l'appartenance au rôle public.

Exemples

Cet exemple ouvre un curseur global et utilise sp_describe_cursor pour fournir un rapport sur les attributs du curseur.

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

Voir aussi

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

Share via