Introduction

Topics covered in this chapter:

What is Mosel?

Mosel is an environment for modeling and solving problems. To this aim, it provides a language that is both a modeling and a programming language. The originality of the Mosel language is that there is no separation between a modeling statement (e.g. declaring a decision variable or expressing a constraint) and a procedure that actually solves the problem (e.g. call to an optimizing command). Thanks to this synergy, one can program a complex solution algorithm by combining modeling and solving statements.

Each category of problem comes with its own particular types of variables and constraints and a single kind of solver cannot be efficient in all cases. To take this into account, the Mosel system does not integrate any solver by default but offers a dynamic interface to external solvers provided as modules. Each solver module comes with its own set of procedures and functions that directly extends the vocabulary and capabilities of the Mosel language. The link between Mosel and a solving module is achieved at the memory level and does not require any modification of the core system.

This open architecture can also be used as a means to connect Mosel to other software. For instance, a module could define the functionality required to communicate with a specific database.

The modeling and solving tasks are usually not the only operations performed by a software application. This is why the Mosel environment is provided either in the form of libraries or as a standalone program.

General organization

As input, Mosel expects a text file containing the source of the model/program to execute (henceforth we use just the term 'model' for 'model/program' except where there might be an ambiguity). This source file is first compiled by the Mosel compiler. During this operation, the syntax of the model is checked but no operation is executed. The result of the compilation is a BInary Model (BIM) that is saved in a second file. In this form, the model is ready to be executed and the source file is not required any more. To actually 'run' the model, the BIM file must be read in again by Mosel and then executed. These different phases are handled by different modules that comprise the Mosel environment:

The runtime library: This library contains the VIrtual MAchine (VIMA) interpreter. It knows how to load a model in its binary format and how to execute it. It also implements a model manager (for handling several models at a time) and a Dynamic Shared Objects manager (for loading and unloading modules required by a given model). All the features of this library can be accessed from a user application.

The compiler library: The role of this module is to translate a source file into a binary format suitable for being executed by the VIMA Interpreter.

The standalone application: The 'mosel' application, also known as 'Mosel Console', is a command line interpreter linked to the two previous modules. It provides a single program to compile and execute models.

Various modules: These modules complete the Mosel set of functionalities by providing, for instance, optimization procedures. As an example, the mmxprs module extends the Mosel language with the procedure maximize that optimizes the current problem using the Xpress Optimizer.

This modularized structure offers various advantages:

• Once compiled, a model can be run several times, for instance with different data sets, without the need for recompiling it.
• The compiled form of the program is system and architecture independent: it can be run on any operating system equipped with the Mosel runtime library and any modules required.
• The BIM file can be generated in order to contain no symbols at all. It is then safe, in terms of intellectual property, to distribute a model in its binary form.
• As a library, Mosel can be easily integrated into a larger application. The model may be provided as a BIM file and the application only linked to the runtime library.
• The Mosel system does not integrate any kind of solver but is designed in a way that a module can provide solving facilities. The direct consequence of this is that Mosel can be linked to different solvers and communicate with them directly through memory.
• This open architecture of Mosel makes extensions of the functionality possible on a case by case basis, without the need to modify the Mosel internals.

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] [-tf trf] [-sdm sdm] [-sr rst]
              [-dp dsopath] [-bx bimpfx] 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 -tf defines a trace file (see command trace below); the option -sdm specifies the maximum size of stack dumps (displayed when a model terminates on a runtime error, an assertion fails or triggered by a call to dumpcallstack; 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 (to locate modules and packages) while -bx sets a list of bim file prefixes (used to find packages, see Section Directive uses). Both options -dp and -bx might be stated several times, the resulting setting will correspond to the concatenation of the provided values separated by the appropriate symbol. The command parameter is one of the following commands and cmd_args are the associated arguments that must be stated after the options described above (square brackets indicate optional arguments):

comp[ile] [-gGIpwiwewuninaxSETVFD] [-pwd pwd] [-pk priv] [-k|-kf pub] [-ix incpfx] [-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. The flag ' -g' adds debugging information: private object names ( e.g. variables, constraints) are included in the BIM file as well as required information for locating runtime errors. 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). The flag ' -na' disables assertions when the model is compiled with debug information (see assert). 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). Adding the flag ' -wu' will ask the compiler to report unused public symbols (excluding subroutines in packages), otherwise only private unused symbols are reported. 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 option ' -ix' defines the file name prefix for file inclusion (see Section Source file inclusion). 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|-trac] [-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), the option ' -trac' activates the tracing mode (see command trace) 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.
All command parameters stated after the ' --' marker are passed directly to the model that can access them using the deploy module (see Section Deploying models).
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', ' -cov' or ' -trac' 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) or the percentage of the total execution time (if option '-prof 2' is used) 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 (if option ' -cov 2' is used it is 0 or 1). Moreover existing files are updated instead of being replaced ( i.e. iteration counts of each statement are added up).

