sp_trace_setfilter (Transact-SQL)

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

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

Transact-SQL 構文表記規則

構文

sp_trace_setfilter [ @traceid = ] trace_id  
          , [ @columnid = ] column_id 
          , [ @logical_operator = ] logical_operator 
          , [ @comparison_operator = ] comparison_operator 
          , [ @value = ] value

引数

• [ @traceid= ] trace_id
  フィルターを適用するトレースの ID を指定します。 trace_id のデータ型は int で、既定値はありません。 ユーザーは、この trace_id 値を使用して、トレースの識別、変更、および制御を行います。

• [ @columnid= ] column_id
  フィルターが適用される列の ID を指定します。 column_id のデータ型は int で、既定値はありません。 column_id が NULL の場合、指定したトレースのすべてのフィルターが消去されます。

• [ @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 型の Object ID 列に適用する場合、value のデータ型は int であることが必要です。 value のデータ型が nvarchar または varbinary である場合、その長さの最大値は 8,000 です。

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

  SQL Server 2005 以降では、value に NULL を指定し、NULL 列値のイベントをフィルター選択できます。 NULL では、0 (= 等号) 演算子および 1 (<> 不等号) 演算子だけが有効です。 この場合、これらの演算子は、Transact-SQL の IS NULL 演算子および IS NOT NULL 演算子と等価です。

  列の値の範囲にフィルターを適用するには、sp_trace_setfilter を '>=' と '<=' の各比較演算子で 1 回ずつ、合計 2 回実行する必要があります。

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

戻り値

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

説明

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

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

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

権限

ユーザーに ALTER TRACE 権限が必要です。

使用例

次の例では、トレース 1 に 3 つのフィルターを設定します。 フィルター N'SQLT%' と N'MS%' は、"LIKE" 比較演算子を使用して 1 つの列 (AppName、値 10) に適用されます。 フィルター N'joe' は、"EQUAL" 比較演算子を使用して別の列 (UserName、値 11) に適用されます。

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';

関連項目

参照

sys.fn_trace_getfilterinfo (Transact-SQL)

sys.fn_trace_getinfo (Transact-SQL)

概念

SQL トレース