NAME

var_units -- define and access an array of variable records

PROTOTYPES

unitptr var_set( char *pcName, int iNum, int iFields, char **ppcFmt, unitptr uHost)

unitptr var_get( char *pcName, int iNum, int iFields, char **ppcFmt, unitptr uHost)

unitptr var_info( char *pcName, int iNum, char *pcOptions, unitptr uHost)

unitptr var_def( char *pcName, int iNum, int *piDim, int iFields, char **ppcFmt, unitptr uHost)

ARGUMENTS

char *pcName
name of variable record array May be followed by options: %S save data with unit formatted to file; %B save data with unit in binary form to file; (the default is not to save any stored data).
int iNum
nr of dimensions. A value of iNum=0 requests linear indexing of an arbritrary dimensioned var\_def unit. Otherwise, the normal vector indexing is used.
int iFields
nr of fields per record
char **ppcFmt
format of single record
unitptr uHost
host unit
char *pcOptions
Unused and for future extensions
int *piDim
iNum index limits, one for each dimension. Note that iNum may not be chosen as zero for the var_def unit (this differs from the other var_units, where iNum=0 requests linear indexing mode). An index limit of zero specifies that the corresponding dimension shall be dynamic, i.e., storage is allocated as required by assigned elements.

RETURN VALUE:

A pointer to the created unit or NULL in the case of an error.

INTERFACE OF CREATED UNIT:

The var_def unit has no inputs or outputs. The var_set unit has the inputs as specified in the array ppcFmt[] (using the same conventions as for the void_unit3() ) plus an extra index input field (in next-to-last position) for the index (scalar float vector with iNum elements if iNum>0, single scalar float pin for linear index, if iNum=0) of the accessed element. The last field is the usual control field with a single scalar float pin. The var_get unit has the outputs as specified in the array ppcFmt[] (using the same conventions as for the void_unit3() ), an index input field in position 0 for the index (scalar float vector with iNum elements if iNum>0, single scalar float pin for linear index, if iNum=0) of the accessed element. The last field is the usual control field with a single scalar float pin. The var_info unit has a single output field. For iNum>0, this is a scalar float vector of iNum index limits. The k-th index limit is the highest index value along the k-th dimension for which an element was assigned by a var_set invocation since the creation of the var_def unit or its last initialization with NST_INIT ( var_set operations with linear indexing are properly taken into account).

EXECUTION OF CREATED UNIT:

The var_def unit does nothing when being executed (its sole task is to allocate/deallocate memory for the defined variable array when it is created/removed). The var_set unit writes its current input data into a selected record of the variable array of the associated var_def unit. The selected record is determined by an index vector which is the integer part of the values at the at the index input field of the var_set unit. The var_get unit provides at its output pins the values of a selected record of the variable array of the associated var_def unit. The selected record is determined by an index vector which is the integer part of the values at the index input field of the var_get unit.

DESCRIPTION:

The var_def unit allocates a named iNum-dimensional array of records. Argument piDim[] specifies the iNum index limits for the array dimensions. The total number of records in the array will thus be piDim[0]*piDim[1]..*piDim[iNum-1]. A special role is played by the index limit 0. If this is specified, the corresponding dimension becomes `dynamic'', i.e., the number of assignable elements need not be limited in advance and memory is allocated as needed (if the used index tuples form a sparse set, only a set of pointers for a `spanning tree'' that covers the used index tuples with axis-parallel branches is allocated in addition to the actually assigned data elements). The name of the array is given by pcName. Each record can consist of one or several variables of one of the NST - supported types scalar float, float vector, int16 vector, byte vector or string. All records of the same var_def unit must have the same structure. The structure is defined by specifying with ppcFmt[] a number of fields consisting of pins of the NST data types. Example: to have a record with consisting of a vector of 10 floats, 5 scalar floats, a byte array of 1000 byte and three variable length strings, you could specify

    char *ppcFmt[]={"f10s5c1000t80t80t80"}; int iFields=1;

