xp_trace_sethostfilter (T-SQL)

Specifies the host name filter, or the hosts (computers) to include and/or exclude for the events specified. Microsoft® SQL Server™ captures the required information, configured by executing xp_trace_seteventclassrequired, for the included hosts, if any, and does not capture the required information for the excluded hosts, if any.

Syntax

xp_trace_sethostfilter {queue_handle, 'include_hosts', 'exclude_hosts'}

Arguments

queue_handle

Is an integer that represents the handle for the trace queue. queue_handle is used to reference the trace queue and is placed in an output parameter by xp_trace_addnewqueue.

'include_hosts'

Is a string value that represents the host include filter. The host include filter indicates the hosts, separated by semicolons (;), that should be considered when capturing data previously determined by sp_seteventclassrequired. The % wildcard character can be used in specifying the hosts to include in the trace. If NULL is passed, there are no restrictions on hosts to include for the specified event classes.

Note Host names can be found in the sysprocesses system table.

'exclude_hosts'

Is a string value that represents the host exclude filter. The host exclude filter indicates the hosts, separated by semicolons (;), that should not be considered when capturing data previously determined by sp_seteventclassrequired. The % wildcard character can be used in specifying the hosts to exclude from the trace. If NULL, there are no excluded hosts for the specified event classes.

Return Code Values

0 (success) or >1 (failure)

Result Sets

xp_trace_sethostfilter returns this message:

The command(s) completed successfully.

Remarks

Generate the event class list by executing xp_trace_geteventnames.

When you have specify one or more hosts to include, all other hosts are excluded.

Permissions

Execute permissions for xp_trace_sethostfilter default to members of the sysadmin fixed server role but can be granted to other users.

Examples

This example configures the host filter value for trace queue so all hosts starting with the string SEATTLE will be included in the trace.

USE master

DECLARE @queue_handle int, @column_value int

SET @column_value = 16|32|8192|128|512

EXEC xp_trace_addnewqueue 1000,

    5,

    95,

    90,

    @column_value,

    @queue_handle OUTPUT

EXEC xp_trace_sethostfilter @queue_handle,

    'SEATTLE%',

    NULL

See Also