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