NAME
nst_call - function interface to execute NST unit
PROTOTYPE
int nst_call( unitptr uHost, char *pcMethod, ...)
ARGUMENTS
- unitptr uHost
- the unit to call
- char *pcMethod
- the method name (NULL to call uHost itself)
- ...
- the arguments for the interface of the called unit (cf. description below)
SYNOPSIS:
Provides a function-like interface for executing a NST unit
and to supply input and retrieve output values via a
function argument list.
RETURN VALUE:
The routine returns the return value from the execution of
the chosen NST unit (usually 0 for ok), or -1, when the
to-be-executed subunit
was not available (or pcMethod had wrong syntax).
In this case, the remaining arguments were not used.
A return value of NST_EXCEPTION indicates that an NST
exception was thrown and more error information can be
printed with nst_errtrace(), nst_errtype() and
nst_errtext().
DESCRIPTION:
Executes u or a (possibly nested) subunit whose path name must then be supplied
in the string pcMethod) of u. Expects pcMethod to be followed by
parameters for specifying and/or passing back input pin and/or
output pin (=result) values to/from the the to-be-executed unit.
Any values of the input parameters are copied into the input
pins of the to-be-executed unit, then the unit is executed and
any output pin values are written to the output parameters, after
which the routine returns.
Specification of the executed unit:
If pcMethod=NULL, the to-be-executed unit (in the following
abbreviated as TBU) is u. Otherwise, pcMethod
should have the format
name1:name2:..:namek
in which case the TBU will be the named subunit
namek inside subunit . inside named subunit name2
inside named subunit name1 inside u (this requires that
the loaded unit u has a hierarchy of subunits with the
specified names, otherwise the routine will return the
error code -1 without any further operation.
Alternatively, the TBU can also be chosen by a chain
of container-relative subunit positions i, j, ... k
(0 always denoting the position of the first subunit
in a container):
#i:#j:..:#k [not yet implemented]
(the hash symbol is required).
Specification of input parameters:
If the unit has any input fields, for each of
them the parameter list expects first the special
indicator argument NST_INP, followed by the
argument parameters that pertain to the corresponding
input field.
For each non-scalar input pin of the TBU,
the NST_INP argument must be followed by a
pair of parameters. The first element of the pair
is an int specifying a dimension value (cf. below).
The second element of the pair must point
to the address of a variable that holds
a data object that is suitable to be copied into
the input pin associated with the pair.
Here is a list of the required types:
- NST_FLOAT_T pin:
- int,float** pair
- NST_INT_T pin:
- int,int** pair
- NST_BYTE_T pin:
- int,unsigned char** pair
- NST_DYNFLOAT pin:
- int,float** pair
- NST_DYNINT pin:
- int,int** pair
- NST_DYNBYTE pin:
- int,unsigned char** pair
- NST_STRING_T pin:
- int,char** pair
A slight modification occurs for NST_SCALAR_T pins:
here each consecutive sequence of such pins within
the same input field is considered as a group for
which a int,float** pair must be provided:
- NST_SCALAR_T pins:
- int,float* pair
Note that the passed argument is always a pointer
to the type required by its pin! This allows
to use the parameter value NULL to indicate that
the value of the associated input pin shall remain
unchanged.
Passing for the address *ppvAdr of an input parameter
the address of the pin data (available with the
NST macros pfNstInp() etc.) will omit the
copy step and allows to avoid copy and memory
overhead.
The dimension value is used to tell the routine
how many elements are accessible at the address
passed with the second element of a pair. The
value is currently ignored for NST_STRING_T pins.
In the case of a dynamic input pin, this will
set the pin dimension.
In the case of a fixed dimension
input pin, the routine will set only the specified
number of input elements. If the passed value is larger
than the actual pin dimension, the excess elements
will not be used.
Specification of output parameters:
If the unit has any output fields, for each of
them the required group of argument parameters is
introduced by the special indicator argument
NST_OUT
(output parameters follow after all input parameters).
The rules for the output argument types are identical
as for the input arguments, except that
for the dynamic and the NST_STRING_T pins
the former int dimension parameter
now becomes a int* to allow
passing back the actual dimension of the result
(the length of the string that is passed back
in the case of the NST_STRING_T pin).
Here is a listing of the cases that differ
from the input side
- NST_STRING_T pin:
- int*,char** pair
- NST_DYNFLOAT pin:
- int*,float** pair
- NST_DYNINT pin:
- int*,int** pair
- NST_DYNBYTE pin:
- int*,unsigned char** pair
- NST_STRING pin:
- int*,char** pair
(All others as explained in previous section).
Again, NULL values can be used to indicate that
the result at the associated pin shall not be passed
back.
The last parameter must always be NST_END. This allows
to check at least for the correct nr of arguments.
If there is no match, an error message with the
expected signature will be printed.
Control of memory allocation for output values:
For the fixed-dimension array pins NST_FLOAT_T,
NST_INT_T and NST_BYTE_T, there is the possibility to
request automatic allocation of the result memory:
If a parameter ppvArg is non-NULL, but points to
an address that is NULL (i.e., *ppvArg=NULL), this
is taken as request to allocate sufficient memory
for the result and to return in *ppvArg the address
of the allocated memory (which has been filled with
the result). Otherwise, if *ppvArg!=NULL, it is
assumed to point to sufficient memory to accomodate
the result (in particular, one may set *ppvArg to
the address of the pin data (e.g., using the NST
macros pfNstOut() etc.) to avoid any extra
memory use). In the non-allocation case, the value
in the dimension parameter is taken as the limit
to the maximal number of elements that may be
copied into the result array (provide the actual
pin dimension or a larger value to get all elements
back).
For dynamic or NST_STRING_T pins, there is always
an automatic reallocation of the supplied memory
under dimension changes (therefore, never supply
an array address!), and the new dimension is
written into the associated dimension parameter *piDim,
except when *piDim is a negative value D<0
(and the supplied *ppvArg is non-NULL).
In this case, it is understood that memory reallocation
for the memory block at *ppvArg forbidden, and
the memory block provides at least ABS(D) elements
to accommodate the first ABS(D) values of the result
(any remaining values will not be
passed back in this case, and the negative value
of *piDim will remain untouched as well).
This restriction makes it possible to pass for
ppvArg the address of a fixed array for receiving
a length-limited result.
Ownership policy:
The routine does not change the ownership of any
object for which it has received a reference (this
is true also under reallocations of the object).
When the routine is requested to newly allocate an
object, ownership of the newly allocated
object is given to the caller.
Checking of argument types:
Argument type checking is limited and based
on verifying the correct positions of the
NST_INP and NST_OUT marks and the final
NST_END mark. If an inconsistency is detected,
an error message with the expected argument type
sequence is printed and the routine returns.
If the interface for the selected unit is not known,
it can be queried
at runtime with the usual NST routines (the
source code of the present routine illustrates
how the pins and their types can be looked up).
FILE
/amnt/loge/users/nistaff02/nistaff/rhaschke/nst7/man/../o.linux//../srvsrc/Nst_misc.c