sp_describe_cursor_columns (Transact-SQL)

Article
03/07/2014

Fournit un rapport des attributs des colonnes contenues dans le jeu de résultats d'un curseur côté serveur.

S'applique à : SQL Server (SQL Server 2008 via la version actuelle).

Icône Lien de rubrique Conventions de la syntaxe Transact-SQL

Syntaxe

sp_describe_cursor_columns 
   [ @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 de type cursor, sans valeur par défaut, et ne doit pas être associé à des curseurs au moment où sp_describe_cursor_columns 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 de 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 de 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 de type nvarchar(128).

global_cursor_name peut aussi être le nom d'un curseur côté serveur d'API ouvert par une application ODBC, puis nommé en appelant SQLSetCursorName.
[ @cursor\_identity= ] N'input_cursor_variable'
Nom d'une variable de curseur associée à un curseur ouvert. input_cursor_variable est de type nvarchar(128).

Valeurs des codes de retour

Aucune

Curseurs retournés

sp_describe_cursor_columns encapsule son rapport sous la forme d'un paramètre de sortie Transact-SQL cursor. Cela permet aux lots, procédures stockées et déclencheurs Transact-SQL de travailler sur une seule ligne de sortie à 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 sortie 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.

Le tableau suivant indique le format du curseur qui est retourné à l'aide de sp_describe_cursor_columns.

Nom de la colonne	Type de données	Description
column_name	sysname (accepte les valeurs NULL)	Nom attribué à la colonne du jeu de résultats. La colonne est NULL si elle a été spécifiée sans être accompagnée de la clause AS.
ordinal_position	int	Position relative de la colonne par rapport à la colonne la plus à gauche du jeu de résultats. La première colonne est à la position 0.
column_characteristics_flags	int	Masque de bits indiquant les informations stockées dans DBCOLUMNFLAGS dans OLE DB. Il peut s'agir d'un des éléments suivants ou d'une combinaison de ceux-ci : 1 = Signet 2 = Longueur fixe 4 = Pouvant être Null 8 = Contrôle de version de ligne 16 = Colonne pouvant être mise à jour (définie dans le cas de colonnes projetées d'un curseur n'ayant pas de clause FOR UPDATE. Si une colonne de ce type existe, il ne peut y en avoir qu'une par curseur). Lorsque les valeurs binaires sont combinées, les caractéristiques des valeurs binaires combinées s'appliquent. Par exemple, si la valeur binaire est égale à 6, la colonne est de longueur fixe (2) et accepte les valeurs NULL (4).
column_size	int	Taille maximale possible d'une valeur de cette colonne.
data_type_sql	smallint	Numéro indiquant le type de données SQL Server de la colonne.
column_precision	tinyint	Précision maximale de la colonne telle que définie par la valeur bPrecision dans OLE DB.
column_scale	tinyint	Nombre de chiffres à droite du séparateur décimal pour les types de données numeric ou decimal tel que défini par la valeur bScale dans OLE DB.
order_position	int	Position de la colonne dans la clé d'ordre relative à la colonne la plus à gauche si la colonne prend part à la définition de l'ordre du jeu de résultats.
order_direction	varchar(1) (accepte les valeurs NULL)	A = La colonne fait partie de la clé d'ordre et l'ordre est croissant. D = La colonne fait partie de la clé d'ordre et l'ordre est décroissant. NULL = La colonne ne fait pas partie de la clé d'ordre.
hidden_column	smallint	0 = Cette colonne apparaît dans la liste de sélection. 1 = Réservé pour un usage ultérieur.
columnid	int	Identification de la colonne de base. Si la colonne du jeu de résultats a été créée à partir d'une expression, columnid est égal à -1.
objectid	int	ID d'objet de l'objet ou de la table de base qui fournit la colonne. Si la colonne du jeu de résultats a été créée à partir d'une expression, objectid est égal à -1.
dbid	int	ID de la base de données contenant la table de base qui fournit la colonne. Si la colonne du jeu de résultats a été créée à partir d'une expression, dbid est égal à -1.
dbname	sysname (accepte les valeurs NULL)	Nom de la base de données contenant la table de base qui fournit la colonne. Si la colonne du jeu de résultats a été créée à partir d'une expression, dbname a la valeur NULL.

Notes

sp_describe_cursor_columns décrit les attributs des colonnes du jeu de résultats d'un curseur côté serveur, tels que le nom et le type de données de chaque curseur. Utilisez sp_describe_cursor pour obtenir une description des attributs globaux du curseur côté serveur. 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 des curseurs côté serveur Transact-SQL qui sont visibles sur la connexion.

Autorisations

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

Exemples

L'exemple suivant ouvre un curseur global et utilise sp_describe_cursor_columns pour fournir un rapport sur colonnes utilisées dans le curseur.

USE AdventureWorks2012;
GO
-- Declare and open a global cursor.
DECLARE abc CURSOR KEYSET FOR
SELECT LastName
FROM Person.Person;
GO
OPEN abc;

-- Declare a cursor variable to hold the cursor output variable
-- from sp_describe_cursor_columns.
DECLARE @Report CURSOR;

-- Execute sp_describe_cursor_columns into the cursor variable.
EXEC master.dbo.sp_describe_cursor_columns
    @cursor_return = @Report OUTPUT
    ,@cursor_source = N'global' 
    ,@cursor_identity = N'abc';

-- Fetch all the rows from the sp_describe_cursor_columns 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_columns.
CLOSE @Report;
DEALLOCATE @Report;
GO
-- Close and deallocate the original cursor.
CLOSE abc;
DEALLOCATE abc;
GO