sp_trace_setfilter (Transact-SQL)

適用対象: SQL サーバー

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

重要

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

[ @logical_operator = ] logical_operator

AND (0) 演算子または OR (1) 演算子を適用するかどうかを指定します。 @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 である必要があります。 @value が nvarchar または varbinary の場合、最大長は 8000 になります。

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

@valueのNULLを指定して、NULL列の値を持つイベントを除外できます。 NULLでは、0 (=等しくない) 演算子と1演算子 (<>等しくない) のみが有効です。 この場合、これらの演算子は 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 ストアド プロシージャです。 トレースのフィルターを作成、適用、削除、または操作するには、xp_trace_set*filter拡張ストアド プロシージャの代わりにsp_trace_setfilterを使用します。 詳細については、「トレースのフィルター処理を参照してください。

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

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

アクセス許可

ALTER TRACE 権限が必要です。

例

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

関連するコンテンツ

• sys.fn_trace_getfilterinfo (Transact-SQL)
• sys.fn_trace_getinfo (Transact-SQL)
• SQL トレース (SQL Trace)