(initializing the length of the variable length strings to 80 in this example). This would result in a var_def unit in which all variables are lumped together into a single field of 10 pins (1 float vector, 5 scalar float, 1 byte vector and 3 string pins). If it is more convenient to separate the different elements into separate fields, this is possible by making a corresponding definition, e.g.:

    char *ppcFmt[]={"f10","s5","c1000","t80","t80t80"};
    int iFields=5;

While the var_def unit defines a named array and allocates sufficient memory (initializing all entries to zero or the empty string), the var_set and var_get units set/get the values of single records, selecting on record at a time by an integer index vector that must be provided at the next-to-last input field in both cases. To access the variables of a var_def unit by means of a var_get/set unit requires that the names pcName and the field structure match for both units. I.e., a var_get - unit for one of the above var_def units would have to use the same name and the same ppcFmt[] string and could then not be used for accessing the variables for the second definition, although the structure of the records is the same in both cases. To create a var_get/set unit does not require the presence of the associated var_def unit, however, the var_def unit must be present at the time of execution of the var_set/get unit.

MIXING VECTOR AND LINEAR INDEXING:

If all array dimensions of a var_def unit are non-zero (i.e., non-dynamic), it is allowed to access array elements by both the normal index vector (i0,i1,..ik) (.k is the number of array dimensions) or, alternatively, by a single linear index i, given by

    i = i0 + i1*d0 + i2*d1*d0 + ... ik*d_k-1...d1*d0

To make a var_get or var_set unit accept the linear array index requires to create it with parameter iNum=0.

VISIBILITY OF VARIABLES:

If the var_def unit is located in a container u that is not named (don't confuse a *name* with a *label* here! Names must be given with the name_unit() routine!) then its variables can only be accessed by (are `visible'' for) var_get/set/info units that are contained in the same container u (they may, however, be arbitrarily deeply nested in subunits of u). To extend the visibility of a var_def unit to the next outer nesting level (i.e., to all units that are contained in the same container as the container u), requires to give the container a name, say "box". Then, var_get/set/info units outside of u (but inside the container of u ) can access the var_def unit by the `composite name'' "box:name" (assuming "name" to be the name for the variable set that was passed to the var_def - unit's constructor function). In the same manner, by naming the container of u and its container, and so on, the visibility of a var_def unit can be extended to several outer nesting levels (requiring for access a composite name of the type "outermostbox:nextinnerbox:...:box:name" ). Note that this is the same scheme that applies to the visibility of named units for the use_named unit. The only difference is that the variable set names are in a different name space than those used by the use_named unit and the name_unit() routine. Note also that, as a consequence, a unit that contains var_get/set units that reference var_def units that are located at an outer nesting level is severely restricted in its portability: it will not work in other host units, unless there is a matching var_def unit somewhere up in the nesting hierarchy. Several var_get/set units can reference the same var_def unit and thereby operate on a shared array of records.

INITIALIZATION:

Variables are initialized to zero or the empty string. All other operations must be done by var_set units. The control call NST_INIT overwrites all existing variable values by the initial values of zero or the empty string. The index bounds queried by var_info return 0.

LOAD AND SAVE:

To minimize unnecessary automatic storage of data to disk, the default behaviour for the var_def unit is NOT to save any stored data to disk when the save_unit method is invoked. This behaviour can be changed by specifying the option %S or %B after the name (separated with a space) of the variable set. Instances of var_def units created with this option will save their data to disk so that the data later can be reloaded again (the %S or %B option may occur also for the other var_units, but it is ignored by them). %S will save the data in formatted (and thus portable) form, %B will use binary format and is, therefore, much faster, but not necessarily portable between architectures. The behavior of the load_unit operation is entirely determined by the contents of the loaded file: if it contains any previously saved data, this data will be loaded into the var_def unit, irrespective of the presence or absence of the %S or %B option.

CONTROL MODES:

NST_INIT
clear all variables, set index bounds to 0.
NST_UNBIND
(only for internal use) destroy all references among var units (will be rebuilt at next exec).

             

EXAMPLES:

DistMat

FILE

/amnt/loge/users/nistaff02/nistaff/rhaschke/nst7/man/../o.linux//../nstsrc/nst_var.c