Structures for passing information

The main interface structure that must be passed to Mosel in the module initialization function holds the lists of constants, subroutines, types and services that are provided by the module. Each list is preceded by an integer value that indicates its size. A list and its size may be NULL and 0 respectively if the module does not define any object of the corresponding category.

Structure XPRMdsointer:

{
 int sizec; XPRMdsoconst *tabconst;
 int sizef; XPRMdsofct *tabfct;
 int sizet; XPRMdsotyp *tabtyp;
 int sizes; XPRMdsoserv *tabserv;
};

List of constants

Structure XPRMdsoconst:

A constant_definition contains the name of a constant, its type and its value. It is best obtained through one of the following macros:

XPRM_CST_INT(char *name, int value)
XPRM_CST_BOOL(char *name, int value)
XPRM_CST_STRING(char *name, char *value)
XPRM_CST_REAL(char *name, static const double value)

Note that the value of real constants cannot be set directly in this list but must be given via a C variable of type static const double.

List of subroutines

Structure XPRMdsofct:

{
 char *name;
 int code;
 int type;
 int nbpar;
 char *typpar;
 int (*vimfct)(XPRMcontext ctx, void *libctx);
}

The entries of this structure need to be defined as follows:

name

name of the subroutine, or operator sign preceded by `@'; empty string for getparam and setparam. It is not possible to use any reserved word (the complete list is given in the Mosel Reference Manual) as the name of a subroutine.

code

reference number for the type within the module. It must not be smaller than 1000 and be given in ascending order; value XPRM_FCT_GETPAR for function getparam (must be first in the list) and XPRM_FCT_SETPAR for procedure setparam (must come second) if these are defined by the module.

type

type of the return value.

XPRM_TYP_NOT	no return value (procedure)
XPRM_TYP_INT	integer
XPRM_TYP_REAL	real number
XPRM_TYP_STRING	text string
XPRM_TYP_BOOL	Boolean
XPRM_TYP_EXTN	external type defined by this module (the exact type must be indicated in the parameter format string typpar)

nbpar

number of parameters.

typpar

string with parameter types (in the order of their appearance in the subroutine) or operand types. If the return value is an external type the string starts with the name of the type, separating it with a colon from the parameter format.

i	an integer
r	a real
s	a text string
b	a Boolean
v	a decision variable (type mpvar)
c	a linear constraint (type linctr)
I	a range set
a	an array (of any kind)
e	a set (of any type)
|xxx|	xternal type named `xxx'
!xxx!	the set named `xxx'
Andx.t	an array indexed by `ndx' of the type `t'. `ndx' is a string describing the type of each indexing set. `ndx' may be omitted in which case any array of type `t' is a valid parameter.
Et	a set of type `t'
Lt	a list of type `t'
*	must be the last character to indicate that the function has a variable number of arguments

vimfct

the module library function that implements this subroutine or operator. The first argument is the context of Mosel (type XPRMcontext), the second the context of the module. For return codes see Section Error codes.

Overview on operators in Mosel

All operators have a two-character name, the first character of which is always `@'. Operators can be defined for any type and return any type, however, they cannot replace a predefined operator. For instance the addition of reals @+(r,r):r cannot be re-defined in a module.

Typically, only a subset of all possible operators needs to be defined for a given type. For instance, arithmetic and logical operators are usually not applied to the same objects. Furthermore, in certain cases Mosel is able to deduce the definition of an operator (and also of aggregate operators) if some other operators are defined, so that it is not necessary to define all operators. Any implications that may be drawn are noted in the following list. Where operations are marked `commutative', Mosel deduces the result for (B,A) if the operation is defined for (A,B), assuming that A and B are of different types.

In the following list (Table Overview on operators), read → as `returns'.

If A and B are of external types, they must be deleted by the operator with the exception of comparators where nothing is to be deleted.

The arguments of a subroutine or the objects that an operator is applied to must be obtained from the stack in the order that is specified in the format string typpar (see Section Working with the stack, macros for taking objects from the stack). If the library function implements a function (that is, if argument type has a value other than XPRM_TYP_NOT), the value that is to be returned by the function must be put back onto the stack (see Section Working with the stack, macros for putting objects onto the stack).

List of types

Structure XPRMdsotyp:

{
 char *name;
 int code;
 int props;
 void *(*create)(XPRMcontext ctx, void *libctx, void *ref, int typnum);
 void (*fdelete)(XPRMcontext ctx, void *libctx, void *todel, int typnum);
 int (*tostring)(XPRMcontext ctx, void *libctx, void *toprt, char *dest,
                 int maxsize, int typnum);
 int (*fromstring)(XPRMcontext ctx, void *libctx, void *toinit,
                 const char *src, int typnum, const char **end);
 void (*copy)(XPRMcontext ctx, void *libctx, void *dest, void *src, int tnop);
 void (*compare)(XPRMcontext ctx, void *libctx, void *t1, void *t2, int tnop);
}

The entries of this structure have the following meaning (see the Mosl NI Reference Manual for details):

name

name of the type. It is not possible to use any reserved word (the complete list is given in the Mosel Reference Manual) as the name of a type.

code

reference number for the type within the module, must be smaller then 65536 and listed in ascending order.

props

bit coded set of properties.

create

type creation function (required).

fdelete

type deletion function (NULL if none defined).

tostring

function for converting type to a string (NULL if none defined).

fromstring

function for initializing type from a string (NULL if none defined).

copy

type copy function (NULL if none defined).

compare

type compare function (NULL if none defined).

List of services

Structure XPRMdsoserv:

{
 int code;
 void *ptr;
}

The code indicates the type of service that is provided by the function (or data structure) ptr. The format of the pointer ptr depends on the service that it provides:

XPRM_SRV_PARAM

Encode a parameter: for a given parameter name, this function fills in the type information and returns the reference number if it is defined in the module, otherwise it returns -1. This function must be provided if the module defines any control parameters. The last three arguments are optional (see NI Reference Manual for their use).
int findparam(const char *name, int *type, int why,
    XPRMcontext ctx, void *libctx)

XPRM_SRV_PARLST

Enumerate the parameter names. Mosel calls this function repeatedly until it returns NULL. At its first execution, the value of ref is NULL, at any subsequent call, it contains the value that has been returned by the preceding function call. The definition of this function is optional. Only if it is defined does the command examine of the Mosel Command Line Interpreter display the list of parameters provided by a module.
void *nextparam(void *ref, const char **name,
    const char **desc, int *type)

XPRM_SRV_RESET

Reset a DSO for a run. This function is called at the start and termination of the execution of a Mosel program that uses the module. It should be used to create/initialize and, at the second call, to delete any internal structures of the module (its context) that need to be kept in memory during the execution of a Mosel program. Among others, the definition of new types requires this service.
void *reset(XPRMcontext ctx, void *libctx, int version)

The complete set of services provided by the Mosel Native Interface is documented in the NI Reference Manual. In addition to the service functions listed above, there are also services to override the default module version control, to handle licencing of modules, to enable inter-module communication, to indicate dependencies on other modules, and to define the I/O drivers implemented by a module.

Parameters

It may be convenient to store the control parameters provided by a module in a structure similar to the following:

struct
{
 char *name;
 int type;
 char *desc;
}

where name is the parameter name (it must always be given in lower case), type the type and access rights, and desc an optional description of the parameter that is displayed with the command examine of the Mosel Command Line Interpreter if the PARLST service is defined for the module. The type encoding will be composed of the parameter type that is one of

XPRM_TYP_INT — an integer number
XPRM_TYP_REAL — a real number
XPRM_TYP_STRING — a text string
XPRM_TYP_BOOL — a Boolean

and the read/write flags (if a flag is not set, the feature is disabled):

XPRM_CPAR_READ — read-enabled
XPRM_CPAR_WRITE — write-enabled

For example

 XPRM_TYP_REAL|XPRM_CPAR_READ|XPRM_CPAR_WRITE

defines a real-valued parameter that is read-write-enabled.