View source for General Controller

[[Category:Models]] [[Category:PGM]] [[Category: Control]]
{{Navigation|[[Models]]|[[Models#Control Models|Control Models]]}}
{{Control Models Header table| currentpage=1 }}
Related Links: [[PGMs|PGM]], [[Example PGM Files]]
----
{{TOC}}
== 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 [[PGMs|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 [[PGMs|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|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:

'''[[Introductory 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 ===

[[Image: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 [[PGMs|PGM Documentation]].

== Reload File ==

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 (e.g. Notepad, Excel)
* the user starts another run
* the reload button is pressed

== PGM Execution ==

#When SysCAD starts solving, only PGM code written inside the optional [[Trigger Subroutines]] InitialisePreStart(), PreStart() and InitialiseSolution() will be executed.
#When SysCAD stops, only PGM code written inside the [[Trigger Subroutines]] TerminateSolution() will be executed.
#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.

If the user wishes to keep using the [[Predefined_Constants_and_Variables#OLD Special Constants - to be removed in future builds|OnInitialise() and OnTerminate()]] functions in SysCAD 9.3 (up to {{Removed139|||y}}), then  the '''Old135Format''' box on the first Tab of the general controller must be checked, checking this box will use the SysCAD 9.2 PGM execution logic.  
:[[image:old135format.png]]

NOTES: 
#Ticking the '''Old135Format''' affects how the PGM is executed, and prevents the use of the new [[Trigger Subroutines]].  
#Ticking the '''Old135Format''' does NOT affect other PGM functions and PGM features (implemented in SysCAD 9.3) such as [[Data Types|DropList]], [[Tag Functions|[] for GetTag]], etc. 
#The '''Old135Format''' and '''OnInitialise()''' and '''OnTerminate()''' functions will be removed in future updates.  We strongly recommend users convert any use of these to the [[Trigger Subroutines]].

== Set Tag Validation in Build139 == 

New option "BulkSetTagsValidation" has been implemented in Build 139 where setting of tags from a General Controller (defined in a PGM file) will be validated as a group.
:[[image:bulkvalidation.png]]
*This option is enabled by default.
*Data validation is required in models where the sum of all values must add up to 100, such as [[Feeder-Cross_Page_Connector#DSp_Tab_Page|DSp Tab]] in [[Feeder-Cross Page Connector|Feeder]], Size Distribution tabs in various models such a [[Feeder-Cross Page Connector|feeder]], [[Crusher2|crusher]], or [[Screen 2|screen]], and breakage function tabs in a [[Crusher2|Crusher]] model and so on.
*If this option is not enabled, then data validation will be called after each tag is set (i.e. as per behaviour in Build138 or earlier). This is equivalent to a user manually entering a single value and pressing the OK button.

== 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,

# '''[[#General Controller Page|GControl]]''' tab - Contains general information relating to the unit.
# Any watched variables will be added to "default data tabs" (e.g. D1 for data, M1 or matrix and so on) or user defined tabs (if pagelabel is used within the PGM file).
# '''[[Common Data Sections#Common Data on Info Tab Page|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.
{|   border="1" cellspacing="0" cellpadding="5"
|Width=10%|'''Tag (Long/Short)'''|| Width=10%|'''Input / Calc'''||Width=80%|'''Description'''
|-
{{Common Data on First Tab Page}}
|-
|  colspan="3" font style="background: #ebebeb"  | '''''Requirements'''''
|-
|On ||Check Box || The user may enable or disable the general controller using this box.
|-
|Old135Format ||Check Box || Older pgm using [[Predefined_Constants_and_Variables#OLD Special Constants - to be removed in future builds|OnInitialise() and OnTerminate()]] predefined constants can still be loaded by checking this box.  <br>If this box is unchecked, and the pgm file contains OnInitialise() or OnTerminate(), then the PGM will failed to load.  
*We recommend changing the use of OnInitialise() or OnTerminate() to [[Trigger Subroutines]] as this feature will be removed in future updates. 
*'''NOTE:''': Please see [[General_Controller#PGM_Execution_SysCAD_9.2_vs_SysCAD_9.3|PGM Execution]] for more information..
|-
|BulkSetTagsValidation / BulkValidation || Tickbox || {{Available139}}  This option is on by default.  Performs Set Tag validation as groups (model based). See [[General_Controller#Set_Tag_Validation_in_Build139|Set Tag Validation]]
|-
|  valign="top"  |FileName ||  valign="top"  |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 ||  font style="background: #ebebeb"  |Feed Back || The full path/folder of the pgm file is displayed here.
|-
|rowspan="4" valign="top"| FileState ||font style="background: #ebebeb" valign="top"| OK || File is found and has no errors.
|-
|font style="background: #ebebeb" valign="top"| Not Specified || The user has not specified a file.
|-
|font style="background: #ebebeb" valign="top"| Not Found || The specified file can not be found.
|-
|font style="background: #ebebeb" valign="top"| Load Error || There is an error in the file.  The State and Message (MSG) fields will provide further information.
|-
|  valign="top"  |State ||   font style="background: #ebebeb" valign="top"  |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.
|-
|  colspan="3" font style="background: #ebebeb"  |'''''Errors:'''''
|-
| MSG_1 to MSG_4 ||   font style="background: #ebebeb"  |Output ||These message lines are used to report PGM compile errors or errors while the PGM code is executing.
|-
| colspan="3" font style="background: #ebebeb"   | &nbsp;
|-
|Edit ||   font style="background: #ebebeb"  |Edit PGM || This allows the user to edit the specified PGM file, normally using the Notepad text editor.
|-
|Reload||  font style="background: #ebebeb"   |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||   font style="background: #ebebeb"  |Browse PGM ||This is used to locate a PGM file.
|-
|RuntimeDebug || font style="background: #ebebeb"  |Enable Debug / Disable Debug || {{Available139|32530}} This feature toggles the PGM Runtime Debug mode on or off for the General controller. <br>To locate where runtime errors (like divide by zero) occur in the code, click the ‘Enable Debug’ button. This action will reload the PGM, examine the code for potential division by zero errors, and store line numbers that could potentially cause such an error. This information is then used to report any runtime errors in the message window. <br>Please note that at the next project load, any models in RuntimeDebug mode will revert to normal operation.
|-
|Concealed ||   font style="background: #ebebeb"  |Show Concealed / Hide Concealed||This toggles the show/hide concealed variables in the PGM file.
|-
| ResetConcealed||  font style="background: #ebebeb"  |Reset Concealed||This resets the concealed tag status, use this button when concealed tag status has been modified in the PGM file.  
|-
|ZeroAllVars||  font style="background: #ebebeb"  |Zero All Variables||Resets ALL variables to zero value and strings to empty.
|-
|ZeroVars||   font style="background: #ebebeb"  |Zero Variables||Resets all result and internal variables to zero value and strings to empty. User input fields are left unchanged.
|-
|InitVars||   font style="background: #ebebeb"  |Init Variables||{{Available139|33127}} Reset all variables to the user defined initial values. That is variables that have been declared with an Init value in the PGM code. A count of the number of controller variable tags with Init values is shown in comment on RHS of the button.
|-
| colspan="3" font style="background: #ebebeb"   | &nbsp;
|-
|EditMainPGM||   font style="background: #ebebeb"  |Button||This is used to edit the main PGM file.  The PGM file name will be displayed on the button.
|-
| Edit include x||   font style="background: #ebebeb"  |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.
|-
|  colspan="3" font style="background: #ebebeb"  |'''TagList...'''
|-
| Inputs || Copy To Clipboard || Generates a list of all the writeable variables in the PGM (from the Watch Variable Pages).  A context menu of options is given to allow selection of different groups of tags with or without conversions.  Useful for reports.
|-
| Results|| Copy To Clipboard || Generates a list of all the read only variables in the PGM (from the Watch Variable Pages).  A context menu of options is given to allow selection of different groups of tags with or without conversions.  Useful for reports.
|-
| All || Copy To Clipboard || Generates a list of all the variables in the PGM (from the Watch Variable Pages).  A context menu of options is given to allow selection of different groups of tags with or without conversions.  Useful for reports.
|-
|  colspan="3" font style="background: #ebebeb"  |'''Global Settings'''
|-
| ExecuteTimeout || Input || This is the maximum time SysCAD will spend evaluating/executing the PGM code for one step. It is designed to prevent logic that causes an endless loop from freezing SysCAD. If a timeout error occurs, you should review the PGM logic.  This a global option which applies to all general controllers. Also available in [[Plant Model - FlwSolve]] Tab.
|-
| StopForPGMFileError || Tick Box|| {{Available139|31388}} Prevents project from running if there is a PGM file missing or fails to load. This a global option which applies to all general controllers. Also available in [[Solver Setting - FS Solver|Solver Settings]]. Will not be applied if General Controller is not ''On''.
|-
|Track.DivideZeroByZero / Track.DivZeroByZero || Tick Box || {{Available139|32139}}  This is used for tracking the special case of zero divide by zero (0/0). If this box is not ticked, then runtime warnings are not reported while running PGM code, the result is 0 (as before). <br>This tick box does not apply to the normal division by zero cases, the "some value/0" cases will always return a runtime warning.
|}

=== Watched Variables Page(s) ===
{|   border="1" cellspacing="0" cellpadding="5"
|Width=10%|'''Tag '''|| Width=10%|'''Input / Calc'''||Width=80%|'''Description'''
|-
|  colspan="3" font style="background: #ebebeb"  | 
*If PageLabel() is used in the PGM code, then each page label will be displayed in a new Tab.  
*If no PageLabel() is defined, then the default Tab will be '''D1''';
*If the PGM file uses of user defined [[Class#Syntax|Classes]] with the '''ClassAsPageLabel()''' defined, then each class instance declared will be displayed on a new tab page.
|-
|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 ===

{|   border="1" cellspacing="0" cellpadding="5"
|Width=10%|'''Tag '''|| Width=10%|'''Input / Calc'''||Width=80%|'''Description'''
|-
|  colspan="3" font style="background: #ebebeb"  | TagRefs....
|-
|  colspan="3" font style="background: #ebebeb"  | ''Tag References''
|-
|ClearDuringInit || Tickbox || If this is selected, the Reference Unit Tags will be cleared during initialisation.
|-
|TagCount|| font style="background: #ebebeb"  |Feedback|| The number of tags referenced in the PGM code. 
|-
|UnitCount|| font style="background: #ebebeb"  |Feedback || The number of unit models referenced in the PGM code.  
|-
|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.<br>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.<br>'''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.<br>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.<br>'''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.   
<syntaxhighlight>
Plant_Feed.QmReqd
P815_.Qo.Qm
P814_.Qo.Qm
P800.Qo.Qm
P1050.Qo.Qm
H2SO4_Source.Total.Qm
Air_Source.Total.Qm
P101.Qo.QEl.Ni
P408.Qo.QEl.Ni
P101.Qo.QEl.Cu
P304.Qo.QEl.Cu
P612.Qo.QEl.Cu
</syntaxhighlight>
|-
|  colspan="3" font style="background: #ebebeb"  | Reference Unit Tags
|-
|UnitTagxxx || font style="background: #ebebeb"  |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: 
<syntaxhighlight>
Plant_Feed
P815_
P814_
P800
P1050
H2SO4_Source
Air_Source
P101
P408
P304
P612
</syntaxhighlight>
|-
|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. 
|-
|}

== Adding this Model to a Project ==

{{Adding Model to a Project | DllName=Control1 | DllSubGroup=Control | UnitOp=General | Group=General}}

== Hints and Comments ==

# 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.
# 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.
# 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.
# 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 some sample PGM files.