UDT Parameters

Parameters effectively act as variables that can be referenced by properties on members. A common use case for a parameters in UDTs is to make the OPC Item Path on OPC Tag members dynamic, allowing you to replace parts of the OPC Item Path with the parameter's value. However, parameter values can be referenced by other member properties, such as expressions on Expression Tags.

UDT Parameters are configured on UDT Definitions. Instances of a UDT can override the value of a parameter, much like any other property on an Instance.

Pre-Defined Parameters

UDTs have a few parameters already defined to make things easier for you. They give you access to the name and various paths associated with a UDT member Tag. These parameters can be accessed from anywhere in a Tag that a normal parameter can be used. Each of these parameters uses that Tag it is in as a starting point for its path.

Parameter Name	Description
{InstanceName}	The name of the UDT Instance that this Tag is inside. In cases where UDTs are nested, this parameter will return the name of the UDT the member belongs to. Thus referencing this parameter in a nested UDT will return the name of the nested UDT.
{ParentInstanceName}	New in 8.1.13 The instance name of the parent UDT Instance. This is similar to InstanceName, except the name of parent UDT Instance will be returned when binding from UDT Instance parameters.
{PathToParentFolder}	The full path to the folder that this Tag is in.
{TagName}	The name of the Tag that is using this parameter.
{PathToTag}	The full path to the Tag using this parameter.
{RootInstanceName}	New in 8.1.13 Returns the top-most UDT Instance name.

Adding a Parameter to a UDT

In this example, our plant has multiple compressors. We created a Compressor UDT, but we want each instance of the Compressor UDT to reference a different set of Tags. Our Compressor UDT has two OPC Tags: lineVoltage and motorAmps. These two Tags are pointing to a specific address in the PLC. In order to reference a different set of Tags for each instance, we need to add a parameter to our Compressor UDT that we called "CompressorNum."

1. In the Tag Browser, we clicked on the UDT Definitions tab to find our Compressor UDT.
2. Double click on the Compressor UDT to open it in the Tag Editor and click on the edit icon next to the Parameters property. The Parameters pane will open.
3. Click the Add icon to create a parameter. Enter the parameter Name and Data Type of String.
   

Referencing Parameters from Member Properties

Continuing with the example from above, this next example will show you how parameters are referenced from member properties.

1. In the Tag Editor, replace the Compressor Number for each Tag with the new parameter CompressorNum. Select the lineVoltage Tag and click on the binding icon and click Edit.
   

2. This opens the OPC Item Path window for editing the lineVoltage Tag. Place your cursor at the end of 'Compressor1', delete the '1', and enter '{CompressorNum}'. Click Commit.

   Changed in 8.1.17

   Starting in version 8.1.17, you may also edit tag paths inline in the Tag Editor rather than opening the OPC Item Path window. For this example, you would highlight '1' in the OPC Item Path and replace it with the new parameter, '{CompressorNum}'

3. Repeat Step 2 for the motorAmps Tag. .1 Both Tags will now show the CompressorNum parameter in the OPC Item Path.

4. Now, let's create an instance of the Compressor UDT using the CompressorNum parameter under the Tags tab of the Tag Browser. To keep UDT instances organized, we created a Plant Compressors folder.

5. Right-click on the Plant Compressors folder and select New Tag > Data Type Instance > Compressor UDT.

6. Enter a Name for the Instance (i.e., HVAC Compressor), then click on the pencil icon next to the Parameters property and enter a value (i.e., 2). Click OK to save the HVAC Compressor instance.
   

7. Under the Tags tab, you'll see the HVAC Compressor was created showing the Parameter that was used and the values for the OPC Tags listed in the OPC Item Path.
   

Data Type Parameters in Expressions

It is possible to use the value of data type parameters directly in expression bindings within a UDT. Parameter references can be quickly inserted into an expression.

While a UDT member is selected in the Tag Editor, you can edit bindable properties, such as the Expression on Expression Tags by clicking the Edit icon next to the property.

This opens the Expression window. Click on the UDT Parameters icon on the right of the expression area, select a parameter, then click Commit.

Combining Parameters and Tag References

Because parameter and Tag references differ in syntax, some consideration must be made when attempting to use both in the same expression. Tag references must not be placed inside of quotes. After adding a string Tag to the Turbine UDT, a reference to the Tag can be added to Member Location's expression. Single quotes were added to create a space between the Member's Location and the string value.

