Running Mosel

The Mosel environment may be accessed either through its libraries or by means of two applications, perhaps the simplest of which is Xpress Workbench, a development studio type environment for working with your Mosel models. Xpress Workbench is a complete modeling and optimization development environment that presents Mosel in an easy-to-use graphical interface with a built-in text editor.

In its standalone version, Mosel offers a simple interface to execute certain generic commands directly from the command prompt (or shell) of the operating system. The user may compile or execute source models or programs (.mos files), run binary models (.bim files) or retrieve information related to the Mosel environment itself (like properties of modules or version number of the system). An interactive debugger as well as a profiler are also included: the debugger allows to execute the model step by step, specify breakpoints from where status of the model can be examined. Running a model with the profiler provides detailed information on what part of the code is actually executed and how much time each statement requires. This information may be helpful for optimizing the model (by locating hot spots where the code is using a great deal of computer time) and also for building testsuites (by checking whether the data sets used in the test set exercise all statements of a given model).

mosel command: invocation

The mosel executable is typically used with the following syntax from an operating system console:

mosel command [-l lang] [-d dir] [-sdm sdm] [-sr rst] [-dp dsopath] cmd_args

Where the option -l selects the language for message translation (see Section Message translation); the option -d sets the working directory of the process; the option -sdm specifies the maximum size of stack dumps (displayed when a model terminates on a runtime error, this can also be set via the environment variable MOSEL_SDMAX, the default value of 0 disables the display of the stack trace); the option -sr defines the active restrictions (see Section mosel command: restricted mode) and -dp specify an initial DSO path (see Section Directive uses). The command parameter is one of the following commands and cmd_args are the associated arguments (square brackets indicate optional arguments):

comp[ile] [-sgGIpwiwenixSETVFD] [-pwd pwd] [-pk priv] [-k|-kf pub] [-ix incpfx] [-bx bimpfx] [-o outf] [-c usrcom] src [src2 ...]

Compile the model src and generate the corresponding Binary Model (BIM) file if the compilation succeeds. The extension .mos is appended to src if no extension is provided. If option ' -o outf' (filename to use for saving BIM file) is not given, the extension .bim is used to form the name of the binary file. If the flag ' -s' is selected, the private object names ( e.g. variables, constraints) are not saved into the BIM file. The flag ' -g' adds debugging information: it is required to locate a runtime error. The flag ' -G' adds both debugging and tracing information: it is required to run the model with the debugger. When the ' -G' flag is used, the compiler adds instructions in the generated code that may slow down execution speed of the model. The flag ' -I' may also be added to enable the xbim extension (see Section Directive options). The flag ' -D' enables generation of documentation annotations in the resulting BIM file (by default documentation annotations are ignored). With the flag ' -wi', the compiler emits a warning message each time a symbol is implicitly declared and the flag ' -ni' disables implicit declarations (see Section About implicit declarations). When the flag ' -we' is used warnings are handled like errors such that any warning will make the compilation fail. The option ' -c usrcom' may be used to add a commentary to the BIM file (see debugger command LSMODS). The options ' -ix' and ' -bx' define respectively the file name prefix for file inclusion (see Section Source file inclusion) and the file name prefix for package loading (see Section Directive uses). If the flag ' -p' is selected, only the syntax of the source file is checked, the compilation is not performed and no output file is generated.
The flag ' -x' will be used to generate a POT file (Portable Object Template) for message translation (see Section Message translation).
The other options are related to handling encrypted or signed BIM files (see Section mosel command: securing bim files): option ' -S' will be used to produce a signed file. Unless the option ' -pk' is specified, the default private key personal.key (see ssl_dir) is used for the signature. The options ' -V' and ' -T' control how to handle signed packages: by default signature of packages is ignored but, if the first option is used, the signature is checked and the loading fails if it cannot be verified. With option ' -T', only signed packages with a valid signature can be used ( i.e. packages without signature are not allowed). Public keys that are required for the verification are searched for in the default public keys directory pubkeys (see ssl_dir).
BIM file encryption is enabled by the ' -E' option: the encryption key is either deduced from the password stated via option ' -pwd' (if the flag ' -F' is active, the value of ' -pwd' is interpreted as a text file the first line of which is the password) or generated randomly. Optionally, the encryption key can be stored in the BIM file itself in encrypted form (this is required if it has been randomly generated): in this case the encryption requires public keys of the recipients of the BIM file (who will be able to decrypt the file using their own private keys). Public keys can be listed by using the ' -k' or ' -kf' options: in the first case, one public key is listed at a time (the ' -k' parameter may be used several times) and in the second case a file containing a list of keys is specified. Each line of this file is interpreted as a key file name (except empty lines or lines starting with ' !' or ' #' that are ignored). Unless they include a path specification, key files are considered to be located in the default public keys directory (for instance the key file "somekey" is searched in the public keys directory but the file "./somekey" comes from the current working directory). An encrypted BIM file can always be decrypted by its creator thanks to his private key.
Several source files may be passed to the compiler command in a single step (this is not compatible with option ' -o'): each file gets compiled individually.