trace [compile_opts] [run_opts] src [param=value [...]] [-- ...]

This command is equivalent to ' execute -trac', the model is compiled and then run in tracing mode: the activity of the program is logged in a trace file that is automatically generated or extended (if the file already existed). The file name for this report is either defined using the ' -tf' option or taken from the environment variable MOSEL_TRFILE. In both cases a question mark in the file name will be replaced by the process ID expressed in hexadecimal. If no trace file is defined the default name 'tmpdir/xprm_?.trac' will be used ( 'tmpdir' being the temporary directory of the system). Refer to the Section mosel command: tracing mode below for further information on the trace file.

exam[ine] [-pwd pwd] [-pk priv] [-cspthHirvaumfLVF] [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. By default required packages are not loaded (but modules are loaded): using option ' -L' will force loading of all dependencies. To load only the header of the bim file to check its dependencies use option ' -H'. 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. With the flag ' -f' arguments are interpreted as bim-file names and loaded directly without search. 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: "%.10g")
• 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). For unions, the notation symbol.type is supported ( e.g. "myun.integer"), it is also possible to use suffixes array, set and list to access union values. Some functions can be applied to arrays: the result is the evaluation of the function for each cell of the array. Symbols are expected to be fully qualified: even if a symbol is expressed without namespace reference in the model source (thanks to the namespace search, see Section Namespaces) it is necessary to use its full name from the debugger. In particular private symbols of packages must be prefixed by the package name (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.

A program may interrupt its execution and trigger the interactive debugger by using the following special annotation (see Section Annotations):

!@mc.dbgmsg break

When the program is compiled with tracing information (option -G) this annotation is replaced by a special instruction that will cause an interruption when the program is being run through the debugger (otherwise it is silently ignored).

mosel command: tracing mode

Running a program in tracing mode results in the generation of a trace file that collects the activity of the program. Each record of this file consists in a single line of text that can take the following forms:

0O timestamp

The file has been open

0C timestamp

The file has been closed

mmS timestamp modelname

The model number mm with name modelname is starting. Line tracing is enabled

mmTrr timestamp modelname

The model number mm with name modelname is finishing, its status code is rr

mm- timestamp msg

The model number mm has disabled line tracing (with optional message msg), submodels are not affected

mm+ timestamp msg

The model number mm has enabled line tracing (with optional message msg), submodels are not affected

mm! timestamp msg

The model number mm logs message msg

mmLpp timestamp

The model number mm is loaded by model number pp

mmUpp timestamp

The model number mm is unloaded by model number pp

mm:nn fname

The model number mm is executing the statement at line nn of file fname (that becomes the current file for this model). These records are not emitted when line tracing is disabled.

mm nn

The model number mm is executing the statement at line nn of current file as specified previously for the given model These records are not emitted when line tracing is disabled.

A program may control the behaviour of the tracer using the special annotation mc.dbgmsg (see Section Annotations). The following annotations are interpreted:

!@mc.dbgmsg traceoff msg
!@mc.dbgmsg traceon msg
!@mc.dbgmsg tracelog msg

When the program is compiled with tracing information (option -G) this annotation is replaced by a special instruction that communicates with the tracer (it is silently ignored if the program is not run in tracing mode). The first syntax disables the line tracing (it is active by default), the second has the opposite effect while the last syntax makes it possible to insert a message in the trace file. In all cases the message text msg is optional.

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.

References

Mosel could be described as an original combination of a couple of well known technologies. Here is a non-exhaustive list of the most important 'originators' of Mosel:

• The overall architecture of the system (compiler, virtual machine, native interface) is directly inspired by the Java language. Similar implementations are also commonly used in the languages for artificial intelligence (e.g. Prolog, Lisp).
• The syntax and the major building blocks of the Mosel language are in some aspects a simplification and for other aspects extensions of the Pascal language.
• The aggregate operators (like 'sum') are inherited from the 'tradition of model builders' and can be found in most of today's modeling languages.
• The dynamic arrays and their particular link with sets are probably unique to Mosel but are at their origin a generalization of the sparse tables of the mp-model model builder.

Structure of this manual

The main body of this manual is essentially organized into two parts. In Chapter The Mosel Language, the basic building blocks of Mosel's modeling and programming language are discussed.

Chapter Predefined functions and procedures begins the reference section of this manual, providing a full description of all the functions and procedures defined as part of the core Mosel language. The functionality of the Mosel language may be expanded by loading modules: the following chapters describe the modules currently provided with the standard Mosel distribution.