ComScript Profile Setup

Please refer to the ComScript manual for more details on individual commands.

profile

The main xml tag that holds all devices and scripts. It requires either all or none of the following attributes. Including no attributes will result in the profile executing once.

Attributes:
start
the time at which execution should begin (dd/mm/yyyy hh:mm:ss)
end
the time at which execution should stop (dd/mm/yyyy hh:mm:ss)
interval
the number of seconds between profile iterations
consoleoutput
True to output logs to the console window, False to hide them
debug
True to enable debug messages, False to hide them
logfile
True to log command output, False to hide it
failscript
The name of the script to run if the profile fails
dateformat
The MS date format to use for logging messages. The default is "MM/dd/yyyy HH/mm/ss".
Sample XML:
<profile start="12/25/2009" end="12/26/2009" interval="25" consoleoutput="true" failscript="myscript" >
...
...
...
</profile>
emailaccount

Command used to configure an email account. Email command is used to send messages.

Attributes:
address
the email address
password
the password for the email account
server
the host for the email account
default
True to use this account when sending messages
ssl
True to use SSL when connecting to the server (required for gmail accounts)
Sample XML:
<emailaccount address="test@email.com" password="password" server="smtp.gmail.com" default="true" ssl = "true" />
device

Configures a serial (Com port) device or tcp (internet) device connection.

Attributes:
type
"serial" or "tcp" depending on the type of connection

Serial attributes when type="serial"

name
a string used to identify the device in the command script
port
a local port to which the device is connected
baudrate
the baud rate for the connection
parity
The value of the parity for the connection (Even, Odd, None, Mark, or Space)
stopbits
The integer value for the stop bits for the connection
databits
The integer value for the data bits for the connection
handshake
None, XOnXOff, RequestToSend, RequestToSendXOnXOff
dtr
True, False

TCP/IP attributes when type="tcp"

ip
The ip address of the device
dns
The url of the device
port
The tcp port to connect to
Sample XML:
<device name="MySerialDevice" type="serial" port="COM1" baudrate="9600" parity="Even" stopbits="1" databits="8" handshake="None" dtr="False" />
<device name="MyTCPDevice" type="tcp" port="12345" ip="10.1.0.10" />
<device name="MyTCPDevice" type="tcp" port="12345" dns="my.device.com" />
script

A set of commands that run as a single piece of code. You can place scripts in external files within a profile directory and include them in the profile using the Import command (see below).

Attributes:
name
a unique string to identify the script (this is not required when importing a script from an external file)
Notes:

A script named "main" is required for the profile to execute. It is called everytime the profile iterates. The Run command below can be used to call other scripts from within the "main" script.

Sample XML:
<script name="main" >
...
...
...
</script>
scripts

Tags uss to indicate the start and end of a subscript page (external to the profile.xml file).

Sample XML:
<scripts>
  SubScript1
  SubScript2
  SubScript3
</scripts>

ComScript Data Interface Configuration

Data Interface Configuration File

A file named config.xml located in the specific profile folder is used to configure the variables that appear in the Data Interface. It is loaded into the running profile with the loadvars command (described below) in the "startup" script.

Attributes:
name
the name of the variable
value
the value of the variable
visible
True if the variable is to appear in the Data Interface, False otherwise (default is False)
editable
True if the variable is editable in the Data Interface, False otherwise (default is True)
final
True if the variable's value cannot be changed by the profile, False otherwise (default is False)
label
The label that will appear after the value textbox in the Data Interface, good for unit of measurement or type of data
type
byte, char, int16, int32, int64, uint16, uint32, uint64, float, double (used for binary parsing)
inputtype
"textbox" or "checkbox" depending on the desired input type in the Data Interface. Regarding conditional tests (i.e. if or while), checkboxes will set the variable's value to 0 (unchecked) or 1 (checked).
Sample XML:
<variables>
    <var name="ounces" value="3" visible="true" editable="true" final="false" label="Fluid Oz." />
    <var name="StartProgram" type="checkbox" value="0" visible="true" editable="true" final="false" label="Check to start" />
...
...
...
</variables>

ComScript File Commands

exists

Checks a directory or file path and stores True or False in a profile variable.

Attributes:
path
The directory or file to be checked
result
The variable in which to store the result
Sample XML:
<exists path="test.txt" result="var1" />
<exists path="C:\MyDirectory" result="var2" />
create

Creates a file.

Attributes:
file
The path and filename to be created
Sample XML:
<create file="test.txt" />
<create file="C:\path\to\file.txt" />
createdir

Creates a directory.

Attributes:
path
The path to be created
Sample XML:
<createdir path="a\b\c" />
<createdir file="C:\path\to\create" />
delete

Deletes a file.

Attributes:
file
The path and filename to be deleted
Sample XML:
<delete file="test.txt" />
<delete file="C:\path\to\file.txt" />
deletedir

