IBNOTIFY
Board-Level/Device-Level
Purpose
Notify user of one or more GPIB events by invoking the user callback.
Format for ibnotify
C
unsigned long ibnotify (int ud, int mask, GpibNotifyCallback_t Callback, void * RefData)
Visual Basic (6.0)
CALL ibnotify (ud%, mask%, AddressOf Callback&, RefData$)
or
status% = ilnotify (ud%, mask%, AddressOf Callback&, RefData$)
Interactive Control
Not supported
Input for ibnotify
| ud | Board or device descriptor |
| mask | Bit mask of GPIB events to notice |
| Callback | Pointer to the callback function (see following prototype) |
| RefData | User-defined reference data for the callback |
Output for ibnotify
| Function Return | The value of Ibsta |
Description of ibnotify
If mask is non-zero, ibnotify monitors the events specified by mask, and when one or more of the events is true, the Callback is invoked. For a board-level ibnotify call, all mask bits are valid except for ERR and RQS. For a device-level ibnotify call, the only valid mask bits are CMPL, TIMO, END, and RQS. If TIMO is set in the notify mask, ibnotify calls the callback function when the timeout period has elapsed, if one or more of the other specified events have not already occurred. If TIMO is not set in the notify mask, the callback is not called until one or more of the specified events occur.
|
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 ibnotify call at any one time. If a current ibnotify is in effect for ud, it is replaced by a subsequent ibnotify call. An outstanding ibnotify call for ud can be canceled by a subsequent ibnotify call for ud that has a mask of zero.
If an ibnotify call is outstanding and one or more of the GPIB events it is waiting on become true, the Callback is invoked.
Before placing a board or device (and thus the ud) offline, all outstanding ibnotify calls must be cancelled by a subsequent ibnotify call for ud that has a mask of zero.
Callback Prototype for ibnotify
C
| int __stdcall Callback (int LocalUd, unsigned long LocalIbsta, unsigned long LocalIberr, unsigned long LocalIbcnt, void *RefData) |
Visual Basic (6.0)
| Function Callback (LocalUd%, LocalIbsta%, LocalIberr%, LocalIbcnt&, RefData$) |
Callback Parameters
| LocalUd | Board or device descriptor |
| LocalIbsta | Value of Ibsta |
| LocalIberr | Value of Iberr |
| LocalIbcnt | Value of Ibcnt |
| RefData | User-defined reference data for the callback |
Callback Return Value
Bit mask of the GPIB events to notice next.
The Callback function executes in a separate thread in your process. Therefore, it has access to any process global data, but no access to thread local data. If the Callback needs to access global data, you must protect that access using a synchronization primitive (for example, semaphore) because the Callback is running in a different thread context. Alternatively, the issue of data protection can be avoided entirely if the Callback simply posts a message to your application using the Windows PostMessage() function. The Callback function can call any of the NI-488.2 API with the exception of ibnotify. When the Callback is invoked, the values of the NI-488.2 global functions (Ibsta, Iberr, Ibcnt) are undefined. The status variables 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 return value of the Callback is interpreted as a mask value, which is used to automatically rearm the asynchronous event notification mechanism. If the return value is zero, it is not rearmed. If the return value is non-zero, the asynchronous event notification mechanism is rearmed with the return mask 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 ibnotify 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 ibnotify Usage section.
Possible Errors for ibnotify
| EARG | A bit set in mask is invalid. |
| ECAP | ibnotify has been invoked from within an ibnotify Callback function, or the handler cannot perform notification on one or more of the specified mask bits. |
| EDVR | The NI-488.2 driver is either configured incorrectly or is not properly installed. Ibcnt contains a system-dependent error code. |
| EHDL | ud is invalid or out of range. |
| ELCK | The requested operation could not be performed because of an existing lock by another process. |
| ENEB | The interface is not installed or is not properly configured. |
Possible Errors for ibnotify Callback
| EARM | The Callback return failed to rearm the Callback. |
| ERST | The event notification was cancelled due to a reset of the interface. |
Related Topics: