Normally a function takes several numbers as arguments and returns a number. Only a few built in Vensim functions, such as, ALLOC_P take vector arguments. While ALLOC_P is an exception among built in functions, vector arguments are used more commonly with external functions.
When you request vector arguments instead of a number, you get a pointer to a number. Typically, the reason you would want a pointer is to evaluate a series of numbers. For example you might define VECTOR_AVERAGE as a function to take the average value of a vector. To do this you would define VECTOR_AVERAGE to have two arguments, and one vector argument. In Vensim you might have:
city : ALBANY,NEW YORK,ROCHESTER ~~|
average price = VECTOR_AVERAGE(price[Albany],ELMCOUN(city)) ~~|
The external function would receive a vector of floats and the number of elements in the vector and return the average over that number of elements. This simple example would be equivalent to
average price = SUM(price[city!])/ELMCOUNT(city) ~~|
With external functions you are not limited to taking averages and some things that are very difficult to do in Vensim are very easy to do when using external functions.
VECTOR_ARG
Vector arguments are passed as a pointer to a VECTOR_ARG structure:
typedef struct {
COMPREAL *vals ;
const COMPREAL *firstval ;
const DIM_INFO *dim_info ;
const char *varname ;
} VECTOR_ARG ;
vals is address of the value for the model variable. In the example above it would be the address of price[Albany]. Vensim arrays are stored as vectors with the last subscript varying most quickly so that arrays are also passed as a pointer to one of the elements (often the first) in the array.
firstval is the address of the first value for the variable being passed. You should never modify a value that precedes this. You can use an inequality test vals + offset < firstval to check that you are not about to do this.
dim_info is a pointer to a dimension information structure. This can be used to determine the range of the vector as described below.
varname is the name of the model variable (with no subscripts) for the argument.
The example venext.c file has a function called validate_vector_arg that can be used to make sure operations you will be performing will not go outside the range of the variable being passed. If this function detects an error it generates a floating point exception. This will cause the simulation to terminate and Vensim to report the equation in which the error occurred.
DIM_INFO
No values in the DIM_INFO structure should ever be modified. Some are useful for determining how to process a vector argument and those are detailed below.
typedef struct
V4BYTEU reserved ;
V4BYTEU tot_vol ; /* the total size */
VAL_OFF dim[MAX_DIM] ; /* total size of a dimension */
VAL_OFF dim_vol[MAX_DIM] ; /* the total volume for one subscript */
ST_INDEX fam[MAX_DIM] ; /* families for elements */
V2BYTES tot_dim ; /* number of elements */
V2BYTES align ;
} DIM_INFO ;
tot_vol is the total volume of the variable being passed. For example, a 3 x 5 matrix would have a volume of 15. Only elements of vals that are >= firstval and < firstval+tot_vol are valid.
dimis the number of elements in each dimension.
dim_vol is the volume that an increment in the subscript value covers. For example in a 4*3x5 array the third subscript has a volume of 1, the second a volume of 5 and the first a volume of 15.
tot_dim is the total number of dimensions used. This is a number between 0 (for a scalar) and MAX_DIM which is 8.