Deletes a directory.

Attributes:
path
The path to be deleted
Sample XML:
<deletedir path="a\b\c" />
<deletedir file="C:\path\to\delete" />
rename

Renames a file.

Attributes:
file
The path and filename
to
The new path and filename
replace
True to overwrite existing file, false to prevent overwriting (default is true)
Sample XML:
<rename file="test.txt" to="test2.txt" replace="true" />
copy

Copies a file.

Attributes:
file
The path and filename
to
The new path and filename
replace
True to overwrite existing file, false to prevent overwriting (default is true)
Sample XML:
<copy file="test.txt" to="test2.txt" replace="true" />
append

Appends the contents of a file to another file.

Attributes:
file
The source filename
to
The destination filename
newline
True add a new line before appending the content (default is false)
Sample XML:
<append file="test.txt" to="test2.txt" newline="true" />

ComScript Commands

Command (abstract)

The folllowing attributes can be used in any of the commands

Attributes:
onfail
"True" to return true even when a profile fails, "False" by default
log
"False" to disable logging for the command, "True" by default
Notes:

Most attributes allow for profile variables and ascii codes to be included in the arguments. Use square braces [ ] for variables and curly braces { } for ascii codes.

break

Breaks out of the inner-most loop of the executing script

Sample XML:
<break />
canconnect

Attempts to connect to a device. Sets variable to True if connection is successful, False otherwise.

Attributes:
var
the variable to store the result in
device
the name of the device
Sample XML:
<canconnect var="isconnected" device="MyDevice" />
closeport

Closes the serial or TCP connection to the specified device

Attributes:
device
the name of the serial device
Sample XML:
<closeport device="MyDevice" />
collect

Connects to the last set device and collects data based on the following attributes. The collect and send commands are central to ComScript and can be configured in numerous ways to allow data collection from various types of devices. Please refer to the Device Communication section of the manual and the examples for more information

Attributes:
file
the filename to write all collected data to
var
the variable to write all collected data to
type
"Hex" or "Text" depending on the type of communication
behavior
"triggerterminator(tt)", "chars", or "numberofbytes". Trigger/Terminator collected all data between a trigger string and a terminator string. Number of Bytes collects a specific number of bytes. Chars collects a specific number of characters.
timeout
the max milliseconds to wait before terminating communication with the device
aftercollection
the string containing the delimiter to be written after the collected data
Trigger/Terminator Attributes:
ms
Integer value for the minimum milliseconds to wait after collection begins
trigger
The string to wait for before collecting/looking for the terminator. Empty string to begin collecting immediately.
terminator
The string to wait for before terminating the connection. Empty string to collect until the timeout occurs.
keeptrigger
"True" or "False" - determines if the trigger is also collected along with the data following it
keepterminator
"True" or "False" - determines if the terminator is also collected along with the data preceding it
Number of Bytes Attributes:
bytes
the number of bytes to collect
bytescollected
the name of the variable to store the number of collected bytes
Chars Attributes:
length
the number of characters to collect
collected
the name of the variable to store the number number of collected characters
Sample XML:
<collect file="CollectionFile.txt" var="data" behavior="tt" ms="5000" trigger="{13}" terminator="{13}" timeout="8000" type="Text" keeptrigger="false" keepterminator="true" />
<collect file="CollectionFile.txt" var="data" behavior="numberofbytes" bytes="32" bytescollected="collected" timeout="5000" type="Hex" />

To collect 8 characters (e.g. "ABCDEFGH") from the device:

<collect file="data.txt" behavior="chars" length="8" collected="total" timeout="5000" type="Text" />
date

Stores the current date and time in a variable

Attributes:
var
the name of the variable to store the data string in.
format
the Microsoft date format string (click here)
Sample XML:
<date var="Date" format="yyyy-MM-dd" />
<date var="DateTime" format="MM/dd/yyyy HH:mm:ss" />
<date var="Hour" format="HH" />
email

Send a message to a specific email address

Attributes:
to
the email address to send to
subject
The subject of the email
message
The body of the email message
files
A comma-separated list of attachments
wait
True to wait for the message to send before continuing execution (default is false)
result
The name of the variable in which store the result (e.g "true" or "false")
Sample XML:
<email to="test@email.com" subject="w2w update" message="The profile failed!" files="text.txt, file.doc" wait="true" result="sent" />
elapsedtime

Gets the elapsed time since the profile has started. Can be restarted at zero with the reset attribute.

Attributes:
var
The variable to store the elapsed time in
format
days, hours, minutes, ms, or seconds
reset
"True" to reset the timer
Sample XML:
<elapsedtime var="time" format="seconds" reset="False" />
if

Allows different sets of commands to be executed based on a condition

