From SysCAD Documentation

Navigation: PGMs

Contents 1 Data Types 2 Variable declaration 2.1 Introduction 2.2 Declaring variables for internal use within a PGM 2.3 Declaring variables as read only (@) 2.4 Declaring variables as input or read/write (*) 2.5 Declaring variables with conversion information 2.6 Declaring variables with ranges 2.7 Declaring variable options using { } 3 Labels 3.1 PageLabel 3.2 TextLabel 3.3 Labels Example 4 Classes: declarations and access to members 4.1 Accessing members of a class

Data Types

The variable types supported by the PGM are shown below. See also Variable declaration.

Type Name	Value Type	Range of Values
BIT	Boolean	FALSE = 0; TRUE <> 0
BYTE	Integer	0 to 255
INTEGER	Integer	-2147483648 to 2147483647
LONG	Integer	-2147483648 to 2147483647
REAL	Real	-1.0 E308 to 1.0 E308
DOUBLE	Real	-1.0 E308 to 1.0 E308
STR	String	ASCII Character Set; unlimited length
STRING	String	ASCII Character Set; unlimited length
MEMO	String	ASCII Character Set; unlimited length, scrolls onto multiple lines as required

Note: INTEGER, REAL, STRING and MEMO are only available in SysCAD 9.2 Build 132 or later.

Variable names must be alphanumeric and uniquely declared within their current scope.

The PGM language is NOT case sensitive.

When a value or variable is assigned to another variable, it is ranged within the new variable type's range, as illustrated in the examples below.

Examples

LONG  w
BIT   i
BYTE  z

z = 1035    ;z = 255         maximum value of Byte type is 255.
z = -2.3    ;z = 0           minimum value of Byte type is 0.
z = 5.6     ;z = 5           byte can only be integer, it takes the first digit
w = 1.3e12  ;w = 2147483647  maximum value of Long type
w = NAN     ;w = -2147483648 not a number, assigned with the minimum value of type
w = 335.4   ;w = 335         long type are integers only.
z = w       ;z = 255         limited by the maximum value of byte type.
i = 0.1     ;i = 1 (true)    Bit is true if i ≠ 0
i = 12      ;i = 1 (true)    Bit is true if i ≠ 0
i = -3      ;i = 1 (true)    Bit is true if i ≠ 0
i = 0.0     ;i = 0 (false)   Bit is false if i = 0

Variable declaration

Introduction

Variables must be declared as one of the permissible data types, the valid data types are: BIT, BYTE, INTEGER, LONG, REAL, DOUBLE, STR, STRING or MEMO (See 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.

Examples

DOUBLE FeedMassFlowrate, Temp, Ratio
LONG   g1, g2
STR    one, two

When declaring variables, some keywords/symbols can be assigned to the variable for added functionality; these are shown in the following example. The added symbols are explained in the subsequent headings. For example, adding a * after a variable name defines it as input field and adding a @ defines it as read only.

Bit     Init*, Start*, Stop*
Memo    State@                          ; State Message String
Double  MFWashEff*("Frac","%")<0,40>    ; Required Filter Wash efficiency.
Double  MFCakeMoist*("Frac","%")        ; Required Filter Cake Moisture Content. 
Double  FeedMassFlowrate@("Qm","t/h")   ; Filter Feed Mass flowrate
Double  CakeDensity@("Rho","kg/m^3")    ; Filter Cake density

Declaring variables for internal use within a PGM

A variable is simply declared. It is invisible to the user and inaccessible outside of the PGM.

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 Declaring variable options using { } for more information).
2. Read only variables can also be declared as one of the options in { } using r or result (refer to Declaring variable options using { } 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 Declaring variable options using { } for more information).
2. Writeable variables can also be declared as one of the options in { } using i or input (refer to Declaring variable options using { } for more information).

Examples

LONG    x
STR     y@
INTEGER z*
DOUBLE  StreamFlow, Ratio*, RqdFlow@

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

