Tag Functions

Navigation: PGMs ➔ Functions ➔ Tag Functions

Functions					Subroutines		Classes
Defining a Function	Predefined Functions	Tag Functions	Mathematical Functions	String Functions	Defining a Subroutine	Trigger Subroutines	Defining a Class

---

GetTag Functions

Function	Function Syntax	Data Type	Description / Examples / Notes
Getting Tag or Value from SysCAD Recommended Syntax	variable = ["full tag"] variable = [str "full tag"] variable = [string]	variable: this should be of the same data type as the value that is to be returned. Both numerical and string data types are allowed with this function. full tag: refer to Tags for the correct tag syntax. The tag must be in quotes. It may optionally include the conversions units. 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.	This syntax is used for fetching both numerical and string type tags. Use Copy Tag for PGM to Copy the Tags. This replaces the old syntax: GetTag, GetDynTag and GetDynStrTag listed below. See Example 1
Getting Value from SysCAD Alternative Syntax	variable = GetTag("full tag") variable = GetTag(string)	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. full tag: refer to Tags for the correct tag syntax. The tag must be in quotes. It may optionally include the conversions units. 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.	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 user must use the GetDynStrTag function to get the text string. These functions can be replaced with the simplified syntax of [" "].
	variable = GetDynTag("full tag") variable = GetDynTag(string)
Getting Tag from SysCAD Alternative Syntax	variable = GetDynStrTag(string)	variable: This should be a STR variable type 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.	returns the Tag name of the parameter, referred to by the tag contained in string. See Example 2

SetTag Functions

Function	Function Syntax	Data Type	Description / Examples / Notes
Setting Tag or Value to SysCAD Recommended Syntax	["full tag"] = variable	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. Both numerical and string data types are allowed with this function.	Setting a numerical tag. ["X_001.GM.IOs.[P_001].Split (%)"] = 10 ["XPG_001.P_Reqd (kPag)"] = HP_Steam_P
	[StringVariable] = variable		Setting a numerical tag using a String variable containing a tag. MyTag = "X_001.GM.IOs.[P_001].Split (%)" [MyTag] = 10
	[str "full tag"] = StringVariable		Setting a string tag, user MUST include a 'str' or 'string' before the tag. CtrlOutputTag = "FUEL.QmReqd (t/h)" [str "FUEL_ADDITION_PID.Cfg.[0].Output_Tag"] = CtrlOutputTag
Setting Value from SysCAD Alternative 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 conversions units. value : this may be either be a single value or an expression which resolves into a single value, the value must be numeric.	The function assigns the value to the parameter, referred to by the full tag. User must use the SetDynStrTag function to set the text string. This function can be replaced with the simplified syntax of [" "] = variable. See Example 3
	SetDynTag(string, value) SetDynTag("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.	The function assigns the value to the parameter, referred to by the full tag. User must use the SetDynStrTag function to set the text string. These functions can be replaced with the simplified syntax of [" "] = variable. See Example 3
	SetDynStrTag(String1, String2)	string1: is a variable of type STR that refers to a tag. A conversion may also be specified within the string1. 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. this function can be replaced with the simplified syntax of [Str String1] = String2. See Example 4

DynTagExists

Function	Function Syntax	Data Type	Description
Dynamic Tag Exists	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', True/False.	Returns 1 if tag exists Returns 0 if tag is not found.

Examples

Example 1

Real      Flow_Split
Real      Pressure_1@("P", "kPag")
Real      Pressure_2@("P", "kPag")
String    MyTag, UnitTag{Tag}, Condition@

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

MyTag      = "X_001.GM.IOs.[P_001].Split (%)"
Flow_Split = [MyTag]
UnitTag    = "X_001"
Pressure_2 = [Concatenate(UnitTag, ".OperatingP.Result (kPag)")]
Condition  = ["PlantModel.StateDesc"]       ;Use the same syntax when the tag being fetched is a string variable
$

Example 2

[string] or 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")
 InputStream01 = ["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.

Example 3

String MyTag, CtrlOutputTag
Real   HP_Steam_P
  
["X_001.GM.IOs.[P_001].Split (%)"] = 10
["XPG_001.P_Reqd (kPag)"] = HP_Steam_P
 
CtrlOutputTag = "FUEL.QmReqd (t/h)" 
[str "FUEL_ADDITION_PID.Cfg.[0].Output_Tag"] = CtrlOutputTag
 
MyTag = "X_001.GM.IOs.[P_001].Split (%)"
[MyTag] = 10

Example 4

Setting Dynamic String Tag 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*

Sub InitialiseSolution()
  If TestCond == 1
    SelectControllerOutput = "MudLiqByPass.GM.IOs.[P_094].Splt.Liquids (%)"
  Else 
    SelectControllerOutput = "TNK_002.GM.Recovery.Composition (%)"
  Endif
  [Str "PID_002.Cfg.[1].Output_Tag"] = SelectControllerOutput
EndSub

Notes

• A conversion is NOT checked to see if it exists or is valid when the PGM code is loaded and compiled, but is checked when the PGM code is executed for the first time. If no conversion is assigned or the specified conversion unit is invalid, the SysCAD SI unit will be used.
• 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.

1. GetTag and SetTag (and ["FullTag"]): 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.
2. GetDynTag and SetDynTag: These functions have a number of differences and uses:
   • 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)")).
   • 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 Trigger Subroutines sections).
   • In the Trigger Subroutines sections of a PGM (i.e. 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).