Defining services

Services are declared in the table of services (see Section Table of services). Each entry of the table is the pair ( service code, service implementation ) (a pointer). This section describes the available codes together with the functionality the user has to provide in order to implement the corresponding service.

Service ``Reset''

XPRM_SRV_RESET: void *reset(XPRMcontext ctx, void *libctx, int version)

During the execution of a model, a module may have to store some data that is specific to this particular session. This information is called its context of execution. Each function of the module is always called with 2 contexts: the first one is the Mosel execution context and the second one the module context. The service XPRM_SRV_RESET is used to handle this module context: when the execution of the model starts, this function is called with a Mosel context and the constant NULL as its parameters. At this call, the reset function must return a pointer that will be used as the module context for the following calls to functions of the module.

When the model is reset (either before a new execution or before deleting it from memory) the reset function is called again but with the pointer it returned after its first execution. This time, the reset function has to release the resources used by the module context.

The last parameter sent to this function is the version number required by the running model. This information may be useful if the module can emulate different versions: from this function it may build an appropriate context depending on the version requested.

Service ``Module priority''

XPRM_SRV_PRIORITY: int priority

This service may be used to define a priority value for the module. Modules with lower priority values are initialised before those with an higher priority. The resetting (i.e. call to the onexit function and second call to the reset function) is performed in the reverse order of the initialisation. The default priority value is 0, specifying a new value requires the use of the XPRM_MKPRIORITY macro (e.g. XPRM_MKPRIORITY(100)).

Service ``Unload''

XPRM_SRV_UNLOAD: void unload(void)

Mosel may decide to unload a module when it is not required any more. In some cases, a module has to release some resources it has allocated during its initialization (for instance, it uses a licensed software and has to release a license or some global data). For this purpose, this function is called just before Mosel unloads the module.

Service ``Check Version''

XPRM_SRV_CHKVER: int chkvers(int requested_version)

The convention for module version numbers is to use a code version with 3 numbers ( major, minor, release ). When loading a module at runtime, Mosel checks if the obtained module is compatible with the one requested by the model (at compile time, the version numbers of all used modules are stored in the BIM file). A module version A can be used in place of module version B if major(A) = major(B) and minor(A) ≥ minor(B). With the ``check version'' service a module can change this default behavior. This may be useful if, for instance, a module can emulate the behaviour of an older version. The parameter requested_version is the version number expected by the model to be able to run. If this function returns 0, the module is accepted; otherwise it is rejected due to the incompatibility in version numbers.

Service ``Find Parameter''

XPRM_SRV_PARAM: int findparm(const char *pname, int *type, int why,
                               XPRMcontext ctx, void *libctx)

This function is used to translate a parameter name into an internal code. This code is then used at run time by the Mosel Virtual Machine for calling the special routines getparam and setparam. If the function returns a value smaller than 0, the parameter named pname is not supported by the module; otherwise, the value returned is the code expected by getparam and setparam. Moreover, the function findparm has to set the paramater type to the type of this parameter. The parameter type is bit encoded using the type constants (XPRM_TYP_INT, XPRM_TYP_REAL, XPRM_TYP_STRING, XPRM_TYP_BOOL) plus the access rights (XPRM_CPAR_READ,
XPRM_CPAR_WRITE): a parameter tagged XPRM_CPAR_READ can be accessed with the getparam function and a parameter tagged XPRM_CPAR_WRITE can be set using setparam.
The two last arguments passed to this function are usual execution contexts while the third one indicates how the function is used: argument why is XPRM_FNDP_MCREAD (0) when the compiler looks for a parameter to be read (with getparam); it is XPRM_FNDP_MCWRITE (1) when the compiler requires a parameter for writing (call to setparam). In both cases the module context libctx is NULL. When the execution of the model is starting and module parameters are set via the model parameter string this function is called with a value of XPRM_FNDP_RTWRITE (2) for why (before a call to setparam). During execution when another module requests the value of a parameter using getdsoparam this function is called with a value of XPRM_FNDP_NIREAD (3) for why. Finally, why takes the value XPRM_FNDP_RTREAD (4) when the function is used after execution by the library function XPRMgetdsoparam.
This service must be defined if the module provides control parameters.

