sp_trace_setfilter (Transact-SQL)
適用対象:SQL Server
トレースにフィルターを適用します。 sp_trace_setfilter
は、停止されている既存のトレースでのみ実行できます (@status です 0
)。 このストアド プロシージャが存在しないトレースまたは@statusが実行されていないトレースで実行された場合、SQL Server はエラーを0
返します。
重要
この機能は、 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の場合、SQL Server はNULL
指定されたトレースのすべてのフィルターをクリアします。
[ @logical_operator = ] logical_operator
AND () 演算子または OR (0
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 になります。
比較演算子が or NOT LIKE
の場合、論理演算子にはLIKE
、操作に適したフィルターまたはその他のフィルターをLIKE
含%
めることができます。
列の値を使用してイベントを除外する@valueをNULL
指定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 つの列 (AppName
値10
) をフィルター処理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';
関連するコンテンツ
フィードバック
https://aka.ms/ContentUserFeedback。
近日公開予定: 2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub イシューを段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、以下を参照してください:フィードバックの送信と表示