Variable names and calling conventions

Describes the coding practices of the C API with respect to variable names and calling conventions.

Routines in the Callable Library obey the C programming convention of call by value (as opposed to call by reference, for example, in FORTRAN and BASIC). If a routine in the Callable Library needs the address of a variable in order to change the value of the variable, then that fact is documented in the Callable Library Reference Manual by the suffix _p in the argument name in the synopsis of the routine. In C, you create such values by means of the &  operator to take the address of a variable and to pass this address to the Callable Library routine.

For example, let’s look at the synopses for two routines, CPXgetobjval and CPXgetx, as they are documented in the Callable Library Reference Manual to clarify this calling convention. Here is the synopsis of the routine CPXgetobjval:

int CPXgetobjval (CPXCENVptr env, CPXCLPptr lp, double *objval_p);

In that routine, the third argument is a pointer to a variable of type double . To call this routine from C, declare:

double objval;

Then call CPXgetobjval in this way:

status = CPXgetobjval (env, lp, &objval);

In contrast, here is the synopsis of the routine CPXgetx

int CPXgetx (CPXENV env, CPXLPptr lp, double *x, int begin, int end);

You call it by creating a double-precision array by means of either one of two methods. The first method dynamically allocates the array, like this:

double *x = NULL;
x = (double *) malloc (100*sizeof(double));

The second method declares the array as a local variable, like this:

double x[100];

Then to see the optimal values for columns 5 through 104, for example, you could write this:

status = CPXgetx (env, lp, x, 5, 104);

The parameter objval_p in the synopsis of CPXgetobjval and the parameter x in the synopsis of CPXgetx are both of type (double *). However, the suffix _p in the parameter objval_p indicates that you should use an address of a single variable in one call, while the lack of _p in x indicates that you should pass an array in the other.

For guidance about how to pass values to CPLEX routines from application languages such as FORTRAN or BASIC that conventionally call by reference, see Call by reference in this manual, and consult the documentation for those languages.