Class - Using a Class

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

---

Using Class Instances

Class control is used in scenarios where logic is repeated more than once in the same iteration. What makes class so useful is its application to instances. One a class is declared, instances must be defined. This section will detail how to define instances and display them in the general controller.

Syntax for Declaring Class Instances

Once the Class has been defined (template complete), the user can include this named class definition (template) in pgm files to declare any number of class instances. Class instances are then used in subsequent to code to perform calculation acting on the individual class instances.

1. Include File: If the Class has been written in the form of an "include file", then we need to first add the include file into the main program by adding:
   • >>IncludefileName.pgm See Example using Include File
2. Declaring Class instances: Class instances can be declared individually (in the same way normal data variables are declared) or as an array of class instances:
   • Example of individually named class instances: CSTR_Class Tank_1, Tank_2 See Example - declaring class instances.
   • Example of Class Array: CSTR_Class Tank[3] See Example - Declaring Class Instances in an array.
3. Syntax Rules: The Class instance name follows the same syntax rules as a normal PGM variable. Note that it must be alphanumeric.
4. Using ClassTag(): If you are matching the class name to the unit model tag through use of UnitTag = ClassTag() within the class definition, then we can use the unit tag name as the class instance name.
   • For example, we have two tanks in the project: Tank_A and Tank_B, then we can simply declare two CSTR_class instances using the same name:CSTR_Class Tank_A, Tank_B
5. Initialise Unit Tag Name:If the unit model tag name starts with a number, then user cannot use the model tag name to define the class instance name, as the class instance name must be alphanumeric. In this case, use a different variable to declare the class instance, then initialise the UnitTag during "InitialiseSolution()" subroutine using the Model tag name.
   • For example:Model Tag name is "101-TK-001", this name cannot be used as the Class instance name. We will define the class instance as TankA, then add this line to initialise the tagname. TankA.UnitTag = "101-TK-001".
6. Class Grid: Classes can be displayed in grids in the access window using ClassGrid keyword after defining the instances. Alternatively use the # symbol or long format {ClassGrid} or {Grid} with the class type when declaring the class instances.
   • For example:CSTR_Class# Tank_A, Tank_B or CSTR_Class{Grid} Tank_A, Tank_B
   • Example with array:CSTR_Class# Tank[3]{ez}
7. Class List: Classes can be added to define a list or collection of class instances using ClassList keyword after defining the instances. Alternatively use the {ClassList} or {List} keyword with the class type when declaring the class instances.
   • For example:CSTR_Class{List(Tanks)} Tank_A, Tank_B
   • Example with List and Grid:CSTR_Class{List(Area2Tanks),Grid} Tank005,Tank007,Tank008,Tank012

Performing class functions

Once the class instance has been declared, user can access class variable tags and perform the Class functions or subroutine.

• Setting a value to a data member of an instance.

  For example, we can set the UnitTag for class instance "TankA" during the "InitialiseSolution()" subroutine: TankA.UnitTag = "TANK_A".

• Retrieving the value of a data member of an instance.

  For example: we can retrieve a value from a class function and assign it to a variable: ReactionExtent = TankA.CuLeachExtent

• Retrieving the value returned by a member function of an instance.

  For example: we can get the species index of water from the predefined Species Database Class: SpeciesIndex = SDB.FindSpecies("H2O(l)")

• Performing Class Function / subroutine calculations.

  For example, we can perform the Exec() function for class instances Tank_A and Tank_B:

  Tank_A.Exec()

  Tank_B.Exec()

Performing class functions as a group

If user have declared many class instances, it will be quite tedious to define each function call separately. To execute some of these functions more efficiently, we have added some special "ForEach" macros. For example:

• ForEachSub (previously ForEachClass) Macro Function: used to call subroutines for all instances of the class.
• ExcludeClass Used to block class from use in ForEach macro. Commonly used to block instance at index 0 in an array of classes.
• ClassList Used to define a list of class instances as aa single variable and then use this with ForEach Macros and ForEach Macro Functions.

Class Macro

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.

See Class - Macros.

ClassList

Available from Build 139.32530. The keyword ClassList can be added to define a list or collection of class instances. The significant advantage for coder is to define the list of classes once and reference the list in multiple ForEach macros later in the code. Syntax is:ClassList NAME {ClassInstance1,…}

