Many trigger actions use compound strings that let you build complex strings using the values from variables in the system. If you are familiar with programming, compound strings are similar to functions such as "printf()".
The following example shows a Log Message action using a compound string in its Message parameter. When the action executes, the message is dynamically built using the text in the parameter and the substitution variables $(trig) and $(devicevar). The variable $(trig) is defined to use a trigger macro, Macros.$TRIGGER, that contains the name of the trigger. The variable $(devicevar) is defined to use the value of a device variable, globVar.TriggerStatusChange1.
Notice the substitution variables $(trig) and $(devicevar) are added as parameters to the Input tab when they are typed into the Message parameter. You can define them to reference any started device, constant, trigger macro, trigger local variable, trigger static variable, or event variable available from the pull down list displayed for the Value cell for that row.
When the trigger and this example Log Message action executes, the message that is dynamically built and written to the Exceptions Log:
- The substitution variable $(trig) has been replaced by the value of Macros.$TRIGGER. In this case, the name of the example trigger is Compound_string_example.
- The substitution variable $(devicevar) has been replaced by the value of the device variable globVar.TriggerStatusChange1. In this case that device variable had a value of 1.
Floating point limitation
Currently there is no way to limit the precision of floating point values when printed, which may result in a large number of digits after the decimal point when printing floating point values. To avoid this problem, you may wish to first convert the floating point value to an integer value, which will prevent any decimal points from being printed.
Supported escape characters
When building your string, you may need to insert special characters such as new lines or null terminators into your string. The compound string handler uses a backslash as an escape character to note the start of an escape sequence. The supported escape sequences are described in the table below. If an invalid escape character is specified, the sequence will be ignored and the compound string will be built without the escape sequence as well as without the '\' in the string.
The following control characters are supported when using the compound string feature to build your string.
| Pattern | Result |
|---|---|
| \t | The tab character |
| \r | The line feed character |
| \n | The new line character (0x0A) |
| \xNN | Any character specified in
hexadecimal notation, for example \x35
will print the number 5. Warning: use of \x00 to specify an embedded null should not be used. |
| \0 | Null - not supported for embedded nulls. String functions that use the length of the string when processing will not give the expected results. |
|
Places a backslash \ character |
| $$ | Places a dollar sign $ character |