Handling errors

Describes error handling in the C++ API.

In Concert Technology two kinds of errors are distinguished:

• Programming errors, such as:

  • accessing empty handle objects;

  • mixing modeling objects from different environments;

  • accessing Concert Technology array elements beyond an array’s size; and

  • passing arrays of incompatible size to functions.

    Such errors are usually an oversight of the programmer. After they are recognized and fixed there is usually no danger of corrupting an application. In a production application, it is not necessary to handle these kinds of errors.

    In Concert Technology such error conditions are handled using assert statements. If compiled without -DNDEBUG , the error check is performed and the code aborts with an error message indicating which assertion failed. A production application should then be compiled with the -DNDEBUG compiler option, which removes all the checking. In other words, no CPU cycles are consumed for checking the assertions.

• Runtime errors, such as memory exhaustion.

  A correct program assumes that such failures can occur and therefore must be treated, even in a production application. In Concert Technology, if such an error condition occurs, an exception is thrown.

All exceptions thrown by Concert Technology classes (including IloCplex) are derived from IloException. Exceptions thrown by algorithm classes such as IloCplex are derived from its child class IloAlgorithm::Exception. The most common exceptions thrown by CPLEX are derived from IloCplex_Exception, a child class of IloAlgorithm::Exception .

Objects of the exception class IloCplex::Exception correspond to the error codes generated by the CPLEX Callable Library. You query the error code from a caught exception by calling the method:

IloInt getStatus () const;

You query the error message by calling the method:

const char* IloException::getMessage() const;

That method is a virtual method inherited from the base class IloException. If you want to access only the message for printing to a channel or output stream, it is more convenient to use the overloaded output operator (operator<< ) provided by Concert Technology for IloException.

In addition to exceptions corresponding to error codes from the C Callable Library, a cplex object may throw exceptions pertaining only to IloCplex. For example, the exception MultipleObjException is thrown if a model is extracted containing more than one objective function. Such additional exception classes are derived from class IloCplex_Exception; objects can be recognized by a negative status code returned when calling method getStatus .

In contrast to most other Concert Technology classes, exception classes are not handle classes. Thus, the correct type of an exception is lost if it is caught by value rather than by reference (that is, using catch(IloException& e) {...} ). This is one reason that catching IloException objects by reference is a good idea, as demonstrated in all examples. See, for example, ilodiet.cpp . Some derived exceptions may carry information that would be lost if caught by value. So if you output an exception caught by reference, you may get a more precise message than when outputting the same exception caught by value.

There is a second reason for catching exceptions by reference. Some exceptions contain arrays to communicate the reason for the failure to the calling function. If this information were lost by calling the exception by value, method end could not be called for such arrays and their memory would be leaked (until env.end is called). After catching an exception by reference, calling the exception’s method end will free all the memory that may be used by arrays (or expressions) of the actual exception that was thrown.

In summary, the preferred way of catching an exception is this:

catch (IloException& e) {
  ...
  e.end();
}

where IloException may be substituted for the desired Concert Technology exception class.