CalledInstances

(Engine-Level Function)

Description:	Returns the object values of module instances that are called by a particular module.
Returns:	Object(s)
Usage:	Script Only.
Function Groups:	Advanced Module,  Compilation and On-Line Modifications
Related to:	ChildInstances | Self | GetInstance | Instance | NumInstances | Valid
Format:	CalledInstances(Object[, Options])
Parameters:

Object

Required. An object value of the module instance for which to get the number of called instances.

Options

Optional. Any numeric expression that defines which modules are to be included in the returned set. The value for this parameter is formed by adding together the values from the following table: (See: Bitwise Parameters & Operations) Options Bit Number Description 1 0 Include all modules, even if they are in the same window as their caller. Set false to include only (root) modules for modules in separate windows. 2 1 Recurse into called modules of called modules. Set false to include only modules directly called by the Object parameter. 4 2 Group all instances of the same module into an array and store that array of object values in the element of the returned array, instead of the object value.

Comments:

The return value is an array of objects which are called from Object. If no instances are called from Object, Invalid is returned.

Example:

  i = -1;
 ... If i == -1;
  [
    NumCalled = CalledInstances(Self()); 
    i++; 
  ] If Valid(NumCalled[i]);
  [
    Slay(NumCalled[i], 0); 
    i++; 
  ]

The first If statement and script creates an array of object values to all instances called by the current module. The second If and script slays all of these instances. Notice that in the case of the first script, the action trigger must be based on i rather than on a Valid test of NumCalled. If this were not the case and ! Valid(NumCalled) was used instead, then if there were no instances called from this module, CalledInstances would return Invalid, and an "if one" (infinite loop) condition would occur.