NAME

array_of - make array of units

PROTOTYPE

unitptr array_of( int iNumDim, int *piDim, unitptr *puArray, unitptr uHost)

ARGUMENTS

int iNumDim
nr of array dimensions
int *piDim
limits for the iNumDim array dimensions
unitptr *puArray
initializer array for array els
unitptr uHost
host unit

INTERFACE OF CREATED UNIT:

If pcOpt=NULL:
X_in[iNumDim]:
(input field 0) for each array dimension an index value.
CTL_in[1]:
(control field) a value of 0 switches the unit off.

DESCRIPTION OF CREATED UNIT:

Provide an array of units of the same type and interface as its successor unit. The successor unit serves as a `moveable window'' into the array: after each execution of the array_of unit, the operand unit assumes the identity of one of the array elements. The array element is selected by providing an index vector at input field X_in of the array_of - unit. The operand of an array_of unit may not be an operator (however, it may be a virtual_unit, see below). The array from which the array_of unit dynamically selects an element (``mapping'' it onto its operand) can be specified via argument parameter puArray. To this end, puArray should specify a sufficient number of pointers to NST-units that are all of the same type and interface as the unit that is the operand of the array_of unit. However, the array elements may not be any operators. The array is assumed to have iNumDim dimensions. The iNumDim index limits of the array must be specified in piDim[0..iNumDim-1] when the unit is created. The units themselves need not exist already at creation time of the array_unit, however, they must be created (and the addresses of their unitptr's must be written into puArray) as subunits of the array_of-unit BEFORE the array_of unit is first accessed with an exec_unit, ctrl_unit, load_unit or save_unit call. NOTE: to enforce that the created array unit takes notice of the values in puArray, a ctrl_unit(NST_UPDATE_ARRAY,u) call can be issued. The successor unit of the array_of unit will be associated with the array index that was valid at the input of the array_of unit when this call was made. After this, the array puArray need not be any longer maintained. In NST, the operand unit of an array_of - unit may not be changed after the array_of - unit was used (executed, controlled, loaded, saved).

USE OF THE ARRAY_OF UNIT IN NEO:

In Neo, the array argument puArray is not used. Instead, the array elements neither need to be specified explicitly (.Neo simply makes the required nr of copies of the operand unit) nor is the above restriction present. Whenever the array_of unit is used and its operand has changed, it will remove its non-selected array elements and make a set of new ones (only the currently selected array element will not be removed; it survives in the previous operand of the array_of unit onto which it is still mapped). A unit that ceases to be operand of an array_of - unit (e.g., because the array_of unit is moved away or deleted) keeps its identity as the array element that was most recently selected by the array_of unit. A unit that newly becomes operand of an array_of unit (e.g., because the array_of unit is moved in front of it) is used as the array element with the index value at X_in of the array_of unit when the array_of unit is used for the first time after the change. At this time, also the remaining array elements are created by making copies of the operand unit.

ARRAY OF A VIRTUAL UNIT:

If the operand is a virtual_unit, the array_of unit uses as its `true operand'' the unit that is referenced by the virtual_unit, not the virtual_unit itself. In particular, the array elements are made from the `true'' operand unit, not from the virtual_unit (which would make little sense, since all copies of the virtual_unit would reference only the same NST-unit). Likewise, all mapping operations (including the mappings that occur when the array_of unit is created, requeued or removed) then refer to the unit that is referenced by the virtual_unit. IMPORTANT NOTE: the translation of an array_of unit followed by a virtual_unit into NST source code does not maintain Neo's dynamic referencing mechanism: to make the array elements, the code generator inserts a for - loop with a copy of the creation call that is generated (subsequently) for the NST unit referenced by the virtual_unit. Thus, to make later code changes to the creation call of this referenced unit (including any code modifications that change the relative position of this referenced unit and the container of its referencing virtual_unit) also take effect for the array elements of its associated array_of unit requires that corresponding changes are also made in the aforementioned for - loop also [comments of this are are inserted in appropriate locations of the generated code]. LOADING/SAVING: Saving an array_of unit saves all the units of the associated array. Loading an array_of unit loads the data of the previously saved array element units into the current array element units. This requires that all elements of the array_of unit have been instantiated before and are of the same type and interface as was the case for the saved array_of unit.

CONTROL:

Any control call is sent to all non-selected array elements. The additional control mode NST_UPDATE_ARRAY enforces making/updating of the array elements according to the current operand (in Neo) or the current values in puArray (in NST). In both cases, the current operand (=successor unit) of the array unit will be associated with the index input that was present at the time of this call (this applies even if in NST this operand come only later).

FILE

/local/homes/rhaschke/nst7/man/../o.linx86//../nstsrc/nst_array.c