次の方法で共有


sp_trace_setfilter (Transact-SQL)

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

重要

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

適用対象: SQL Server (SQL Server 2008 から現在のバージョンまで)

トピック リンク アイコン 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 演算に適した他のフィルターを含めることができます。

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

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

    データ列のデータ型の詳細については、「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 を使用できます。 詳細については、「トレースへのフィルターの適用」を参照してください。

特定の列に適用するフィルターはすべて、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 トレース