PGM Programming and Conventions

From SysCAD Documentation
Jump to navigation Jump to search

Navigation: PGMs ➔ PGM Programming and Conventions

PGM Syntax Data Types Declaring Variables Predefined Variables Labels


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

When assigning variables with Engineering Units, the Engineering units are Case Sensitive.

Special Characters


The user may add comments to the pgm control file by inserting a semicolon, ;, into the code at any point. All text after the ; will be treated a comment and ignored by the compiler.


Current Syntax Syntax used in earlier versions
;Calculate the nickel recovery as a % = Nickel in Cathodes/Nickel in Feed
NiCathodes = ["P_407.Qo.QEl.Ni (t/h)"]  
NiInFeed   = ["P_001.Qo.QEl.Ni (t/h)"]
NiRecovery = NiCathodes / NiInFeed * 100
;Calculate the nickel recovery as a % = Nickel in Cathodes/Nickel in Feed
NiCathodes = GetTag("P_407.Qo.QEl.Ni (t/h)")
NiInFeed   = GetTag("P_001.Qo.QEl.Ni (t/h)")
NiRecovery = NiCathodes / NiInFeed * 100

End of File

  • The dollar sign, $, is used to mark the end of the PGM file, and MUST be added at the end of the main pgm file.
  • Any code following the dollar sign will be ignored.
  • If an include file is used, do NOT use a $ in the include file as this will be interpreted as the end of the PGM program.

Include Files

Other PGM files can be included in the main pgm file by using the symbols >> followed by the filename.

  1. The >>Filename must appear on a new line.
  2. The line containing >>Filename may not have any comments or other symbols.
  3. The include file must NOT end with a $ symbol as this will end the overall file!


  1. The filename may include a full path, if the included file is not in the current project.
  2. If the included file is saved in the same folder as the main PGM file, then only the name of the PGM include file needs to be given. For example:
    • >>UtilityClasses.pgm
  3. Relative File Paths can be used.
    • Example 1: If main pgm file is in the normal Controls folder within the project folder, to use PGM files in a folder at the same level as the project .spf folder:
    • Example 2: If the include file is stored a few levels higher in the folder tree, user can specify the location relative to the project folder, using symbolic path names.
      (The symbolic path names can be found in View - Project - Select the Symbolic paths tick box.)
  4. Files may be saved anywhere, including on the network, as long as the correct file path is included. For example:
    • >>n:\Users\SysCAD Users\Common Files\UtilityClasses.pgm
  5. If the file cannot be opened, an error is reported.

SetChangeTagOn and SetChangeTagOff

Include SetChangeTagOn or SetChangeTagOff to control if Change Tag (of unit/pipe tags) is applied to PGM, MP and include files. Because an MP file would not have a tag, the default for allowing tag change in file is OFF, but for PGM (General Controller) the default is ON. The user can override this in the text file with the keywords SetChangeTagOff and SetChangeTagOn anywhere in the file.

If writing include files with class definitions, these would normally have no tags so it would be good to add SetChangeTagOff.

Skipping search and replace for tags in pgm and mp file where they are not necessary significantly improves speed for tag changes. This is especially noticeable in projects using MP in large numbers of pipes and/or units. Project Merge where there are lots of tag changes in a project with lots of PGM/MP files is also significantly faster.

This feature is available in Build 137 and later.

Data Type and Declaration

Please see the following pages for more information.

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.

Please see page Predefined Constants and Variables for more information.

SysCAD Tags

Each SysCAD unit model variable can be considered as a tag, these can be used in the PGM file for customised calculation:

  1. Any read-write variables (in White fields) can be accessed and changed from the PGM, thus extracting and setting values as per the user's instructions. (PGM Codes.)
  2. The read only variables (in Grey fields) can also be accessed. However, their values cannot be changed from the pgm.

These allow external parameters to be referenced and manipulated within the PGM. These parameters are not only limited 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. Tags that are defined as string variables and built during code execution are only checked at runtime when actually used.

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 one of the following from the pop up lists:
    Copy Full Tag (Ctrl+T) - this copies the full tag only
    Copy Tag For PGM (Shift+Alt+T) - this copies the full tag plus the tag function syntax.
    Copy Tag - use this if the tag is used in the MP file or as part of the string concatenate function.

See example on the right for what is copied.


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)  

Referencing Tags

Tags can be referred to in two ways:

1. Fully defined fixed string constants:
 SysCAD 9.3 Format: 
    MassFlow = ["P_001.Qm (t/h)"] 
 GetTag function Format:
    MassFlow = GetTag("P_001.Qm (t/h)") 
2. Dynamically defined string variables:
 SysCAD 9.3 Format: 
    MassFlow  = [s1]
    MassFlow  = [Concatenate(PipeTag, ".Qm (t/h)")]
GetDynTag function Format: 
    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 for the variable.

NOTE: Engineering units ARE case sensitive.

See Declaring variables with conversion information for more information.

Alternatively, user may look at this table for a list of conversions used: Conversion List Table.

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 an 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.

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


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


Please see sections Predefined Functions and Defining a Function.

Simple template example:

Function functName (argument list)
   Return value


Please see section Defining a Subroutine and Trigger Subroutines.

Simple template example:

Sub functName (argument list)


Please see sections Predefined Classes and Defining a Class

Simple template example:

Class className

   Variable declaration(s)

 Function Exec()
   ... Code ...
   Return 0


Classes: declarations and access to members

The declaration of an instance of a class is similar to the declaration of a variable, except that the instance must be declared from a predefined class. See Class - How to Define a Class.

An instance may be positioned anywhere in the PGM code, as long as it is declared before it is used.

A * CANNOT be appended to the instance name. Use the Watch Keyword.

The first three examples below are based on the CSTR example class described on the Class page. The last one is based on the Predefined Species Database Class. The Species Database Class does not need to be declared and can only return values (no values can be set).

Class/Function Call Syntax Example Description
Declaration of the Class instance ClassName InstanceName(s) CSTR TankA Creating an instance of the CSTR Class, TankA.
Setting the value of a data member of an instance InstanceName.dataMember = value
  • InstanceName : an instance of the class, declared above.
  • dataMember : is a data member belonging to the predefined instance
  • value : is the value to be assigned to the data member.
TankA.UnitTag = "TANK_A" Setting the unit tag name (an alternative to using the Init function)
Retrieving the value of a data member of an instance variable = InstanceName.dataMember
  • InstanceName : an instance of the class, declared above.
  • dataMember : a data member belonging to the predefined instance.
  • variable : a pre-declared variable
ReactionExtent = TankA.CuLeachExtent Getting the calculated value of the Cu Leach reaction extent
Retrieving the value returned by a member function of an instance variable = InstanceName.memberFunction()
  • InstanceName : an instance of the class, declared above or predefined.
  • memberFunction : is a function declared within the predefined instance
  • variable : is a pre-declared variable, its value is returned by memberFunction.
SpeciesIndex = SDB.FindSpecies("H2O(l)") Getting the species index of water from the Species Database Class