Error Reporting for IVI

The IVI engine has an extensive mechanism for reporting errors. Almost all functions in the IVI engine return a negative status code if an error occurs and return VI_SUCCESS (0) if the function succeeds. A few functions return positive values to indicate warnings. The Ivi_GetAttributeViString function returns a positive value if the buffer you pass is not large enough to hold the current attribute value. The positive value indicates the size of the buffer you must pass to obtain the complete value.

The IVI engine functions return error and warning values from several sets of status codes. Some status codes are unique to the IVI Library. 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. The status codes topic lists the numeric ranges of the different sets of status codes. It also contains a listing of all the IVI error codes and the most commonly used VISA status codes.

Each IVI session has the following three attributes for reporting error information:

IVI_ATTR_PRIMARY_ERROR

IVI_ATTR_SECONDARY_ERROR

IVI_ATTR_ERROR_ELABORATION

Each instrument driver defines its own constant name for these attributes, with the instrument prefix replacing IVI in the name.

You can call Ivi_SetErrorInfo to set all three attributes at once. You can call Ivi_ClearErrorInfo to clear all three attributes at once. You can call Ivi_GetErrorInfo to obtain and then clear the values of all three attributes at once. Each instrument driver exports a Prefix_ version of each of the Get and Clear functions.

You also can access the attribute values using the following functions:

• Ivi_SetAttributeViInt32 to set primary or secondary error code

• Ivi_SetAttributeViString to set error elaboration string

• Ivi_GetAttributeViInt32 to obtain primary or secondary error code

• Ivi_GetAttributeViString to obtain error elaboration string

The three attributes describe the first error or warning that occurred since the last call to Ivi_GetErrorInfo or Ivi_ClearErrorInfo on the session. The primary error code specifies the primary reason for the error or warning. If no error or warning occurred, the primary error code is VI_SUCCESS (0). The secondary error code is optional and provides additional information about the error or warning condition. A value of 0 indicates no additional information. The error elaboration parameter is a string that can contain further descriptive information about the error or warning condition.

The IVI engine also maintains a primary error code, secondary error code, and error elaboration string for each execution thread. When you call Ivi_SetErrorInfo or Ivi_ClearErrorInfo on a session, the function sets or clears the error information for both the session and the thread. When you pass VI_NULL for the vi parameter to Ivi_SetErrorInfo or Ivi_ClearErrorInfo, the function sets or clears only the error information for the thread. This is useful when you do not have a session handle to pass, which occurs when a call to Ivi_SpecificDriverNew fails. To obtain the error information for the thread, you must call Ivi_GetErrorInfo with the vi parameter set to VI_NULL.

Normally, it is the responsibility of the 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 an elaboration string.

Ivi_SetErrorInfo does not overwrite existing significant error information unless you request it to do so. This allows you to make multiple calls to Ivi_SetErrorInfo at different levels in your instrument driver source code without the risk of losing important error information. It also preserves the information about the first error for the user. Refer to the Ivi_SetErrorInfo function description for more information on this mechanism.