Remote Invocation Protocol

Topics covered in this chapter:

A Mosel instance may be started remotely using either the connect procedure of the module mmjobs or its equivalent routine of the XPRD library. From any of these environments one can compile, load and run models as well as access files on the remote system. The remote invocation protocol also makes it possible to control more precisely the execution of models (e.g. suspending execution or profiling) and query information of a model (such as the value of entities) or the entire instance (e.g. to retrieve the list of available modules).

This protocol relies on two mechanisms:

1. the procedure setcontrol (available in mmjobs and XPRD) to (re)define Mosel instance control parameters
2. the special remote file 'mcmd' that only supports read access: the file name is interpreted as a query and the retrieved data is the answer to this request

Instance control parameters

Mosel instance control parameters are either defined at the instance level or they apply to a specific model (see setcontrol). Some of the parameters serve for changing the behaviour of other commands, others provide a means to execute some specific command.

The supported instance parameters are:

• zerotol (real,instance): set the zero tolerance used for comparison and displaying real numbers (i.e. a real number smaller than the tolerance is treated as 0)
• realfmt (string,instance): set the C-format used to display reals
• flushdso (none,instance): unloads unused modules (i.e. calls XPRMflushdso)
• lang (string,instance): set the language of the instance
• defaultnode (integer,instance): set the default node number used by the "rmt:" IO driver when it is used without node reference (see Section Driver rmt)
• runmode (int,model): set the execution mode of a model (cannot be changed during the execution of the model):
  • 0: default
  • 1: debug
  • 2: profile
  • 3: tracing
• dbgctrl (string,model): send a command to the debugger (model must be running in debug mode). See Section Debugger interface
• dbgbrksub (int,model): toggle breaksub mode during a debugging session (default is 0)
• sdmax (int,instance): set the maximum depth of a call stack dump (default is 0)

mcmd pseudo file

The special remote file 'mcmd' takes the form of an I/O driver where the file name is interpreted as a query and the retrieved data is the answer to this request. Except for the dsostream command that can also be open in write mode, 'mcmd' only supports read access. A file name for this driver has the following form:

mcmd:cmd[-opts][@mod[.submod]] cmdargs

cmd:

the operation to execute ( e.g. 'eval', 'profres'...).

opts:

options to change the format of the result. By default all data are sent using the Mosel binary format 'bin:'. Adding option 't' switches to text format (still compatible with initialisations blocks) and 'j' will cause results to be sent as a JSON object (not compatible with initialisations blocks). If option 'z' is used the resulting file is compressed with gzip. A given command may also support additional options (see 'lslib'). Except for the 'eval' command, the result set publishes always the same records that are either scalars of basic types or lists of basic types. When a collection of values is returned a specific label indicating the dimension of the list precedes the list.

mod:

master model on which the operation will be performed.

submod:

submodel. Only some operations can be applied to a submodel. Note that submodel '0' is the master model itself (the first submodel has ID '1').

Supported commands:

covres (model)

Retrieve profiling results for test coverage. This command can only be called after the model has been run in profiling mode (see Section Profiler interface).

tottime:real
Rlines: range
lines:  array(Rlines) of integer
iters:  array(Rlines) of integer
Rfiles: range
files:  array(Rfiles) of string
Rstarts:range
starts: array(Rstarts) of integer

dbgbrkp [ lndx [ cond|* ] ] (model or submodel)

Breakpoint management. The model must be suspended. Without any parameters this command returns the current list of breakpoints; the first parameter is interpreted as a line index and the second parameter is a logical expression ( i.e. the breakpoint condition). With only one parameter, the breakpoint on the corresponding line index is removed (no operation is performed if there was no breakpoint). Use '*' to remove all breakpoints. With two parameters the corresponding breakpoint is created (or modified). To set an unconditional breakpoint use '*' as the condition. Note that breakpoints are attached to a model: even if several models running concurrently are resulting from the same source file, setting a breakpoint for one model (instance) will have no effect on the others.

Rlndx: range
lndx:  array(Rlndx) of integer
cond:  array(Rlndx) of string

dbgflndx [ fctname|* ] (model or submodel)

Line indices corresponding to a function name. This command returns the line indices corresponding to the beginning ( lndx) and end ( elndx) of the requested function (several values are returned when the routine is overloaded). The values of elndx are valid only if the model has been compiled with option -G. Without any arguments or with argument '*', the command returns all functions of the model. If option 'N' is used, the arrays are sorted according to the function names. With option 'L' arrays are sorted following the line indices order.