Here's what it looks like in the Tag Browser.

Attribute Referencing and Parameterized Types

As mentioned above, many properties in the member Tag configuration can reference the parameters available in the data type. When instances are created, these references are replaced with the values defined for the type. Parameter references also support basic offsets and numerical formatting, providing a great deal of flexibility. To reference a parameter, use the syntax {ParameterName}.

To offset a value, use the form {ParameterName+offset}. To format a value, use the form {ParameterName|format}. The format pattern is the same as that used for the numberFormat expression function. In short, "0" can be used to require a digit, and "#" can be used for optional digits. ie: ##0

Example:

For this example, we'll assume that we've parameterized OPC Item Path, and that the data type has an integer attribute named BaseAddress defined. We'll pretend the OPC Server provides Tags named like DataPoint1.

Standard Referencing

OPC Item Path: DataPoint{BaseAddress}

Offset

Imagine that our data type had three fields, and these were laid out sequentially in the device. Instead of specifying each address for each Tag, we can simply offset from the base address:

Member 1: DataPoint{BaseAddress+0}

Member 2: DataPoint{BaseAddress+1}

Member 3: DataPoint{BaseAddress+2}

Formatting

Continuing from the example above, imagine that our OPC server actually provided addresses in the form DataPoint001, in order to stay consistent up to "DataPoint999". This can be accommodated using number formatting in the reference:

Member 1: DataPoint{BaseAddress+0|000}

Member 2: DataPoint{BaseAddress+1|000}

Member 3: DataPoint{BaseAddress+2|000}

This format of three zeros means "three required digits". If our instance has a base address of 98, the resulting paths will be DataPoint098, DataPoint099, DataPoint100.

Parameters support more mathematical operators in addition to offsets and formatting. There is a simple expression language available that can be used in conjunction with formatting. The following table shows all available operators in their order of operations (they are evaluated starting at the top of the table).

Operator	Description	Example
()	Parenthesis. These operators are used for grouping any number of values. Also used to change the order of operations.	{Baseaddress*(2+3)}
^	Power. This operator is used to raise a number to a power.	{BaseAddress^2}
-	Negative. Used to create a negative value from one number.	{BaseAddress*-2}
*	Multiplication. Multiply two numbers.	{BaseAddress*2}
/	Division. Dividing the first number by the second number.	{BaseAddress/2}
%	Modulus. This operator returns the remainder of a division operation. IE: 7/3 = 2 with a remainder of 1, so 7%3 = 1	{BaseAddress%2}
+	Addition. Add two numbers.	{BaseAddress+2}
-	Subtraction. Subtract two numbers	{BaseAddress-2}
|	Used to define a formatting pattern. Patterns are defined with 0 and # characters.	{BaseAddress

Example

# This dynamic OPC Item path takes in three parameters to determine the tag path
ns=1;s=[DeviceName]Path/to/tag{BaseAddress+(ParamNum*Multiplier)|0000}
 
# The OPC Item path resolves to the following assuming the following values:
# BaseAddress = 5
# ParamNum = 8
# Multiplier = 2
ns=1;s=[DeviceName]Path/to/tag0021

Calculations and Numerical Parameter Names

If the parameter names are purely numerical values (we don't recommend this: it gets confusing), then quotation marks must encase the parameter to run any sort of calculations on the value of the parameter.

For example, if a UDT contains a parameter named 0, and its value is 10:

// This will evaluate to 0, because it thinks you mean the integer 0, not the parameter named "0"
{0 * 1000}
 
// This will evaluate to 10000, because the quotation marks denote a parameter named "0"
{"0" * 1000}

Nonexistent UDT Parameters

Changed in 8.1.8

Parameter references in bindings that do not evaluate to an existing UDT instance parameter will be returned as a string. For example, say a binding on a member used the following:

SomeText/{myParameter}

If the UDT definition does not contain a parameter named "myParameter", then the binding above would be treated as a string literal, returning a value of "SomeText/{myParameter}".

Null Values on Parameters

Changed in 8.1.8

If the value of a UDT parameter is null, then any bindings that reference to the value of that parameter will instead return a string literal, similar to how referencing nonexistent parameters works. For example, say a UDT definition has the a parameter named "NullParameter". If the value of that parameter is null, then references to it would return the string "{NullParameter}". Thus, if we had a binding that included the parameters:

SomeText/{NullParameter}

The binding would return a value of:

"SomeText/{NullParameter}"