ILOG CPLEX 11.0 User's Manual

program—can discover the length of these arrays by first calling CPXgetcols with a valueof 0 for cmatspace. This call will return an error status of CPXERR_NEGATIVE_SURPLUSindicating a shortfall of the array length specified in cmatspace (in this case, 0); it will alsoreturn the actual number of matrix nonzeros in the requested range of columns.CPXgetcols deposits this shortfall as a negative number in the integer pointed to bysurplus_p. Your application can then negate this shortfall and allocate the arrays cmatindand cmatval sufficiently long to contain all the requested matrix elements.The following sample of code illustrates this procedure. The first call to CPXgetcols passesa value of 0 (zero) for cmatspace in order to obtain the shortfall in cmatsz. The samplethen uses the shortfall to allocate the arrays cmatind and cmatval properly; then it callsCPXgetcols again to obtain the actual matrix coefficients and row indices.status = CPXgetcols (env, lp, &nzcnt, cmatbeg, NULL, NULL,0, &cmatsz, 0, numcols - 1);if ( status != CPXERR_NEGATIVE_SURPLUS ) {if ( status != 0 ) {CPXmsg (cpxerror,"CPXgetcols for surplus failed, status = %d\n", status);goto TERMINATE;}CPXmsg (cpxwarning,"All columns in range [%d, %d] are empty.\n",0, (numcols - 1));}cmatsz = -cmatsz;cmatind = (int *) malloc ((unsigned) (1 + cmatsz)*sizeof(int));cmatval = (double *) malloc ((unsigned) (1 + cmatsz)*sizeof(double));if ( cmatind == NULL || cmatval == NULL ) {CPXmsg (cpxerror, "CPXgetcol mallocs failed\n");status = 1;goto TERMINATE;}status = CPXgetcols (env, lp, &nzcnt, cmatbeg, cmatind, cmatval,cmatsz, &surplus, 0, numcols - 1);if ( status ) {CPXmsg (cpxerror, "CPXgetcols failed, status = %d\n", status);goto TERMINATE;}That sample code (or your application) does not need to set the length of the array cmatbeg.The array cmatbeg has one element for each column in the requested range. Since thislength is known ahead of time, your application does not need to call a query routine tocalculate it. More generally, query routines use surplus arguments in this way only for thelength of any array required to store problem data of unknown length. Problem data in thiscategory include nonzero matrix entries, row and column names, other problem data names,special ordered sets (SOS), priority orders, and MIP start information.ILOG CPLEX 11.0 — USER’ S MANUAL 129