sp_trace_setfilter (Transact-SQL)
Applique un filtre à une trace. La procédure stockée sp_trace_setfilter ne peut être exécutée que sur des traces existantes qui sont arrêtées (status est égal à 0). SQL Server retourne une erreur si cette procédure stockée est exécutée sur une trace qui n'existe pas ou dont la valeur de status n'est pas définie 0.
.gif "Icône Lien de rubrique")
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. L'argument 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é. L'argument 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) doit être appliqué. L'argument logical_operator est de type int et n'a pas de valeur par défaut.[ @comparison_operator= ] comparison_operator
Indique le type de comparaison à effectuer. L'argument 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 Classes 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 Filtrage d'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 SQL Trace (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