Predefined Functions
Navigation: PGMs ➔ Functions ➔ Predefined Functions
| Functions | Subroutines | Classes | |||||
|---|---|---|---|---|---|---|---|
| Defining a Function | Predefined Functions | Tag Functions | Mathematical Functions | String Functions | Defining a Subroutine | Trigger Subroutines | Defining a Class |
Predefined Functions
A summary of the predefined functions available in SysCAD are listed in the Tables below. These do not include functions written for predefined classes. For information on those functions, please refer to the Predefined Classes section for the appropriate links.
Notes:
- All Function names are NOT case sensitive.
- "String" or "Message" used in the following functions refer to "A string" or "a variable of the STRING type".
Tag Related Functions
The Tag functions are used to Fetch/Set Values from/To SysCAD Project. See Tag Functions
| Function | Syntax | Description |
| = [ ] (Recommended format) |
variable = ["Full SysCAD Tag"] variable = [StringVariable]
|
This function gets a tag from SysCAD and returns the value of the parameter. This format can be used in place of GetTag(), GetDynTag() and GetDynStrTag()
|
| GetTag() | variable = GetTag("Full SysCAD Tag")
|
The GetTag function returns the value of the parameter in numerical type.
|
| GetDynTag() | variable = GetDynTag("String")
|
The GetDynTag function returns the value of the parameter in numerical type, referred to by the tag contained in string |
| GetDynStrTag() | String Variable = GetDynStrTag("String")
|
The GetDynStrTag function returns the Tag name of the parameter, referred to by the tag contained in string.
|
| [ ] = (Recommended format) |
["FullTag"] = variable [StringVariable] = variable [Str "FullTag"] = StringVariable
|
This function assigns the value to the parameter. This format can be used in place of SetTag(), SetDynTag() and SetDynStrTag()
|
| SetTag() | SetTag("Full SysCAD Tag", value)
|
The SetTag function assigns the value to the parameter, referred to by the tag contained in Full SysCAD Tag.
|
| SetDynTag() | SetDynTag(string, value) or SetDynTag("Full SysCAD Tag", value)
|
The SetDynTag function assigns the value to the parameter, referred to by the tag contained in string or Full SysCAD Tag.
|
| SetDynStrTag() | SetDynStrTag(String, String2)
|
The SetDynStrTag function assigns a String2 to String.
|
| DynTagExists() | variable = DynTagExists("String")
|
The DynTagExists function returns True if the SysCAD tag represented by the string exists, otherwise it returns False.
|
Conditional Functions
The Conditional Functions are used to evaluate the condition of the project, based on the result, set a value or command to the project. See Conditional Functions
| Function | Syntax and Example | Description |
| If() Elseif() Else Endif |
if (expression1)
statements1
elseif (expression2)
statements2
else
statementsN
endif
|
statements1 : are executed if expression1 is True, otherwise they are ignored.
|
| iif() | variable = iif(expression, truePart, falsePart)
For Example: |
The iif function is two-part if() statement, based on the condition of the expression, the True or False value is returned.
|
| iifStr() | String Variable = iifStr(expression, truePart, falsePart)
For Example: |
Available in Build139.29680 or later. The iifStr function is a two-part if() statement, based on the condition of the expression, the True or False value is returned.
|
| While() EndWhile |
While (expression1)
statements
endWhile
|
While the expression is true, the statements will be executed. When writing the While loop, ensure the loop can end, else the solver will be "stuck" inside the loop.
|
Time Related Functions
| Function | Syntax | Example | Description |
| DeltaTime() | variable = DeltaTime()
|
Simulation_Time = Simulation_Time + DeltaTime() ; This will increment the simulation time every iteration.
|
The DeltaTime function returns the current SysCAD value of Delta Time (simulation step size) in seconds. For ProBal this is always 1.
Note: during the Initialisation step, DeltaTime will equal zero as no time has passed. |
| Time() | variable = Time()
|
Sub InitialiseSolution()
StartTime = Time()
EndSub
|
The Time function, returns the SysCAD time in seconds. |
Miscellaneous Functions
| Function | Syntax and Example | Description |
| Random() | variable = Random(Number)For Example: |
The Random function, returns a random number between 0 and Number. If Number is NAN then the function returns an integer between 0 and 32767. Precision is 1 in 32768. d = a random number between 0 and 100 |
| ForEachClass() | ForEachClass(ClassName, SubroutineName())
ForEachClass({ClassNameList}, SubroutineName())
ForEachClass({ClassInstanceList}, SubroutineName())
ForEachClass(ClassArray, SubroutineName())
|
Available in Build 139.31388 or later. The ForEachClass macro generates code that loops through all instances of the user specified Class (or all members of the specified Class Array) and calls the specified Sub. The Sub may have parameters. Class instances must be in the global scope and declared prior to the ForEachClass() macro.
|
Species Functions
See Species Database Class for additional functions related to species properties.
| Function | Syntax | Examples | Description |
| MW() | variable = MW("Species")
variable = MW("Compound")
variable = MW("Element")
|
MW_Water = MW("H2O(l)") ;Species
MW_H2O = MW("H2O") ;Compound
MW_H_Gas = MW("H")*2 ;Elements
MW_H_Gas = MW("H2") ;Compound
MW_SO4 = MW("S") + MW("O")*4 ;Elements
|
Returns the Molecular Weight of Species, Compound or Element. NOTES:
|
| SpI() | variable = SpI("Species")
|
Water_Species_Index = SpI("H2O(l)")
|
Efficient function to return the Species Index of the specified species in the list of the project species. A file load error occurs if species is not found.
|
| ElemI() | variable = ElemI("Element")
|
Na_Elemental_Index = ElemI("Na")
|
Only available in Build 139.29999 or later.
Efficient function to return the Element Index of the specified element in the list of the elements used in the project. A file load error occurs if element is not used in the project.
|
User Defined Messages and Errors Functions
Please note that the SysCAD log file may be enabled or disabled by the user by ticking the Log to file : $Prj\MessageLog.csv tick box on the Message Window Options Tab. By default this option is disabled. If this option is enabled, then SysCAD will create the MessageLog.csv file in the project.
| Function | Syntax and Examples | Description |
| LogError() | LogError(string)For Example: |
The LogError function displays the supplied message string in the SysCAD message window on the messages tab with an error indicator. Supports multiple string parameters. |
| LogWarning() | LogWarning(string)
For Example: |
The LogWarning function displays the supplied message string in the SysCAD message window on the messages tab with a warning indicator. Supports multiple string parameters. Available in Build 139.32341 or later. |
| LogNote() | LogNote(string)
For Example: |
The LogNote function displays the supplied message string in the SysCAD message window on the messages tab with a note indicator. Supports multiple string parameters. |
| ConditionError() | ConditionError(Index, Boolean expression, string)
For Example: |
Index - valid range from 0 to 7, that is, only 8 error messages can be reported per PGM/General Controller. If the Boolean expression evaluates to true, then the message string specified is displayed in the Condition tab of the Message Window. As a Condition state message this is only shown for the current solver iteration. Supports multiple string parameters. |
| ConditionNote() | ConditionNote(Index, Boolean expression, string)
For Example: |
Index - valid range from 0 to 7, that is, only 8 error messages can be reported per PGM/General Controller. If the Boolean expression evaluates to true, then the message string specified is displayed in the Condition tab of the Message Window. As a Condition state message this is only shown for the current solver iteration. Supports multiple string parameters. |
| MsgBox() | MsgBox(string)
For Example: |
The MsgBox function displays the supplied message string in the SysCAD message window in exactly the same way as LogNote.
|
| StopSolver() | StopSolver(string)
For Example: |
The StopSolver function stops the SysCAD solver and displays the supplied message string in the message window. Supports multiple string parameters. Available in Build 139.32346 or later. |
| PauseSolver() | PauseSolver(string)
For Example: |
The PauseSolver function pauses the SysCAD solver and displays the supplied message string in the message window. Supports multiple string parameters. Available in Build 139.32346 or later. |
| Beep() | Beep()
|
The Beep function calls the MS Windows MessageBeep function playing a simple beep. Note that this is asynchronous and queues the beep to be played when the application is idle. Behaviour of the beep() function will depend on number of calls to Beep(), CPU utilisation, as well as OS & sound card settings. NOTE: If a value is defined within the function, it is ignored. |
| Sound() |
Sound(Freq, Duration)For Examples: |
The Sound function allows the user to set:
Warning: Use with caution as Duration uses CPU time, using sound with long duration every iteration will slow down the solve time! |
Conversion Functions
See Also Conversion Functions and Declaring Variables
| Function | Syntax | Description |
| Cnv() | variable = Cnv(variable1, unit)
|
The Cnv function converts variable1 to the conversion units specified by unit and returns the result.
|
| CnvVal() | variable = CnvVal(variable1, family, unit, ReqdUnit)
|
The CnvVal function converts variable1 from the conversion units specified by unit to the conversion units specified by ReqdUnit for the specified conversion family and returns the result.
|
Tag Visibility Functions
| Function | Syntax | Description |
| SetConcealedState() | SetConcealedState(variable, bit ConcealVariable)
|
The SetConcealedState function hides or shows the variable in the Access window.
|
SetConcealedState
Use SetConcealedState to set a variable to be hidden from the access window, the hidden variable can be viewed when the ShowConcealed button is pressed on the PGM access window. The variable (tag) is still accessible by other controllers, Excel reporting, etc. It is simply hidden from user in Access window when it is concealed.
Syntax:
SetConcealedState(Variable, bit ConcealVariable)
- Variable: a valid variable or class for which the Concealed state must be set.
- ConcealVariable: this may be either be a single bit value (true or false) or an expression which resolves into a single true or false result.
- The SetConcealedState function is used to change the Concealed state of data variables based on the specified bit value. By changing the Concealed state the variables become visible or concealed on the Access window. Concealed variables are still accessible as tags in the flowsheet (e.g. from Excel).
- The Variable can be a data variable or a class. If it is a class, all the variables for that class will have the state changed.
- Only watched variables that are defined as inputs or outputs can have the state set. It is meaningless to use SetConcealedState on variables that are not declared as input or output to make them visible as tags.
Example:
Bit UseSetSplit{i,s}
Real RequiredSplit{i,Cnv("Frac","%"),Range(0,100)}
Sub InitialiseSolution()
SetConcealedState(RequiredSplit, (UseSetSplit==false)) ;Only want variable visible if option is chosen where this is used
EndSub
if (UseSetSplit)
SetTag("X_001.GM.IOs.[P_002].Split (%)", RequiredSplit)
endif
Using SetConcealedState with Classes:
- It is possible to set the concealed state of a variable in a class, for example
SetConcealedState(T.d1, true). - It is also possible to set the concealed state of a variable in an array of classes as long as the index is specified directly, for example
SetConcealedState(T[3].d1, true). - It is NOT possible to specify the index pragmatically, for example
SetConcealedState(T[i].d1, true). - When writing a function within a class definition, it is possible to use SetConcealedState to change the concealed status of variables within the class. This is useful for a class to adjust visible variables as a function of its parameters. You can set the concealed state of all variables within the class by specifying this as the Variable parameter.
For example, include these functions in the class to show/hide all variables in the class.
;Show all variables in the class
Sub ShowAll()
SetConcealedState(this, false)
EndSub
;Show hide variables in the class
Sub HideAll()
SetConcealedState(this, True)
EndSub
For more information on how to apply this to a PGM class, please see Aqueous Feed Concentration Calculator example PGM file.