Attributes:
condition
The condition to be evaluated (use LT, LTE, GT, GTE, ==, !=, AND, OR for comparisons). Use single quotes to do string comparisons.
Sample XML:
<if condition="[x] LT 10" >
    <set var="x" value="10" />
    <pause seconds="5" />
    <else>
       <set var="x" value="0" />
       <pause seconds="2" />
    </else>
</if>
Sample Condition Strings:
condition="[x] LTE 10"
condition="'[x]' == 'ABC'"
condition="([x] LT 10) AND ([y] GT 20)"
import

Includes a Command Script stored in an external file in the profile. The file can be located anywhere within the current profile's directory

Attributes:
file
The path (relative to profile folder) and file name of the XML file containing the external script
Sample XML:
<import file="SubScripts/myScripts.xml" />
kill

Stops profile execution.

Attributes:
message
the message to be logged by this command. The default message is "terminating profile".
Sample XML:
<kill />
<kill message="Terminating profile execution" />
loadvars

Loads variables from an xml or text file

Attributes:
file
the path of the xml or text file relative to the profile's directory
type
The type of file the system is reading from ("text" for textfile, "xml", "string")
line
The int value for the line of the file to parse (for text files only)
delimiter
The string separating each value in the line (for text files only)
string
The string of data to parse
vars
The comma-delimited string of variables to save the data to (for text files only)
multi
"True" to treat multiple instances of the delimiter as a single instance, "False" by default
chars
The number of ASCII characters to put into each variable
Sample XML:
<loadvars file="config.xml" type="xml" />
<loadvars string="1,2,3,4,5" type="string" delimiter="," vars="a,b,c,d,e" />
<loadvars string="1 2 3 4 5" type="string" delimiter=" " vars="a,b,c,d,e" multi="True" />
<loadvars file="myFile.txt" type="text" delimiter="," line="1" vars="a,b,c,d,e" />
<loadvars file="myFile.txt" type="text" chars="2" line="1" vars="a,b,c,d,e" />
<loadvars string="ABCDEF" type="string" vars="x,y,z" chars="2" /> - result: x=AB, y=CD, z=EF
log

Logs a string to the profile's log file. Ascii codes wrapped in { } and variables wrapped in [ ] will be substituted.

Attributes:
message
the message to be logged
Sample XML:
<log message="Hello World!" />
<log message="The value of X equals [X]{13}" />
math

Evaluates a math expression and saves the result to a variable.

Attributes:
var
the name of the variable to store the result
expression
the math expression (click here for details and a list of supported functions:)
Sample XML:
<math var="x" expression="5.555 * 11" />
<math var="y" expression="round([x])" /> Note that the variable x is inside square brackets
multitask

Executes a set of commands wihle continuing profile execution. Caution: Switching Devices during a MultiTask command in a profile that uses device connections outside of the MultiTask command can result in the incorrect device being used.

Attributes:
timeout
ms to wait before terminating the MultiTask
Sample XML:
<multitask timeout="20000" >
   <log message="Five..." />
   <pause ms="1000" />
   <log message="Four..." />
   <pause ms="1000" />
   <log message="Three..." />
   <pause ms="1000" />
   <log message="Two..." />
   <pause ms="1000" />
   <log message="One..." />
   <pause ms="1000" />
<\multitask>
parse

Parses a hex string into a list of variables or a list of variables into a hex string

Attributes:
hexvar
the name of the variable containing the hex string
vars
The comma-separated list of variable names
type
vars2hex to parse the variables into a hex variable, hex2vars to parse the hex variable into variables
Sample XML:
<set var="0xNum1,0xNum2,0xNum3" type="byte,uint16,uint32" > Note: must delcare hex variable sizes before parsing into them
<set var="HexString" value="FFAAAAF1E2D3C4" >
<parse type="hex2vars" hexvar="HexString" vars="0xNum1,0xNum2,0xNum3" /> Note: ComScript parses the hex string into individual variables based on the number of bytes designated above
...results: 0xNum1(FF)=255 in decimal, 0xNum2(AAAA)=43690 in decimal, 0xNum3(F1E2D3C4)=4058174404 in decimal
<parse type="vars2hex" hexvar="HexString2" vars="0xNum1,0xNum2,0xNum3"/> Note: This builds a new hex string out of the individual decimal variables. Notice that the variables are already designated as such so no square brackets ([])
...result HexString2 = FFAAAAF1E2D3C4
pause

Pauses profile execution for a specified ammount of time.

Attributes:
seconds
the integer value for the number of seconds to pause for
ms
the integer value for the number of milliseconds to pause for
Sample XML:
<pause ms="3000" />
<pause seconds="3" />
readfile

Reads individual lines of a file into a variable until it reaches the end of the file. Readfile is structured as a loop to allow a command or sequence of commands to operate on (e.g. loadvars command) the line read from the file befroe the next line is loaded.

