Navigation: PGMs ➔ PGM Programming and Conventions

PGM Syntax	Data Types	Declaring Variables	Predefined Variables	Formatting

General

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

Comments

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.

Example:

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, $ or EndFile, is used to mark the end of the PGM file, it MUST be added at the end of the main pgm file.
Any code following the dollar sign (or EndFile) will be ignored.
If an include file is used, do NOT use a $ (or EndFile) 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.

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

Notes:

The filename may include a full path, if the included file is not in the current project.
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
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:
>>..\..\CommonControlFiles\UtilityClasses.pgm
- 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.)
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
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.

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:

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.)
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:

These tags can be checked for validity at solver startup or by CheckTags button.
The functions [" "], GetTag and SetTag can be used.
For numerical tags Conversions (or Engineering Units) can be used.

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:

These tags are only checked during solve time when running PGM code because the tags are built programmatically ("dynamically built").
The functions [Variable], GetDynTag and SetDynTag can be used.
For numerical tags Conversions (or Engineering Units) can be used.

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.

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

Operators

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

Functions

Please see sections Predefined Functions and Defining a Function.

Simple template example:

Function functName (argument list)
   ...code...
   Return value
EndFunct

Subroutines

Please see section Defining a Subroutine and Trigger Subroutines.

Simple template example:

Sub functName (argument list)
   ...code...
EndSub

Classes

Please see sections Predefined Classes and Defining a Class

Simple template example:

Class className
  ... Variable declaration(s) ...

  Sub Init()
    ... Code ...
  EndSub

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

EndClass

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 * or @ 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 SDB instance. The SDB class instance 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

PGM Programming and Conventions

Contents

General

Special Characters

Comments

End of File

Include Files

SetChangeTagOn and SetChangeTagOff

Data Type and Declaration

Predefined Constants and Variables

SysCAD Tags

Checking Tags

The variable naming syntax

Referencing Tags

Conversions (or Engineering Units)

Checking Conversions

Conversion Syntax

Operators

Functions

Subroutines

Classes

Classes: declarations and access to members

Navigation menu

PGM Programming and Conventions

General

Special Characters

Comments

End of File

Include Files

SetChangeTagOn and SetChangeTagOff

Data Type and Declaration

Predefined Constants and Variables

SysCAD Tags

Checking Tags

The variable naming syntax

Referencing Tags

Conversions (or Engineering Units)

Checking Conversions

Conversion Syntax

Operators

Functions

Subroutines

Classes

Classes: declarations and access to members

Navigation menu

Search