Declaring Variables

From SysCAD Documentation
Jump to: navigation, search

Navigation: PGMs

PGM Syntax Data Types Declaring Variables Predefined Variables Labels

Introduction

  • Variables must be declared as one of the permissible Data Types.
  • A variable may be positioned anywhere in the PGM code, as long as it is declared before it is used.
  • Any number of variables of the same data type may be declared together by separating each one with a comma, e.g. real SolidsFlow, LiquidsFlow, MetalRecovery
  • When declaring variables, some optional keywords/symbols can be assigned to the variable for added functionality. Some of the common keywords are summarised in the table below, Common Options for Variable declaration. A list of all options is given at: All Options when Declaring variables.
  • Users may also conceal variables based on a based on a test. Please see Conceal Variables.

Available Options when Declaring Variables

When declaring variables described in the table below:

  • The options can be chosen by specifying either the Short cut or short name enclosed in { } after the variable is declared.
  • Multiple options are chosen by separating them with commas within the same set of { }.

Summary Table of Common Options for Variable declaration

Keyword/Special Symbol Description Example
, Comma - Used to separate variables defined in the same line. Bit Init, Start, Stop
* Appending * allows the variable to be viewed and set in the access window (white box). Checkbox Init*
@ Appending @ allows the variable to be viewed only in the access window (grey box). Real Recovery@
("Family", "Units") Adds Engineering Units for the variable.
Do be aware that conversion units ARE case sensitive.
See heading Declaring variables with conversion information
Real MassFlow*("Qm","t/h")
Real VolumeFlow*("Qv","m^3/h")
Real StreamDensity@("Rho","kg/m^3")
Real Concentration@("Conc","g/L")
<min, max> Assign valid Range to an input variable.
See Declaring variables with ranges
Long Option*<1,10> ;Valid between 1 and 10
Real FlowSplit*<, 100> ; Maximum is 100, no minimum
Real FeedRate*<20,> ; Minimum is 20, no maximum
{Comment(" xxxxx ")} Adds a short Comment to the variable
See Advanced Options when Declaring variables
Real Ratio{r, Comment("gAcid/tProduct")}

Examples

Long      Options*, Conditions*
String    Message1*, SolutionCondition*
Checkbox  UsePredefinedValues*
Memo      WasherState@                                 ; WasherState Message String
Real      MFWashEff*("Frac","%")<0,100><<75>>          ; Required Filter Wash efficiency.
Real      Energy*("E","kJ")         
Real      Power*("Pwr","kW")           
Real      Pressure*("P","bar")          
Real      Temperature*("T","C")        
Real      Time*("Time","h")               
Real      FeedSolids{i,("Frac", "%"),Range(0,100),Comment("Wt%")}

Summary Table of All Available Options when Declaring Variables

