General Controller

From SysCAD Documentation
Jump to: navigation, search

Navigation: Main Page -> Models -> Control Models

Related Links: PGMs


General Description

This is used to simulate plant control, plant operations or calculate displays. This model is often used to customise or extend the functionality of a standard unit operation. These functions may be as simple or complex as may be required.

The General Controller reads a text file, set up by the user, which allows the user to include fairly powerful programming functions. The files are known as "pgm" files and are detailed in a separate section of the documentation PGMs. The control logic (or program code) that you write for a General Controller is executed once every iteration.

The PGM language includes the following capabilities:

  • Accessing tags by name within any unit or stream on the flowsheet.
  • Modification of any permissible tags within any unit or stream on the flowsheet.
  • Real, Integer and Boolean arithmetic.
  • Strings and string manipulation routines.
  • Declaration of user tags (PGM variables) which are then accessible at run time for view, change, reporting, trending, etc.
  • General-purpose functions and classes may be defined and used.

This document only describes the access window for the general controller, and some of the more common problems that may occur. The PGM help documentation contains examples of pgm files and various applications that can be simulated using this model.

For dynamic projects this is used extensively to simulate the control system as well as operator actions. It can be used to simulate events, for example the random failure of equipment.

Tags that are controlled (using SetTag) or referenced (using GetTag) by the General Controller will have a coloured triangle shown in the access window of that unit. When the user right clicks on one of these referenced tags it will indicate which controller is referencing the tag. See Controlled and Referenced Variables.

Location of Control Text files

  • When the user creates a control file, SysCAD automatically creates a sub-folder in the project called Controls and stored all control files (with the extension .pgm) in this folder.
  • The user may store the control files in any other location, although this is not recommended. The use of Relative File Path is allowed.
  • The user may view the location of all the control files in a project by accessing Project Window - Files List.

Video Links

The Tutorial section has a number of videos showing users how to write a simple PGM file for a General Controller:

Basic Tutorial - General Controller and PGMs

Similar Models

  • Set Tag Controller - the user may carry out the simple ratio control and set multiple tags using the the Set Tag Controller model.


Diagram

Models-Controller-Image001.gif

The diagram shows the default drawing of the General Controller.

Inputs and Outputs

There are no connections to this unit.

Model Theory

The power of this model is contained in the program (PGM) written by the user. The pgm syntax for programing the control file is described in PGM Documentation.

Reload File in 9.3

In SysCAD 9.3 or later the PGM file can not be reloaded unless the model is stopped. If the model is stopped and the PGM file is changed, the file will automatically be reloaded (once SysCAD is reactivated).

If the file is modified while the model is running then the file will be reloaded when any of the following occur after the model is stopped:

  • the SysCAD application is activated (click anywhere on it) after another application was in use (eg. Notepad, Excel, etc)
  • the user starts another run
  • the reload button is pressed

PGM Execution SysCAD 9.2 vs SysCAD 9.3

PGM Execution Differences:

  • In SysCAD 9.2 (Build 135 or earlier):
  1. When SysCAD starts, the full PGM file is executed once at start up, once at Stop and once every iteration. So if a project was solved for 5 iterations, then the full pgm file is executed 7 times.
  2. Functions Oninitialise() and OnTerminate() can be used in SysCAD 9.2 only.
  • In SysCAD 9.3 (Build 136 onwards):
  1. When SysCAD starts, only PGM code written inside the Trigger Subroutines PreStart() and InitialiseSolution() will be executed
  2. When SysCAD stops, only PGM code written inside the Trigger Subroutines TerminateSolution() will be executed
  3. The remaining PGM code will be executed once every iteration. So if a project was solved for 5 iterations, then the pgm file is executed 5 times.
  4. Functions Oninitialise() and OnTerminate() CANNOT be used in SysCAD 9.3 format.

If the user wishes to keep using the Oninitialise() and OnTerminate() functions in SysCAD 9.3, then the user has to keep the SysCAD 9.2 PGM execution logic by ticking the Old135Format box on the first Tab of the general controller. This means the PGM code will be executed at Start, Stop and every iteration.

