xp_trace_generate_event (T-SQL)

Adds a user-defined event to all queues. Returns no result set.

Syntax

xp_trace_generate_event {event_class} [, event_subclass]
    [, integer_data] [, 'server_name'] [, 'event_text_data'] [, binary_data]
    [, severity] [, database_id]    [, object_id] [, index_id]
    [, transaction_id]     [, connection_id] [, 'nt_user_name']
    [, 'nt_domain_name'] [, 'host_name'] [, host_process_id]
    [, 'application'] [, 'sql_user_name'] [, spid]
    [, duration] [, start_time] [, end_time] [, read]
    [, write] [, cpu_usage] [, dont_set]

Arguments

event_class

Is an integer value representing the user-defined event class for the user-defined event. event_class should be a value not used for Microsoft® SQL Server™ event classes. For more information about supported SQL Server event classes, see xp_trace_geteventnames.

event_subclass

Is an integer value representing the user-defined event subclass for the user-defined event.

integer_data

Is an integer value representing any integer value for a user-defined event.

'server_name'

Is a character value representing the name of the server that generated the event.

'event_text_data'

Is a character value representing the user-defined event description, up to 255 characters.

binary_data

Is a binary value representing binary data for the user-defined event.

severity

Is an integer value representing the user-defined event's severity. Use severity to capture user-defined events only with the specified severity level.

database_id

Is an integer value representing the database identification number for the user-defined event.

object_id

Is an integer value representing the object identification number for the user-defined event.

index_id

Is an integer value representing the index identification number for the user-defined event.

transaction_id

Is an integer value representing the transaction identification number for the user-defined event.

connection_id

Is an integer value representing the connection identification number for the user-defined event.

'nt_user_name'

Is a character value representing the Microsoft Windows NT® username for the user-defined event (used with Windows NT Authentication).

'nt_domain_name'

Is a character value representing the Windows NT domain name for the user-defined event (used with Windows NT Authentication).

'host_name'

Is a character value representing the host or computer name for the user-defined event.

host_process_id

Is an integer value representing the host process identification number for the user-defined event.

'application'

Is a character value representing the application name for the user-defined event. If sending data to a table (using xp_trace_setqueuedestination), application_name must be specified; otherwise, no data is added to the table.

'sql_user_name'

Is a character value representing the SQL Server username for the user-defined event (used with SQL Server Authentication).

spid

Is an integer value representing the system process identification number (SPID) for the user-defined event.

duration

Is an integer value representing the duration of the user-defined event.

start_time

Is an integer value representing the start time of the user-defined event.

end_time

Is an integer value representing the end time of the user-defined event.

read

Is an integer value representing the number of reads for the user-defined event.

write

Is an integer value representing the number of writes for the user-defined event.

cpu_usage

Is an integer value representing the cpu usage of the user-defined event.

dont_set

Is an integer value (item mask) representing those required data columns that SQL Server should not automatically fill for this user-defined event. For more information about required data columns, see xp_trace_addnewqueue.

Return Code Values

0 (success) or >1 (failure)

Result Sets

xp_trace_generate_event returns this message for a valid user-defined event:

The command(s) completed successfully.

Remarks

Use xp_trace_generate_event to write a producer and to produce user-defined events.

The event classes designated with an event class description of UserConfigurable (UserConfigurable:1, UserConfigurable:2, UserConfigurable:3, UserConfigurable:4, and UserConfigurable:5) are those event classes that can be used with xp_trace_generate_event. To obtain the event class numbers and corresponding names, execute xp_trace_geteventnames.

Permissions

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

Examples

This example creates a user-defined event with an event class of 82. This event class indicates the running of a script, and the completion of one stage of the process.

DECLARE @myvariable int

SET @myvariable = 4 -- Initialize to completion level.

EXEC xp_trace_generate_event @event_class = 82,

    @event_text_data = 'Stage 1 of Stage 3',

    @application_name = 'Myscript',

    -- Put the return value in a variable to check completion status.
    @integer_data = @myvariable,

    @nt_user_name = 'janetj'

See Also