viWaitOnEvent

NI-VISA 15.0 Help

Edition Date: June 2015

Part Number: 370131S-01

»View Product Info

Purpose

Waits for an occurrence of the specified event for a given session.

C Syntax

ViStatus viWaitOnEvent(ViSession vi, ViEventType inEventType, ViUInt32 timeout, ViPEventType outEventType, ViPEvent outContext)

Visual Basic Syntax

viWaitOnEvent&(ByVal vi&, ByVal inEventType&, ByVal timeout&, outEventType&, outContext&)

Resource Classes

All I/O session types

Parameters

Name Direction Description

vi

IN

Unique logical identifier to a session.

inEventType

IN

Logical identifier of the event(s) to wait for.

timeout

IN

Absolute time period in time units that the resource shall wait for a specified event to occur before returning the time elapsed error. The time unit is in milliseconds.

outEventType

OUT

Logical identifier of the event actually received.

outContext

OUT

A handle specifying the unique occurrence of an event.

Return Values

Completion Codes Description

VI_SUCCESS

Wait terminated successfully on receipt of an event occurrence. The queue is empty.

VI_SUCCESS_QUEUE_NEMPTY

Wait terminated successfully on receipt of an event notification. There is still at least one more event occurrence of the type specified by inEventType available for this session.

VI_WARN_QUEUE_OVERFLOW

The event returned is valid. One or more events that occurred have not been raised because there was no room available on the queue at the time of their occurrence. This could happen because VI_ATTR_MAX_QUEUE_LENGTH is not set to a large enough value for your application and/or events are coming in faster than you are servicing them.

Error Codes Description

VI_ERROR_INV_OBJECT

The given session reference is invalid.

VI_ERROR_INV_EVENT

Specified event type is not supported by the resource.

VI_ERROR_TMO

Specified event did not occur within the specified time period.

VI_ERROR_NENABLED

The session must be enabled for events of the specified type in order to receive them.

VI_ERROR_QUEUE_OVERFLOW

No new event is raised because there is no room available on the queue. This means you have already received all previous events but not closed them. You must call viClose on each event you receive from viWaitOnEvent.

Description

The viWaitOnEvent() operation suspends the execution of a thread of an application and waits for an event of the type specified by inEventType for a time period specified by timeout. You can wait only for events that have been enabled with the viEnableEvent() operation. Refer to individual event descriptions for context definitions. If the specified inEventType is VI_ALL_ENABLED_EVENTS, the operation waits for any event that is enabled for the given session. If the specified timeout value is VI_TMO_INFINITE, the operation is suspended indefinitely. If the specified timeout value is VI_TMO_IMMEDIATE, the operation is not suspended; therefore, this value can be used to dequeue events from an event queue.

When the outContext handle returned from a successful invocation of viWaitOnEvent() is no longer needed, it should be passed to viClose().

If a session's event queue becomes full and a new event arrives, the new event is discarded. The default event queue size (per session) is 50, which is sufficiently large for most applications. If an application expects more than 50 events to arrive without having been handled, it can modify the value of the attribute VI_ATTR_MAX_QUEUE_LENGTH to the required size.

The outEventType and outContext parameters are optional and can be VI_NULL. This can be used if the event type is known from the inEventType parameter, or if the outContext handle is not needed to retrieve additional information. If VI_NULL is used for the outContext parameter, VISA will automatically close the event context.


Related Topics

Events

VI_ATTR_MAX_QUEUE_LENGTH

viClose

viEnableEvent

VISA Resource Template

WAS THIS ARTICLE HELPFUL?

Not Helpful