Status and return values

Describes coding conventions of the C API with respect to status and return values.

Most routines in the Callable Library return an integer value, 0 (zero) indicating success of the call. A nonzero return value indicates a failure. Each failure value is unique and documented in the Callable Library Reference Manual. However, some routines are exceptions to this general rule.

The Callable Library routine CPXopenCPLEX returns a pointer to a CPLEX environment. In case of failure, it returns a NULL pointer. The argument *status_p (that is, one of its arguments) is set to 0 if the routine is successful; in case of failure, that argument is set to a nonzero value that indicates the reason for the failure.

The Callable Library routine CPXcreateprob returns a pointer to a CPLEX problem object and sets its argument *status_p to 0 (zero) to report success. In case of failure, it returns a NULL pointer and sets *status_p to a nonzero value specifying the reason for the failure.

Some query routines in the Callable Library return a nonzero value when they are successful. For example, CPXgetnumcols returns the number of columns in the constraint matrix (that is, the number of variables in the problem object). However, most query routines return 0 (zero) reporting success of the query and entail one or more arguments (such as a buffer or character string) to contain the results of the query. For example, CPXgetrowname returns the name of a row in its name argument.

It is extremely important that your application check the status (whether the status is indicated by the return value or by an argument) of the routine that it calls before it proceeds.