Rsign: range
sign:  array(Rsign) of string
lndx:  array(Rsign) of integer
name:  array(Rsign) of string
elndx: array(Rsign) of integer

dbglndx (model or submodel)

Retrieve the mapping of the line indices of a model/submodel. The model must be either suspended or not running. The debugger interface works on line indices: each line index corresponds to a file name and a line number in this file.

Rfiles: range
files:  array(Rfiles:range) of string
Rlines: range
lines:  array(Rlines:range) of integer

dbgstat (model or submodel)

Current execution status of a model. The model must be suspended. If no submodel is specified, statuses of all submodels are returned in addition to the master model (to get the status of the master model only use submodel '0').

Rid:  range
id:   array(Rid) of integer
stat: array(Rid) of integer
stlev:array(Rid) of integer
lndx: array(Rid) of integer

dbgstlev [ stlev|* [ maxlev ] ] (model or submodel)

Stack management. The model must be suspended. Without any arguments or with argument '*', the command returns a stack dump ( i.e. a list of line indices). If the argument is ≥0, it becomes the current stack level. The optional argument 'maxlev' defines the maximum number of levels to return (default:10). The stack level defines the context in which expression evaluations are performed in the 'eval' command.

Rid: range
id:  array(Rid) of integer
stat:array(Rid) of integer
stlev:array(Rid) of integer
lndx:array(Rid) of integer

dsostream dsoname [specific parameters] (model or submodel)

This command opens a stream to the specified module (this command supports both read and write mode). The module must implement the SRV_DSOSTRE service. The behaviour of the stream and the expected parameters depend on the implementation.

eval label:expression [ range ] (model or submodel)

Evaluate an expression in the context of the provided model/submodel. Execution of the model must be completed or suspended. If option 'i' is used, array indices are reported as order numbers instead of values. With option 'n' array values are replaced by empty strings. The label " label" is used to identify the expresion in the result file: if it is '.' no label is generated (the data result is directly sent to the result file), if it is omitted then the expression itself is used as the label, otherwise the provided string is the label. Several expressions may be evaluated in a single request (in this case they must all be labelled).
It is possible to grab 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 structure and type of the result set depends on the expression.

info (instance, model or submodel)

This command reports all symbols defined by Mosel (if used without specifying any argument), a module (the argument is the module name) or a model (the argument is a model or submodel ID). In the case of a module, the command loads the module if it is not yet in memory. For a model (or package), it must have been loaded prior to this command since it is referenced by its ID and be either not running or suspended. Information returned by the 'info' command:

fmt:     integer
Rhdr:    range
hdr:     array(Rhdr) of string
Rdeps:   range
deps:    array(Rdeps) of integer
depsvers:array(Rdeps) of integer
depstyp: array(Rdeps) of integer
Rtyps:   range
typs:    array(Rtyps) of string
typscod: array(Rtyps) of integer
Rparms:  range
parms:   array(Rparms) of string
parmsval:array(Rparms) of integer
parmsdesc:array(Rparms) of string
Rconsts: range
consts:  array(Rconsts) of string
conststyp:array(Rconsts) of integer
Rcstint: range
cstint:  array(Rcstint) of integer
Rcststr: range
cststr:  array(Rcststr) of string
Rcstdbl: range
cstdbl:  array(Rcstdbl) of real
Rvars:   range
vars:    array(Rvars) of string
varstyp: array(Rvars) of integer
varsopt: array(Rvars) of integer
Rarrndx: range
arrndx:  array(Rarrndx) of string
Rfct:    range
fct:     array(Rfct) of string
fctsign: array(Rfct) of string
fcttyp:  array(Rfct) of integer
Rdtyp:   range
dtyp:    array(Rdtyp:range) of string
dtyptyp: array(Rdtyp) of integer
Rrecsstart:range
recsstart:array(Rrecsstart) of integer
Rrecfield:range
recfield:array(Rrecfield) of string
recftype:array(Rrecfield) of integer
Riodrv:  range
iodrv:   array(Riodrv) of string
iodrvinfo:array(Riodrv) of string
Rannsident:range
annsident:array(Rannsidente) of string
Rannsstart:range
annsstart:array(Rannsstart) of integer
Ranns:     range
anns:      array(Ranns) of string

