Release 12. XPRESS-MP Modeller Subroutine Library XMSL. Reference Manual

Size: px

Start display at page:

Download "Release 12. XPRESS-MP Modeller Subroutine Library XMSL. Reference Manual"

Jane Mathews
5 years ago
Views:

1 Release 12 XPRESS-MP Modeller Subroutine Library XMSL Reference Manual Dash Associates June 15, 2000

3 XMSL Reference Manual Contents i Contents 1 Introduction 1 2 The XMSL Routines Functionality Features Return Values The C Interface initxm modver model freexm The FORTRAN Interface Compiling and Linking The XPRESS Environment Variable Using the Dynamic Link Library Edition Using XMSL with FORTRAN... 7 Appendix A: An Example C Program 9 Appendix B: An Example FORTRAN Program 11 Appendix C: An Example VB Program 13 Index 15

5 XMSL Reference Manual Introduction 1 1 Introduction The XPRESS-MP Modeller Subroutine Library (XMSL) is designed to provide the programmer with access to the XPRESS-MP model builder. It allows the developer to embed the functionality of the Console XPRESS model builder, mp-model, into bespoke applications. Together with the XPRESS-MP Optimiser Subroutine Library (XOSL), the developer can build integrated modelling and optimisation applications. For details of XOSL, see the XOSL Reference Manual. Greater flexibility, for example in interrogating and changing data tables, is provided by the XPRESS Entity Modelling and Optimisation Subroutine Library (EMOSL). See the EMOSL Reference Manual for details. XMSL is supplied as an object library or Dynamic Link Library which can be linked in with your own programs, together with a set of include files and tools. Chapter 2 describes the functionality, features and calling conventions of XMSL. Chapter 3 describes how to compile user-written routines and link them with XMSL. Example programs using XMSL in C, Fortran, and VB are contained in the the appendices. For details of the modelling language, the files used by the model builder, and connecting to databases and spreadsheets using XPRESS Connect ODBC, please see the XPRESS-MP Reference Manual. A tutorial-based introduction to these same topics is provided by the XPRESS-MP User Guide.

7 XMSL Reference Manual The XMSL Routines 3 2 The XMSL Routines 2.1 Functionality The XPRESS-MP modelling subroutine library contains four routines: initxm, model, freexm and modver. These routines give access to the modeller in a variety of ways, but essentially provide the same functionality as the Console XPRESS model builder, mp-model. Problems can be read from an ASCII model file or interactively from the terminal. Matrices may be generated or post-optimal processing performed. 2.2 Features Modelling mode - mode This allows the user to indicate whether the model routine should generate a matrix or perform post-optimal processing. When the mode is set to generate a matrix, the model file is read until a GENERATE, BIFGENERATE or END is encountered, at which point the matrix is generated (if the model is valid) and the routine finishes. When the mode is set to perform post-optimal processing, those statements following the GENERATE, BIFGENERATE or END are processed and the routine finishes without generating a matrix. Input/Output - echo This allows the user to indicate how the model routine should handle console input and output. It can be set so that: there is no console input/output; only error messages are produced; a full output listing is given; or input/output is read/written interactively (like mp-model). Error file - prterr A separate ASCII file listing all of the errors encountered by the model routine can be produced. This indicates where any errors have occurred in the model file without having to produce a full listing. This facility can be switched on or off using prterr. Number of errors - nerror The number of errors encountered by the model routine is returned into the nerror variable. 2.3 Return Values The routines return an integer value indicating success or failure. A return value of 0 indicates success while a non-zero return value indicates an invalid argument, a memory or file error or some sort of internal error. Below is a full list of return values and their meanings:-

