Session Callback Functions
The IVI Engine allows an instrument driver to install two callback functions that are global to an entire IVI session: operation complete and check status.
Operation Complete Callback
The operation complete callback waits until the instrument finishes processing all pending operations. Many instruments cannot accept a command while processing a previous one. If an instrument takes a long time to process an attribute setting, the driver must avoid sending another command until the instrument is ready. By setting IVI_VAL_WAIT_FOR_OPC_AFTER_WRITES for the attribute, the driver causes the IVI Engine to invoke the operation complete callback after invoking the write callback for the attribute.
High-level instrument driver functions can call the operation complete callback directly. For example, a high-level measurement function might use the operation complete callback to wait until the instrument has completed an acquisition before attempting to retrieve the data from the instrument.
The IVI Engine invokes the operation complete callback in the following two cases:
- Before invoking the read callback for attributes, for which the IVI_VAL_WAIT_FOR_OPC_BEFORE_READS flag is set
- After invoking the write callback for attributes, for which the IVI_VAL_WAIT_FOR_OPC_AFTER_WRITES flag is set
The operation complete callback is optional. By default, an IVI session does not have an operation complete callback. The driver can install an operation complete callback by calling Ivi_SetAttributeViAddr with the IVI_ATTR_OPC_CALLBACK attribute.
The operation complete callback must have the following prototype:
ViStatus _VI_FUNC <function name>(ViSession vi, ViSession io);
Check Status Callback
Most instruments have status registers and an error queue. The status register indicates whether one or more errors are in the queue. Typically, the check status callback queries the status registers to determine if the instrument has encountered an error. If it has, the driver returns the IVI_ERROR_INSTR_SPECIFIC error code. The user then calls the Prefix_error_query function. The Prefix_error_query function extracts instrument specific error information from the instrument error queue and returns it to the user.
The IVI Engine invokes the check status callback in the Ivi_SetAttribute and Ivi_GetAttribute functions. It does so only when a Prefix_SetAttribute function passes the IVI_VAL_DIRECT_USER_CALL flag in optionFlags parameter of the corresponding Ivi_SetAttribute function.
The high-level functions in an instrument driver also invoke the check status callback. They do so at the end of functions that make one or more Ivi_SetAttribute or Ivi_GetAttribute calls or that perform direct instrument I/O.
The user can disable the check status callback by setting the IVI_ATTR_QUERY_INSTR_STATUS attribute to VI_FALSE. The driver can disable the check status callback for a particular attribute by setting the IVI_VAL_DONT_CHECK_STATUS flag.
The check status callback is optional. By default, an IVI session does not have a check status callback. The driver can install a check status callback by calling Ivi_SetAttributeViAddr with the IVI_ATTR_CHECK_STATUS_CALLBACK attribute.
The check status callback must have the following prototype:
ViStatus _VI_FUNC <function name> (ViSession vi, ViSession io);
Instruments without Error Queues
Some instruments have status registers but no error queue. All the error information is in the status registers. The act of reading the status registers clears them. When the check status callback queries the registers, it destroys the error information.
In this case, the check status callback must queue the error information in software so that the Prefix_error_query function can return it. The IVI Engine contains functions to manage the software error queue for a session. The check status callbacks calls Ivi_QueueInstrSpecificError to add the error information to the queue.
The Prefix_error_query function first calls Ivi_InstrSpecificErrorQueueSize to determine if the software queue is empty. If the queue is empty, Prefix_error_query calls the check status callback and then checks the software queue size again. In either case, if there is an error in the queue, Prefix_error_query calls Ivi_DequeueInstrSpecificError to extract the error information and then returns the error information to the user.