GpibNotify

Board-Level/Device-Level

Purpose

Notify user of one or more GPIB events by invoking the user callback. GpibNotify is an OLE control.

Format for the GpibNotify OLE Control

Visual Basic

status& = GpibNotify<x>.SetupNotify ud%, mask%

where <x> is the instance of the GpibNotify OLE control.

Interactive Control

Not supported

Input for the GpibNotify OLE Control

The mask parameter is optional. Alternative ways to set the mask value include using the SetSetupMask method or changing its value on the SetupMask page of the GpibNotify control properties.

Output for the GpibNotify OLE Control

Description of the GpibNotify OLE Control

If mask is non-zero, GpibNotify monitors the events specified by mask, and when one or more of the events is true, the Callback is invoked. For a board-level GpibNotify call, all mask bits are valid except for ERR and RQS. For a device-level GpibNotify call, the only valid mask bits are CMPL, TIMO, END, and RQS.

Note Notification is performed when the state of one or more of the mask bits is true, so if a request is made to be notified when CMPL is true, and CMPL is currently true, the Callback is invoked immediately.

For device-level usage, notification on RQS is not guaranteed to work if automatic serial polling is disabled. By default, automatic serial polling is enabled.

A given ud can have only one outstanding GpibNotify call at any one time. If a current GpibNotify is in effect for ud, it is replaced by a subsequent GpibNotify call. An outstanding GpibNotify call for ud can be canceled by a subsequent GpibNotify call for ud that has a mask of zero.

If a GpibNotify call is outstanding and one or more of the GPIB events it is waiting on become true, the Callback is invoked.

Note After you make a SetupNotify call, the global NI-488.2 status functions ( Ibsta , Iberr , and Ibcnt ) are undefined. Instead, use the thread-specific NI-488.2 status variable calls (ThreadIbsta, ThreadIberr, and ThreadIbcnt), to examine the NI-488.2 status variables returned by the SetupNotify call. This restriction applies only to the SetupNotify call; for the rest of the NI-488.2 calls, you can continue to examine Ibsta , Iberr , and Ibcnt .

Visual Basic exhibits odd behavior if the GpibNotify control is destroyed before the Callback has been executed. For this reason, cancel any outstanding Callbacks by calling SetupNotify with a mask of zero before the control is destroyed. In addition, your application should give any blocked Callback threads an opportunity to run before destroying the control by executing a Sleep 0 call.

Callback Prototype for the GpibNotify OLE Control

where <x> is the instance of the Notify callback routine. Each GpibNotify call has its own Callback routine.

Callback Parameters

The Callback function can call any of the NI-488.2 calls with the exception of GpibNotify. When the Callback is invoked, the values of the NI-488.2 global functions (Ibsta, Iberr, and Ibcnt) are undefined. The status functions passed to Callback should be examined, instead of the NI-488.2 globals, to determine why the Callback was invoked. Notice that it is possible that the Callback may be invoked because of an error condition rather than because of the setting of one or more of the requested mask bits.

The RearmMask is interpreted as a mask value that the NI-488.2 software uses to automatically rearm the asynchronous event notification mechanism. If RearmMask is set to zero, the Callback is not rearmed. If RearmMask is set to non-zero, the Callback is rearmed with the RearmMask value. If the Callback rearm fails due to an error, the Callback is invoked with ERR set in LocalIbsta and LocalIberr set to EARM.

Like ibwait, ibstop, and ibonl, the invocation of the GpibNotify Callback can cause the resynchronization of the handler after an asynchronous I/O operation has completed. In this case, the global variables passed into the Callback after I/O has completed contain the status of the I/O operation.

For an overview of asynchronous event notification in an NI-488.2 application, refer to the Asynchronous Event Notification section. For more information about usage, refer to the GpibNotify Usage section.

Possible Errors for the GpibNotify OLE Control

Possible Errors for the GpibNotify OLE Control Callback

Related Topics:

ibnotify

ibnotify Usage

ibnotify Usage Example