Variables
Variables and their evaluation with conditional expressions are absolutely central to the power of ComScript. All variables are treated as "global" so they are available throughout the profile.xml file as well as imported subscripts. They also do not have to be "passed" from one script to another. While this greatly simplifies variable handling in ComScript, users need to be careful not to reuse variable names in a particular project. Variable names are also case sensitive so substituting X for x will cause an undesirable result.
Set:
Unlike more complicated languages, ComScript variables types (e.g. int, float, double, char) do not have to be set and there are no memory allocation requirements. Simply use the set command to set an initial value or to replace it with a new value. Text variables (strings) are also supported with the set command.
Examples:
<set var="TempLimit" value="99" />
<set var="message" value="Temperature limit exceeded" />
<set var="TempLimit" value="99" />
<set var="message" value="Temperature limit exceeded" />
Reference:
To reference a variable (write to a file, evaluate in a conditional expression, etc.) it must be enclosed in square brackets (e.g. [TempLimit] ) so that ComScript knows to substitute the current variable value into the expression or command. If you see that the variable name in the console or the log file where you expect a variable value, it usually means that the square brackets were omitted, the variable name was misspelled or that no value was loaded.
Tip: Empty variables often cause problems in both conditional and math expressions. Writing them to the desktop utility window with the log command is a simple way to verify a variable value.
Examples:
<write file="MyDataFile.txt" string="The Temperature limit of [TempLimit] has been exceeded" /> note: [ ] around TempLimit variable
<math var="TempInC" expression="([TempInF] -32) *9/5" /> note: [ ] around TempInF to reference value stored in the variable, but not for the TempInC variable which is being set with the math command.
<if condition="[TempInC] GT [TempLimit]" >
<email to="jsmith@gmail.com" subject="Temperature alarm" message="The Temperature of [TempInC]
<email to="jsmith@gmail.com" subject="Temperature alarm" message="The Temperature of [TempInC]
has exceeded the limit of [TempLimit] " />
</if>
Parsing data into variables:
Variables can also be loaded directly from the set device with the send and collect commands or from files and strings with the loadvars command. By using the trigger and terminator attributes of the send and collect commands, the input that comes in between them is loaded into the designated variable (var attribute). This collection variable could be just one nice and neat single value captured between the trigger and terminator, but it's often an alphanumeric string that must be parsed (split) into individual variables. This is achieved using the loadvars command that parses strings with multiple values into individual variables.
Example:
<send string="data request{13}" var="DataLine" trigger="data:" terminator="end" timeout="100"/>
<write file="MyDataFile.txt" string="The complete data line = [DataLine] {13}" />
<loadvars string="[DataLine]" delimiter="," vars="a,b,c,d,e" type="string" />
<write file="MyDataFile.txt" string="Parsed into variables (a,b,c,d,e): [a],[b],[c],[d],[e]{10}{13}" />
<write file="MyDataFile.txt" string="The complete data line = [DataLine] {13}" />
<loadvars string="[DataLine]" delimiter="," vars="a,b,c,d,e" type="string" />
<write file="MyDataFile.txt" string="Parsed into variables (a,b,c,d,e): [a],[b],[c],[d],[e]{10}{13}" />
Explanation: In this example ComScript sends the string "data request" and a carriage return (ascii 13) to the set decvice. The response of the device is initially parsed between "data" and " end". Lets assume that the device responds with 'data: 99, 100, 72, -999, valid end' so that the variable DataLine= 99, 100, 72, -999, valid. The loadvars command breaks up the individual values in string [DataLine] that are separated or delimited by a ',' so that variables a=99, b=100, c=72, d=-999, and e=valid. Variables a-e are now available to write to a file as is done in the example above or for evaluation in conditional expressions. Data parsing can be a little tricky so Green Eyes has provided a detailed example profile with the ComScript download called DataLineParse that demonstrates how to parse a variety of data lines.
Users are strongly encouraged to run DataLineParse and to look at its profile.xml file and the output file to gain a strong understanding of data parsing.
Data Interface - Config.xml file
Variables can also be loaded with the loadvars command from the config.xml file that is used to include variables in the data interface. Because these variables are declared in the config.xml file they do not need to be set in the profile code. Data interface variables can be changed by the user in the data interface (if editable="True" in config.xml) and/or by the operation of the profile. See the data interface section to learn how to utilize this powerful feature. Be aware that is the config.xml file is re-loaded when an entire profile loops, it will set the defined variables back to the values set in config.xml.
Example:
<loadvars file="config.xml" type="xml" />