lsattr (model or submodel)

Return the list of available types attributes. The array 'attrsntyp' gives the type supporting the attribute and 'attrsatyp' is the type of the attribute.

Rattrs:   range
attrs:    array(Rattrs) of string
attrsntyp: array(Rattrs) of integer
attrsatyp: array(Rattrs) of integer

lslib (instance)

Return the list of available packages and modules. If option 'p' is used, packages are reported with their full path.

Rpkgs: range
pkgs:  array(Rpkgs) of string
Rdsos: range
dsos:  array(Rdsos) of string

lsloc (model or submodel)

This command is similar to 'info' but it can only be applied to a suspended model: it reports all local variables.

Rtyps:   range
typs:    array(Rtyps) of string
typscod: array(Rtyps) of integer
Rvars:   range
vars:    array(Rvars) of string
varstyp: array(Rvars) of integer
varsopt: array(Rvars) of integer
Rarrndx: range
arrndx:  array(Rarrndx) of string

profrep [ srcpath ] (model)

Ask for generation of result files after a profiling or covering execution, the result of this operation is a list of strings corresponding to the messages displayed by the commands profile or cover. This command can only be called after the model has been run in profiling or covering mode (see Section Profiler interface). The optional srcpath argument is a list of paths (conforming to the operating system conventions) where the source files can be found. The option 'C' implies the generation of the coverage files ( e.g. 'file.mos.cov'), with option 'c' the same files are produced but without counting of lines ( i.e. a line that is executed is marked with '1' instead of the actual number of executions). The option 'P' (the default) will generate the profiling files ( e.g. 'file.mos.prof'), with option 'p' timings are reported in percentage of the total amount of time (instead of elapsed time).

msg:list of string

profres [ path ] (model)

Retrieve profiling results. This command can only be called after the model has been run in profiling mode (see Section Profiler interface). The path argument indicates which execution is requested: several "executions" may be available when the model starts other models with 'mmjobs' (the returned data set includes the number of additional executions available via the nbsub field). For instance the path 1.3 corresponds to the third "execution" started by the first "execution".

tottime:real
nbsub:  integer
nbnoprf:integer
Rlines: range
lines:  array(Rlines) of integer
iters:  array(Rlines) of integer
times:  array(Rlines) of real
elaps:  array(Rlines) of real
Rfiles: range
files:  array(Rfiles) of string
Rstarts:range
starts: array(Rstarts) of integer

Profiler interface

Profiling a model requires a bim file compiled with option '-G'. The runmode has to be set to '2' before starting the execution. After the end of the profiler run, calls to the command 'mcmd:profres', 'mcmd:profrep' or 'mcmd:covres' can be used for retrieving the results.

Debugger interface

The debugger can be started even if the flag '-G' has not been used for compilation but in this case most commands will fail to return useful information. To run a debugging session the runmode of the model must be set to '1' before starting its execution. If the model was compiled with '-G', the execution is immediately suspended before the first statement of the model and a notification event is sent.

During a debugging session changes of the model execution status are notified by specific events of class 'EVENT_DBG' (32770). The value of these events is a 32bit integer (cast to a real): the first 16 bits are a parameter (meaning depending on the reason) and the following 16 bits indicate the reason for the notification:

• DBG_NOTIF_START (1<<16): Submodel starting (the parameter is the submodel ID)
• DBG_NOTIF_END (2<<16): Submodel ending (the parameter is the submodel ID)
• DBG_NOTIF_STOP (3<<16): Execution suspended (the parameter is the VM status)

When an event 'DBG_NOTIF_STOP' is received, the model (and its submodels) is in suspended state and can be sent commands (see Section mcmd pseudo file). To continue execution a control parameter 'dbgctrl' has to be set. The possible values are (the operation applies to the master model unless a submodel number 'num' is given):

• C: continue
• E: end of execution, abort debugging session
• N [num]: continue to next statement
• S [num]: step into subroutine
• F [num]: continue up to end of subroutine
• T num lndx: continue up to the specified line number on submodel 'num' (0 for master model)

Additionally, during the execution of a model running in debugging mode (but that is not suspended), the following 'dbgctrl' commands can be used:

• B: suspend execution (e.g. consequence of ctrl-C)
• E: end of execution, abort debugging session

When the execution of the model is about to end (including after an error), it is suspended just before exiting such that the user can look at the current status.