Error Macros for IVI

The ivi.h header file contains macros that you can use in your source code to facilitate error handling. These macros require that you have the following declaration at the top of the function in which the macro appears:

ViStatus error = VI_SUCCESS;

The macros also require that you have the following label near the end of the function:

Error:

Some of these macros require access to a ViSession variable named vi, which they pass to Ivi_SetErrorInfo in certain cases. The names of these macros all begin with viCheck.

Normally, you use the macros around function calls, but you can also use them around variables or expressions.

The following describes the behavior of each macro.

checkAlloc(pointer)

If pointer is VI_NULL, assign VI_ERROR_ALLOC to the error variable and jump to the Error label.

checkErr(status)

Assign status to the error variable. If status is positive, coerce the error variable to zero. If status is negative, jump to the Error label.

checkWarn(status)

Assign status to the error variable. If negative, jump to the Error label.

viCheckAlloc(pointer)

If pointer is VI_NULL, assign VI_ERROR_ALLOC to the error variable, call Ivi_SetErrorInfo with VI_ERROR_ALLOC as the primary error code, and jump to the Error label.

viCheckErr(status)

Assign status to the error variable. If status is positive, coerce the error variable to zero. If status is negative, pass it to Ivi_SetErrorInfo and jump to the Error label.

viCheckErrElab(status, elabString)

Assign status to the error variable. If status is positive, coerce the error variable to zero. If status is negative, pass it and elabString to Ivi_SetErrorInfo and jump to the Error label.

viCheckParm(status, parameterPosition, parameterName)

Assign status to the error variable. If status is positive, coerce the error variable to zero. If status is negative, do the following:

• Convert parameterPosition into one of the VXIplug&play error codes for invalid parameters, and pass it as the secondary error code to Ivi_SetErrorInfo. Pass status as the primary error code, and pass parameterName as the error elaboration.
• Jump to the Error label.

viCheckWarn(status)

Assign status to error. If status is nonzero, pass it to Ivi_SetErrorInfo. If status is negative, jump to the Error label.

Notice that the checkWarn and viCheckWarn macros preserve warnings whereas the other viCheck macros discard them. Also, viCheckWarn calls Ivi_SetErrorInfo on both warnings and errors, whereas the other macros call Ivi_SetErrorInfo only on errors.

When to Use the viCheck Macros

When returning an error or a warning, each user-callable instrument driver function must set the error information for the session and thread. You can do this by explicitly calling Ivi_SetErrorInfo at the end of the function, or you can use the viCheck macros in the function or in the lower-level routines that the function calls.

You can call the viCheck macros only when the following two conditions are true:

• The function in which it appears has a ViSession parameter named vi that is an IVI session handle or VI_NULL.
• The first argument you pass to the macro is either a pointer value, in the case of viCheckAlloc, or a status code that is negative if and only if an error occurs. IVI and VISA functions return such status codes.

It is best to use the viCheck macros at the lowest level in your code where these two conditions are true. You can then use the check versions of the macros at higher levels. All IVI engine functions that take the IVI session handle as a parameter call Ivi_SetErrorInfo when they return errors. Thus, you do not have to use the viCheck macros around calls to IVI functions. Nevertheless, it is harmless to make redundant use of the viCheck macros. The viCheck macros call Ivi_SetErrorInfo in such a way that it does not overwrite existing significant error information.

Examples

The following example shows how to handle errors returned by calls to IVI functions.

The following example shows how to handle errors that VISA functions return. This method also works for other libraries that return errors as negative values.

The following example shows how to report an error with an elaboration string.

if (triggerCount > 1 || sampleCount > 1)

viCheckErrElab( IVI_ERROR_INVALID_CONFIGURATION,

"Cannot use single point measurement "

" functions when DMM is configured for"

" multi-point.");

The following example shows how to report a parameter error in a user-callable instrument driver function.