8 XMSL Reference Manual The XMSL Routines 4 0 program terminated normally with END, GENERATE or BIFGENERATE 1 bad input encountered or termination with QUIT 2 bad or corrupt file - unrecoverable 4 memory error 8 corrupt use e.g. security violations, dongle not present or missing password and/or message files 16 program error 32 modeller has found errors in initialisation stage and has reverted into student mode 128 can't find coprocessor Note that a QUIT command in a model returns a return code of 1 by default from the model routine which is the same code used to indicate syntax or other errors in the model. If QUIT is followed by an expression, the value of the expression is returned, so QUIT 0 in the model file returns zero. 2.4 The C Interface initxm This routine controls the initialisation of the modeller. It must be called before any other XMSL routine. int initxm(char *qpath, int memry, int echo) where qpath memry echo is the directory where the XMSL security files mp-model.msg and xpress.pwd are stored. It is possible to pass a NULL argument instead, in which case the XPRESS environment variable is consulted. In either case, if the files are not found, then the directory containing the executable (or DLL for the DLL edition) is checked. is the amount of memory to be allocated to XMSL (in bytes). It is possible to supply a value of zero, in which case the XPMEMMOD environment variable is consulted instead. controls the console input and output from XMSL as follows: 0 indicates no console input/output 1 indicates banner heading and error message output only with no console input 2 indicates a full list output with no console input 3 indicates both console input and output. This is interactive (like mp-model). All console output is suppressed in the DLL edition of XMSL modver This routine gets the release number of XMSL. int modver(char *release) where release is a string buffer of 8 characters into which the release number string will inserted model This routine controls the processing of a model file. int model(char *qprblm, int mode, int prterr, int *nerror) where

9 XMSL Reference Manual The XMSL Routines 5 qprblm mode prterr nerror is the problem name, which is normally just the file name from which the problem is to be read. No file name extension is assumed and so files with any extension can be read; although if no extension is supplied, one of.mod is assumed. The file name can optionally include a drive and/or path specification. determines the modelling mode where: 1 indicates matrix generation 2 indicates post-optimal processing determines whether an ASCII error file is produced where: 0 indicates that no error file is produced 1 indicates that a error file is produced is an int variable that will be set to be the number of errors encountered in the problem file As with mp-model, the problem name is used as a basis for naming other files used by XMSL, unless overridden by file name specifications in the model. For instance, the listing file will be written to problem_name.lst, the error file to problem_name.err, and matrix to problem_name.mat. The problem name can also include d arguments, similar to mp-model, to define symbolic parameters to be used in the model. For instance, if the problem name string passed is "setex dfred=jim" then all occurrences of the string %fred% in the model setex will be replaced by jim freexm This routine frees the memory and resources used by the modeller. int freexm(void) 2.5 The FORTRAN Interface The FORTRAN version of the routines are called thus: call initxm_f(qpath, memry, echo) character*(*) qpath integer memry integer echo call modver_f(qver) character*(*) qver call model_f(qprblm, mode, prterr, nerror) character*(*) qprblm integer mode integer prterr integer nerror call freexm_f() All arguments are passed by reference. The variables take the same values as those defined in the C routines above.

11 XMSL Reference Manual Compiling and Linking 7 3 Compiling and Linking 3.1 The XPRESS Environment Variable All the makefiles supplied by Dash use the XPRESS environment variable to work out the location of various header and library files. It is important that this is set to the installation directory for the environment for which you are compiling. For example, if you are using the Windows 32-bit DLLs and you have installed the XPRESS-MP 32-bit DLL kit in the c:\xpressmp\library directory, then you should type the following before compiling XMSL applications. set XPRESS=c:\xpressmp\library 3.2 Using the Dynamic Link Library Edition Under Windows, XMSL exists as a dynamic link library (DLL) which can be called from any Microsoft Windows application. Each XMSL DLL function retains its name from the subroutine library but is capitalised and prefixed with XP (note that this is done automatically in the xpressm.h header file when using C). This is to avoid naming conflicts with some of the Windows development environments. All DLL functions take the same parameters as their subroutine library counterparts. int cb; int errors;... cb = initxm("c:\\xpressmp", ,0); cb = model("c:\\models\\setex",1,1,&errors); cb = freemod() 3.3 Using XMSL with FORTRAN The document Using the XPRESS Libraries with FORTRAN provided with the XPRESS Libraries distribution discusses the use of Compaq FORTRAN with XOSL.

