viWaitOnEvent

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

Specific items that apply in Windows only will be marked with a icon.

Syntax

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

Description

This function waits for an occurrence of the specified event for a given session. In particular, this function suspends execution of an application thread and waits for an event inEventType for at least the time period specified by timeout. See the individual event descriptions for context definitions.

If the specified inEventType is VI_ALL_ENABLED_EVENTS, the function waits for any event that is enabled for the given session. If the specified timeout value is VI_TMO_INFINITE, the function is suspended indefinitely to wait for an occurrence of an event.

If the value VI_TMO_IMMEDIATE is specified in the timeout parameter of viWaitOnEvent, application execution is not suspended. This operation can be used to dequeue events from an event queue by setting the timeout value to VI_TMO_IMMEDIATE.

viWaitOnEvent removes the specified event from the event queue if one that matches the type is available. The process of dequeuing makes an additional space available in the queue for events of the same type.

You must call viEnableEvent to enable the reception of events of the specified type before calling viWaitOnEvent. viWaitOnEvent does not perform any enabling or disabling of event reception.

If the value VI_NULL is specified in the outContext parameter of viWaitOnEvent and the return value is successful, viClose is automatically invoked on the event context rather than returning it to the application. Important: C/C++ programs do this, see Note on Context Return in visa32.cs and visa32.vb below.

The outEventType and outContext parameters to the viWaitOnEvent operation are optional. They can be used if the event type is known from the inEventType parameter or if the eventContext is not needed to retrieve additional information.

Since system resources are used when waiting for events (viWaitOnEvent), the viClose function must be called to free up event contexts (outContext).

This table lists events and associated read-only attributes implemented by Keysight VISA that can be read to get event information on a specific event. Use the viReadSTB function to read the status byte of the service request.

Instrument Control (INSTR) Resource Events

Event Name	Attributes	Data Type	Range
VI_EVENT_SERVICE_REQ	VI_ATTR_EVENT_TYPE	ViEventType	VI_EVENT_SERVICE_REQ
VI_EVENT_VXI_SIGP	VI_ATTR_EVENT_TYPE VI_ATTR_SIGP_STATUS_ID	ViEventType ViUInt16	VI_EVENT_VXI_STOP 0 to FFFFh
VI_EVENT_TRIG	VI_ATTR_EVENT_TYPE VI_ATTR_RECV_TRIG_ID	ViEventType ViInt16	VI_EVENT_TRIG VI_TRIG_TTL0 to VI_TRIG_TTL11 VI_TRIG_TTL0 through VI_TRIG_TTL7 apply to both VXI and PXI trigger lines. VI_TRIG_TTL8 through VI_TRIG_TTL11 apply only to PXI trigger lines.; VI_TRIG_ECL0 to VI_TRIG_ECL5; VI_TRIG_STAR_INSTR
VI_EVENT_IO_COMPLETION	VI_ATTR_EVENT_TYPE VI_ATTR_STATUS VI_ATTR_JOB_ID VI_ATTR_BUFFER VI_ATTR_RET_COUNT VI_ATTR_RET_COUNT_32 VI_ATTR_RET_COUNT_64 VI_ATTR_OPER_NAME	ViEventType ViStatus ViJobId ViBuf ViUInt32 ViString	VI_EVENT_IO_COMPLETION N/A N/A N/A 0 to FFFFFFFFh N/A
VI_EVENT_VXI_VME_INTR Not supported by Keysight VISA	VI_ATTR_EVENT_TYPE VI_ATTR_INTR_STATUS_ID VI_ATTR_RECV_INTR_LEVEL	ViEventType ViUInt32 ViInt16	VI_EVENT_VXI_VME_INTR 0 to FFFFFFFFh 1 to 7,  VI_UNKNOWN_LEVEL
VI_EVENT_PXI_INTR	VI_ATTR_EVENT_TYPE	ViEventType	VI_EVENT_PXI_INTR
VI_EVENT_USB_INTR	VI_ATTR_EVENT_TYPE VI_ATTR_USB_RECV_INTR_SIZE VI_ATTR_USB_RECV_INTR_DATA VI_ATTR_STATUS	ViEventType ViUInt16 ViBuf ViStatus	VI_EVENT_USB_INTR 0 to FFFFh N/A N/A

Memory Access (MEMACC) Resource Events

This section contains information specific to the Windows product.

Event Name	Attributes	Data Type	Range
VI_EVENT_IO_COMPLETION	VI_ATTR_EVENT_TYPE VI_ATTR_STATUS VI_ATTR_JOB_ID VI_ATTR_BUFFER ATTR_RET_COUNT VI_ATTR_OPER_NAME	ViEventType ViStatus ViJobId ViBuf ViUInt32 ViString	VI_EVENT_IO_COMPLETION N/A N/A N/A 0 to FFFFFFFFh N/A

GPIB Bus Interface (INTFC) Resource Events

Event Name	Attributes	Data Type	Range
VI_EVENT_GPIB_CIC	VI_ATTR_EVENT_TYPE VI_ATTR_GPIB_RECV_CIC_STATE	ViEventType ViBoolean	VI_EVENT_GPIB_CIC VI_TRUE VI_FALSE
VI_EVENT_GPIB_TALK	VI_ATTR_EVENT_TYPE	ViEventType	VI_EVENT_GPIB_TALK
VI_EVENT_GPIB_LISTEN	VI_ATTR_EVENT_TYPE	ViEventType	VI_EVENT_GPIB_LISTEN
VI_EVENT_CLEAR	VI_ATTR_EVENT_TYPE	ViEventType	VI_EVENT_CLEAR
VI_EVENT_TRIG	VI_ATTR_EVENT_TYPE VI_ATTR_RECV_TRIG_ID	ViEventType ViInt16	VI_EVENT_TRIG VI_TRIG_SW
VI_EVENT_IO_COMPLETION	VI_ATTR_EVENT_TYPE VI_ATTR_STATUS VI_ATTR_JOB_ID VI_ATTR_BUFFER VI_ATTR_RET_COUNT VI_ATTR_RET_COUNT_32 VI_ATTR_RET_COUNT_64 VI_ATTR_OPER_NAME	ViEventType ViStatus ViJobId ViBuf ViUInt32 ViString	VI_EVENT_IO_COMPLETION N/A N/A N/A 0 to FFFFFFFFh N/A

Backplane (BACKPLANE) Resource Events

This section contains information specific to the Windows product.

Event Name	Attributes	Data Type	Range
VI_EVENT_TRIG	VI_ATTR_EVENT_TYPE VI_ATTR_RECV_TRIG_ID	ViEventType ViInt16	VI_EVENT_TRIG VI_TRIG_TTL0 to VI_TRIG_TTL11 VI_TRIG_TTL0 through VI_TRIG_TTL7 apply to both VXI and PXI trigger lines. VI_TRIG_TTL8 through VI_TRIG_TTL11 apply only to PXI trigger lines.; VI_TRIG_ECL0 to VI_TRIG_ECL5; VI_TRIG_STAR_SLOT1 to VI_TRIG_STAR_SLOT12
VI_EVENT_VXI_VME_SYSFAIL	VI_ATTR_EVENT_TYPE	ViEventType	VI_EVENT_VXI_VME_SYSFAIL
VI_EVENT_VXI_VME_SYSRESET	VI_ATTR_EVENT_TYPE	ViEventType	VI_EVENT_VXI_VME_SYSRESET

TCPIP Socket (SOCKET) Resource

Event Name	Attributes	Data Type	Range
VI_EVENT_IO_COMPLETION	VI_ATTR_EVENT_TYPE VI_ATTR_STATUS VI_ATTR_JOB_ID VI_ATTR_BUFFER VI_ATTR_RET_COUNT VI_ATTR_OPER_NAME	ViEventType ViStatus ViJobId ViBuf ViUInt32 ViString	VI_EVENT_IO_COMPLETION N/A N/A N/A 0 to FFFFFFFFh N/A

Parameters

Name	Dir	Type	Description
vi	IN	ViSession	Unique logical identifier to a session.
inEventType	IN	ViEventType	Logical identifier of the event(s) to wait for.
timeout	IN	ViUInt32	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	ViPEventType	Logical identifier of the event actually received.
outContext	OUT	ViPEvent	A handle specifying the unique occurrence of an event.
Special Values for outEventType Parameter
Value			Description
VI_NULL			Do not return the type of event.
Special Value for outContext Parameter
Value			Description
VI_NULL			Do not return an event context.

Return Values 

Type ViStatus	This is the function return status. It returns either a completion code or an error code as follows.
Completion Code	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 specified inEventType type available for this session.
Error Code	Description
VI_ERROR_INV_EVENT	Specified event type is not supported by the resource.
VI_ERROR_INV_SESSION VI_ERROR_INV_OBJECT	The given session or object reference is invalid (both are the same value).
VI_ERROR_TMO	Specified event did not occur within the specified time period.

Note on Context Return in visa32.cs and visa32.vb

This section contains information specific to the Windows product.

It is not possible to pass a 'null' pointer for the 'ref context' parameter in viWaitOnEvent as it is defined in visa32.cs and visa32.vb. This means that VISA will not close the context and when viWaitOnEvent is called in a loop, the system will eventually run out of resources.

The solution is to close the returned context after a successful return from viWaitOnEvent. Here is some C# sample code that works:

          ...
          int context = 0;
          err = visa32.viWaitOnEvent(vi, visa32.VI_EVENT_SERVICE_REQ, 500, ref eventType, ref context);
          if (err >= visa32.VI_SUCCESS)
           {
                visa32.viClose(context);
          }
          ...

See Also

See Programming with VISA for more information on event handling.