Prefix_error_query

ViStatus Prefix_error_query (ViSession vi, ViInt32 * errCode, ViChar errMessage[]);

Purpose

Queries the instrument and returns the instrument specific error information.

Generally, you call this function after another function in the instrument driver returns the IVI_ERROR_INSTRUMENT_STATUS error code. The driver returns IVI_ERROR_INSTRUMENT_STATUS when the instrument's status register indicates that the instrument's error queue is not empty. Prefix_error_query extracts the first error out of the instrument's error queue. For instruments that have status registers but no error queue, the driver simulates an error queue in software.

Parameter

Input
Name	Type	Description
vi	ViSession	Unique identifier for an IVI session.
Output
Name	Type	Description
errCode	ViInt32	Instrument error code
errMessage	ViChar array	Instrument error message

Return Values

Contains the status code that the function call returns. IVI engine functions can return error and warning values from several sets of status codes. Some status codes are unique to the IVI engine. Other status codes are the same codes that VISA Library functions return. Still others are error or warning values that functions in specific instrument drivers return. Each set of status codes has its own numeric range.

Regardless of the source of the status code, 0 always indicates success, a positive value indicates a warning, and a negative value indicates an error.

Related Topic

IVI Status Codes

Implementation Requirements

Report an error if the user passes VI_NULL for either of the output parameters.

If the instrument has status registers and an error queue, do the following.

1. Call Ivi_LockSession to lock the IVI session.
2. If simulation is disabled, send the error query command to the instrument. On IEEE 488.2 instruments, you do this by sending the :SYST:ERR? command. Then read the results from the instrument into the errCode and errMessage output parameters.
3. If simulation is enabled, set the errCode output parameter to 0, and copy "No error." into the errCode output parameter.
4. Call Ivi_UnlockSession to unlock the IVI session.

Some instruments have status registers but no error queue. The act of reading the status registers clears the error information. For such instruments, the check status callback must call Ivi_QueueInstrSpecificError to add the error information to a software error queue whenever the status registers indicate an error. The Prefix_error_query function must do the following:

1. Call Ivi_LockSession to lock the IVI session.
2. Call Ivi_InstrSpecificErrorQueueSize to determine if the software error queue is empty. If it is empty, call the check status callback and then Ivi_InstrSpecificErrorQueueSize again to determine if the software error queue is still empty.
3. If the software queue is not empty, call Ivi_DequeueInstrSpecificError to extract the error information into the errCode and errMessage parameters.
4. Otherwise, set the errCode output parameter to 0, and copy "No error." into the errMessage output parameter.
5. Call Ivi_UnlockSession to unlock the IVI session.

If the instrument cannot perform an error query, you should still include the function in the driver and return the warning VI_WARN_NSUP_ERROR_QUERY.