run [-TVF] [-pwd pwd] [-pk priv] [-k|-kf pub] [-is in] [-os out] [-es err] [-dbg|-prof|-cov] [-sdir dir] [-nl] bim [param=value [...]]

Load the provided BIM file bim and then run it. Options ' -is in', ' -os out' and ' -es err' can be specified to define alternative default input, ouput and error streams to be used by Mosel. With option ' -prof' or ' -cov' the model is run through the profiler (see commands profile and coverage below) and with option ' -dbg' it is passed to the interactive debugger (see command debug). The option ' -sdir' can be used in addition to the profiler or debugger to indicate alternative locations for source files (this option may be stated several times).
The options ' -V' and ' -T' control how to handle signed BIM files (see Section mosel command: securing bim files): by default signature of files is ignored but, if the first option is used, the signature is checked and the loading fails if it cannot be verified. With the second option, only signed BIM files with a valid signature can be used ( i.e. files without signature are not allowed). For this verification task public keys are usually searched for in the default public keys directory pubkeys (see ssl_dir) but alternatively a list of expected keys may be specified with the ' -k' or ' -kf' options: in the first case, one public key is listed at a time (the ' -k' parameter may be used several times) and in the second case a list of keys is read from the given file. Each line of this file is interpreted as a key file name (except empty lines or lines starting with ' !' or ' #' that are ignored). Unless they include a path specification, key files are considered to be located in the default public keys directory (for instance the key file "somekey" is searched in the public keys directory but the file "./somekey" comes from the current working directory). Moreover, the special file name * implies that keys stored in the default location can also be used.
The options ' -pwd' and ' -pk' may be required to load an encrypted BIM file: the former defines the password to use (if the flag ' -F' is active, the value of ' -pwd' is interpreted as a text file the first line of which is the password) and the option ' -pk' servers to specify a private key file (to be used in place of the default personal.key in ssl_dir).
Optionally, a list of parameter values may be provided in order to initialize the run-time parameters of the model and/or the control parameters of the modules used. The syntax of such an initialization is param_name = value for a model parameter and dsoname.ctrpar_name = value for a control parameter, where dsoname is the name of a module and ctrpar_name the control parameter to set.
The option ' -nl' can be used when running the debugger on Unix/Linux systems to deactivate the command history if the terminal is not properly handled by the command history mechanism.

exec[ute] [compile_opts] [run_opts] src [param=value [...]]

Compile src, load, and then run the model. This command is equivalent to the consecutive execution of compile and run except that no BIM file is generated. All options documented for both, compile and run, can be used with this command. The use of option ' -prof' or ' -cov' implies the compiler flag ' -G' and the use of option -dbg will also add compiler flag ' -G' if flag ' -g' is not explicitly specified.

debug [compile_opts] [run_opts] src [param=value [...]]

This command is equivalent to ' execute -dbg', the model is compiled and then run through the interactive debugger. If the model is compiled with flag ' -G' (the default with this command), the execution is immediately suspended before the first statement. Otherwise the execution starts as usual but can be suspended by pressing ctrl-C. Note that if a critical operation is being processed, the interruption is delayed until the operation completes (for instance, the Optimizer cannot be interrupted during an iteration of its algorithm). Execution is suspended once more just before the program terminates: this makes it possible to inspect model data before the end of execution. Refer to the Section mosel command: interactive debugger below for further information on the use of the debugger.

