Problem handling

Prototypes for all BCL functions are contained in the header file, xprb.h, which needs to be included at the top of any program which makes BCL function calls. The first stage in the model building process is to initialize BCL, either explicitly with a call to XPRBinit or implicitly by creating a new problem with function XPRBnewprob (see below). During its initialization BCL also initializes the Xpress Optimizer, so if the two are to be used together, a separate call to XPRSinit is unnecessary (for further detail on using Optimizer functionality with BCL please refer to Appendix Using BCL with the Optimizer library). The initialization function checks for any necessary libraries, and runs security checks to determine license information about your Xpress installation.

Once models have been constructed and BCL routines are no longer needed, the function XPRBfree may be called to reset BCL.

Problem creation and deletion

BCL has an object-oriented design. A mathematical model is represented in BCL by a problem that contains a collection of other objects (variables, constraints, index set etc). Every BCL function takes as the first argument the object it operates on.

A problem reference in BCL is a variable of type XPRBprob. A problem is created using the XPRBnewprob function, additionally providing a problem name, in the following way:

XPRBprob prob;
   ...
prob = XPRBnewprob("MyProb");

The problem reference, prob, is subsequently provided as the first argument to functions operating on the problem.

Once use of a particular problem has ended, the problem should be removed using XPRBdelprob, freeing associated resources. It should be noted that resources associated with problems are not released with a call to XPRBfree, so failure to explicitly delete each problem may result in memory leakage. It is also possible to delete just the solution information stored by BCL after an optimization run (including all problem-related information loaded in Xpress Optimizer), if the definition of the problem is to be kept for later re-use but its solution data is not required any longer (function XPRBresetprob).

Initialize a new model

XPRBprob pb1;
...
pb1 = XPRBnewprob("Problem1");

Delete problem definition

XPRBdelprob(pb1);

Delete solution information

XPRBresetprob(pb1);

Load problem matrix

XPRBloadmat(pb1);

Fix column ordering

XPRBsetcolorder(pb1,1);

Get problem name

XPRBgetprobname(pb1);

Change problem name

XPRBsetprobname(pb1,"ProbOne");

Figure 2.1: Creating, accessing and deleting problems in BCL

Note that for every BCL problem of type XPRBprob exists a corresponding Xpress Optimizer problem (type XPRSprob). Although it is usually not necessary to access the optimizer problem directly in BCL programs, this may be required for certain advanced uses (see Appendix Using BCL with the Optimizer library for more detail).

Other basic functions

Other functions are also useful for problem handling and manipulation. With XPRBgetprobname, the name for a particular problem specified by a reference may be obtained, and with XPRBsetprobname it can be changed.

The function XPRBloadmat is really only needed by Optimizer library users. It explicitly transforms the BCL problem into the matrix representation in the Optimizer, passing the problem directly into the Optimizer. Usually this is done automatically by BCL whenever required, but it may be necessary to load the matrix without optimizing immediately, e.g. so that an advance basis can be loaded before starting the optimization. The matrix generated by BCL remains unchanged in repeated executions of the program; the column ordering criterion may be changed by setting the ordering flag to 1 (function XPRBsetcolorder) before the matrix is loaded.

Input and output settings

BCL supports a number of functions for directing the input and output of a program. Those functions are independent of the particular problem and consequently do not take the problem pointer as an argument or may be used with a NULL argument. They may be called prior to the creation of any problem using XPRBnewprob, and even prior to the initialization of BCL. Any other BCL function will result in an error if it is executed before BCL has been initialized.

Printout of BCL status information, warnings or error messages may be turned off (function XPRBsetmsglevel). With function XPRBdefcbmsg, the user may define the message callback function to intercept all output printed by BCL (including messages from the Optimizer library and output from the user's program printed with function XPRBprintf, the latter not being influenced by the setting of the message print level). Section User error handling in the next chapter shows an example of a message callback.

The formating of real numbers used by the BCL output functions (including matrix export) can be set with the function XPRBsetrealfmt.

For data input in BCL (using functions XPRBreadlinecb and XPRBreadarrlinecb), it is possible to switch from the (default) Anglo-American standard of using a decimal point to some other character, such as a decimal comma (XPRBsetdecsign).

Set number format

XPRBsetrealfmt(prob, "%8.4f");

Set decimal sign

XPRBsetdecsign(',');

Set printout level

XPRBsetmsglevel(prob,1);

Set error handling

XPRBseterrctrl(0);

Error handling callback

void myerror(XPRBprob my_prob, void *my_object, int num,
int type, const char *txt);
XPRBdefcberr(prob,myerror,object);

Printing callback

void myprint(XPRBprob my_prob, void *my_object, const char *msgtext);
XPRBdefcbmsg(prob,myprint,object);

Get version number

const char *version;
version = XPRBgetversion();

Figure 2.2: Input and output settings, and error handling in BCL

Error handling

By default, BCL stops the program execution if an error occurs. With function XPRBseterrctrl the user may change this behavior: the error messages are still produced but the user's program has to provide the error handling. This setting may be useful, for instance, if an BCL program is embedded into some other application or executed under Windows.

Error handling by the user's program may either be implemented by checking the return values of all BCL functions, or preferably, by defining a callback (with function XPRBdefcberr) to intercept all warnings and errors produced by BCL. This function is not influenced by XPRBsetmsglevel, that is the user may turn off message printing and still be notified about any errors that occur. Section User error handling in the next chapter shows an example of an error callback.

When reporting problems with the software, the user should always give the version of BCL. This information can be obtained with the function XPRBgetversion.