String expressions

A string expression is a way of specifying a dynamic value (a value that can change during project run time) instead of a static value for a setting or property that requires a string.

There are many settings and properties throughout a project, such as Caption and Message, that accept String values. If a String value is typed into the setting, it will be static, meaning that the String value does not change during runtime operation. Many of these settings and properties allow the use of a String Expression, which is a method of changing the String value based on the value of a tag or an expression.

If a tag or expression is typed into a String setting, it will be evaluated as a static string value. A String Expression is created by enclosing the tag name or expression in braces: {}, for example: {tag name} or {expression}. The expression can be composed of tags and built-in language functions. The example below shows the use of a String Expression in a Button object Caption.

Note: This method of enclosing a string expression in braces only works for settings and properties that normally require strings. There are other settings and properties (such as triggers) that explicitly require expressions, and those expressions are not enclosed in braces.

Note: String expressions are not always supported on IoT View or on Mobile Access. For more information, see Supported features in IoT View and Supported features in Mobile Access.

Note: Braces are sometimes also known colloquially as curly brackets, but that is not correct in the context of programming languages. Any occurrences of the term curly brackets that appear elsewhere in this documentation are artifacts that will be corrected or removed as we continue to revise this documentation.

Settings and properties that accept String Expressions are listed below, organized by screen object type or Project Explorer tab. Some settings and properties only accept tags, not expressions. These are marked below:

Project Settings Options tab:

• Database Configuration dialog: Connection string, User name (tag only), Password (tag only), and Name (tag only) fields (opened using the Alarm Database or Event Database buttons for the History FormatDatabase setting)

• Default Database Configuration dialog: Connection string, User name (tag only), and Password (tag only) fields (opened using the Default Database button)

Screens, screen objects and Project Explorer Graphics tab:

• Screen Attributes dialog Background Picture group Shared image field and Runtime Properties group Titlebar field

• Rectangle shape: Caption field

• Button active object: Caption field

• Pushbutton active object: Caption field

• Check Box active object: Caption field

• Radio Button active object: Caption field

• List Box active object: Message fields

• Smart Message active object: Messages Configuration dialog Text/Message fields and Text File Data Source Source File field

• Alarm/Event Control data object

  • Filter dialog Group, Selection, Tagname, Message, and Username fields (all fields tag only)

  • Advanced dialog PDF Filename field

• Trend Control data object: Points dialog Label fields

• Grid data object:

  • Advanced dialog Condition and PDF Filename fields

  • Columns dialog Label, Unit, and Field fields

  • Grid Data - Text File dialog File field

  • Database Configuration dialog: Connection string, User name (tag only), Password (tag only), and Name (tag only) fields (opened using the Data source settings button for the Data source Database setting)

• Symbol (Linked Symbol) library object: See Create and edit project symbols for more information.

  Note: The Text object Caption field does not accept String Expressions. Use the Text Data Link animation to create dynamic strings for Text objects.

Project Explorer Global tab:

• Event Logger Message fields

Project Explorer Tasks tab:

• Alarm worksheet:

  • Header Email Settings dialog To, Cc, Bcc, and Custom fields

  • Body Message fields

• Trend worksheet:

  • Trend Advanced Settings dialog Name and Description fields (opened using the Advanced button)

  • Database Configuration dialog: Connection string, User name (tag only), Password (tag only), and Name (tag only) fields (opened using the Database Configuration button for the History FormatDatabase setting)

  • Historian dialog: Server, User Name (tag only), Password (tag only), Prefix, Host.

    Note: Port accepts the expression syntax in the dialog, but it is converted to a number when you click OK, so a tag in Port has no effect. Only Host is evaluated at run time.

• Recipe worksheet header File Name field (tag only)

• Report worksheet header Output File field (tag only)

• Database/ERP:

  • Connections folder Database Connection dialog Connection String, User Name, and Password fields

  • Worksheet Table and Condition fields

• Project Explorer Comm Tab

• Drivers

  • Settings / communication parameters dialog: IP Address (Serial Encapsulation set to TCP/IP or UDP/IP) and Phone (Serial Encapsulation set to Modem) fields.

  • Main Driver Sheet Station fields (tag only)

  • Standard driver sheet Header and Station fields (both tag only)

• OPC UA worksheet body Node Id fields

• TCP/IP worksheet header Server IP Address, User Name, and Password fields (all fields tag only)

Example: Button Caption

One of the more common uses of a dynamic String Expression is in the caption on a Button object. When you insert a Button object in a project screen, you can edit its properties in order to add a caption, which is a string. Even if the caption consists entirely of numerals, those numerals are handled and displayed as a string rather than as an integer or real number.

An example of a static value for the caption is START, on a button that starts a device:

This static string works if you have separate buttons for START and STOP, but you may want a single button with a caption that changes depending on the current state of the device: START when the device is stopped, and STOP when the device is started. In other words, you might want to specify a dynamic value for the caption.

To do this, create/select a tag or compose an expression that determines the value. In this example, the purpose of the button is to start and stop the device, so the object is probably configured to toggle the value of a tag (Device_1.State) when the button is pressed:

The value toggles between two possible values: 0 (FALSE) for stopped, and 1 (TRUE) for started. Therefore, you need to compose an expression that gets the value and then determines the appropriate caption. There are many ways to do this using the built-in language, so here is just one example that uses the If function:

If(Device_1.State,"STOP","START")

Note: In this example, the If function is not being used to determine the current state of the device; it is being used to determine which caption should be used, based on the current state of the tag. This is why the strings seem to be reversed: "STOP" if the value is TRUE (the device is started), and "START" if the value is FALSE (the device is stopped).

Now, if you type this example without additional formatting in the Caption box, it will be displayed as a literal string because there is nothing to indicate it is an expression that should be evaluated before it is displayed. To indicate that, you must enclose the expression in braces ({}):

When the project screen is opened and the button is displayed, the string expression is evaluated and the caption is determined.

Taking this a step further, you can combine a string expression with plain text to form a longer string. Only the string expression — that is, only the contents of the braces — will be evaluated before it is displayed. The plain text will be displayed as is. For example: