viWaitOnEvent

Agilent VISA.NET

viWaitOnEvent

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.

Note: 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 Agilent 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_TTL7; VI_TRIG_ECL0 to VI_TRIG_ECL1

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 Agilent 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

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_TRIGGER

VI_ATTR_EVENT_TYPE
VI_ATTR_RECV_TRIG_ID

ViEventType
ViInt16

VI_EVENT_TRIGGER
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

VXI Mainframe Backplane (BACKPLANE) Resource Events

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_TTL7; VI_TRIG_ECL0 to VI_TRIG_ECL1

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 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 specified inEventType type available for this session.

Error Codes

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

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 in the Agilent VISA User’s Guide for more information on event handling.