• The classes in the list must all be of the same class definition type.
• The list is a comma separated list of class that can be a specific named class instances, a named class array or an indexed class within a class array.
• The ClassList isn’t a real variable, it is a defined name ("synonym") that can be reused later in the code. At PGM load time, SysCAD simply sees the list of classes wherever we use the ClassList “variable” is used.
• The ClassList is then used in various macros (e.g. ForEachSub, ForEachVarSet, etc.) It can also be used with ClassGrid.
• Class instances can be used (repeated) in multiple lists.
• The ClassList can be added when declaring the class instances or they can be defined separately afterwards.

  Example of adding the ClassList when declaring the class instance: TankClass{List(Tanks)} T1,T2,T3,T[5]

  Example of adding the ClassList after class instances have already been defined: ClassList ABC {T1,T2,T3,T4,T5}

• See Examples - using ClassList.

ExcludeClass

To block a specific class instance from being used in macros (even if the class instance is in a list), use ExcludeClass followed by one or more ClassNames. A comma separated list of any number of class instances, including indexed class instances of a class array can be listed. Syntax is: ExcludeClass ClassInstance1,... For example: ExcludeClass Tank[0] ExcludeClass is primarily used for excluding the class at index 0 within a class array as shown in above example. From Build 139.32530 it is possible to define this when declaring the class array using {ExcludeClassZero} or {ecz}. However because it is very common to use both ExcludeClass and ExcludeWatch, then use {ExcludeZero} or {ez}. For example:

const long TankCount = 11 TankClass T[TankCount] ExcludeWatch T[0] ExcludeClass T[0] ;From {{Available139|32530||y}}, the above can be replaced by TankClass T[TankCount]{ExcludeZero} ;using full keyword TankClass T[TankCount]{ez} ;using abbreviated keyword

ExcludeWatch

To hide a specific class instance from the access window display, use ExcludeWatch followed by one or more ClassNames. A comma separated list of any number of class instances, including indexed class instances of a class array can be listed. Syntax is: ExcludeWatch ClassInstance1,... For example: ExcludeWatch Tank[0] ExcludeWatch is primarily used for hiding the the class at index 0 within a class array as shown in above example. From Build 139.32530 it is possible to define this when declaring the class array using {ExcludeWatchZero} or {ewz}. However because it is very common to use both ExcludeClass and ExcludeWatch, then use {ExcludeZero} or {ez}. For example:

const long TankCount = 11 TankClass T[TankCount] ExcludeWatch T[0] ExcludeClass T[0] ;From {{Available139|32530||y}}, the above can be replaced by TankClass T[TankCount]{ewz,ecz} ;or in full {ExcludeWatchZero,ExcludeClassZero} ;or simply the common combined form: TankClass T[TankCount]{ExcludeZero} ;using full keyword TankClass T[TankCount]{ez} ;using abbreviated keyword

Class Instance Variable Display Options

When class instances are declared, any watched variables will be available on the access window.

• When declaring the class instances, * or @ CANNOT be appended to the class instance name.
• Class instances are automatically added to the access window.
• To exclude certain class instances from being used, see topic Exclude.

ClassComment

