PGM Introduction

From SysCAD Documentation
Jump to navigation Jump to search

Navigation: PGMs ➔ Introduction


SysCAD uses the PGM (Programmable Module) language in a number of contexts, mainly in the General Controller Model and Model Procedures. A subset of the PGM commands can be used in the PID Controller Model for "SetpointTag" and "MeasuredTag" fields.

The PGM language offers the following facilities:

  • Accessing permissible variables by name within any unit or stream on the flowsheet.
  • Modification of any permissible variables within any unit or stream.
  • Real, integer, Boolean and Bitwise arithmetic.
  • Strings and string manipulation routines.
  • Displaying of PGM local variables at run time and allowing charting of these variables.
  • Can make use of a number of supplied PGM classes, (see Predefined Classes).
  • Custom general-purpose functions and classes may be coded.

PGM code is executed once per SysCAD iteration. It allows the user to develop sophisticated programs to control the SysCAD model and to emulate real plant conditions.

Text Editor

The PGM (or MP) file is a text file in a pre-defined format. It must be created using a text editor.

We recommend that you use Microsoft VS Code or Notepad++ as the text editor. Please see Using VS Code or Using Notepad++ for more information on installing and setting up these software editors.

Other editors that SysCAD users have found convenient include Textpad, UltraEdit and Emacs, the links give some notes on setup.

How to create and use PGM file in SysCAD

To Create a new PGM file in a General Controller for use in a project, do the following:

  1. In a project, insert a General Controller.
  2. On the access window of the General controller, press the Edit PGM button. SysCAD will create a text file with the same name as the General Controller unit.
  3. Alternatively, the user may type in the required name of the pgm file in the FileName field. The file MUST have the extension .pgm.

To use an existing PGM file in a General Controller, do the following:

  1. In a project, insert a General Controller.
  2. On the access window of the General controller, press the Browse PGM button.
  3. The user may then browse to the required .pgm file and click on the 'Open' button.

A similar procedure is used for Model Procedures.

Template file

There is the flexibility to allow a template pgm file to be used. This template must be called template.pgm and can be placed in either the CfgFiles folder used by the project or the BaseFiles folder of the SysCAD installation. A full installation of SysCAD will include a file called template.pgm in the BaseFiles folder. The user may edit this file to suit. SysCAD will look in the CfgFiles folder first for a template and then the BaseFiles folder if one is not found in the CfgFiles folder.

The same is true for include files. In this case, the template is called

The template file is used to create the starting PGM file. The example below shows a PGM file created using the template.pgm (as distributed with build 139).

Example -- Blank file auto generated by SysCAD

;--- SysCAD General Controller (PGM) program logic file ---
; Revision: 1     Date:     Author:

;--- variable declarations ---

;--- Logic - executed at EVERY step ---

$ ; --- end of file ---
; Following lines are ALL IGNORED - SysCAD does not recognise anything after the $ symbol.

; Useful quick reference for optional procedures executed before first step or after last step.

Sub InitialisePreStart()
  ;--- Logic executed very early before first iteration,
  ;For example to activate/deactivate flowsheets or turn controllers/units on/off

Sub PreStart()
  ;--- Logic executed early before first iteration,
  ;For example to turn controllers/units on or off, set options/methods

Sub InitialiseSolution()
  ;--- Logic executed during initialisation before first iteration
  ;For example to set initial values, or set values in units

Sub TerminateSolution()
  ;--- Logic executed after last iteration (when solver is stopped)
  ;For example calculate values for reporting

; Useful quick reference for variables.


;Variable Declaration  Data Type      Range of Values

;Real or Double        Real           -1.0 E308 to 1.0 E308
;Integer or Long       Integer        -2147483648 to 2147483647
;String or Str         String         ASCII Character Set
;Memo                  String         ASCII Character Set, scrolls to multiple lines.
;Bit or CheckBox       Boolean        FALSE = 0; TRUE <> 0
;Byte                  Integer        0 to 255
;EnumDropList          Integer        -2147483648 to 2147483647

;When a user declares a variable, they may display the variable in the Controller access window, as follows:
;  * after the variable name allows the variable to be changed by the user in the access window (white box).
;  @ after the variable name displays the variable, but it cannot be changed by the user (grey box).
;  If there is neither a '*' nor an '@' then the variable is NOT displayed.
;The user may also choose to display conversion units for a real  variable (as shown in the examples below).

;Conversion Type     SysCAD Symbol     Some Common Units            Variable Declaration Example

;Concentration       Conc              g/L, mg/L, kg/m^3            real NickelConc@("Conc","g/L")
;Density             Rho               kg/m^3, t/m^3, lb/ft^3       real SlurryDensity@("Rho","kg/m^3")
;Energy              E                 J, kJ, cal                   real RequiredEnergy*("E","kJ")
;Fraction            Frac              %, ppm, -                    real RequiredSolidsFraction*("Frac","%")
;Mass Flow           Qm                t/h, kg/h, t/d, ST/h         real MeasuredFlow@("Qm","t/h")
;Power               Pwr               kW, kJ/s, MJ/h, BTU/h        real PowerUsed@("Pwr","kW")
;Pressure            P                 bar, atm, kPa, kPag, psi     real RequiredPressure*("P","bar")
;Temperature         T                 C, K, F                      real AutoclaveTemperature@("T","C")
;Time                Time              s, min, h, d, week           real ResidenceTime@("Time","h")
;Volumetric Flow     Qv                m^3/h, L/h, gal/min          real WaterFlow@("Qv","m^3/h")


;To read data from SysCAD: MeasuredValue = ["SysCAD Tag"]
;To write data to SysCAD : ["SysCAD Tag"] = RequiredValue

;    Declaring Variables:   
;    Conversion Types and units:
;    Examples of General pgm files:
;    General PGM Help sitemap: