NAME

use_named_unit -- call existing unit by name

PROTOTYPE

unitptr use_named_unit( char *pcName, int* piIDesc, int* piIRefs, int *piODesc, int* piORefs, unitptr uHost)

ARGUMENTS

char *pcName
name of unit to be called
int* piIDesc
nr of mirrored input fields and their dimensions
int* piIRefs
field numbers of mirrored input fields of referenced operand [array entries 1..\#InputFields, 0-entry not used]
int *piODesc
nr of mirrored output fields and their dimensions
int* piORefs
field numbers of mirrored output fields of referenced operand [array entries 1..\#OutputFields, 0-entry not used]
unitptr uHost
host unit

RETURN VALUE:

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

INTERFACE OF CREATED UNIT:

A subset of the inputs and outputs of the unit that is referenced by the name pcName. For details, see MIRRORING FIELDS below.

DESCRIPTION:

The named_unit provides a mechanism to use another unit (referred to as the referent of the named_unit ) in place of the named_unit's position within a circuit. This is similar to the virtual_unit. For a comparison, see USAGE

SELECTION OF A REFERENT UNIT:

To make an existing unit u available as a referent of a named_unit v, u must have been given a string name with the name_unit() routine (in Neo this can be done interactively with the Name command). Thereafter, u can be referenced by this name from any named_unit that is a (not necessarily direct) subunit of u's host unit.

EXECUTION AND ADAPTATION:

Whenever the named_unit is executed or adapted this operation will be carried out for its referent (even though it is located somewhere else). The same referent can be referenced by several named_units from different places. This provides a mechanism to use the same unit in different places. The referent is selected dynamically during each exec_unit or adapt_unit -call of the named_unit, therefore, if a name that is used by a named_unit has been re-used for a different unit, this new unit will be referenced when the named_unit is executed.

MIRRORING FIELDS:

The named_unit can `mirror'' some (or all) of the input and/or output fields of its referent. That means, that the named_unit will inherit some of the fields of its referent. When the named_unit is executed or adapted, data at the mirrored input fields will be transported to the corresponding input fields of its referent unit, then the referent unit will be adapted or executed, and any results at the referent's output fields will be transported back to any corresponding `mirrorred'' output fields of the named_unit. Thus, by mirroring the required input/output fields, an named_unit can invoke the data transformation effected by the execution or adaptation of its referent unit at any location within a circuit.

USAGE OF THE NAMED UNIT:

The named_unit and the virtual_unit share the feature of allowing the execution of another unit that exists in a different location. However, both units serve a different

purpose:

(1) a virtual_unit makes its direct host unit into an operator and its referenced unit into an operand of this operator. Therefore, the referenced operand becomes "invisible" for normal exec_unit or adapt_unit calls. In contrast, the referenced unit of a named_unit remains a normal unit and its behavior under exec_unit or adapt_unit calls is not changed. Likewise, the host unit of a named_unit does not become an operator. (2) A named_unit references its referent unit by a string name and allows more freedom for the location of its referenced unit. The referenced unit may be located in any of the nested hierarchy of units that enclose the considered named_unit. In contrast, a virtual_unit requires its referenced unit to be a successor unit of its direct host unit. The referenced unit is specified by its successor position relative to the virtual_unit's host unit. (3) A named_unit requires that its referent has been given a name with the name_unit routine. A virtual_unit has no such requirement. The bottom line of this is that the named_unit should be preferred when the purpose is just to share an existing unit in several different places, and that the virtual_unit should be used when it is desired to make a composite unit that has the property of being an operator that dynamically binds to its successor unit(s).

EXAMPLE:


   uCallByName = named\_unit("foo",[2,5,-10],[0,2,1],[1,3],[0,0],uHost);
   ...
   name\_unit("foo",uMyunit);

will create a unit uCallByName that references the unit uMyunit that is named foo. Note that the naming itself need not occur before the creation of a named_unit that uses the name. It only must have been done before the first exec_unit or adapt_unit call of any such named_unit. In the example above, the created named_unit will have 2 input fields of dimensions 5 and -10 that will `mirror'' the two input fields with field numbers 2 and 1 of uMyunit (assuming that uMyunit has these fields and that the dimensions match. However, these conditions need only be satisfied later at run-time, not when the named_unit is created). Further, the created named_unit will have one output field with 3 pins, mirroring output field 0 of uMyunit.

LOAD SAVE CONTROL:

The named_unit is invisible to the load_unit, save_unit and ctrl_unit calls, i.e., no file entries are produced or read, and no control calls are sent to the referenced operand. An exception are control calls issued by a ctrl_op unit: these are passed to the referenced unit, even if the reference proceeds via one or several named_units [this is the same convention as used by a virtual_unit]. [the non-effect of the control calls may be changed in later versions].

SEE ALSO:

virtual_unit, neo

FILE

/local/homes/rhaschke/nst7/man/../o.linx86_64//../nstsrc/nst_stdr.c