sp_WaitForEvent

Advantage SQL Engine

  Previous topic Next topic  

This procedure allows a client to synchronously wait for an event notification to be sent by the server. If an event notification for the specified event has already been sent, then this will return immediately. In other words, the event notification does not have to occur while this procedure is actively waiting. This means that an application can check for an event periodically and use a small (or zero) timeout period.

This procedure will always return immediately when executed by a stored procedure or a trigger or within a script. A client must execute this as a singleton SQL statement in order to actually be able to receive an event notification. If it is executed in a script or by a stored procedure or trigger, the server returns an error.

 

When a signal is received from an event created with the ADS_EVENT_WITH_DATA option, one record will be returned for each signal that was sent to the event.  The signals will be in the order they were sent and the EventCount of each record will be the signal number rather than the total signal count.  Each record in the result set will also contain the event data from each signal in the StringData field.  Events created without the ADS_EVENT_WITH_DATA option will only return one record when a signal is received, as it has been done in the past.  In that case the EventCount will be the total number of signals that were received by that event and the StringData field will be empty.

 

Syntax

sp_WaitForEvent( EventName, char, 200,

                Timeout, integer,

                PollInterval, integer,

                Options, integer );

Timeout, integer,

PollInterval, integer,

Options, integer

);

Parameters

EventName (I)

Name of the event to wait for.

Timeout (I)

Maximum time to wait in milliseconds. 0 means it simply checks to see if a notification message has been sent to the client. It does not actually wait for an event to occur. As long as the client is registered, the server can save the notification to the client even if it is not waiting. Note that the timeout period may not be exact to the millisecond because the call requires a call to the server. The timeout period does not include that turnaround time. A value of -1 can be passed to specify an infinite wait.

PollInterval (I)

Only used for local server connections. Remote server connections use an efficient wait mechanism. Used to specify the interval between polls of the shared events table when waiting for the event. Zero can be passed to specify a default interval (which is currently configured at 300 milliseconds).

Options (I)

Options, reserved for future use, pass the value 0 for this parameter.

EventName (O)

Name of event that was signaled (for completeness and consistency with sp_WaitForAnyEvent).

EventCount (O)

Integer return value that indicates how many times the event was signaled.  A value of 0 means that it timed out (and was not signaled).  If the event was created with the ADS_EVENT_WITH_DATA option, the EventCount is the signal number rather than the total signal count.

StringData (O)

Event data that was sent to the event via the sp_SignalEvent procedure.

 

See Also

sp_CreateEvent

sp_DropAllEvents

sp_DropEvent

sp_SignalEvent

sp_WaitForAnyEvent

Example

-- wait for up to 2 seconds for the event to be signaled.

EXECUTE PROCEDURE sp_WaitForEvent( ‘my_event’, 2000, 0, 0 );