From SysCAD Documentation

Navigation: PGMs

Contents 1 General 1.1 Semicolon (;) 1.2 Dollar sign ($) 1.3 EndFile 1.4 Include Files 2 Data Type and Declaration 3 Predefined Constants and Variables 3.1 Standard constants 3.2 Special constants 3.3 Special variable 3.4 User Defined Constants using the Const Keyword 4 SysCAD Tags 4.1 Checking Tags 4.2 The variable naming syntax 5 Conversions (or Engineering Units) 5.1 Checking Conversions 5.2 Conversion Syntax 6 Operators 7 Functions and Classes

General

1. The PGM language is NOT case sensitive. This applies to keywords (programming language) and user defined variables.

Semicolon (;)

Any text between a semicolon and the rest of the line is treated as a comment and is not interpreted.

Dollar sign ($)

The dollar sign is used to mark the end of the PGM file. Any code following the dollar sign will be ignored. If an include file is used, be careful not to use a $ in the include file as this will be interpreted as the end of the PGM program.

EndFile

For SysCAD 9.0 version Build 115 Update 4 and later: EndFile can also be used to mark the end of the file. Same function as $

Include Files

1. PGM files can include other PGM text files (recursively if required) by using the symbols >>filename.
   • This must appear on a new line.
   • The filename may include a full path.
   • If the file cannot be opened, an error is reported and the line is ignored.
   • The line containing the include file may not have any comments or other symbols.
   • The include file is treated as a normal PGM file and is read as though it were part of the main file. Therefore the include file must NOT end with a $ symbol as this will be interpreted as the end of the overall PGM program!
2. To include a file that's stored with the other PGM files (usually in the controls folder within the project folder), only the name of the PGM include file needs to be given. For example:

   >>CommonFunctions.pgm

3. Relative paths can be used. This will be relative to the main pgm file. For example, to use PGM files in a folder at the same level as the project .spf folder:

   >>..\..\CommonControlFiles\UtilityClasses.pgm

Data Type and Declaration

Please see section Declaring and Managing Variables

Predefined Constants and Variables

Constants can be used in expressions and statements. Constants are effectively read only variables. You can declare your own constants using the Const Keyword.

Standard constants

BIT	true	= 1
BIT	false	= 0
DOUBLE	PI	= 3.14159265358979
DOUBLE	NAN	= *

Special constants

BIT	OnStart	= 1 for the first iteration when SysCAD run is executed. = 0 for all subsequent iterations. This is useful for some initialisation code.
BIT	OnInitialise	= 1 for the first iteration when the SysCAD run command is passed but before it is executed. = 0 for all subsequent iterations. This can be used to set tags that will become unchangeable once SysCAD is solving, which includes tags such as solving methods, any list boxes or tick boxes and datum in Dynamic. Note: SetDynTag(Tag, value) and GetDynTag(Tag) must be used to do this.
BIT	OnTerminate	= 1 for the last iteration when the SysCAD stop command is passed. = 0 for all other situations. This can be used to the check condition of the solve solution and generate user defined messages based on the results.
BYTE	SolveMode	This indicates the SysCAD solver mode.
STR	ModelTag	This contains the tag of the model that is using the PGM. It refers to the parent or owner of the PGM code. For example, this is useful for Log messages to distinguish between different General Controller models using PGM code.

Special variable

BIT	StopSimulation	If this is set to 1 (true) then the PGM halts the SysCAD run. This is useful for running a scenario for a fixed time or for stopping SysCAD under certain conditions.
BIT	PauseSimulation	If this is set to 1 (true) then the PGM pauses the SysCAD run.

User Defined Constants using the Const Keyword

Syntax:

Const variable declaration = value

The Const keyword ensures that the value assigned to the variable will remain unchanged (ie becomes a read only variable). See Predefined Constants and Variables.
NOTE: You cannot declare a Constant variable in a Class.

Example

const double OreDensity = 5000
const double H2OMW = 18.015

const long Auto = 1
const long Manual = 2

const bit Running = 1
const bit Stopped = 0

SysCAD Tags

Each SysCAD unit model variable can be considered as a tag, these can be used in the PGM file for customised calculation. Any read-write variables can be accessed and changed from the PGM, thus extracting and setting values as per the user's instructions. (PGM Codes.) The read only variables can also be accessed, however, their values can not be changed from the pgm.

These allow external parameters to be referenced and manipulated within the PGM. These parameters does not only limit to the unit model variables, they can be also include driver tags.

NOTE: Tag names are NOT case sensitive.

Checking Tags

A tag is NOT checked to see if it exists or is valid when the PGM code is loaded and compiled, but is checked when the PGM code is executed for the first time or the Check Tags button on the Access window is pressed. The PGM can only access other external numerical tags.

The variable naming syntax

The tag names can be typed in or copied from the SysCAD Access Window. As the tag names can be complex at times, we recommend all tag names should be copied from SysCAD. To copy the tag name from SysCAD, from the access window, right click on the variable(s) and select Copy Full Tag from the pop up lists (or simply press [Ctrl+C] to copy) .

If the SysCAD Tag needs to be typed in, the syntax is as follows:

1. If the required variable is on the first tab page (or any page with same name) of the access window and not indented below another name, then the required form of the tag will be as follows:

    SysCAD Unit's tag name.variable name
    e.g.  P_001.Qm (t/h)

2. If the required variable is indented, in the access window, beneath the name of another variable or on a tab page with a different name, then the required form of the tag will be as follows:

    SysCAD Unit's tag name.variable group (or page) name.variable name 
    e.g.  P_001.Qo.Sf (%) 
          P_001.Qo.CMC:L.NaOH (g/L)  

Examples

Tags can be referred to in two ways:

1. The functions GetTag and SetTag, allow Conversions (or Engineering Units).

    MassFlow = GetTag("P_001.Qm (t/h)")

2. The functions GetDynTag and SetDynTag, allow Conversions (or Engineering Units).

    MassFlow  = GetDynTag(s1)
    MassFlow  = GetDynTag(strcat(PipeTag, ".Qm (t/h)"))

Conversions (or Engineering Units)

These can be added to the tag, to specify the required engineering units that the variable should be accessed in.

NOTE: Engineering units ARE case sensitive.

To find out the list of Engineering Units that are available, from SysCAD, go to file menu View|Project, this will open the Project.spj Dialog box. Select the Conversions Tab page to view the list.

Alternatively, user can find a list of available engineering units at List of SysCAD Conversion Units.

Checking Conversions

A conversion is NOT checked to see if it exists or is valid when the PGM code is loaded and compiled, but is checked when the PGM code is executed for the first time.

Note: if no conversion is assigned or the conversion is invalid, the default SI (or MKS) units will be used. An error message is given in the Message Window when invalid conversion is specified.

Conversion Syntax

The conversion must be separated from the variable name by at least one space. The conversion is normally placed in brackets, but it is possible to not include the brackets.

Examples: 
       P_001.Qm (kg/s)
       P_001.Qo.Sf %

Operators

Operators (+,-,AND, OR, <, >, etc.)

Functions and Classes

Please see sections Defining a Function & Defining a Class