Option Name Abbr. Short cut Description
input i * Makes the variable an input (writeable) field. This is equivalent to Declaring variables as input or read/write (*).
result r @ Makes the variable a result (read only) field. This is equivalent to declaring variables as read only (@).
concealed c ** or @@ Conceals the variable from the access window. The variable can only be seen in the access window if the ShowConcealed button is pressed. Otherwise it still acts as a input or result field, ie. it can be written to if it is an input field and it can be referenced externally. If this variable is not defined as a input or result, then it is assumed to be an input field. See Declaring concealed variables for more information.
cnv n/a () The conversion units for the variable can be defined. The format is Cnv(Conversion Family, Engineering Units). The same format as described above can also be used ie. (Conversion Family, Engineering Units). See Declaring variables with conversion information for more information.
range n/a <> A range, minimum or maximum can be set for the variable. The format is Range(minimum, maximum). The same format as described above can also be used ie. <minimum, maximum>. To specify minimum only <minimum,>. See Declaring variables with ranges for more information.
nan n n/a Allows the user to enter NAN (Not A Number), shown as a "*" on the SysCAD Access window. Can only be used for Summary Table of Data Types DOUBLE or REAL. If this variable is not defined as a input or result, then it is assumed to be an input field.
hidden h n/a Makes the variable normally hidden in the access window. Otherwise it still acts as a input or result field, ie. it can be written to if it is an input field and it can be referenced externally.
This field can be seen by pressing the More button. (Or, in SysCAD 9.2, the All Fields button).
If this variable is not defined as a input or result, then it is assumed to be an input field.
Note: If a variable was originally declared as hidden but the user no longer wishes it to be hidden, then the user needs to choose the Reset formatting, conversions and visibility option for SysCAD to clear this as a hidden field (as well as amending the variable declaration in the PGM file).
stopped s n/a The variable can only be set when the SysCAD model is stopped. If this variable is not defined as a input or result, then it is assumed to be an input field.
tag t n/a Adds the Find Unit and Find and Access buttons next to the variable in the access window. If the string is (or contains) a valid SysCAD tag then these buttons can be used to find the unit and its access window. Can only be used for Data Types STR, STRING or MEMO. If this variable is not defined as a input or result, then it is assumed to be an input field.
comment n/a n/a A short comment description string for the variable that is displayed to right of tag in the access window. The format is Comment(string).
excludesave e n/a The variable (or class) state is not saved with the project.
init(value) n/a <<value>> Assign an initial value to an input variable. See Declaring variables with an Initial Value
help n/a n/a A description string for the variable that is displayed as a help string at the top of the access window when the field is selected. The format is Help(string).

Note: The order the options are specified is not important. For example, a{i,c} is the same as a{c,i}.

Examples

DOUBLE   a1{input}, b1{i}       ; a1 and b1 are input fields - equivalent to DOUBLE a1*, b1* 
INTEGER  a2{result}, b2{r}      ; a2 and b2 are result fields - equivalent to INTEGER a2@, b2@ 
DOUBLE   a3{c}, b3{r,c}         ; a3 is a concealed input field, b3 is a concealed result field. Equivalent to DOUBLE a3**, b3@@.
DOUBLE   a4{n}                  ; a4 is an input field that allows NAN(*) to be entered. Equivalent to DOUBLE a4{i,n} 
INTEGER  a5{h}, b5{r,h}         ; a5 is a hidden input field, b5 is a hidden result field. 
STRING   a6{t}, b6{r,t}         ; a6 is an input field, b6 is a result field, both will have additional buttons next to them. 
DOUBLE   a7{s}                  ; a7 is an input field which can only be set while the model is stopped. 
INTEGER  a8{i,c,s}              ; a8 is a concealed input field which can only be set while the model is stopped. 
DOUBLE   a9{r, ("Qm", "kg/s")}         ; a9 is a result field with mass flow units. 
DOUBLE   a10{r, Cnv("Qm", "kg/s")}     ; a10 is a result field with mass flow units. 
DOUBLE   a11{*,("Qm","kg/s"),<10, 20>} ; a11 is a mass flow input field with a range of 10-20 kg/s. 
REAL     a12{i,Range(0,10),Comment("Required ratio")}   ; a12 is an input field with range 0 to 10 and "Required Ratio" next to the field. 
DOUBLE   a13{*,("Qm","kg/s"),<10,>} ; a13 is a mass flow input field with a MINIMUM value of 10 kg/s. 
DOUBLE   a14{*,("Qm","kg/s"),<,50>} ; a14 is a mass flow input field with a MAXIMUM value of 50 kg/s. 

The Access window will look as follows:

PGM Display 4.2.png

Declaring variables for internal use within a PGM

A variable is simply declared and is used within the pgm code. If no options are used, then it is not visible in the controller's access window and hence it is inaccessible outside of the PGM.

Examples

real Subtotal, Solidsflow, ReqdLiquid
integer i, count, NumberOfTanks

Declaring variables as read only (@)

Appending a @ to the end of the variable name is the shortcut to make the variable visible as a read only tag. It appears in the access window as a result with a grey background. The user will not be able to change its value externally.

