Class - Macros

Navigation: PGMs ➔ Classes

Functions					Subroutines		Classes
Defining a Function	Predefined Functions	Tag Functions	Mathematical Functions	String Functions	Defining a Subroutine	Trigger Subroutines	Defining a Class

Related Links: User Defined Class and Functions, Example PGM Files

Class - Introduction	Class - Defining a Class	Class - Using a Class	Class - Macros	Class - Examples

Global Predefined Class Instances: Species Database Class, Particle Size Definition Class, Plant Model Class
Predefined Classes: Array Class, StrArray Class, Matrix Class, TagSelect Class, Noise Class, TimeClass

---

Class Macros

Macro Parameters

Classes Parameter

All of the class macros include a Classes parameter which is used to define the list of class instances that need to be looped through. There are a number of different ways of defining the list of class instances to be used. If the list of classes includes any class instances marked as excluded using ExcludeClass, this are ignored and excluded from the list of class instances used in the macros.

The different methods for defining Classes to be used in macros are:

Classes	Description	Example
ClassType	A named Class Type Definition. List used will be all class instances from global scope, up to this point in the code, of the specified class definition.	ForEachSub(TankClass, Exec())
ClassList	A previously defined ClassList name. List used will be from the defined ClassList used.	ForEachSub(TanksList, Exec())
{ClassInstance1,…}	A comma separated list of class instances, that may include indexed classes in class array. List used will be as specified in the {} list.	ForEachSub({T1,T2,T3}, Exec()) ForEachSub({FeedTank,T[5],T[6],T003}, Exec())
{ClassType1,…}	A comma separated list of class type definitions. List used will be all class instances from global scope, up to this point in the code, of all the specified class definitions.	ForEachSub({TankClass,CSTR_Class}, Exec())
ClassArray	A class array. List used will be all the classes in the Class Array.	ForEachSub(T, Exec())

OperationMethod Parameter

Many of the class macros include a OperationMethod parameter which is used to define the operator method to be applied to the results of the functions or values of the variables for each class instance in the list of class instances that need to be looped through. The Operators allowed are: + - * or and bor band bxor.

For example to sum all the values of a class variable use the "+" operator. Sum = ForEach(+, TankClass, flow).
For example to test a bit flag in all classes use the "or" operator. AnyTanksFull = ForEach(or, TankClass, IsFull()).

Class Macros

When working with multiple class instances, a number of Macros are available which will perform repetitive functions on each class instance. At load time, a macro is converted into a sequence of normal code. This saves the user from writing out loops or multiple lines of code. It also makes it very easy to add and remove class instances without having to remember to adjust code using the class instances. Macros can work with a predefined ClassList or the classes list can be provided as a parameter for the macro. Class instances can be blocked from use in macros using ExcludeClass.

Macro	Macro Syntax	Description/Notes/Examples
ForEachSub	ForEachSub(classes, SubName(..))	The macro ForEachSub provides an efficient method to loop through all class instances from a list of classes and call a Sub within the class. Examples: ForEachSub(TankClass, Exec()) ClassList MainTanks {T1,T5,FeedTank,TankLine.MidTank,TankLine.EndTank} ForEachSub(MainTanks, UpdateResults(AmbientT))
ForEachFn	ForEachSub(classes, SubName(..))	The macro ForEachSub provides an efficient method to loop through all class instances from a list of classes and call a Sub within the class. Example: ForEachFn(Total, +, {T1,T2,T3}, CalcArea()) which is equivalent to: Total = T1.CalcArea() + T2.CalcArea() + T3.CalcArea()
ForEachVar	ForEachVar(ResultVariable, OperationMethod, Classes, ClassVariable)	The macro ForEachVar provides an efficient method to loop through all class instances from a list of classes and using a variable within the class performing the specified operation and storing the result in the specified variable. Example: ForEachVar(TotalVol, +, {T1,T2,T3}, Volume) which is equivalent to: TotalVol = T1.Volume + T2.Volume + T3.Volume
ForEachVarSet	ForEachVarSet(Classes, Variable, Expression)	The macro ForEachVarSet provides an efficient method to loop through all class instances from a list of classes and set the value of a numeric variable (string variables not supported) within the class to be equal to the specified value (or result of an expression). Example: ForEachVarSet({T1,T2,T3}, Height, 17) which is equivalent to T1.Height = 17 T2.Height = 17 T3.Height = 17

Macro Functions

A "Macro Function" can be used in expressions similar to a function, unlike a "Macro" which can only be used like a Sub.