For a double or real variable conversion information may be specified in round brackets: (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 find out the list of Engineering Units that are available, in SysCAD go to file menu View|Project, this will open the Project.spj Dialog box. Select the Conversions Tab page to view the list.

The conversion family (this is predefined by SysCAD, users CANNOT create new one) is shown after the default SI unit. For example, Heat Transfer is UA and its default SI unit is kW/K. The available engineering units under the group can be used. To add/modify the engineering units available in SysCAD (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:

double  VolumeFlow("Qv","m^3/h"), FeedTemp("T", "dC")

;This is equivalent to using the CnvInfo Function after the variable has been declared normally.  See Conversion Info for more information.

;NOTE on using 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 must specify both a minimum and a maximum.

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.

Example:

double  RequiredFlow*("Qm", "kg/s")<0, 10>

The input variable RequiredFlow will be restricted to values between 0 and 10 kg/s.

Declaring variable options using { }

Additional variable declaration options are available in SysCAD 9.2 Build 132 or later. The available options are described in the table below. The options can be chosen by specifying either the option name or short name enclosed in { } after the variable is declared. Multiple options are chosen by separating them with commas within the same set of { }.

Option Name	Abbr.	Short cut	Description
input	i	*	Makes the variable an input (writeable) field. This is equivalent to declaring variables with a watch (*).
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.
cnv		()	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		<>	A range 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>. See Declaring variables with ranges for more information.
nan	n		Allows the user to enter NAN (Not A Number), shown as a "*" on the SysCAD Access window. Can only be used for Data Type 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		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 All Fields button. If this variable is not defined as a input or result, then it is assumed to be an input field.
stopped	s		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		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 Type 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			A short comment description string for the variable that is displayed to right of tag in the access window. The format is Comment(string).
help			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 will be input (writable) fields.   This is equivalent to DOUBLE a1*, b1* 
INTEGER  a2{result}, b2{r}      ; a2 and b2 will be result (read only) fields. This is equivalent to INTEGER a2@, b2@ 
DOUBLE   a3{c}, b3{r,c}         ; a3 will be a concealed input field, b3 will be a concealed result field. This is equivalent to DOUBLE a3**, b3@@.
DOUBLE   a4{n}                  ; a4 will be a input field that allows NAN(*) to be entered. An equivalent to this would be DOUBLE a4{i,n} 
INTEGER  a5{h}, b5{r,h}         ; a5 will be a hidden input field, b5 will be a hidden result field. 
STRING   a6{t}, b6{r,t}         ; a6 will be an input field, b6 will be a result field, both will have additional buttons next to them. 
DOUBLE   a7{s}                  ; a7 will be an input field which can only be set while the model is stopped. 
INTEGER  a8{i,c,s}              ; a8 will be a concealed input field which can only be set while the model is stopped. 
DOUBLE   a9{r, ("Qm", "kg/s")}         ; a9 will be a mass flow result field with units of kg/s. 
DOUBLE   a10{r, Cnv("Qm", "kg/s")}     ; a10 will be a mass flow result field with units of kg/s. 
DOUBLE   a11{*,("Qm","kg/s"),<10, 20>} ; a11 will be a mass flow input field with a range of 10-20 kg/s. 
REAL     a12{i,Range(0,10),Comment("Required ratio")}   ; a12 will be a input field with range 0 to 10 with comment "Required Ratio" appearing in access window. 

Labels

PageLabel

PageLabel(string)

This function is used to create a new access window tab page with the specified string.

For Example:

PageLabel("Water")

This will create a tab page with name "Water". (see example below)

Hint: Do not use a long name for a the Page Label, as this is displayed on the Access Tab.

TextLabel

TextLabel( string [ , string])

This function is used to create text description lines on the access window.

1. For a single comment:
   • TextLabel("Enter the feed options:")
2. For a blank line, use TextLabel().
3. To insert a text label with a blank line before the label, specify a comma before the label:
   • TextLabel(, "Water Flows In").
4. You can specify multiple lines with comma (,) separator:
   • TextLabel("Alumina", "Area 5").

Labels Example

This code will show the following Access Window view:

PageLabel("Water")
TextLabel("Water Balance")
Double   TotalIn@("Qm","t/h"), TotalOut@("Qm","t/h"),  TotalWaterError@("Qm","t/h")

TextLabel(, "Water Flows In")
Double   MineBrine@("Qm","t/h"), BrineInOre@("Qm","t/h"), GuarWater@("Qm","t/h")

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, EndClass Keywords.

An instance may be positioned anywhere in the PGM code, as long as it is declared before it is used.

A `* CANNOT be appended to the instance name. Use the Watch Keyword.

Examples

PID2   TempControl
ARRAY  Counter

TempControl and Counter are instances of their respective classes.

Accessing members of a class

The method used to access the data members and functions of a predefined instance of a class is shown below. (See Instance declaration)

Setting the value of a data member of an instance

InstanceName.dataMember = value

InstanceName 

is the name of the pre-defined instance of a class.

dataMember  

is a data member belonging to the predefined instance, InstanceName.

value  

is the value to be assigned to the data member.

Example

TempControl.spt = 50    ; Setting the set point of the temperature controller (PID2)

Retrieving the value of a data member of an instance

variable = InstanceName.dataMember

InstanceName 

is the name of the pre-defined instance.

dataMember  

is a data member belonging to the predefined instance, InstanceName.

variable  

is a pre-declared variable, its value is set to the value of the dataMember.

Example

OldSetPoint = TempControl.spt   ; Getting the set point of the temperature controller (PID2)

Retrieving the value returned by a member function of an instance

variable = InstanceName.memberFunction()

InstanceName  

is the name of the predefined instance.

memberFunction 

is a function declared within the predefined instance, InstanceName.

variable  

is a pre-declared variable, its value is returned by memberFunction.

Example

CounterValue5 = Counter.GetAt(4) ; Getting the 5th Element of the Counter Array.