Notes:

  1. Appending @@ to the end of the variable name makes it a read only concealed variable (refer to Available Options when Declaring Variables for more information).
  2. Read only variables can also be declared as one of the options in { } using r or result (refer to Available Options when Declaring Variables for more information).

Declaring variables as input or read/write (*)

Appending a * to the end of the variable name is the shortcut to make the variable visible as a writable tag. It appears in the access window as an input with a white background. The user will be able to change its value.

Notes:

  1. Appending ** to the end of the variable name makes it a writeable concealed variable (refer to Available Options when Declaring Variables for more information).
  2. Writeable variables can also be declared as one of the options in { } using i or input (refer to Available Options when Declaring Variables for more information).
  3. The user may also display the variable in the Access window as a read/write variable by using the Watch functionality.

Examples

INTEGER    x
STRING     y@
INTEGER    z*
REAL       StreamFlow, Ratio*, RqdFlow@

The access window of the controller looks as follows: PGM Display variables 1.png

  • Variables x and StreamFlow are internal. (not visible on access window or accessible as tags)
  • Variables y and RqdFlow are read only. (Visible result fields accessible as tags)
  • Variables z and Ratio are writeable. (Visible input fields accessible as tags)

Declaring variables with conversion information

Conversion information may be specified when declaring a real (or double) variable.

  1. The form is: real ABC(Conversion Family, Engineering Units).
  2. The variable will ALWAYS be in the engineering units defined when used in code in the pgm file.
    • It is VERY important when using the variable and using GetTag or SetTag to match the engineering units.
    • For example, if the variable is mass flow and is defined with ("Qm", "kg/h"), then it will always be used as kg/h. So if you use a GetTag with t/h this will cause conversion problems.
  3. The Conversion Family specified is used for display purposes in the access window.
    • Based on the Conversion Family, the user can change the display units reported in the access window as for any model in SysCAD.
    • Please note that changing this in the Access window does not change the engineering units or value as used in the underlying pgm code.

When specifying (Conversion Family, Engineering Units), a valid predefined SysCAD conversion family and unit must be specified in the brackets separated by a comma. The conversion family and conversion units ARE case sensitive. See Conversion List Table for a list of available conversion families.

To view the available list of Engineering Units while in SysCAD, go to menu Edit|Conversions|Defaults and Displays.., this will display the following Window:

Conversions DisplayandDefaults.png

The list shows the default units and conversion family for each conversion group. The available engineering units for the selected group are shown on the right hand panel. To add/modify the engineering units (excluding SI units), please refer to Conversions Table for instructions.

Some common conversion families are shown below:

Conversion Type SysCAD Conversion Family Some Common Units Example
Concentration Conc g/L, mg/L, kg/m^3 ("Conc","g/L")
Density Rho kg/m^3, t/m^3, g/L ("Rho","kg/m^3")
Energy E J, kJ, cal ("E","kJ")
Fraction Frac  %, ppm ("Frac","%")
Mass Flow Qm t/h, kg/h, t/d, kh/min ("Qm","t/h")
Power Pwr kW, kJ/s, MJ/h ("Pwr","kW")
Pressure P bar, atm, kPa, kPag, psi ("P","bar")
Temperature T C, K, F ("T","C")
Time Time s, min, h, d, week, year ("Time","h")
Volumetric Flow Qv m^3/h, L/h, L/min ("Qv","m^3/h")

Examples:

Real  FeedTempReqd*("T", "C"), VolumeFlow@("Qv","m^3/h")

Will be visible in the controller Access window as shown here: PGM Display variables 2.png

NOTE:

  1. When the defined variable in PGM file, care must be taken when using GetTag or SetTag to use the same units:
    • VolumeFlow = GetTag("P_001.Qv (m^3/h)") Correct
    • VolumeFlow = GetTag("P_001.Qv (m^3/s)") Incorrect - VolumeFlow wrong by factor of 3600!

Declaring variables with ranges

