sp_trace_setfilter (Transact-SQL)

Aplica um filtro a um rastreamento. sp_trace_setfilter pode ser executado apenas em rastreamentos existentes que são interrompidos (status é 0). O SQL Server retorna um erro se esse procedimento armazenado for executado em um rastreamento que não existe ou cujo status não seja 0.

Importante
Esse recurso será removido em uma versão futura do Microsoft SQL Server. Evite usar esse recurso em desenvolvimentos novos e planeje modificar os aplicativos que atualmente o utilizam. Usar eventos estendidos.

Convenções da sintaxe Transact-SQL

Sintaxe

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

Argumentos

• [ @traceid= ] trace_id
  É a ID do rastreamento para o qual o filtro está definido. trace_id é int, sem padrão. O usuário emprega este valor trace_id para identificar, modificar e controlar o rastreamento.

• [ @columnid= ] column_id
  É a ID da coluna na qual o filtro é aplicado. column_id é int, sem padrão. Se column_id for NULL, SQL Server desmarcará todos os filtros para o rastreamento especificado.

• [ @ logical_operator =] logical_operator
  Especifica se o operador AND (0) ou OR (1) é aplicado. logical_operator é int, sem padrão.

• [ @ comparison_operator= ] comparison_operator
  Especifica o tipo de comparação a ser feita. comparison_operator é int, sem padrão. A tabela contém os operadores de comparação e os valores representativos dos mesmos.

  Valor	Operador de comparação
  0	= (Igual)
  1	<> (Diferente de)
  2	> (Maior que)
  3	< (Menor que)
  4	>= (Maior ou igual a)
  5	<= (Menor ou igual a)
  6	LIKE
  7	NOT LIKE

• [ @value= ] value
  Especifica o valor no qual filtrar. O tipo de dados de value deve corresponder ao tipo de dados da coluna a ser filtrada. Por exemplo, se o filtro for definido em uma coluna ID Objeto que é um tipo de dados int, value deve ser int. Se value for nvarchar ou varbinary, poderá ter um comprimento de máximo de 8.000.

  Quando o operador de comparação for LIKE ou NOT LIKE, o operador lógico poderá incluir "%" ou outro filtro apropriado para a operação LIKE.

  Em SQL Server 2005 e posteriormente, você pode especificar NULL para value para eliminar por filtro eventos com valores de coluna NULL. Apenas os operadores 0 (= Igual) e 1 (<> Diferente de) são válidos com NULL. Neste caso, esses operadores são equivalentes aos operadores Transact-SQL IS NULL e IS NOT NULL.

  Para aplicar o filtro entre uma série de valores de coluna, sp_trace_setfilter deve ser executado duas vezes, uma com um operador de comparação maior ou igual a ('>=') e outra com um operador menor ou igual a ('<=').

  Para obter mais informações sobre os tipos de dados da coluna de dados, consulte Referência de classe de evento do SQL Server.

Valores de código de retorno

A tabela a seguir descreve os valores de código que os usuários podem obter após a conclusão do procedimento armazenado.

Código de retorno	Descrição
0	Nenhum erro.
1	Erro desconhecido.
2	O rastreamento está sendo executado no momento. A alteração do rastreamento neste momento resulta em um erro.
4	A Coluna especificada não é válida.
5	A Coluna especificada não possui permissão para filtro. Este valor é retornado apenas de sp_trace_setfilter.
6	O Operador de Comparação especificado não é válido.
7	O Operador Lógico especificado não é válido.
9	O Identificador de Rastreamento especificado não é válido.
13	Memória insuficiente. Retornado quando não há memória suficiente para executar a ação especificada.
16	A função não é válida para este rastreamento.

Comentários

sp_trace_setfilter é um SQL Server procedimento armazenado que executa muitas das ações executadas anteriormente por procedimentos armazenados estendidos disponíveis em versões mais antigas de SQL Server. Use o sp_trace_setfilter em vez dos procedimentos armazenados estendidos xp_trace_set*filter para criar, aplicar, remover ou manipular filtros em rastreamentos. Para obter mais informações, consulte Filtrar um rastreamento.

Todos os filtros de uma determinada coluna devem ser habilitados juntos em uma execução do sp_trace_setfilter. Por exemplo, se um usuário pretende aplicar dois filtros na coluna de nome de aplicativo e um filtro na coluna de nome de usuário, o usuário deve especificar os filtros em nome de aplicativo em sequência. O SQL Server retorna um erro se o usuário tentar especificar um filtro em nome de aplicativo em uma chamada de procedimento armazenado, em seguida, por um filtro em nome de usuário, e depois, outro filtro em nome de aplicativo.

Os parâmetros de todos os procedimentos armazenados do Rastreamento do SQL (sp_trace_xx) são rigorosamente tipados. Se esses parâmetros não forem chamados pelos tipos de dados com parâmetros de entrada corretos, como especificado na descrição do argumento, o procedimento armazenado retornará um erro.

Permissões

O usuário deve ter a permissão ALTER TRACE.

Exemplos

O exemplo a seguir define três filtros em Rastreamento 1. O filtros N'SQLT%' e o N'MS%' funcionam em uma coluna (AppName, valor 10) que usa o operador de comparação "LIKE". O filtro N'joe' funciona em uma coluna diferente (UserName, valor 11) que usa o operador de comparação "EQUAL".

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

Consulte também

Referência

sys.fn_trace_getfilterinfo (Transact-SQL)

sys.fn_trace_getinfo (Transact-SQL)

Conceitos

Rastreamento do SQL