prof[ile] [compile_opts] [run_opts] src [param=value [...]]

This command is equivalent to ' execute -prof', the model is compiled and then run through the profiler. After execution, the total execution time and some source coverage information is displayed. Moreover a file sourcefile .prof is generated based on the original source file. Each line of this file consists in:

• the number of times the corresponding statement has been executed;
• the total amount of time (in seconds) spent on this particular line (this measure is not valid if the statement is a recursive call);
• the elapsed time (in seconds) between the beginning of the execution and the last time the line was executed;
• the text of the model source

All lines of the original source file are transferred, lines that do not correspond to the beginning of a statement are directly copied without further information.
If the model runs additional submodels via mmjobs, a report for each model execution is also displayed and the associated annotated files are generated in a similar way as for the main model.

cover[age] [compile_opts] [run_opts] src [param=value [...]]

This command is equivalent to ' execute -cov', the model is compiled and then run through the profiler. The difference with the profile command described above is the type of reports generated: the files produced are taking the .cov extension and only collect the number of times each statement has been executed. Moreover existing files are updated instead of being replaced ( i.e. iteration counts of each statement are added up).

exam[ine] [-pwd pwd] [-pk priv] [-cspthirvaumVF] [mod|pkg [mod|pkg...]]

Display the list of constants, procedures/functions, types, IO drivers, control parameters and annotations of modules, packages or the Mosel core library. Optional flags may be used to select which type of information is displayed: ' -h' for general information, ' -c' for constants, ' -s' for subroutines, ' -v' for variables, ' -r' for requirements, ' -t' for types, ' -i' for IO drivers, ' -p' for control parameters and ' -a' for annotations. By default, listings are sorted in alphabetical order, option ' -u' disables sorting. If both, a package and a module of the same name, are available only the information relating to the package is displayed. To select either the package or the module, extension .bim or .dso can be appended to the library name. If the flag ' -m' is used and no package or module can be located then a binary model file is searched for in the current working directory. The displayed information is related to the Mosel core library if no name is specified with the command.
The option ' -V' can be added for checking the signature of signed BIM files (the result of the verification is reported in the header output). The options ' -pwd' and ' -pk' may be required to load an encrypted BIM file: the former defines the password to use (if the flag ' -F' is active, the value of ' -pwd' is interpreted as a text file the first line of which is the password) and the second option specifies a private key file (to be used in place of the default personal.key in ssl_dir).

lslib [-p|-m]

Display a list of available modules and packages. Use the optional flag ' -p' to list only packages and ' -m' to get modules only.

If none of the above keywords is recognized, the first argument of the command is interpreted as a Mosel file. In the case of a BIM file, the command 'run' is executed; otherwise the file name is passed to the command 'execute'.

The mosel command may also be started using only flags. Besides options '-V' (Mosel version information) and '-h' (short help message), all other options relate to starting Mosel in server mode when it is invoked from a remote instance: they should not be used directly (see the documentation of module mmjobs in Chapter mmjobs for further explanations).

After the completion of a command the mosel executable returns a non-zero status to the operating system in case of error and the execution status of the model if a model has been run (e.g. with the command execute). This execution status is the value provided via the procedure exit in the model (by default this is 0).

Some examples:

Execute model 'mymodel.mos' setting values for the model parameters A,B,C and D

> mosel mymodel A=33 B="word" C=true D=5.3e-5

Compile model 'm.mos' located on a web service and store the bim file locally in compressed form

> mosel comp -o zlib.gzip:m.bim.gz mmhttp.url:http://websrv/m.mos

Run 'optmod.bim' from the debugger enabling verbose mode of module 'mmxprs'

> mosel run -dbg optmod mmxprs.XPRS_verbose=true

List all available modules and packages

> mosel lslib

Display the list of subroutines defined by 'mmxprs'

> mosel exam -s mmxprs

Display all constants defined in the Mosel language

> mosel exam -c

Display version information of Mosel

> model -V

mosel command: interactive debugger

