Click or drag to resize

Returning Errors from IVI-C Drivers

IVI-C drivers report errors by returning a failure ViStatus result. The IVI specifications then require that the user be able to call the IVI-defined GetError function to retrieve both the current error code and error message associated with the driver session. Nimbus supplies functions that make it simple for driver developers to define and compose helpful error messages and report them to users from within the driver implementation code.

Error Reporting Basics

Consider a situation where a method in an IVI-C driver receives a bad input parameter value. The IVI specifications say that the driver is supposed to return the IVI-defined error PREFIX_ERROR_INVALID_VALUE. In addition, the driver function is supposed to compose an error message of the following form:

Invalid value '%s' for method '%s', parameter '%s'.

The %s replacement tags are supposed to be filled in with the invalid value itself, the name of the function that generated the error and the name of the parameter. A properly formatted error message might look something like the following:

Invalid value '-2' for method 'ConfigureRamp', parameter 'Time'.

In addition to returning a valid ViStatus value and a properly formatted error message, IVI-C drivers are required to associated the error with the IVI session so that the client application can call the driver's GetError function to retrieve the full error details.

All of the tedious operations related to message formatting and session error management are handled by the ReportError and ReportErrorEx functions. These functions can be used to compose an error message for any error that as been added to the driver or is already available as one of the standard IVI-defined errors.

The code below demonstrates how an error would be properly composed and returned from an IVI-C driver.

C++
ViStatus _VI_FUNC acme4321_ConfigureArmCount(ViSession Vi, ViConstString RepCapIdentifier, ViInt32 ArmCount)
{
    // ...

    if (AttributeValue < 0)
    {
        return ReportError(Vi, ACME4321_ERROR_INVALID_VALUE, std::to_string(AttributeValue).c_str(), "ConfigureArmCount", "ArmCount");
    }
}
Reporting Errors for Invalid Enum Values

Nimbus provides the MemberName function as part of the EnumConverter class for the specific purpose of converting user-supplied enum numeric values to their macro name. This makes it much more convenient to return helpful error messages to users when improper enum values are passed to an IVI-C driver function.

The code below demonstrates the typical usage of the MemberName function.

C++
ViStatus _VI_FUNC acme4321_ConfigureDmmFunction(ViSession Vi, ViInt32 Function)
{
    // ...

    // We only support AC, DC, and Frequency measurements
    // 
    switch (Function)
    {
      case ACME4321_VAL_AC_VOLTS:
        // ...
        break;

      case ACME4321_VAL_DC_VOLTS:
        // ...
        break;

      case ACME4321_VAL_FREQ:
        // ...
        break;

      default:
        // The strMemberName variable will be set to the member name that corresponds to the unsupported value, for 
        // instance, "ACME4321_VAL_AC_CURRENT" or "ACME4321_VAL_TEMPERATURE".  If the value supplied by the user
        // does not correspond to any of the defined values for the enum, then the MemberName function will simply
        // return the numeric value itself converted to a string.
        // 
        auto strMemberName = FunctionEnum::MemberName(Function);
        return ReportError(Vi, ACME4321_ERROR_INVALID_VALUE, strMemberName.c_str(), "ConfigureDmmFunction", "Function");
    }
}
See Also

Download a complete CHM version of this documentation here.