DriverSession::ReportErrorEx

Constructs a formatted error message based on the message associated with the specified error code and then associates the error code and the error message with the driver session.

Syntax

virtual ViStatus ReportErrorEx(ViStatus errorCode, const std::string strElaboration, ...) const;

ViStatus ReportErrorEx(ViSession Vi, ViStatus errorCode, const std::string strElaboration, ...);

Parameters

Vi

[in] ViSession handle for the driver session.

errorCode

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

strElaboration

[in] Additional information to append to the formatted error message associated with the specified errorCode.

... (variable argument list)

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

Return value

The same ViStatus error code supplied as the errorCode parameter.

Remarks

This function is functionally equivalent to the ReportError function except that an additional strElaboration parameter is available for appending custom information about the particular error occurrence. See the documentation of the ReportError function for additional information.

The string arguments supplied to the ReportErrorEx function are used to format the error message associated with the specified errorCode and to format the strElaboration. The arguments are first used to replace any ‘%s’ tags in the error message associated with the error code and then the remaining arguments are used to replace any ‘%s’ tags in the strElaboration string. Getting the order of string arguments correct is crucial in composing a properly formatted error message.

Important

Because this function necessarily uses variable argument lists, there are three 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 ReportErrorEx 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 third common mistake that can be made with the ReportErrorEx function is to specify the string arguments for the strElaboration parameter before those for the error message associated with the error code. The arguments supplied are first used to format the error message associated with the error code and then any remaining arguments are used to format the strElaboration parameter.

Example

The following example demonstrates use of the ReportError function.

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

    // The FUNCTION_NOT_SUPPORTED error message is defined to have 1 string parameter, as follows:
    //
    // Does not support this class-compliant feature: method '%1'
    //

    if (AttributeValue < 0)
    {
        // WRONG!! WRONG!! -- Don't do this. The InstrumentModel function returns a std::string, not a char*
        //
        return ReportErrorEx(Vi, ACME4321_ERROR_FUNCTION_NOT_SUPPORTED, "Function is not supported for instrument model '%s'", "ConfigureArmCount", InstrumentModel());

        // WRONG!! WRONG!! -- Don't do this. We need a total of two arguments, not just one
        //
        return ReportErrorEx(Vi, ACME4321_ERROR_FUNCTION_NOT_SUPPORTED, "Function is not supported for instrument model '%s'", "ConfigureArmCount");

        // WRONG!! WRONG!! -- Don't do this. The instrument model will be used to format the FUNCTION_NOT_SUPPORTED message instead of the elaboration message
        //
        return ReportErrorEx(Vi, ACME4321_ERROR_FUNCTION_NOT_SUPPORTED, "Function is not supported for instrument model '%s'", InstrumentModel().c_str(), "ConfigureArmCount");

        // Correct use.
        //
        return ReportErrorEx(Vi, ACME4321_ERROR_FUNCTION_NOT_SUPPORTED, "Function is not supported for instrument model '%s'", "ConfigureArmCount", InstrumentModel().c_str());
    }
}