Service ``List of Parameters''

XPRM_SRV_PARLST: void *nextpar(void *ref, const char **name, const char **desc,
                               int *type)

This service is used to display the list of parameters provided by the module (for instance by using the command examine of the command line interpreter). It is called repeatedly until it returns NULL. The first argument is a pointer in the internal table of parameters (handled by the module). When this pointer is NULL, the function has to return the first parameter. The information about the parameter is its name, a textual description desc of its meaning (may be an empty string) and its type (using the same encoding as for the service XPRM_SRV_PARAM). The function must return a pointer to the next entry in the list of parameters that can be used as input for the next call to this function. When the information about the last parameter of the module has been returned, the return value must be NULL.

Service ``Inter-Module Communication Interface''

XPRM_SRV_IMCI: void *imci

This service may be used to implement communication between modules at the C language level. The value of this service (a pointer) is returned by the function getdsoctx. Typically, this pointer references a table of functions which are entry points to the module.

Service ``Module Dependency List''

XPRM_SRV_DEPLST: const char *deplst[]

This service defines a table of modules that are automatically loaded when compiling models using this module. Note that this service is used only at compilation time and the corresponding modules will not be loaded during execution if they are not effectively required by the model. Every entry of this table is the name of a module as it is used with the uses directive. The last entry of the list must be NULL.

Service ``IO Driver List''

XPRM_SRV_IODRVS: XPRMiodrvtab iodrvs[]

This service defines the table of IO drivers implemented by this module. Every entry of this table is a pair ( driver name, table of IO functions ). The driver name corresponds to the identifier to be used in file names and the table of functions lists operations supported by the driver (Section Defining IO drivers). The last entry of the list must be the pair ( NULL,NULL ).

Service ``On Exit''

XPRM_SRV_ONEXIT: void onexit(XPRMcontext ctx, void *libctx, int status)

This service may be useful when some clean up operations have to be performed after the model has been run. The onexit function is called just before the end of the execution of the model if the service reset is implemented and has succeeded (i.e. the module context libctx is not NULL). The status provided here is the execution status of the model: it indicates why processing is terminating.

Service ``Check Restrictions''

XPRM_SRV_CHKRES: int chkres(int restr)

This service must be defined for the module to be loaded when Mosel is running in restricted mode (refer to the Mosel Reference Manual for further details). The chkres function is called just after the module has been initialised such that it can check whether it supports the active restrictions: a return value of 0 indicates that the module will observe the stated restrictions; any other value will cause the module to be unloaded.

The restrictions are passed to this routine through the restr parameter as a bit encoded integer. The following restrictions may be set:

XPRM_RESTR_NOWRITE

Disable write access

XPRM_RESTR_NOREAD

Disable read access

XPRM_RESTR_NOEXEC

Disable routines allowing to execute external commands

XPRM_RESTR_WDONLY

Restrict disk access to current working directory

XPRM_RESTR_NOTMP

Disable temporary directory

XPRM_RESTR_NODB

Disable database access

The Mosel file management routines (like fopen) already enforce read/write restrictions for the files they handle. It is the responsiblity of the module to implement the restrictions when it uses any other file management routines. For instance, accessing directly a file using a system routine should only be done after having checked the validity of the file name with pathcheck; starting a separate process to execute an external command should be disabled if the restriction NOEXEC is active etc.

Service ``Update Version''

XPRM_SRV_UPDVERS: void updvers(int event, int what, int *version)

This service is used by the Mosel compiler only: the function is called whenever a feature of the module (routine,type or parameter) is used by the model being compiled. The first argument indicates why the function is called and how to interpret the second argument (what). Possible values are:

XPRM_UPDV_INIT

module loaded for compilation of a model ( what=0) or a package ( what=1)

XPRM_UPDV_FUNC

function code what required

XPRM_UPDV_TYPE