When a model that is executed through the debugger is interrupted (for instance, because the user has typed ctrl-C or an error has occured), the execution is suspended, the text source of the statement being processed is displayed and an interactive session starts. This mode is signaled by the specific prompt '>dbg' and the following commands may be entered (the arguments enclosed in square brackets [] are optional). The command line interpreter is case-insensitive, although we display commands in upper case for clarity:

BCONDITION bk [cond]

Define or remove a condition on a breakpoint. This command may be used to put a condition (Boolean expression) on the specified break point: the execution is suspended at the breakpoint only if the given condition is verified. To remove a condition previously set up, enter this command without specifying any condition.

BREAK [procname]|[line [file]]

Install a breakpoint. When a breakpoint has been set up, execution is interrupted whenever the statement corresponding to the specified location is reached. A procedure or function name may be used as the location: in this case a breakpoint is installed at the beginning of each procedure or function of the provided name. If this command is used without parameters, the breakpoint is defined at the current location.

BREAKPOINTS

List the defined breakpoints.

BREAKSUB [0|1]

Decide whether to suspend execution whenever a submodel is started.

CONTINUE

Resume execution. If the interruption was not due to an error, execution of the model continues, otherwise the execution of the model is aborted and Mosel exits.

DELETE [bk]

Delete a breakpoint.

DISPLAY [expression]

Record an expression to be displayed at every interruption. Used with no expression, this command gives a list of all recorded expressions.

DOWN [nblev]

Go down in the calling stack. If an argument is provided, it indicates how many levels down to go (default is 1).

EXPORTPROB [-pms] [filename [objective]]

Display or save to the given file (option filename) the matrix corresponding to the active problem. The matrix output uses the LP format (default) or the MPS format (flag ' -m'). A problem is available after the execution of a model. The flags may be used to select the direction of the optimization (' -p': maximize), the file format (' -m': MPS format) and whether real object names should be used (' -s': scrambled names — this is the default if the object names are not available). The objective may also be selected by specifying a constraint name.

FINISH

Continue execution until the end of the current subroutine. The execution continues but will be interrupted again after the subroutine terminates.

INFO [*|symbol [symbol...]]

Without arguments, this command displays information about the program being executed (this may be useful for problem reporting). Any specified argument is interpreted as a symbol from the current model. If the requested symbol exists in the model, this command displays some information about its type and structure. Several symbols may be given in a single call and if '*' is used in place of a symbol name then the information is displayed for every symbol of the model.

LIST [[start] nblines]

Display the source file that corresponds to the model being executed. When used with no extra argument, this command lists 10 lines of the source model starting at the current statement; used with a single positive parameter nblines, it displays nblines lines instead of the default 10 lines. If the parameter nblines is negative, it is interpreted as a starting point for the listing relative to the current statement. When 2 parameters are used, the first one is understood as the first line to display (a negative value is relative to the current line) and the second one as the number of lines to display.
Examples (assuming current line is 5):

>list        displays lines 5 to 14
>list 5      displays lines 5 to 9
>list -2     displays lines 3 to 14
>list -2 5   displays lines 3 to 7

LSATTR [typename]

Display the list of available attributes for all used native types or only those related to the specified type typename

LSLIBS

Display the list of all loaded dynamic shared objects (DSO) together with, for each module, its version number and its number of references ( i.e. number of loaded models using it).

LSLOCAL

Display the list of symbols defined locally to the current context.

LSMODS

Display the list of all models currently loaded in core memory. The information displayed for each model is:

• name: the model name and version number (given by the model and version statements in the source file);
• number: the model number is automatically assigned when the model is loaded;
• size: the amount of memory used by the model (in bytes);
• system comment: a text string generated by the compiler indicating the source filename and if the model contains debugging information and/or symbols;
• user comment: the comment defined by the user at compile time (cf. command compile);
• modules: the name and version number of each module required by the model;
• pkg. req.: if the model is a package, the name and version number of each package required by a model using this package;
• pkg. imp.: the name and version number of each package included by this model.

The active model is marked by an asterisk (' *') in front of its name.

LSSYMB [-cspou]

