Ivi_SetErrorInfo
Usage
ViStatus Ivi_SetErrorInfo(ViSession vi, ViBoolean overwrite, ViStatus primaryError, ViStatus secondaryError, ViChar elaboration[ ]);
Purpose
This function sets the error information for the current execution thread and the IVI session you specify. If you pass VI_NULL for the vi parameter, this function sets the error information only for the current execution thread.
The error information includes a primary error code, secondary error code, 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.
The IVI engine retains the information you specify with Ivi_SetErrorInfo until the end-user retrieves it by calling PREFIX_GetError, the end-user clears it by calling PREFIX_ClearError, or you overwrite it with another call to Ivi_SetErrorInfo. Ivi_GetErrorInfo, which the end-user calls through PREFIX_GetError, always clears the error information.
Normally, it is the responsibility of the end-user to decide when to clear the error information by calling PREFIX_GetError or PREFIX_ClearError. If an instrument driver calls Ivi_GetErrorInfo, it should restore the error information by calling Ivi_SetErrorInfo, possibly adding a secondary error code or elaboration string.
Ivi_SetErrorInfo does not overwrite existing significant error information unless you pass VI_TRUE for the Overwrite parameter. Typically, you pass VI_FALSE for this parameter so you can make multiple calls to this function at different levels in your instrument driver source code without the risk of losing important error information. Also, end-users can make multiple calls to the instrument driver and be assured that PREFIX_GetError returns significant information about the first error that occurred since their last call to PREFIX_GetError or PREFIX_ClearError.
The viCheckErr, viCheckErrElab, viCheckParm, viCheckAlloc, and viCheckWarn macros use Ivi_SetErrorInfo. The ivi.h include file defines these macros. The viCheckWarn macro calls Ivi_SetErrorInfo on both warnings and errors, whereas the other macros discard warnings and call Ivi_SetErrorInfo only on errors.
Parameters
| Name | Type | Description |
|---|---|---|
| vi | ViSession |
To set the error information for a particular IVI session, pass the ViSession handle that you obtain from Ivi_SpecificDriverNew. When you pass a ViSession handle, the function also sets the error information for the current thread. To set only the error information for the current thread, pass VI_NULL. |
| overwrite | ViBoolean |
Pass VI_TRUE (1) for this parameter if you want the new error information to overwrite the existing error information regardless of the current contents of the error information. If you pass VI_FALSE (0), the function uses the following logic to determine whether to overwrite the existing error information.
This behavior 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. For instance, if you have already set the primary code to a negative error value, subsequent calls to Ivi_SetErrorInfo do not change the value. Consequently, Ivi_GetErrorInfo always returns the first error that you reported. At the same time, you can make subsequent calls to Ivi_SetErrorInfo to add further information. If your first call to Ivi_SetErrorInfo specifies a negative primary error code, a zero secondary error code, and no elaboration string, you can later add a secondary error code and an elaboration string by calling Ivi_SetErrorInfo with the same primary error code. Normally, end-users expect the error information to describe the first error that occurred since their last call to PREFIX_GetError or PREFIX_ClearError. So avoid passing VI_TRUE for this parameter. |
| primaryError | ViStatus |
Specify a status code describing the primary error condition. Use VI_SUCCESS (0) to indicate no error or warning. Use a positive value to indicate a warning. Use a negative value to indicate an error. |
| secondaryError | ViStatus |
Specify a status code that further describes the error or warning condition. If you have no further description, pass VI_SUCCESS (0) for this parameter. |
| elaboration | ViChar[ ] |
Specify an elaboration string that further describes the error or warning condition. The IVI engine stores the entire string for the session you specify, but it retains only IVI_MAX_MESSAGE_BUF_SIZE-1 (255) characters for the current execution thread. If you have no further description, pass VI_NULL or an empty string. |
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.