Debugging Guide for applications that use the C API of CPLEX.

Answer

This page contains information regarding the C data structures of the CPLEX Callable Library. You may find it helpful for debugging applications that call CPLEX from C, Visual Basic, Delphi, Fortran, and other languages that can call CPLEX through its C interface. ILOG Concert Technology contains distinct C++, Java, and .NET APIs for programmers who wish to call from those environments. Refer to the Concert Debugging Guide for information about debugging programs that use Concert classes.

The most common source of bugs in Callable Library Applications consists of errors in the data arrays used to create or modify a problem. These errors may be difficult to track down because the symptom of the problem may occur much later in the program than the actual error. Furthermore, the behavior of the program may cause the user to suppose there is a bug in the CPLEX library when the actual problem is in the customer's program. Users who familiarize themselves with these fundamental data structures can often find their bugs more efficiently.

Versions 7.0 and later of CPLEX provide two ways for developers to quickly validate the CPLEX data structures in their application. The easiest way consists of turning the datacheck parameter on. This parameter causes CPLEX routines to check the arguments passed to them for validity. To turn on data checking, simply open the CPLEX environment and then insert the following statement into the program.

status = CPXsetintparam (env, CPX_PARAM_DATACHECK, CPX_ON);

CPLEX will then issue an error message for any invalid data it detects in the argument list passed into one of its routines. Be sure to turn this parameter off when an application is finally debugged and ready for production, as data checking can slow down the application.

In some cases, the datacheck parameter may not find the source of the problem. If so, use the diagnostic routines in the source file check.c. This source file comes with the CPLEX distribution. This file contains source code for functions that correspond to the various problem-building routines in the ILOG CPLEX Callable Library. For example, the Callable Library routine CPXcopylp has a corresponding routine in check.c called CPXcheckcopylp. The argument list is the same, so simply precede the call to CPXcopylp with a call to CPXcheckcopylp to verify the problem data arrays passed to CPXcopylp. These routines perform some additional checks beyond those performed in CPLEX when the datacheck parameter is on. In addition, check.c is a source file compiled and linked separately into the application. Therefore, users can step through this source code with a debugger to examine their argument lists more closely. Refer to the Programming Considerations section of the CPLEX Optimization Studio User's Manual for more information about how to use these features.

Another useful tactic for debugging Callable Library applications consists of using the routine CPXwriteprob to write out a binary or text file representation of the problem just before the symptom of the unexpected behavior. Then, read the problem file into the CPLEX Interactive Optimizer (that is, the base system), and see if you can reproduce the behavior. Note that a binary SAV file containing errors in the problem data may cause an ungraceful exit from the CPLEX Interactive Optimizer (that is, the base system). In such cases, the problem data in the program may contain errors, and the customer should turn on the datacheck parameter or use the diagnostic routines in check.c. On the other hand, a text LP or MPS format file should never cause a segmentation fault or other exception from the CPLEX Interactive Optimizer (that is, the base system). Even if the problem contains errors, CPLEX should handle them gracefully. So, in the (very rare) case where an exception occurs by reading an LP or MPS file into the CPLEX Interactive Optimizer (that is, the base system) and optimizing, you have found a problem that requires the attention of the CPLEX developers. Compress the problem file, and contact CPLEX technical support through the IBM support web site.

Click hereto download a program that will read in a SAV file exported by your program and check the problem data arrays for errors. If the program identifies errors in a particular problem data array, examine the code in your program that created that array; it probably is needs to be corrected. Note that you can also use this program on LP and MPS files to examine problem statistics that may identify code that doesn't crash, yet generates a unintended problem data values (although the interactive CPLEX optimizer offers that functionality as well). Finally, click here for a sample program that generates some additional problem statistics in the form of a histogram of problem data coefficients that can also help identify unintended problem data values.