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 Instance Definition
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. Class instances can be declared individually (in the same way normal data variables are declared) or as an array of class instances.
Once the class instance has been declared, user can access class variable tags and perform the Class functions or subroutine.
| Function | Function Syntax | Description/Notes/Example |
|---|---|---|
| Syntax for Instance Definition | Individually: ClassName Instance_1, Instance_2
ClassName Instance[3]
|
Examples:CSTR_Class Tank_1, Tank_2
CSTR_Class Tank[3]
|
| Syntax for Interactive with Class Instances | ||
VariableTag.UnitTag = "InstanceTag"
|
For example, we can set the UnitTag for class instance "TankA" during the "InitialiseSolution()" subroutine: TankA.UnitTag = "TANK_A"
| |
Value ="ClassInstance.ClassVariable
|
For example: we can retrieve a value from a class function and assign it to a variable: ReactionExtent = TankA.CuLeachExtent
| |
?
|
For example: we can get the species index of water from the Species Database Class: SpeciesIndex = SDB.FindSpecies("H2O(l)")
| |
ClassInstance.Function()
ClassInstance.Subroutine()
|
For example, we can perform the Exec() function for class instances Tank_A and Tank_B:
|
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 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.
| Function | Function Syntax | Description/Notes/Examples |
|---|---|---|
| Exclude Watch | ExcludeWatch ClassInstance1,... |
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. For example: const long TankCount = 11
TankClass T[TankCount]
ExcludeWatch T[0]
ExcludeClass T[0]
;From Build 139.32530 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 Comment | ClassComment ClassInstance1 "String1",... |
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. For example: |
| General Formatting Words | ClassAsGroup
|
(Recommended) Keyword 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) ..." |
ClassAsPageLabel
|
Keyword to display one class instance per tab page. | |
ClassAsTextLabelLabel
|
Keyword to display the class name as a text label heading to "separate" the class instances. | |
| Class Grid Display Formatting Keywords | 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:
Notes:
| |
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 Dsiplay 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 ;). |
||
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:
- 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.
- 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.
- 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 below)
- See Include Files for more information.
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}
- Example of adding the ClassList when declaring the class instance:
- 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 Build 139.32530 the above can be replaced by
TankClass T[TankCount]{ExcludeZero} ;using full keyword
TankClass T[TankCount]{ez} ;using abbreviated keyword