After class instances have been declared, ClassComment can be used to specify short text comments for Class Instances (similar to text comment for individual variables). A comma separated list of any number of class instances (including indexed class array instances) with text string in quotes (") can be listed. The display of the comment in the Access window depends on use of ClassAsGroup and if class is shown in Grid.
Syntax is: ClassComment ClassInstance1 "String1",...
For example: ClassComment T[1] "Feed tank"

ClassComment is primarily used for specifying comments for class instances within a class array as shown in above example. In most cases it is more common to include the comment with the declaration of the individual class instance.
For example:TankClass T1{"Feed Tank"}, T2{"Acid Tank"}, T3{"Tank 300-A012"}

General Formatting Keywords

Available from Build 139.32530. A number of different keywords in the class definition can be used to manage how the class variables for class instances should be displayed in the Access window. General formatting options:

• Use ClassAsGroup keyword (recommended) to use the ClassName... group heading for each class instance (and all the variables don't have the repeated ClassName.xxx). This is particularly useful together with a ClassComment for the class instances where the comment is shown in the group heading, displayed as: "ClassName (comment) ...".
• Use ClassAsPagelabel keyword to display one Class instance per tab page.
• use ClassAsTextlabel keyword to display the class name as a text label heading to "separate" the class instances.

ClassGrid

Available from Build 139.32530. With the keyword ClassGrid, class instances of user defined class types can be displayed in Grids (Tables) in the Access window with the class instances as columns. The ClassGrid keyword is used anywhere after class instances are declared to control where the grids are displayed. It is also possible to use the keyword when declaring the class instances. Syntax is: ClassGrid Classes
Where Classes is a list of class instances of the same class definition. Classes can be specified in a number of different methods such as using a previously defined ClassList or list of classes similar to Classes Parameter in ForEach macros.
Example (list of class instances): ClassGrid {T1,T2,T3} (where T1,T2,T3 are previously defined instances of the same class definition)
Example (ClassList): ClassGrid L1 (where L1 is a previously defined ClassList)
Example (class definition type): ClassGrid {TankClass} (where TankClass is a previously defined Class Definition)
Example (class array): ClassGrid Tanks (where Tanks is a previously defined Class Array)

Notes:

• The width of each column can be controlled with the ClassGridColumnWidth keyword in the class definition.
• The maximum number of columns in a grid is controlled with the ClassGridMaxColumns keyword in the class definition. Additional grids are automatically created when there is a larger number of class instances.
• TextLabels within the class grid are shown as row separators, however blank lines and multiple text lines are ignored (only the last TextLabel in a sequence is shown). All text in a grid can be hidden if using keyword ClassGridHideText in the class definition.
• If comments are used for class instances, these are shown as text for each column in first row of grid. This can be disabled using keyword ClassGridHideComment in the class definition.
• If option ClassGridPageLabel is used in class definition, then the grid is displayed on a new tab page in the Access window.
• The use of ClassGrid allows positioning of display of the grid in Access window to be at any point after the declaration of class instances. To display the grid at the point of declaring the classes, use the {Grid} option or # symbol.
• Only user defined classes can be used in the ClassGrid. Predefined PGM class types (TagSelect, Matrix, etc.) cannot be used with ClassGrid.
• A class instance can only be displayed once in a grid.

ClassGrid Formatting Keywords

Available from Build 139.32530. A number of different keywords in the class definition can be used to manage how the class grid is displayed in the Access window:

• ClassGridColumnWidth Width: Use this to change the default width (14) of each column displayed in a class grid.
• ClassGridMaxColumns MaxColumns: Use this to change the maximum number of columns (10) allowed before a new grid is automatically created.
• ClassGridHideComment: Use this to hide the display of class instance comments, that are normally displayed in the first row of the grid.
• ClassGridHideText: Use this to hide the display of all TextLabels shown as text between rows in the grid.

Examples of Grid Display Options

;Class PGM Class TankClass ;ClassAsPageLabel ;ClassAsTextLabel ;ClassAsGroup ;ClassGridColumnWidth 8 ;default is 14 ;ClassGridMaxColumns 3 ;default is 10 ;other code here.... String UnitTag{Tag}@ Real Volume*<<100>>("Vol", "m^3") Real Height*<<1>>("L", "m") Real ResidenceTime*("Time", "h") TextLabel() EndClass ;Main PGM PageLabel("Tanks") TextLabel(,) TankClass Tank1, Tank2 ;TankClass Tank[7] ;ClassGrid TankClass ;ExcludeWatch Tank[0] ;ExcludeClass Tank[0] $ NOTE: The examples presented to the right uses different options from the above code (currently marked with ;).	Using PageLabel keyword only	Using ClassAsPageLabel
	Using ClassAsTextLabel	Using ClassAsGroup
	Using ClassGrid	Using ClassGrid with custom width

Sharing Classes between Projects

The recommended method of setting up a class that will be used in a number of pgms, or projects is as follows:

1. The CLASS definition is defined in a separate file; for example: General_Classes_and_functions.pgm
   • NOTE that this file must NOT contain the $ sign or EndFile token at the end of the file.
2. For shared use in a single project - The class definition file can be stored in the project\controls folder, then inserted into other PGM files using include file syntax >>filename.
   • If the class definition file is stored in the same folder as the PGM file, then use >>General_Classes_and_functions.pgm to insert the file as needed.
3. For shared use across multiple projects - The include file can be saved in a common shared folder, then inserted into other PGM files using include file syntax >>filename, the file name needs to be the relative or full path name.
   • For example: >>d:\Users\SysCAD Common Files\General_Classes_and_functions.pgm (Also See example using Include File)
   • See Include Files for more information.