Display the list of symbols published by the current model. The optional flags may be used to filter what kind of symbol to display: ' -c' for constants, ' -s' for subroutines, ' -p' for parameters and ' -o' for everything else. By default the list is sorted in alphabetical order, option ' -u' disables sorting.

MODEL [modnum]

With no argument this command lists all models running concurrently. The active model (debugger commands are applied to this model) is identified by a star ( "*"). If provided, the argument is interpreted as a model number that becomes the active model.

NEXT [line [file]]

Continue execution until the next statement. The execution continues but will be interrupted again after the current statement has been completed. If a location information is provided (by means of a line number and, if necessary, a file name), the next interruption will occur before the specified statement is executed.

OPTION name [[=] value]

View or change the value of a command line parameter. These parameters are used by the command line interpreter to display real values (especially in command PRINT):

• realfmt: C-style format for printing floating point numbers (default value: "%g")
• zerotol: zero tolerance to decide whether two values are equal (default value: 1e-13). It is also used when printing very small numbers: if a value is smaller than zerotol, "0" is displayed instead.

Although these parameters have the same name and function as those used by Mosel when running a model, they are not synchronised with their internal counterpart.

PRINT expression [>> filename]

Evaluate then display the value of the given arithmetic or Boolean expression. For building the expression, the following functions can be used: getparam, ceil, floor, round, abs, getsize, getmodprop as well as all attributes (see LSATTR command above). In addition to these Mosel functions, the interpreter implements getnbdim that returns the number of dimensions of an array and getndx# that gets the index set of dimension number '#' of an array ( '#' being an integer between 1 and the number of dimensions of the array). get-functions may be called using the suffix notation ( e.g. getact(c) is equivalent to c.act). Some functions can be applied to arrays: the result is the evaluation of the function for each cell of the array. Private symbols of packages may be accessed by prefixing the symbol name by the package name and the symbol ∼ (for instance the identifier aa declared in the package mypkg can be accessed using mypkg∼aa). It is possible to report only a part of a collection (array, set or list) by specifying range information. Ranges definitions take one of these two forms:

• [ maxelt ]: get at most 'maxelt' elements
• [ skip maxelt ]: get at most 'maxelt' entries after skipping 'skip' elements

Several range definitions may be specified (separated by blanks): they are used when exploring complex structures ( e.g. a list of list).
The display format of this command is compatible with the data file format of Mosel. Use the operator >> filename to append output of the command to the file filename.
Examples:

>print getsol(x) >> solfile.txt
>print getact(C(1,"tut"))+c.size
>print toto~a
>print abs(mytol)>1
>print myarray.ndx2 [3]

QUIT

Terminate the debug session. Model execution is aborted and Mosel exits.

STEP

Continue execution until the next statement stepping into procedures and functions. The execution continues but will be interrupted again after the current statement has been completed. If the current statement contains function or procedure calls, interruption will happen in these procedures or functions.

UNDISPLAY [disp]

Remove an expression recorded with DISPLAY. If no parameter is provided, all recorded expressions are removed, otherwise the parameter is understood as a record number.

UP [nblev]

Go up in the calling stack. If an argument is provided, it indicates how many levels up to go (default is 1). Note that expressions are evaluated according to the current stack frame. For example, if variable i is defined in procedure B and execution is suspended in procedure A called by B; it is necessary to go up in the stack in order to view the value of i because it does not exist in the current frame.

WHERE [nblev]

Display the calling stack. The calling stack corresponds to the sequence of procedure and function calls being processed. For instance assume the model calls procedure A which calls procedure B and the execution is suspended in procedure B: the calling stack will contain 3 records (location where A is called, location where B is called and current statement).

If a command is not recognized, a list of possible keywords is displayed together with a short explanation. The command names can be shortened as long as there is no ambiguity (e.g. un can be used in place of UNDISPLAY but u is not sufficient because it could equally denote the UP command). String arguments (the parameter 10 is a number, but "10" or '10' are text strings) may be quoted with either single or double quotes. Quoting is required if the text string starts with a digit or contains spaces and/or quotes.

Execution step by step and breakpoints can be used only if the model has been compiled using option -G. In this case, before the execution starts, a breakpoint is automatically put at the first statement of the model. Otherwise (model has been compiled with option -g), the model will be interrupted only if an error occurs or keys ctrl-C are pressed.

