Ivi_GetErrorInfo
Usage
ViStatus Ivi_GetErrorInfo(ViSession vi, ViStatus* primaryError, ViStatus* secondaryError, ViChar errorElaboration[ ]);
Purpose
This function retrieves and then clears the error information for an IVI session or for the current execution thread. If you specify a valid IVI session for the vi parameter, this function retrieves and then clears the error information for the session. If you pass VI_NULL for the vi parameter, this function retrieves and then clears the error information for the current execution thread.
Instrument drivers export this function to the end-user through the PREFIX_GetErrorInfo function. Normally, the error information describes the first error that occurred since the end-user last called PREFIX_GetErrorInfo or PREFIX_ClearErrorInfo.
The error information includes a primary error code, secondary code error, and an error elaboration string. For a particular session, this information is the same as the values held in the following attributes:
- IVI_ATTR_PRIMARY_ERROR or PREFIX_ATTR_PRIMARY_ERROR
- IVI_ATTR_SECONDARY_ERROR or PREFIX_ATTR_SECONDARY_ERROR
- IVI_ATTR_ERROR_ELABORATION or PREFIX_ATTR_ERROR_ELABORATION
The IVI engine also maintains this error information separately for each thread. This is useful if you do not have a session handle to pass to Ivi_SetErrorInfo or Ivi_GetErrorInfo, which occurs when a call to Ivi_SpecificDriverNew fails.
Normally, it is the responsibility of the end-user to decide when to clear the error information by calling PREFIX_GetErrorInfo or PREFIX_ClearErrorInfo. If an instrument driver calls Ivi_GetErrorInfo, it must restore the error information by calling Ivi_SetErrorInfo, possibly adding a secondary error code or elaboration string.
You can call Ivi_GetErrorMessage to obtain a text description of the primary or secondary error value.
Parameters
| Name | Type | Description |
|---|---|---|
| vi | ViSession |
To obtain the error information for a particular IVI session, pass the ViSession handle that you obtain from Ivi_SpecificDriverNew. To obtain the error information for the current thread, pass VI_NULL. |
| primaryError | ViStatus* |
The primary error code for the session or execution thread. A value of VI_SUCCESS (0) indicates that no error occurred. A positive value indicates a warning. A negative value indicates an error. You can call Ivi_GetErrorMessage or PREFIX_error_message to get a text description of the value. If you are not interested in this value, you can pass VI_NULL. |
| secondaryError | ViStatus* |
The secondary error code for the session or execution thread. If the primary error code is non-zero, the secondary error code can further describe the error or warning condition. A value of VI_SUCCESS (0) indicates no further description. You can call Ivi_GetErrorMessage or PREFIX_error_message to get a text description of the value. If you are not interested in this value, you can pass VI_NULL. |
| errorElaboration | ViChar[ ] |
The error elaboration string for the session or execution thread. If the primary error code is non-zero, the elaboration string can further describe the error or warning condition. If you are not interested in this value, you can pass VI_NULL. Otherwise, you must pass a ViChar array with at least IVI_MAX_MESSAGE_BUF_SIZE (256) bytes. |
Return Value
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.