sp_trace_setfilter (Transact-SQL)

Article
08/19/2013

Applique un filtre à une trace. sp_trace_setfilter ne peut être exécuté que sur les traces existantes qui sont arrêtées (l'argument status prend la valeur 0). SQL Server retourne une erreur si cette procédure stockée est exécutée sur une trace qui n'existe pas ou si l'argument status qu'elle contient n'est pas égal à 0.

Important

Cette fonctionnalité sera supprimée dans une prochaine version de Microsoft SQL Server. Évitez d'utiliser cette fonctionnalité dans de nouveaux travaux de développement et prévoyez de modifier les applications qui utilisent actuellement cette fonctionnalité. Utilisez plutôt des événements étendus.

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

Syntaxe

sp_trace_setfilter [ @traceid = ] trace_id 
          , [ @columnid = ] column_id
          , [ @logical_operator = ] logical_operator
          , [ @comparison_operator = ] comparison_operator
          , [ @value = ] value

Arguments

[ @traceid= ] trace_id
ID de la trace sur laquelle le filtre est défini. trace_id est de type int et n'a pas de valeur par défaut. L'utilisateur emploie cette valeur trace_id pour identifier, modifier et contrôler la Trace.
[ @columnid= ] column_id
ID de la colonne sur laquelle le filtre est appliqué column_id est de type int et n'a pas de valeur par défaut. Si column_id a la valeur NULL, SQL Server efface tous les filtres pour la Trace spécifiée.
[ @logical_operator = ] logical_operator
Indique si l'opérateur AND (0) ou OR (1) est appliqué. logical_operator est de type int et n'a pas de valeur par défaut.

[ @comparison_operator= ] comparison_operator
Spécifie le type de comparaison à effectuer. comparison_operator est de type int et n'a pas de valeur par défaut. Le tableau contient les opérateurs de comparaison et leurs valeurs.

Valeur	Opérateur de comparaison
0	= (Égal à)
1	<> (Différent de)
2	> (Supérieur à)
3	< (Inférieur à)
4	>= (Supérieur ou égal à)
5	<= (Inférieur ou égal à)
6	LIKE
7	NOT LIKE

[ @value= ] value
Indique la valeur sur laquelle appliquer le filtre. Le type de données de value doit correspondre au type de données de la colonne à filtrer. Par exemple, si le filtre est défini sur une colonne d'ID d'objet dont le type de données est int, l'argument value doit être de type int. Si l'argument value est de type nvarchar ou varbinary, sa longueur maximale est de 8000.

Lorsque l'opérateur de comparaison est LIKE ou NOT LIKE, l'opérateur logique peut inclure « % » ou tout autre filtre approprié pour l'opération LIKE.

Dans SQL Server 2005 et versions ultérieures, vous pouvez spécifier NULL comme valeur de l'argument value pour filtrer des événements ayant des valeurs de colonne NULL. Seuls les opérateurs 0 (= Égal) et 1 (<> Différent) sont valides avec la valeur NULL. Dans ce cas, ils sont équivalents aux opérateurs IS NULL et IS NOT NULL de Transact-SQL.

Pour appliquer le filtre à une plage de valeurs de colonne, sp_trace_setfilter doit être exécuté à deux reprises : une première fois avec un opérateur de comparaison supérieur ou égal à (« >= », et une seconde fois avec un opérateur inférieur ou égal à (« <= ».

Pour plus d'informations sur les types de données des colonnes, consultez Référence de classe d'événements SQL Server.

Valeurs des codes de retour

Le tableau suivant décrit les valeurs de code que les utilisateurs peuvent recevoir à la fin de l'exécution de la procédure stockée.

Code de retour	Description
0	Aucune erreur.
1	Erreur inconnue.
2	La trace est en cours d'exécution. La modification de la Trace à cet instant précis entraîne une erreur.
4	La colonne spécifiée n'est pas valide.
5	La colonne spécifiée n'est pas autorisée pour le filtrage. Cette valeur n'est retournée qu'à partir de sp_trace_setfilter.
6	L'opérateur de comparaison spécifié n'est pas valide.
7	L'opérateur logique spécifié n'est pas valide.
9	Le descripteur de trace spécifié n'est pas valide.
13	Mémoire insuffisante. Retourné lorsqu'il n'y a pas assez de mémoire pour exécuter l'action spécifiée.
16	La fonction n'est pas valide pour cette Trace.

Notes

sp_trace_setfilter est une procédure stockée SQL Server qui exécute bon nombre d'actions précédemment effectuées par les procédures stockées étendues disponibles dans les versions antérieures de SQL Server. Utilisez sp_trace_setfilter au lieu des procédures stockées étendues xp_trace_set*filter pour créer, appliquer, supprimer ou manipuler des filtres sur des Traces. Pour plus d'informations, consultez Filtrer une trace.

Tous les filtres d'une colonne particulière doivent être activés ensemble au cours d'une seule exécution de sp_trace_setfilter. Par exemple, si un utilisateur décide d'appliquer deux filtres sur la colonne Nom d'application et un filtre sur la colonne Nom d'utilisateur, il doit spécifier les filtres sur le nom d'application de manière séquentielle. SQL Server retourne une erreur si l'utilisateur tente de spécifier un filtre sur le nom d'application dans un appel de procédure stockée, suivi d'un filtre sur le nom d'utilisateur, puis d'un autre filtre sur le nom d'application.

Les paramètres de toutes les procédures stockées Trace SQL (sp_trace_xx) possèdent un type précis. Si ces paramètres ne sont pas appelés à l'aide des types de données des paramètre d'entrée appropriés, comme spécifié dans la description de l'argument, la procédure stockée retourne une erreur.

Autorisations

L'utilisateur doit disposer de l'autorisation ALTER TRACE.

Exemples

L'exemple suivant définit trois filtres sur Trace 1. Les filtres N'SQLT%' et N'MS%' opèrent sur une colonne (AppName, valeur 10) à l'aide de l'opérateur de comparaison « LIKE ». Le filtre N'joe' opère sur une autre colonne (UserName, valeur 11) à l'aide de l'opérateur de comparaison « EQUAL ».

sp_trace_setfilter  1, 10, 0, 6, N'SQLT%';
sp_trace_setfilter  1, 10, 0, 6, N'MS%';
sp_trace_setfilter  1, 11, 0, 0, N'joe';

Voir aussi

Référence

sys.fn_trace_getfilterinfo (Transact-SQL)

sys.fn_trace_getinfo (Transact-SQL)

Concepts

Trace SQL

Partager via