Tag Functions

From SysCAD Documentation
Jump to navigation Jump to search

Navigation: PGMs

PGM Main Page Defining a Class Defining a Function Tag Functions Mathematical Functions Defining a Subroutine
Example PGM Files Predefined Classes Predefined Functions Tag Functions (9.3) String Functions Trigger Subroutines

Introduction

The following functions for accessing flowsheet tags are supported by the PGM Language.

The difference between (GetTag and SetTag) and (GetDynTag and SetDynTag) is subtle. It is NOT related to dynamic solver mode, but has to do with how SysCAD uses and checks the tags when used by these functions within the pgm code.

  • GetTag and SetTag: At PGM load time SysCAD builds up a list of all tags referenced in GetTag and SetTag calls, but ignores tags in GetDynTag and SetDynTag. Then when you press solve, SysCAD checks this list of tags to see if they exist and can be set/read. SysCAD solver expects that these are ALWAYS accessible, regardless of whether they are actually accessed within PGM execution during an iteration. This implementation is for efficiency of retrieving and setting the tags, and tracking tag dependencies/references between models. For example all the "get" tags are retrieved before execution of the PGM each iteration. For GetTag and SetTag you have to explicitly reference the full tag, for example GetTag("P_001.Qm (t/h)"), and you cannot use String variables, for example GetTag(s) is illegal.
  • GetDynTag and SetDynTag: These functions have a number of differences and uses:
    1. The tag can be "dynamically" built or referenced when required. This can also be a string based on logic using strcat that you want to set/get. For example GetDynTag(s) or GetDynTag(strcat(PipeTag, ".Qm (t/h)")).
    2. For SetDynTag() and GetDynTag() the checking of the tag validity is done at runtime when the command is actually called. Therefore these are ideal for when a tag may not always be writeable or exist (for example, within if blocks and in OnInitialise section).
    3. In the OnInitialise section of a PGM (ie when the PGM is called at startup before the first iteration) GetDynTag and SetDynTag are commonly used, especially to set tags once off, such us switching models on/off (or setting any tags that can't be set while solving).

Alternative Syntax available in SysCAD 9.3

In SysCAD 9.3 the user may use the alternative syntax to replace GetTag and SetTag functions. Please see 9.3 Tag Functions for a description of the syntax.


GetTag Functions

GetTag()

Syntax:
variable = GetTag("full tag")

full tag: refer to Tags for the correct tag syntax. The tag must be in quotes. It may optionally include the conversions units.

variable: this should be of the same data type as the value that is to be returned. Data Type Str is NOT allowed with this function.

The GetTag function returns the value of the parameter in numerical type, referred to by the full tag. If the parameter SysCAD returns is in the type of a text string, then user will get an error saying type mismatch, in that case, user must use the GetDynStrTag function to get the text string.

full tag cannot be replaced by a Str variable, GetDynTag must be used to do that.

GetDynTag()

Syntax:
variable = GetDynTag(string)
or variable = GetDynTag("full tag")

string: is a variable of type STR that refers to a tag. A conversion may also be specified within the string. See Tags for the correct tag syntax.

variable: This should be of the same data type as the value that is to be returned. Data Type Str is NOT allowed with this function.


The GetDynTag function returns the value of the parameter in numerical type, referred to by the tag contained in string. If the parameter SysCAD returns is in the type of a text string, then the user will get an error saying type mismatch, in that case, user must use the GetDynTag function to get the text string.

NOTE: GetDynTag and SetDynTag commands have three main uses:
  1. use in OnInitialise and OnTerminate section
 (eg SetDynTag("TK1SF.Cfg.[0].On", 1))
  
  2. use where the tagname you what to set/get is a variable of str type (ie tag is constructed programmatically) 
 (eg GetDynTag(TagName))
  
  3. refer to a tag that may not always exist, especially for the first iteration 
 (eg GetDynTag("P_007.Qo.Sz.d50.All (um)"))

GetDynStrTag()

Syntax:
variable = GetDynStrTag(string)

string: is a variable of type STR that refers to a tag. A conversion may also be specified within the string. See Tags for the correct tag syntax.

variable: This should be a Str variable type

The GetDynStrTag function returns the Tag name of the parameter, referred to by the tag contained in string.

Example 1:

Real      Flow_Split
Real      Pressure_1@("P", "kPag")
String    MyTag, Condition@

Flow_Split = GetTag("X_001.GM.IOs.[P_001].Split (%)")
Pressure_1 = GetTag("XPG_001.P_Rqd (kPag)")

MyTag      = "X_001.GM.IOs.[P_001].Split (%)"
Flow_Split = GetDynTag(MyTag)                      ;Use GetDynTag instead of GetTag when the tag name is a string variable
Condition  = GetDynStrTag("PlantModel.StateDesc" )  ;Use GetDynStrTag when the tag being fetched is a string variable
$

Example 2:

GetDynStrTag is useful for users wanting to dynamically build up some control logic either in PGM or through Excel.  
For instance, a tank may have many inputs and outputs, users can use this function to get the input stream name for IO point 1.  
This can be done as follows:

String    InputStream01
InputStream01 = GetDynStrTag("TNK_001.Links.[0].DstTag")

When SysCAD is solved, InputStream01 will return the Tag name of the pipe that is connected to IO point input 1.


SetTag Functions

SetTag()

Syntax:
SetTag("full tag", value)

full tag : refer to Tags for the correct tag syntax. The tag must be in quotes. It may optionally include the conversion units.

value : this may be either be a single value or an expression which resolves into a single value, the value must be numeric. If the parameter SysCAD expects is in the type of a text string, then the user will get an error saying type mismatch, in that case, user must use the SetDynStrTag function to set the text string.

The SetTag function assigns the value to the parameter, referred to by the full tag.

tag cannot be replaced by a STR variable, SetDynTag must be used to do that.

SetDynTag()

Syntax:
SetDynTag(string, value)
or SetDynTag("full tag", value)

string: is a variable of type STR that refers to a tag. A conversion may also be specified within the string. See Tags for the correct tag syntax.

value: this may be either be a single value or an expression which resolves into a single value, the value must be numeric. If the parameter SysCAD expects is in the type of a text string, then the user will get an error saying type mismatch, in that case, user must use the SetDynStrTag function to set the text string.

The SetDynTag function assigns the value to the parameter, referred to by the tag contained in string.


NOTE: GetDynTag and SetDynTag commands have three main uses:
  1. use in OnInitialise and OnTerminate section
 (eg SetDynTag("TK1SF.Cfg.[0].On", 1))
  
  2. use where the tagname you what to set/get is a variable of str type (ie tag is constructed programmatically) 
 (eg GetDynTag(TagName))
  
  3. refer to a tag that may not always exist, especially for the first iteration 
 (eg GetDynTag("P_007.Qo.Sz.d50.All (um)"))

SetDynStrTag()

Syntax:
SetDynStrTag(String, String2)

string1: is a variable of type STR that refers to a tag. A conversion may also be specified within the string. See Tags for the correct tag syntax.

string2: is the string you wish to set.

The SetDynStrTag function assigns a String to the parameter, referred to by the tag contained in string1.

Example 1:

String MyTag, CtrlOutputTag
 
SetTag("X_001.GM.IOs.[P_001].Split (%)", 10)
SetTag("XPG_001.P_Rqd (kPag)", 500)

;Use SetDynStrTag when the tag being set is a string variable
CtrlOutputTag = "FUEL.Qm_Rqd (t/h)" 
SetDynStrTag("FUEL_ADDITION_PID.Cfg.[0].Output_Tag", CtrlOutputTag)
  
;Use SetDynTag instead of SetTag when a variable is used to refer to the tag name
MyTag = "X_001.GM.IOs.[P_001].Split (%)"
SetDynTag(MyTag, 10)     


Example 2:

SetDynStrTag is useful for users wanting to dynamically build up some control logic either in PGM or through Excel.  
For instance, the user may want to dynamically change the controller output tag based on some predefined conditions.
This can be done as follows:

String  SelectControllerOutput*
Integer TestCond*

If Oninitialise
  If TestCond == 1
    SelectControllerOutput = "MudLiqByPass.GM.IOs.[P_094].Splt.Liquids (%)"
  Else 
    SelectControllerOutput = "TNK_002.GM.Recovery.Composition (%)"
  Endif
  SetDynStrTag("PID_002.Cfg.[0].Output_Tag", SelectControllerOutput)
Endif


DynTagExists

Syntax:

variable = DynTagExists(string)

string: is a variable of type STR that refers to a tag, but may also be an actual tag, in which case it must be in quotes.

variable: The data type is 'bit', as only a True, 1, or False, 0, value is returned.