xp_trace_getevents (T-SQL)

Removes events from the trace queue created with xp_trace_addnewqueue and returns the events as a result set.

Syntax

xp_trace_getevents {queue_handle, is_fulltext, is_integerevents}
    [, number_of_events]

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.

is_fulltext

Is a Boolean value that determines the length of the text field display.

 

Value	Description
0	Returns up to 255 characters.
1	Returns full text of up to 2,147,483,648 characters (2^31). ( )

is_integerevents

Is a Boolean value that determines the event class display.

 

Value	Description
0	Displays event as a string.
1	Displays event as a integer.

number_of_events

Is an integer that represents the number of events to fetch from the trace queue. If this parameter is not specified, number_of_events fetches events as they are added to the trace queue, which is an infinite setting, and xp_trace_getevents never returns until the trace queue is destroyed. The minimum value is 1 and the maximum value is 2³² or 4294967296.

Return Code Values

0 (success) or >1 (failure)

Result Sets

Permissions

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

Examples

A. Retrieve all events as strings and with full text display

This example retrieves all events from the trace queue, returns the full text event information, and returns each event as a string (rather than an integer).

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_getevents @queue_handle,

    1,

    0

B. Retrieve all events as 255 characters and as integers

This example retrieves all events from the trace queue, displays the event information as a maximum of 255 characters, and displays each event as an integer (rather than a string).

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_getevents @queue_handle,

    0,

    1

See Also