Attributes:
file
The file to be opened
var
The variable in which to store each line
skipempty
True to skip over empty lines, False to read them. (default is true)
Sample XML:
<readfile var="line" file="myTextFile.txt" skipempty="True" >
    <log message="[line]" />
</readfile>
run

Runs a subscript or an external executable file

Attributes:
script
the name of a script contained in the profile.xml file or in an included subscript file
file
the name and path (defauls to local path) to an executable file (.exe, .bat, etc.) to run
args
string containing all arguments to send to the executable file(external files only)
background (external files only)
"True" to start the process and continue profile execution, "False" (default) to wait until the process completes
Sample XML:
<run file="PlotData.bat" />
<run file="C:\StatPackage\StatProgram.exe" args="C:\StatPackage\StatScript.pro" background="True" />
<run script="MySubscript" />
savevars

Saves the current state of all profile variables to a file

Attributes:
file
the path and filename of the xml file
Sample XML:
<savevars file="config.xml" />
send

Extends the collect class to include the ability to send a string to the device before collecting data

Attributes:
string
the string to be send to the device
sendfile
the file to be send to the device
start
the line of the file to start from
sendlines
the number of lines to send
sendchars
the number of ASCII characters to send
Sample XML:
<send string="start" file="CollectionFile.txt" var="Dataline" behavior="tt" trigger="{13}" terminator="{13}" timeout="3000" type="Text" keeptrigger="false" keepterminator="true" />
<send string="off" />
<send sendfile="myfile.txt" sendlines="10" start="1" /> - sends the first 10 lines of the file
<send sendfile="myfile.txt" sendchars="4" start="7" /> - sends up to 4 characters from line 7 of the file
sendfile

Sends a file to a remote server via FTP using an ip address or hostname

Attributes:
localfile
the path and filename of the file to be sent
remotefile
the path and filename where the file should be placed on the server
username
the FTP username for the remote server
password
the FTP password for the remote server
ip
the IP address of the remote server
hostname
the hostname of the remote server
sftp
True to use SFTP, false for regular FTP
Sample XML:
<sendfile localfile="data/collection.txt" remotefile="collection.txt" username="username" password="mypassword" ip="10.10.10.1" />
<sendfile localfile="data/collection.txt" remotefile="collection.txt" username="username" password="mypassword" hostname="gescience.com" />
set

The set command is used to declare a variable(s) with an initial value, to configure general ComScript functions and to define binary data types

Attributes:
var
the name of the variable
value
the new value
logfile
true or false to enable/disable logging to the profile's log file
consoleoutput
true or false to enable/disable console output
onfail
true or false; the value to return from upcoming commands when they fail.
debug
true or false to enable/disable advanced debug messages.
type
not used for ascii, set to a binary data type when parsing hex(binary) variables (see hex and decimal section of manual)
Sample XML:
<set var="i" value="0" />
<set vars="a,b,c,name" values="1,2,3.5,Joe" />
<set logfile="true" consoleoutput="false" onfail="true" />
Array Support:
<set var="i@0" value="2" />
<set var="i@[j]" value="2" />
Binary variable definition
<set var="0xNum1,0xNum2,0xNum3" type="byte,uint16,uint32" />
setdevice

Sets the current device to be used for data transmission

Attributes:
name
the name of the device as specified in the profile
Sample XML:
<setdevice name="MyDevice" />
sizeof

Calculates the size of a variables contents and stores the result in another variable.

Attributes:
var
the variable of which to compute the size
result
the variable in which to store the size
type
"length" to compute the number of characters in a string, "bytes" to compute the number of bytes in a binary(hex) string
Sample XML:
<sizeof var="collectionString" result="size" type="length" />
switch

Executes different sets of commands based on the value of a variable

Attributes:
var
The variable to compare all cases to
Sample XML:
<switch var="x" >
   <case value="1" >
      <pause seconds="1" />
   </case>
   <case value="2" >
      <pause seconds="2" />
   </case>
   <case value="3" >
      <pause seconds="3" />
   </case>
   <default>
      <pause seconds="10" />
   </default>
</switch>
typetest

Checks if a variable can be parsed into certain data type and stores True or False in another variable

Attributes:
var
The variable to be tested
type
"string", "int", "double"
result
The variable to store the result in
Sample XML:
<typetest var="x" type="int" result="isXanInteger" />
while

Executes a set of commands while a condition is true

Attributes:
condition
The condition to be evaluated. See the IF command for help on setting up conditionals.
Sample XML:
<while condition="[x] LT 10" >
    <send string="[x]" />
    <pause seconds="1" />
    <js var="[x]" expression="[x] + 1" />
</while>
write

Creates a file if it doesn't exist and appends a string to the end of it

Attributes:
string
the string to write to the file
file
the file path relative to the profile's directory
Sample XML:
<write string="This is a test" file="testfile.txt" />