NOTE: Ticking the Old135Format only affects how the PGM is executed, and prevents the use of the new Trigger Subroutines. Any other new PGM functions and PGM features are not affected. Therefore, the user may still use the new functionality, such as DropList, [] for GetTag, etc., when the Old135Format is ticked.

Data Sections

The default sections and variable names are described in detail in the following tables. The default General Controller access window consists of one section. The user may set up variables in the pgm code that will be shown on the access window. The number of sections in the access window will depend on the number of variables chosen,

  1. GControl tab - Contains general information relating to the unit.
  2. Info tab - Contains general settings for the unit and allows the user to include documentation about the unit and create Hyperlinks to external documents.

General Controller Page

Unit Type: GControl - The first tab page in the access window will have this name.

Tag Input / Calc Description
Common Data on First Tab Page
Requirements

On

Check Box

The user may enable or disable the general controller using this box.

AutoReload

Check Box

Only available in SysCAD 9.2 (Build 135) or earlier. The pgm will be automatically re-loaded if the file has been changed and saved. For SysCAD 9.3 see Reload File in 9.3 section above.

Old135Format

Check Box

Only available in SysCAD 9.3 or later. The pgm can make use of the OnInitialise and OnTerminate predefined constants, consistent with SysCAD 9.2 (Build 135). If unticked, the pgm can make use of the new Trigger Subroutines.
NOTE: The two sets of syntax cannot be used together.
Please see PGM Execution for more information.

FileName

Input

The user types in the name of the pgm file required for control. The file can be entered in any text editor, and must have the file extension 'pgm'. The user need not always type in the full path of the file. SysCAD will first attempt to locate the file in the project folder, then in the cfgfiles folder. If the file is in neither of these folders, then the user should include the path of the file. If the unit cannot locate the file, it will alarm and send an error message to the 'State' box - NO PROGRAM. The easiest way to load in the pgm file is to use the Browse PGM button.

Folder

Feed Back

The full path/folder of the pgm file is displayed here.

The FileState field is only available in SysCAD 9.3 or later.
FileState OK File is found and has no errors.
Not Specified The user has not specified a file.
Not Found The specified file can not be found.
Load Error There is an error in the file. The State and Message (MSG) fields will provide further information.

State

Output

The state of the PGM file once a load has been attempted. If everything is correct and operating normally, the user will see 'OK' in this box. Otherwise the unit will flag an error message which helps the user to locate the problem with the controller. These messages are also displayed in the message window.

Errors:

MSG_1 to MSG_4

Output

These message lines are used to report PGM compile errors or errors while the PGM code is executing.

 

Edit

Edit PGM

This allows the user to edit the specified PGM file, normally using the Notepad text editor.

Reload

Reload PGM

This reloads and recompiles the PGM code. Use this after changes to the PGM code have been made and saved. This is not necessary if the AutoReLoad check box is ticked.

Browse

Browse PGM

This is used to locate a PGM file.

Check Tags

Button

Only available in SysCAD 9.2 (Build 135) or earlier. This can only be used while SysCAD is not solving or running. It is used to check all the tags used by the pgm and their engineering units. This is done automatically when the solver starts, so you do not need to use this button.

Concealed

Show Concealed / Hide Concealed

This toggles the show/hide concealed variables in the PGM file.

ResetConcealed

Reset Concealed

This resets the concealed tag status, use this button when concealed tag status has been modified in the PGM file.

ZeroAllVars

Zero All Variables

Resets ALL variables to zero value and strings to empty.

ZeroVars

Zero Variables

Resets all result and internal variables to zero value and strings to empty. User input fields are left unchanged.

 

EditMainPGM

Button

This is used to edit the main PGM file. The PGM file name will be displayed either on the button (SysCAD 9.2 or earlier) or as part of the Tag to the left of the button (SysCAD 9.3 or later).

Edit include x

Button

This is used to edit the include file. Each include file will have a separate button. The include file name will be displayed on the button.

NewInclude

Input

