sp_describe_cursor (Transact-SQL)

  • Article

Fournit les attributs d'un curseur de serveur.

Icône Lien de rubriqueConventions de la syntaxe de Transact-SQL

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 curseur déclarée pour recevoir la sortie du curseur. output_cursor_variable est du type cursor, n'a pas de valeur par défaut et ne doit pas être associé à des curseurs au moment de l'appel de sp_describe_cursor. 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 curseur. Le paramètre est du type 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 du type nvarchar(128).

[ @cursor_identity = ] N'global_cursor_name' ]

Nom d'un curseur créé par une instruction DECLARE CURSOR contenant soit le mot clé GLOBAL, soit celui défini par défaut pour GLOBAL. global_cursor_name est du type nvarchar(128).

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

[ @cursor_identity = ] N'input_cursor_variable' ]

Nom d'une variable curseur associée à un curseur ouvert. input_cursor_variable est du type nvarchar(128)

Notes

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 la description des attributs du jeu de résultats retourné 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 en utilisant l'instruction SELECT contenue dans DECLARE CURSOR. SQL Server convertit de manière implicite le curseur en un type qu'il ne peut prendre en charge en utilisant l'instruction SELECT. Si l'option TYPE_WARNING est spécifiée dans l'instruction DECLARE CURSOR, SQL Server envoie à l'application un message d'information lui indiquant qu'une conversion a été effectuée. La procédure sp_describe_cursor peut ensuite être appelée pour déterminer le type de curseur implémenté.

Autorisations

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

Valeurs des codes retournés

Aucune

Curseurs retournés

sp_describe_cursor encapsule son jeu de résultats dans un paramètre de sortie Transact-SQL cursor. Ceci permet aux lots d'instructions, procédures stockées et déclencheurs Transact-SQL d'utiliser une seule ligne de résultat à la fois. Cela signifie aussi 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 résultat cursor doit être lié à une variable de programme, mais les API de base de données ne prennent pas en charge les paramètres ou les variables cursor 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 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 dans une instruction DECLARE CURSOR. Dans SQL Server 2005, si le curseur a été créé en définissant une variable curseur pour un curseur, cursor_name retourne le nom de la variable curseur. Dans les versions précédentes de SQL Server, cette colonne de résultat retourne un nom généré par le système.

cursor_scope

tinyint

1 = LOCAL

2 = GLOBAL

status

int

Valeurs identiques à celles indiqué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, le jeu 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 retournent 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 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 retourner une valeur.

-3 = Aucun curseur ou variable curseur portant le nom spécifié n'existe, ou aucun curseur n'a été alloué à la variable curseur.

model

tinyint

1 = Non sensitif (ou statique)

2 = Contrôlé par clés

3 = Dynamique

4 = Avance rapide

concurrency

tinyint

1 = Lecture seule

2 = Verrous de défilement

3 = Optimiste

Défilable

tinyint

0 = Avant uniquement

1 = Défilable

open_status

tinyint

0 = Fermé

1 = Ouvert

cursor_rows

decimal(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 opération Fetch sur ce curseur. Pour plus d'informations, consultez @@FETCH_STATUS (Transact-SQL).

0 = Opération Fetch réussie.

-1 = L'opération Fetch a échoué ou est hors des limites de curseur.

-2 = La ligne requise est manquante.

-9 = Il n'y a pas eu d'opération Fetch sur le curseur.

column_count

smallint

Nombre de colonnes dans le jeu de résultats du curseur

row_count

decimal(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.

Exemples

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

USE AdventureWorks;
GO
-- Declare and open a global cursor.
DECLARE abc CURSOR STATIC FOR
SELECT LastName
FROM Person.Contact

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

Référence

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)

Autres ressources

Curseurs (moteur de base de données)

Aide et Informations

Assistance sur SQL Server 2005