To configure display symbols | To configure symbol values
A symbol is a placeholder for a value that can be substituted at run time from a symbol file. You can define a symbol in a display by enabling it and giving it a name. Symbol substitution is permitted for the following:
Data source substitution – for example, you can substitute a tag for another tag or an SQL statement for another SQL statement. This method can be used as an alternative to embedding data source names in displays. The display must be configured with a data source prior to configuring data source symbols. A data source symbol can only be substituted with another item from the same data source connector.
For example:
You have a grid in a display that displays tags. You want to be able to swap one of the tags easily and quickly. Using symbol substitution for the data source, you could set up a button that will load a symbol file. The symbol file (when enabled in the display) will swap the currently displayed tag in the grid for the symbol substitute (in run-time). The next time the display is accessed, the original tag is displayed.
Property substitution – can be used for the caption property on text and hyperlink objects.
For example:
You have a text caption on a display that you want to change when the user presses a button. Using symbol substitution for the caption property, you can set up a button that will load a symbol file. The symbol file (when enabled in the display) will swap the currently displayed text in the Text object for the symbol substitute (in run-time). The next time the display is accessed, the original text is displayed.
Parameter substitution – can be used to substitute any parameters used in SQL statements, built-in parameters (such as StartDateTime/EndDateTime), or parameters used in URL lines.
For example:
You have a Time chart in a display that plots the values of a tag. You want to be able to swap the start date/time and end date/time for the tag when the display is first opened. Using symbol substitution for the StartDateTime and EndDateTime parameters, you could set the display to load the symbols when it is opened (by setting the symbol file in the Edit Current Display dialog box). The symbol file (when enabled in the display) will swap the currently displayed tag values in the Time chart for the tag values that are based on the date/time parameters (in run-time).
Symbols are defined by creating a symbol file from an existing display. Open the display where the data sources, properties, and/or parameters exist that you want to set symbols for. Access the Edit Display Symbols dialog box (Edit menu | Display Symbols). If data sources exist in the current display, they will appear on the Data Sources tab. Likewise, if Properties exist in the current display, they will appear on the Properties tab. The Defined Symbols tab displays any symbols already defined on the current display (that are enabled). To enable a symbol, select the Enabled check box and, if necessary, change the name of the symbol by double-clicking in the Symbol field.
Some restrictions apply when naming symbols. Symbol names:
Cannot contain spaces or special characters – only numbers, letters, and underscores.
Must start with an alphabetic character.
Can be up to 300 characters long.
Are not case sensitive.
In many cases, you may want to re-use the same symbol multiple times in a display. For example, if you have a chart and a datalink in a display that both access the same data source when the display is opened, you can set the data source symbol for the chart, and then set the data source symbol for the datalink, giving it the same name as the chart's symbol value. When the symbol file is saved, the first reference is saved as the symbol value. When the symbol is applied, the same value (the first reference) is applied to both the chart and the datalink.
The following rules apply when re-using symbol values:
The reference must be of the same type to be named to an existing reference. For example, a data source substitution can only be named to another data source substitution; a property to a property, and so on.
If the reference type is a data source, the data source type must be the same. For example, you can name a Real Time data source substitution only to another Real Time data source substitution, Historical to Historical, Quality to Quality, and so on.
NOTE: To change the name of a symbol in the Edit Display Symbols dialog box, the symbol must be enabled (select the Enabled check box beside the symbol name).
If you need to edit a symbol value, where there are multiple symbols, make sure that you are changing the first reference. Changing the other references will have no effect, as only the first reference is used.
Symbol values associate a symbol name with a substitution value. Symbol values for properties can be any combination of printable characters, including the marks of punctuation, numbers, and letters. For data sources, the symbol value is the data source item, and for parameters, the symbol value is the parameter value.
After a symbol file has been created, symbol values can be modified from the Edit Symbol Values dialog box. See To configure symbol values for more information.
After symbol files have been created, they can be applied to a display in the following ways:
In the Edit Application Preferences dialog box (Edit menu | Application Preferences). On the Application tab, set the default symbols file. This will set the symbols file as the default for all displays. See Application Preferences for more information.
In the Edit Current Display Settings dialog box (Edit menu | Current Display Settings). On the Display tab, set the symbol file for the current display. When the current display is run, the symbols file will load, and will override the default symbols file set on the Edit Application Preferences dialog box (if set). See Display Settings for more information.
From the Load Symbols command. For example, a button control can be configured with the Load Symbols command so that, during run-time, when the user clicks the button the symbol file is loaded into the display. See Using Commands for more information.
From any command that opens a picture. The Open Picture and Replace Picture commands allow you to specify a symbol file to load with the set display. See Using Commands for more information.
From a hyperlink that opens a display. When a hyperlink is configured to open a display, you can specify the symbol file to load with the display. See Hyperlinks for more information. Rather than loading an entire symbol file, it is possible to configure specific symbols to apply when the display is opened. The symbols must be enabled in the target display before they will appear in the Hyperlink's configuration dialog box. For more information, see Passing Parameters Between Displays.
From the URL line. The SYMFILE parameter can be used in the display's URL to specify the symbol file to load with the display. See Passing Parameters to URLs for more information.
In addition to loading the symbol file, the Symbol(s) must also be enabled in the display. To do this, open the display you want to load the symbol(s) into, access the Edit Display Symbols dialog box, and select the Enabled check box for each symbol you want to enable.
Symbol values can be merged from a display or a symbol file. When symbol values are merged, they combine to form one symbol file. The Edit Display Symbols dialog box or the Edit Symbol Values dialog box can be used to merge symbol values.
Only symbols from the display or symbol file that do not already exist in the target file will be available for merging. If a symbol appears in the Get Symbols From list with the Merge check box cleared, then a conflict exists with a symbol in the target file. Usually a conflict is caused by naming; that is, the name of the symbol in the two files or displays have the same name.
See To merge symbol values from a symbol file and To merge symbol values from a display for more information.