When debugging a model that runs submodels via mmjobs a message is displayed each time a submodel starts or terminates. Moreover, interrupting the execution of the model also suspends the execution of all submodels: the entered commands are applied to the selected active model, the choice of which can be changed with the command MODEL.

mosel command: restricted mode

Mosel may be run in restricted mode: by selecting which restrictions are to be applied, it is possible to control what operations models can perform (in particular regarding disk access). Upon startup, if the option -sr is not stated, the command line interpreter uses the value of the environment variable MOSEL_RESTR for setting the execution restrictions. These restrictions are bit-encoded as an integer (each bit corresponding to a specific restriction) but restrictions can also be expressed by a list of one or more of the following keywords (symbols are not case-sensitive and can be optionally separated by spaces):

NoWrite (bit 0, value 1)

Disable write access on the local system. This restriction concerns all file access except databases. Access to the temporary directory is not affected.

NoRead (bit 1, value 2)

Disable read access on the local system (this also implies NoWrite). This restriction concerns all file access except databases. When this option is selected, the current working directory is automatically set to the temporary directory (which can still be accessed).

NoExec (bit 2, value 4)

Disable external command execution. This restriction deactivates some procedures/functions allowing execution of commands external to Mosel (for instance system or command). Also, Mosel can only load modules from read-only locations when this restriction is active.

WDOnly (bit 3, value 8)

File access is limited to the current working directory and its subdirectories as well as the paths specified by the environment variables MOSEL_RWPATH (for reading and writing) and MOSEL_ROPATH (for reading only). The temporary directory can still be accessed.

NoTmp (bit 4, value 16)

Access to the temporary directory is disabled.

NoDB (bit 5, value 32)

Disable access to databases by blocking connection routines ( e.g. SQLconnect or OCIlogon).

For example, to disable write access and execution of external commands the environment variable MOSEL_RESTR will have to be either the integer value 5 (1+4) or the string "NoWrite NoExec".

Restricted mode is observed by the Mosel core libraries (when accessing files and managing directories) and the system requires that modules also satisfy the stated restrictions (although implementation of restrictions may vary depending on the type of functionality provided by a given module): a module that does not support the restricted mode of execution will fail to load when Mosel is running in this mode.

mosel command: securing bim files

The bim file format is secure with respect to the intellectual property of the author of the model (i.e. it is not possible to recover the original model from the bim file). However, further security mechanisms may be required when a bim file is to be transferred over an insecure media (like the internet): in particular it might be necessary to (1) make sure the file has not been modified during the transfer and (2) guarantee that only the addressee can access the file.

A digital signature ensures the first requirement: it is computed using a private key (exclusively owned by the sender of the document) such that any addressee having the corresponding public key (provided by the sender) can, at the same time, verify that the document has been prepared by the sender and that it has not been altered during the transfer. From the Mosel command line tool, creating a signed bim file can be done by using the '-S' compiler option. When loading a signed bim file with the run command, it is required to enable the signature verification with options '-V' or '-T' as verification is not performed by default.

The second requirement can be satisfied by encrypting the bim file such that it appears as random data during the transfer. Mosel supports two kinds of encryption processes: it can use a usual password based key. In this case the same password is used for both encrypting and decrypting the bim file (the sender and the recipient have to share this key). The alternative is to rely on private/public key pairs like for the signature procedure outlined above: encryption is achieved with the public key of the adressee. Only the recipient will be able to decrypt the bim file using his private key. From the Mosel command line tool, creating an encrypted bim file can be done by using the '-E' compiler option. A password is specified with the '-pwd' option otherwise the public keys of the recipients have to be stated with the '-k' or '-kf' options (a bim file can be encrypted for up to 128 public keys).

Both signature and encryption require the management of private and public keys. These keys are expected to be stored in a predefined location specified by the module parameter ssl_dir.

Mosel relies on the RSA cryptographic system for the management of private/public key pairs (keys must be of at least 1024bits). The signature procedure uses the SHA256 message digest algorithm. Bim files are encrypted using the AES block cipher with keys of 128 bits.