If the Data Type is DOUBLE, REAL, INTEGER, LONG or BYTE, the expected range of the variable may be declared using angled brackets: <minimum, maximum>. The user may specify either a minimum or a maximum or both.

If the variable is an input (writeable) field, then this range is immediately applied, preventing values outside the defined range from being used.

For both input and result fields, the range will be used in Trend windows to define the default range used.

If the variable is a result (read only) field, then this range is ONLY used for the default range in a Trend window. It does NOT prevent the variable from going outside of the defined range.

Examples:

;The input variable RequiredFlow will be restricted to values BETWEEN 1 and 10 kg/h.
Real  RequiredFlow*("Qm", "kg/h")<1, 10>

;The input variable RequiredFlow will be restricted to values ABOVE 1 kg/h.  There is no user defined maximum restriction.
Real  RequiredFlow*("Qm", "kg/h")<1,>

;The input variable RequiredFlow will be restricted to values BELOW 10 kg/h.  There is no user defined minimum restriction. 
Real  RequiredFlow*("Qm", "kg/h")<,10>

Note:

  1. The ability to specify ONLY a minimum or maximum is only available in SysCAD 9.2 build 134 and later.

Declaring Concealed Variables

Any variable may be concealed, or hidden, from the access window. The variable can only be seen in the access window if the Show Concealed button is pressed. It still acts as a input or result field, so it can be written to if it is an input field and it can be referenced externally. If this variable is not defined as a input or result, then it is assumed to be an input field.

real FlowInput**("Qm", "t/h")
integer WashersOnline@@
real EquationConst{c, Comment("Set by PID")}

These variables will not normally be visible in the Access window, but there will be a comment next to the 'Show Concealed' button:

Show Concealed 1.png

If the user clicks on the Show Concealed button, the variables will be displayed in the Access window as follows:

Show Concealed 22.png

Notes:

  1. The user may also conceal or show a variable using the SetConcealedState functionality. This allows the user to show or hide a variable depending on a bit value that may be True or False. See the example below:
bit UseVolumeFlow*
real MassFlowInput*("Qm", "t/h")
SetConcealedState(MassFlowInput, UseVolumeFlow) 
; If the user sets 'UseVolumeFlow' = 1, or True, then 'MassFlowInput' will be hidden,
; otherwise if 'UseVolumeFlow' = 0, or False, then 'MassFlowInput' will be visible in the Access window.

Declaring variables with an Initial Value

NEW in SysCAD 9.3, if the Data Type is DOUBLE, REAL, INTEGER, LONG, BYTE or STRING an initial value may be assigned to the variable using double angled brackets: <<value>> or {init(value)}. The initial value is assigned at the time the variable is first created during the pgm load, so this is a ONCE-OFF initialisation value. The main use of initial values is for variables within classes.

Example:

REAL   Ratio{i,Range(1,10),init(5),Comment("Required ratio")} ;The valid range is 1 to 10, with the initial value set to 5.
REAL   FeedT*("T", "C")<<30>>                ;The initial feed temperature is set to 30 dC - if the initial value was not defined,
                                             ; the initial feed temperature would have been 0 dC)
REAL   TargetT*("T", "C")<<80>><40,120>      ;The initial target temperature is 80 dC, the valid temperature range is 40 to 120 dC
STRING WasherState@<<"Unknown">>             ;The initial washer status is "unknown" 

This will be displayed in the Access window when the pgm is first loaded: PGM Display variables 3.png

NOTES:

  1. The initial value is only set once when the pgm is first loaded and will not be used again - it is NOT set at every initialisation step.
  2. If the user changes the variable value, then the controller will always use the user specified value, it will not revert to the Initial value specified in the code.
  3. If the user changes the Initial value in the code it will not be used when reloading the code (the controller is remembering the state of all variables).
  4. If the user does NOT use the Initial value function when declaring a new variable, the initial value is:

Declaring a Class and access to class members

Please see Classes: declarations and access to members for more information.