sp_trace_setfilter (Transact-SQL)

適用対象:SQL Server

トレースにフィルターを適用します。 sp_trace_setfilter は、停止されている既存のトレースでのみ実行できます (@status です 0)。 このストアド プロシージャが存在しないトレースまたは@statusが実行されていないトレースで実行された場合、SQL Server はエラーを0返します。

重要

この機能は、 SQL Serverの将来のバージョンで削除される予定です。 新規の開発作業ではこの機能を使用しないようにし、現在この機能を使用しているアプリケーションは修正することを検討してください。 代わりに拡張イベントを使用します。

Transact-SQL 構文表記規則

構文

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の場合、SQL Server はNULL指定されたトレースのすべてのフィルターをクリアします。

[ @logical_operator = ] logical_operator

AND () 演算子または OR (01) 演算子を適用するかどうかを指定します。 @logical_operatorは int で、既定値はありません。

[ @comparison_operator = ] comparison_operator

実行される比較の種類を示します。 @comparison_operatorは int で、既定値はありません。 テーブルには、比較演算子とその代表的な値が含まれています。

Value 比較演算子
0 = (等しい)
1 <> (等しくない)
2 > (より大きい)
3 < (より小さい)
4 >= (以上)
5 <= (以下)
6 LIKE
7 NOT LIKE

[ @value = ] value

フィルターの対象となる値を指定します。 @valueデータ型は、フィルター処理する列のデータ型と一致する必要があります。 たとえば、int データ型のオブジェクト ID 列にフィルターが設定されている場合、@valueは int である必要があります。@valuenvarchar または varbinary の場合、最大長は 8000 になります。

比較演算子が or NOT LIKEの場合、論理演算子にはLIKE、操作に適したフィルターまたはその他のフィルターをLIKE%めることができます。

列の値を使用してイベントを除外する@valueNULL指定NULLできます。 (0等しい) 演算子と 1 (<>等しくない) 演算子は 、 で有効ですNULL= この場合、これらの演算子は Transact-SQL IS NULL および演算子と IS NOT NULL 同等です。

列の値の範囲の間にフィルターを適用するには、 sp_trace_setfilter 2 回実行する必要があります。1 回は、より大きいか等しい (>=) 比較演算子を使用し、もう 1 回は等しくない (<=) 演算子を使用します。

データ列のデータ型の詳細については、「SQL Server イベント クラス リファレンス」を参照してください

リターン コードの値

次の表は、このストアド プロシージャの完了時に返されるコード値を示しています。

リターン コード 説明
0 エラーなし。
1 不明なエラー。
2 トレースは現在実行中です。 この時点でトレースを変更すると、エラーが発生します。
4 指定された列が無効です。
5 指定した列はフィルター処理できません。 この値は 、.. から sp_trace_setfilterしか返されません。
6 指定された比較演算子が無効です。
7 指定された論理演算子が無効です。
9 指定されたトレース ハンドルが無効です。
13 メモリが不足しています。 指定されたアクションを実行するのに十分なメモリがない場合に返されます。
16 この関数は、このトレースに対して有効ではありません。

解説

sp_trace_setfilter は、以前のバージョンの SQL Server で使用できる拡張ストアド プロシージャによって以前に実行されたアクションの多くを実行する SQL Server ストアド プロシージャです。 トレースのフィルターをxp_trace_set*filter作成、適用、削除、または操作するには、拡張ストアド プロシージャの代わりに使用sp_trace_setfilterします。 詳細については、「トレースのフィルター処理」を参照してください

特定の列のすべてのフィルターを 1 回の実行 sp_trace_setfilterで一緒に有効にする必要があります。 たとえば、ユーザーがアプリケーション名列に 2 つのフィルターを適用し、1 つのフィルターをユーザー名列に適用する場合、ユーザーはアプリケーション名のフィルターを順番に指定する必要があります。 SQL Server では、ユーザーが 1 つのストアド プロシージャ呼び出しでアプリケーション名にフィルターを指定し、その後にユーザー名にフィルターを、アプリケーション名に対して別のフィルターを指定しようとすると、エラーが返されます。

すべての SQL トレース ストアド プロシージャ (sp_trace_*) のパラメーターは厳密に型指定されます。 これらのパラメーターが、引数の説明で指定されている正しいデータ型で呼び出されないと、このストアド プロシージャではエラーが返されます。

アクセス許可

ALTER TRACE 権限が必要です。

次の例では、トレース 1に 3 つのフィルターを設定します。 "LIKE" 比較演算子を使用して、1 つの列 (AppName10) をフィルター処理N'SQLT%'してN'MS%'操作します。 フィルター 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';