DriverSession::ReportError

Vi

[in] ViSession handle for the driver session.

errorCode

[in] The errorCode to report to the calling program.

... (variable argument list)

[in] Comma-separated list of string arguments to use in formatting the error message.

The same ViStatus error code supplied as the errorCode parameter.

This function is used to report errors from IVI-C driver implementation code. It performs two important tasks. First, it formats the error message associated with the specified error code. Nimbus maintains a an error message macro map in the driver project's Errors.cpp file. Each entry in that map associates an error code with an error message and this association drives the implementation of the ReportError function's message formatting.

The second task performed by this function is to associate the error code and formatted error message with the driver session so that the client application can use the standard IVI-defined GetError function to retrieve both the error code and the formatted error message.

Important

Because this function necessarily uses variable argument lists, there are two common mistakes that can be made with the ReportError function. The first error is to supply a different number of string arguments than are defined in the error message. Such a mismatch between the number of replacement tags in the error message and the number of string arguments supplied can produce unpredictable results, including program crashes. You can view the definition of an error message and the number of replacement tags ('%s' characters) via the Error Editor or by directly looking at the error message macro map in the driver project's Errors.cpp file. The second common mistake that can be made with the ReportError function is to supply a std::string argument instead of a plain ANSI-C string (i.e. a char*). If you wish to use a std::string argument, then simply access the c_str() member or the data() member by supplying an expression such as strMyArg.c_str().

The following example demonstrates use of the ReportError function.

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

    // The INVALID_VALUE error message is defined to have 3 string parameters, as follows:
    // 
    //  "Invalid value '%1' for method '%2', parameter '%3'.
    // 

    if (AttributeValue < 0)
    {
        // WRONG!! WRONG!! -- Don't do this. The std::to_string function returns a std::string, not a char*
        // 
        return ReportError(Vi, ACME4321_ERROR_INVALID_VALUE, std::to_string(AttributeValue), "ConfigureArmCount", "ArmCount");

        // WRONG!! WRONG!! -- Don't do this. The INVALID_VALUE message needs 3 arguments, not just two
        // 
        return ReportError(Vi, ACME4321_ERROR_INVALID_VALUE, std::to_string(AttributeValue).c_str(), "ConfigureArmCount");

        // Correct use. 
        // 
        return ReportError(Vi, ACME4321_ERROR_INVALID_VALUE, std::to_string(AttributeValue).c_str(), "ConfigureArmCount", "ArmCount");
    }
}