適用対象:
SQL Server
トレースにフィルターを適用します。
sp_trace_setfilter は、停止されている (@status が 0されている) 既存のトレースでのみ実行できます。 存在しないトレースまたは @status が 0されていないトレースでこのストアド プロシージャが実行された場合、SQL Server はエラーを返します。
重要
この機能は、 SQL Serverの将来のバージョンで削除される予定です。 新規の開発作業ではこの機能を使用しないようにし、現在この機能を使用しているアプリケーションは修正することを検討してください。 代わりに拡張イベントを使用します。
構文
sp_trace_setfilter
[ @traceid = ] traceid
, [ @columnid = ] columnid
, [ @logical_operator = ] logical_operator
, [ @comparison_operator = ] comparison_operator
, [ @value = ] value
[ ; ]
引数
重要
拡張ストアド プロシージャの引数は、「構文の」セクションで説明されているように、特定の順序で入力する必要があります。 パラメーターが順に入力されていない場合は、エラー メッセージが表示されます。
[ @traceid = ] traceid
フィルターが設定されているトレースの ID。 @traceid は int で、既定値はありません。 ユーザーはこの @traceid 値を使用して、トレースを識別、変更、および制御します。
[ @columnid = ] columnid
フィルターが適用される列の ID。
@columnid は int で、既定値はありません。
@columnidがNULL場合、SQL Server は指定されたトレースのすべてのフィルターをクリアします。
[ @logical_operator = ] logical_operator
AND (0) 演算子または OR (1) 演算子を適用するかどうかを指定します。
@logical_operator は int で、既定値はありません。
[ @comparison_operator = ] comparison_operator
実行される比較の種類を示します。 @comparison_operator は int で、既定値はありません。 テーブルには、比較演算子とその代表的な値が含まれています。
| 値 | 比較演算子 |
|---|---|
0 |
= (等しい) |
1 |
<> (等しくない) |
2 |
> (より大きい) |
3 |
< (より小さい) |
4 |
>= (以上) |
5 |
<= (以下) |
6 |
LIKE |
7 |
NOT LIKE |
[ @value = ] value
フィルターの対象となる値を指定します。 @valueのデータ型は、フィルター処理する列のデータ型と一致する必要があります。 たとえば、フィルターが int データ型のオブジェクト ID 列に設定されている場合、 @value は int である必要があります。 @value が nvarchar または varbinary の場合、最大長は 8000 になります。
比較演算子がLIKEまたはNOT LIKEの場合、論理演算子には、%操作に適したLIKEまたはその他のフィルターを含めることができます。
NULLのを指定して、NULL列の値を持つイベントを除外できます。
0では、= (1等しくない) 演算子と<>演算子 (NULL等しくない) のみが有効です。 この場合、これらの演算子は Transact-SQL IS NULL および IS NOT NULL 演算子と同等です。
列の値の範囲の間でフィルターを適用するには、 sp_trace_setfilter を 2 回実行する必要があります。1 回は大なり等しい (>=) 比較演算子を使用し、もう 1 回は等しくない (<=) 演算子を使用します。
データ列のデータ型の詳細については、「 SQL サーバー イベント クラス リファレンスを参照してください。
リターン コードの値
次の表では、ストアド プロシージャの完了後に取得できるコード値について説明します。
| リターン コード | 説明 |
|---|---|
0 |
エラーなし。 |
1 |
不明なエラー。 |
2 |
トレースは現在実行中です。 この時点でトレースを変更すると、エラーが発生します。 |
4 |
指定された列が無効です。 |
5 |
指定した列はフィルター処理できません。 この値は、 sp_trace_setfilterからのみ返されます。 |
6 |
指定された比較演算子が無効です。 |
7 |
指定された論理演算子が無効です。 |
9 |
指定されたトレース ハンドルが無効です。 |
13 |
メモリが不足しています。 指定されたアクションを実行するのに十分なメモリがない場合に返されます。 |
16 |
この関数は、このトレースに対して有効ではありません。 |
解説
sp_trace_setfilter は、以前のバージョンの SQL Server で使用できる拡張ストアド プロシージャによって以前に実行されたアクションの多くを実行する SQL Server ストアド プロシージャです。 トレースのフィルターを作成、適用、削除、または操作するには、sp_trace_setfilter拡張ストアド プロシージャの代わりにxp_trace_set*filterを使用します。 詳細については、「 トレースのフィルター処理」を参照してください。
特定の列のすべてのフィルターは、 sp_trace_setfilterの 1 回の実行で一緒に有効にする必要があります。 たとえば、ユーザーがアプリケーション名列に 2 つのフィルターを適用し、1 つのフィルターをユーザー名列に適用する場合、ユーザーはアプリケーション名のフィルターを順番に指定する必要があります。 SQL Server では、ユーザーが 1 つのストアド プロシージャ呼び出しでアプリケーション名にフィルターを指定し、その後にユーザー名にフィルターを、アプリケーション名に対して別のフィルターを指定しようとすると、エラーが返されます。
すべての SQL トレース ストアド プロシージャ (sp_trace_*) のパラメーターは厳密に型指定されます。 これらのパラメーターが、引数の説明で指定されている正しいデータ型で呼び出されないと、このストアド プロシージャではエラーが返されます。
アクセス許可
ALTER TRACE 権限が必要です。
例
次の例では、トレース 1に 3 つのフィルターを設定します。 フィルターN'SQLT%'N'MS%'、"AppName" 比較演算子を使用して 1 つの列 (10、値LIKE) で動作します。 フィルター N'joe' は、"UserName" 比較演算子を使用して別の列 (11、値 EQUAL) に適用されます。
EXEC sp_trace_setfilter 1, 10, 0, 6, N'SQLT%';
EXEC sp_trace_setfilter 1, 10, 0, 6, N'MS%';
EXEC sp_trace_setfilter 1, 11, 0, 0, N'joe';