Macro	Macro Syntax	Description/Notes/Examples
ForEachFnCalc	ForEachFnCalc(OperationMethod, Classes, FunctName(...))	The function macro ForEachFn provides an efficient method to loop through all class instances from a list of classes and call a Function within the class performing the specified operation and return the result. Example: Total = ForEachFnCalc(+, {T1,T2,T3}, CalcArea())
ForEachVarCalc	ForEachVarCalc(OperationMethod, Classes, ClassVariable)	The function macro ForEachVar provides an efficient method to loop through all class instances from a list of classes and using a variable within the class performing the specified operation and return the result. Example: TotalVol = ForEachVarCalc(+, {T1,T2,T3}, Volume)
ForEach	ForEach(OperationMethod, Classes, FunctName(...)/ClassVariable)	This function macro is the same as ForEachFnCalc or ForEachVarCalc where at load time it auto detects last parameter type and is then equivalent to ForEachFnCalc or ForEachVarCalc.
ClassCount	ClassCount(Classes)	The function macro ClassCount returns the number of class instances in the list of classes. Examples: Count = ClassCount({TankClass}) AveArea = ForEach(+, {T1,T2,T3}, CalcArea()) / ClassCount({T1,T2,T3})

Other Functions and Keywords

Other functions and keywords are available when using the Class in the main PGM file. These are described in the How to use the Class section.

Functions include:

• ForEachClass Macro Function: used to call subroutines for all instances of the class. See ForEachClass Function for more details.
• ExcludeClass Used to block class from use in ForEachClass. Commonly used to block instance at index 0 in an array of classes.

Keywords include:

• ClassGrid: used to display class instances in a table layout. Available from Build 139.32360.
• ClassList: used to define a list of class instances, the list name can then be used when in other functions such as ForEachClass and ClassGrid. Available from Build 139.32394.

ForEachClass Function

The macro function ForEachClass is the original Macro implemented and only option available before Build 139.32530. The equivalent functionality is available as ForEachSub. Original documentation: ForEachClass provides an efficient method to loop through all instances of a class and call a Sub within the class.

ForEachClass can be used in a number of ways:

Function Syntax	Description and Example
ForEachClass(ClassName,SubroutineName())	For Example:ForEachClass(TankClass, Exec()) Available from Build 139.30094. Used to loop through ALL instances of the defined Class (class type). All instances include those in global scope class arrays and standalone instances. In the example above, function exec() for all the declared class instances of "TankClass" will be called. (Note, this does not include TankClass instances declared after this line. See Example - Using ForEachClass with multiple class declarations)
ForEachClass({ClassNameList},SubroutineName())	For Example:ForEachClass({TankClass,ThickenerClass,WasherClass}, Exec()) Available from Build 139.31388. Similar to above, but used to loop through ALL instances of all the defined classes in the list. In this example, function exec() for all the declared class instances of "TankClass", "ThickenerClass" and "WasherClass" will be called. (Note, this does not include class instances declared after this line. See Example - Using ForEachClass with multiple class declarations)
ForEachClass({ClassInstanceList},SubroutineName())	For Example: ForEachClass({T1,T5,FeedTank,TankLine.MidTank,TankLine.EndTank},UpdateResults()). ClassList ABC {T1,T5,FeedTank,TankLine.MidTank,TankLine.EndTank} ForEachClass(ABC,UpdateResults()) Example 1 above is available from Build 139.31388, example 2 is available from Build 139.32394. Used to loop through the named instances in the specified class instances. In the above example, the function UpdateResults() will be called by Class instance "T1", "T5", "FeedTank", "TankLine.MidTank" and "TankLine.EndTank" only. The ClassInstanceList can be defined using the ClassList keyword, available for Build 139.32394 and later. See Examples - using ClassList
ForEachClass(ClassArray,SubroutineName())	For Example:ForEachClass(Tanks, Init()) Available from Build 139.30094. Used to loop through all instances in the specified Array of classes. In the above example, the function Init() will be called by the class instance array "Tanks". (Equivalent to calling, Tank[0].init(), Tank[1].init(), etc.)

The Sub can have any number of parameters, however string parameters are not supported. Where multiple class names (class types) are used, they must all have the same sub with the same parameters. Available for Build 139.31388 and later. Some examples:

ForEachClass({T1,T5}, SetCalcOptions(true))
ForEachClass({T2,T3,T4}, SetCalcOptions(false))
ForEachClass(TankClass, UpdateResults(EnvironmentTemperature))

NOTES:

• The Class instances or Array must be in the global scope and declared before ForEachClass is called.
• ForEachClass is not a true function, it is a convenient Macro that generates a sequence of code at PGM load time. This is why the location of ForEachClass is important relative to declaration of class instances (because it only uses the classes already declared when encountering ForEachClass during load).
• Use ExcludeClass to block classes from being used with the ForEachClass macro function. For example for an Array of classes use "ExcludeClass Tanks[0]" alongside "ExcludeWatch Tank[0]" to skip the first class instance in the array with any use of ForEachClass. Available from Build 139.31388.
• A class instance within a class is excluded.