Using the Queuing Method

This section contains information that applies to both Windows and Linux.

The queuing method is commonly used when an immediate response from your application is not needed. To use the queuing method for receiving notification that an event has occurred, you must do the following:

Enable one or several events with the viEnableEvent function.
Use viReadAsync to obtain the specific jobId from the session you are monitoring.
When ready to query, use the viWaitOnEvent function with VI_EVENT_IO_COMPLETION to check for queued events.

If the specified event has occurred, the event information is retrieved and the program returns immediately. If the specified event has not occurred, the program suspends execution until a specified event occurs or until the specified timeout period is reached. Refer to Events and Attributes for more information.

Example: Using the Queuing Method

This example program shows one way you can use the queuing method.

main();

ViSession vi;

ViEventType eventType;

ViEvent event;

.

.

viEnableEvent(vi, VI_EVENT_SERVICE_REQ, VI_QUEUE, VI_NULL);

.

.

viWaitOnEvent(vi, VI_EVENT_SERVICE_REQ, VI_TMO_INFINITE, &eventType, &event);

.

.

viClose(event);

viDisableEvent(vi, VI_EVENT_SERVICE_REQ, VI_QUEUE);

}

Enabling Events

Before an event can be delivered, it must be enabled using the viEnableEvent function:

viEnableEvent(vi, eventType, mechanism, context);

These parameters are defined as follows:

Parameter	Description
vi	The session the handler will be installed on.
eventType	The type of event to enable.
mechanism	The mechanism by which the event will be enabled. Specify VI_QUEUE to use the queuing method.
context	Not used in VISA 1.0. Use VI_NULL.

When you use VI_QUEUE in the mechanism parameter, you are specifying that the events will be put into a queue. Then, when a viWaitOnEvent function is invoked, the program execution will suspend until the enabled event occurs or the timeout period specified is reached. If the event has already occurred, the viWaitOnEvent function will return immediately.

Example: Enabling a Hardware Trigger Event

This example illustrates enabling a hardware trigger event.

viEnableEvent(vi, VI_EVENT_TRIG, VI_QUEUE, VI_NULL);

The VI_QUEUE mechanism specifies that when an event occurs, it will go into a queue. If you specify VI_ALL_ENABLE_EVENTS in the eventType parameter, all events that have previously been enabled on the specified session will be enabled for the mechanism specified in this function call. Use the viDisableEvent function to stop servicing the event specified.

Wait on the Event

When using the viWaitOnEvent function, specify the session, the event type to wait for, and the timeout period to wait:

viWaitOnEvent(vi, inEventType, timeout, outEventType, outContext);

The event must have previously been enabled with VI_QUEUE specified as the mechanism parameter.

Example: Wait on Event for SRQ

This example shows how to install a wait on event for service requests.

viEnableEvent(vi, VI_EVENT_SERVICE_REQ, VI_QUEUE, VI_NULL);

viWaitOnEvent(vi, VI_EVENT_SERVICE_REQ, VI_TMO_INFINITE, &eventType, &event);

.

.

viDisableEvent(vi, VI_EVENT_SERVICE_REQ, VI_QUEUE);

Every time a wait on event is invoked, an event context object is created. Specifying VI_TMO_INFINITE in the timeout parameter indicates that the program execution will suspend indefinitely until the event occurs. To clear the event queue for a specified event type, use the viDiscardEvents function.

Example: Trigger Event Queuing

The evntqueu.c sample program illustrates enabling an event queue using viWaitOnEvent and is installed on your system in the ProgrammingSamples subdirectory. See Example Programs and Installation Folders for locations of example programs. This program enables the trigger event in a queuing mode. When the viWaitOnEvent function is called, the program will suspend operation until the trigger line is fired or the timeout period is reached. Since the trigger lines were already fired and the events were put into a queue, the function will return and print the trigger line that fired.

This program is intended to show specific VISA functionality and does not include error trapping. Error trapping, however, is good programming practice and is recommended in your VISA applications. See Trapping Errors for more information.