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