module type code what required

XPRM_UPDV_GPAR

control parameter code what required for getparam

XPRM_UPDV_SPAR

control parameter code what required for setparam

XPRM_UPDV_ENDP

parser has finished analysing the file. Argument what is 0 if this operation succeeded

The last argument is a pointer to the current version number for this module that will be stored in the BIM file after compilation: the function may update this version number depending on the requirements of the model.

When the function is called for the first time (XPRM_UPDV_INIT) the version number may be 0: in this case, it must be changed to the minimum version supported by the module (that must be accepted by the service CHKVER). When the function is called for the last time (XPRM_UPDV_ENDP), changing the version number will make the parser fail.

Service ``Implied Dependency List''

XPRM_SRV_IMPLST: const char *implst[]

This service defines a table of modules that imply the use of this module. At compile time, the module is added to the dependency list (see Section Service ``Module Dependency List'') of each of the listed modules. Every entry of this table is the name of a module as it is used with the uses directive. The last entry of the list must be NULL.

Service ``Annotations''

XPRM_SRV_ANNOT: const char *anns[]

This service defines a table of global annotations. These annotations are added to any model using the module. Note that when compiling a package only "mc." annotations are processed. In the table an annotation is represented by 2 entries: the annotation name followed by its value (for instance {"mc.def","myann global",NULL}). The last entry of the list must be NULL.

Service ``DSO stream''

XPRM_SRV_DSOSTRE: void* fct_open(XPRMmodel model, int mode, char *opts, char *params,
                          int (*fct_data)(void *fctx, char *buf, int len),
                          int (*fct_close)(void *fctx),
                          char *errmsg, int errmsglen)

This service defines a function to open a stream to the module from a remote instance. The function is called when a remote instance opens the file "mcmd:dsostream dsoname parameters" where dsoname is the name of the target module. The stream to create is characterised by a model reference (that may be NULL), the open mode, the mcmd opening options and the remaining parameters of the open string. If the operation is successful the function must return a non-null context pointer and update the parameter fct_data: for an output stream it will be called whenever data is available for reading (any return value smaller than len is interpreted as an error); for an input stream it will be used when the remote instance is expecting data: in this case up to len bytes have to be copied into buf and the return value is the amount of data sent. A return value of 0 indicates an end of stream and a negative value an error. Optionally fct_close may also be set: it will be used when the stream is closed to release its resources. In case of error the function must return NULL and copy an error message into the provided buffer.

Service ``Required types''

XPRM_SRV_REQTYPS: const char *reqtyp[]

This service defines a table of native types that are required by a module and that must be available in order to be able to execute models using this module. Every entry of this table is the name of a type (e.g. "text") optionally prefixed by the name of the module defining it (e.g. "mmsystem.text"). The last entry of the list must be NULL. Note that the modules defining the required types must be first listed in the dependency list (see Section Service ``Module Dependency List'').

Service ``Provider''

XPRM_SRV_PROVIDER: const char *prov

This service defines the identity of the provider for this module as returned by the function getdsoprop for the property XPRM_PROP_SYSCOM.

Service ``Namespace groups''

XPRM_SRV_NSGRP: const char **nsgrps

This service may be used to define namespace groups from a module similar to those created via the nsgroup contruct in the language. The data of this service is an array of constant strings terminated by a NULL reference. Each record consists in two strings: the first one is the name of the namespace and the second defines the list of packages belonging to the group (package names separated by comas without space). If this list is empty the namespace can be used by any package.

Service ``Memory use''

XPRM_SRV_MEMUSE: size_t memuse(XPRMcontext ctx, void *libctx, void *ref, int code)

This routine is used by Mosel to report memory usage of the entire module or of an instance of one of its type. When it is called with NULL for ref and 0 for code the function is expected to return the total amount of memory the module has allocated so far for the running model. When ref is not NULL it is a reference to an entity of type code (internal code as specified in the table of types, see Section Table of types) and the function has to return the amount of memory used by this entity. If the information is not available -1 must be returned.