The user types in the name of the include file required to assist with control. The file can be entered in any text editor, and must have the file extension 'pgm'. The user need not always type in the full path of the file. SysCAD will first attempt to locate the file in the project folder, then in the cfgfiles folder. If the file is in neither of these folders, then the user should include the path of the file. If the unit cannot locate the file, it will alarm and send an error message to the 'State' box - NO PROGRAM.

TagList... (This is available in SysCAD 9.3 only)
Input Copy To Clipboard Generates a list of all the writeable variables in the PGM (from the Watch Variable Pages). Useful for reports.
Output Copy To Clipboard Generates a list of all the read only variables in the PGM (from the Watch Variable Pages). Useful for reports.
All Copy To Clipboard Generates a list of all the variables in the PGM (from the Watch Variable Pages). Useful for reports.

Watched Variables Page(s)

Tag Input / Calc Description
If PageLabel() is used in the PGM code, then each page label will be displayed in a new Tab. In SysCAD 9.3, if no PageLabel() is defined, then the default Tab will be D1;

Watched Variables

Variable

Any variables that the user specifies as 'watched' will be shown on one or more tab pages. This may include calculated variables, which may not be changed by the user, or variables that the user may change during execution of the program.


TagRefs Page

Tag Input / Calc Description
TagRefs.... This page is available in SysCAD 9.3
Tag References
ClearDuringInit Tickbox If this is selected, the Reference Unit Tags will be cleared during initialisation.
TagCount Feedback The number of tags referenced in the PGM code, e.g. P_001.Qm, P_001.To, FT_6.BPE
UnitCount Feedback The number of unit models referenced in the PGM code. For example, P_001, FT_001
Clear Clear If this is selected, the Reference Unit Tags will be cleared during initialisation.
TryFixTags Change Old Tags If the PGM code was written in an earlier build, where some of the SysCAD variable names may be different, using this button may fix the PGM code.
If the PGM code was changed, SysCAD will generate a message in the message window as well as the bottom of the PGM file. Please see SysCAD 9.3 Tag Changes for more information.
Note: This method uses a tag list based on the PGM code when loaded.
TryFixTags2 Change Old Tags If the PGM code was written in an earlier build, where some of the SysCAD variable names may be different, using this button may fix the PGM code.
If the PGM code was changed, SysCAD will generate a message in the message window as well as the bottom of the PGM file. Please see SysCAD 9.3 Tag Changes for more information.
Note: This method uses a tag list based on the PGM code when solved. Therefore, this button will be greyed out before the project has been solved at least once after load.
TagList Copy To Clipboard Generates a list of SysCAD Variable tags used in the PGM code. This includes both get tag and set tags. For example, P_001.Qm, P_001.To, FT_6.BPE
Reference Unit Tags
UnitTagxxx Feedback The unit tag name(s) referenced by the PGM code.
UnitsTagList Copy To Clipboard Generates a list of SysCAD Unit tags used in the PGM code. This includes both get tag and set tags. For example, P_001, FT_001
UnitTags Find Opens Find dialog with the list of Unit tags from UnitsTagList selected. Not shown before first solve or if no tags referenced in the model. Available in Build 137 and later.

Adding this Model to a Project

Insert into Configuration file

Sort either by DLL or Group.

 

DLL:

Control1.dll

Units/Links

Control: General

or

Group:

General

Units/Links

Control: General

See Project Configuration for more information on adding models to the configuration file.


Insert into Project

 

Insert Unit

Control

General

See Insert Unit for general information on inserting units.

Hints and Comments

  1. If the pgm file contains a tag that is invalid, SysCAD will not begin execution, but will flag that user that there is an error in the pgm. Check the Messages window for a list of the invalid tags.
  2. If the user edits the pgm file, loads it using the 'Reload' button, but does not see the expected changes, it may be that the pgm file has not been saved before reloading.
  3. If there is more than one copy of the pgm file in various folders, it is always a good idea to open the file using the 'Edit' button on the access window. This will ensure that you are editing the file that the unit is accessing.
  4. It is always a good idea to pause or stop the SysCAD execution before reloading a pgm file into the general controller. This is because if there is an error in the file, the unit will cease all control functions, which may cause problems in the project.

Please see Example PGM Files for an example of a simple PGM file.