Once Vensim has the library successfully loaded, Vensim calls the function user_definition.This function must be exported and has the following format (note that the format is different from what it was in earlier releases):
int VEFCC user_definition(
int setup_index,
char **sym,
` char **arglist,
int *num_args,
int *num_vector,
int *func_index,
int *dim_act,
int *modify,
int *num_loops
int *num_literal,
int *num_lookup)
setup_index is the index for the call to user_definition. Vensim passes indices starting from 0 and incrementing by 1 each time. Vensim will continue to call user_definition until a 0 value is returned.
sym is the name of the function as you want it to appear in Vensim. You should assign this a value using *sym =.
arglist is a string that will be placed inside of the parenthesis () for the function when you select the function name in the Equation Editor. To be consistent with the rest of Vensim this should be a string in the form " {arg1_desc} , {arg_desc} " starting and ending in a space with spaces around commas and curly brackets around the argument descriptions. Also there should not be any spaces in the argument descriptions so that double clicking on an argument description allow easy replacement. You should assign arglist a value using *arglist =.
num_args is the number of arguments the function takes. You should assign this a value using *num_args =. If you are using user_loop functions, as discussed in the next section, this value is the number of arguments in the Vensim function, and will be one less than the number of arguments Vensim uses when calling the function library.
num_vector is the number of vector arguments the function takes. You should assign this a value using *num_vector =. Vector arguments, instead of being passed as floating point numbers are passed a pointer to a VECTOR_ARG structure (see Vector Arguments below). These are useful when dealing with arrays of elements. Vector arguments are passed after Literals and Lookups but before any regular arguments.
func_index is the index of the function. This must be a number between 0 and 32000. You should use *func_index= to assign it a value. Vensim uses this value to tell the library which function is desired.
dim_act is reserved for future use. You should not assign it a value.
modify is a flag to tell Vensim whether or not the function may modify its vector arguments. This flag should take on one of three values: 0 to indicate that it is a normal function that does not modify values; 1 to indicate that it will modify values; 2 to indicate that it will modify values and also serve as the solver for a simultaneous set of equations. The last of these is analogous to the FIND_ZERO function described in the Reference Guide. See Modifying Values below for more discussion. Use *modify= to assign a value.
num_loops tells Vensim how many loops the function expects to manage computation for. See the section on User Loops below for more details. Assign this a value using *user_loops =. If you mark a function as controling loops the left hand side variable will also be passed to the function as a VECTOR_ARG. Note that in order to mark a function as a Constant Definition function you should assign -1 (CONSTDEF_MARKER) to num_loops. To mark a function as a Data Definition function assign -2 (DATADEF_MARKER) to num_loops. See the section on Constant and Data definition functions.
num_literal tells Vensim how many string liiterals will be passed to the function. This is normally 0. If literals are passed they are passed before either Lookups or Vector arguments and they are passed as char *. Assign this a value using *num_literal =.
num_lookup tells Vensim how many Lookup functions will be passed to the function. Assign this a value using *num_lookup =. Lookups are passed as pointers to TAB_TYPE - see Lookup Arguments below. Lookups are passed before any vector arguments but after any literal arguments
Return value
The return value should be 1 if assignments were made and 0 if nothing was done. Once Vensim receives a 0 return it will stop calling the function.
The user_definition function defines the nature of the function. In order to actually call an external function during simulation, Vensim uses the vensim_external function.