13 XMSL Reference Manual An Example C Program 9 Appendix A: An Example C Program An example C program which calls XMSL is given below. It simply reads a model supplied by the user and generates a matrix assuming that the model contains no errors. #include <stdio.h> #include "xpressm.h" main() { char myproblem[128]; int errors, returnvalue; scanf("%s", myproblem); /* Initialise the modeller with no console I/O */ if( returnvalue = initxm(null, , 0) ) checkerror(returnvalue); /* Generate the matrix */ if( returnvalue = model(myproblem, 1, 1, &errors) ) checkerror(returnvalue); /* Free the modeller memory */ if( returnvalue = freexm() ) checkerror(returnvalue); } return 0; checkerror(int errno) { printf("error number %d encountered\n",errno); exit(1); }

15 XMSL Reference Manual An Example FORTRAN Program 11 Appendix B: An Example FORTRAN Program An example FORTRAN program which calls XMSL is given below. It reads the model setex1 from directory c:\models and generates the corresponding matrix. program model c c Example main program for the subroutine library. c character*128 myproblem character*128 security integer errors c myproblem = c:\models\setex1 c Initialise the modeller for no console I/O call initxm_f(, ,0) c c Generate the matrix c call model_f(myproblem, 1, 1, errors) if( errors.ne. 0 ) goto 8000 c freexm_f() c stop c 8000 print *,errors, errors detected. end

17 XMSL Reference Manual An Example VB Program 13 Appendix C: An Example VB Program The Visual Basic include file xpress.bas must be used in VB projects that use XPRESS-MP. Sub Modelit() Dim ssecurity As String Dim sproblem As String Dim lreturn As Long Dim lmodmemory As Long Dim lecho As Long Dim lmode As Long Dim lprterr As Long Dim lmoderrors As Long You may need to change the following to valid paths/files on your computer sproblem = "d:\model\pplan" lmodmemory = Initialise the Modeller lecho = 0 no console I/O lmode = 1 mode set for matrix generation lprterr = 1 produce a.err file lmoderrors = 0 number of errors in the model file lreturn = XPINITXM(vbNullString, lmodmemory, lecho) If lreturn <> 0 Then Call MsgBox(...) End End If Run the model lreturn = XPMODEL(sProblem, lmode, lprterr, lmoderrors) If lmoderrors > 0 Then Call MsgBox("...) lreturn = XPFREEXM() End End If Free the modeller memory lreturn = XPFREEXM() Now we are going to optimise....

19 XMSL Reference Manual Index 15 freexm_f 5 functionality 3 A Index arguments in problem name -d 5 C C example program 9 interface 4 compiling and linking 7 console input/output 3, 4 D -d arguments 5 DLL 7 dynamic link library see DLL E EMOSL 1 environment variable XPMEMMOD 4 XPRESS 4, 7 error file 3, 5 errors listed in file 3, 5 number of 3, 5 example program C example 9 FORTRAN example 11 VB example 13 F files security 4 files used by the model builder 1, 5 FORTRAN example program 11 interface 5 freeing XMSL 5 freexm 5 I initialising XMSL 4 initxm 4 initxm_f 5 input console 3, 4 interfaces C 4 FORTRAN 5 M matrix generation 3, 5 memory 4 mode modelling 3, 5 model 4 model file 3 processing 4 model_f 5 modelling language 1 modelling mode 3, 5 modver 4 modver_f 5 mp-model 1, 3 mp-model.msg 4 O output console 3, 4 P post-optimal processing 3, 5 problem name 5 Q QUIT command in model files 4 R release number 4 return values 3 routines 3 freexm 3 initxm 3

20 XMSL Reference Manual Index 16 S model 3 modver 3 security files 4 symbolic parameters defining 5 V VB example program 13 version 4 X XMSL 1 freeing 5 initialising 4 version 4 XOSL 1 XPMEMMOD environment variable 4 XPRESS Connect ODBC 1 XPRESS environment variable 4, 7 xpress.pwd 4

Release 12. Using the XPRESS Libraries with VB and VBA

Release 12. Using the XPRESS Libraries with VB and VBA Release 12 Using the XPRESS Libraries with VB and VBA Dash Associates June 15, 2000 Using the XPRESS Libraries with VB and VBA Contents i Contents 1 Introduction 1 1.1 Functionality... 1 1.2 Prerequisites...