Below are commands related to file operations, internet file transfers, and email operations.

execute

Syntax: execute timeout hide_flag executable <parameter1> <parameter2> … <parameterx>

This command executes the external Windows program “executable” with optional parameters.

It is allowed to run for as long as “timeout” seconds. If "timeout" is 0 then the command returns as soon as the program is executed. The variable PROCESSID is set to the Windows process id of the program. If "hide_flag" is "true", the external program is started up with its main window minimized.

If "timeout" is 0, EXITCODE is set to 0 if the program started successfully or 2 if not started successfully.

If "timeout" is not 0, EXITCODE is set to:

  • 1: if the program did not finish by the specified time limit
  • 2: if the program did not start successfully
  • The exit code returned by the external program. This is usually 0 unless an error is reported by the program. Note that if the error reported by the program is 1 or 2, it can't be discriminated from those detailed above.

If the the timeout expires, consideration should be given to terminating the external program using the Windows 'taskkill' program and the PROCESSID variable.

The variable FILEERROR is "true" if EXITCODE is not 0.

directorymake

Syntax: directorymake directoryname

This command makes (if it does not already exist) a directory named "directoryname" as a sub-directory of the directory specified by the IMAGEDIRECTORY variable. It then sets the variable IMAGEDIRECTORY to the new fully qualify directory name. If the directory cannot be created, the error is reported and the variable FILEERROR is set accordingly.

directorydate

Syntax: directorydate

This command creates (if it does not already exist) a directory named "yyyy-mm-dd" (year, month, and date in the current local time) in the directory specified by the IMAGEDIRECTORY variable. Regardless, it sets the variable IMAGEDIRECTORY to the new fully qualify directory name. If the directory cannot be created, the error is reported and the variable FILEERROR is set accordingly.

deletefile

Syntax: deletefile filename <silent>

This command deletes the file "filename". "filename" must be fully-qualified. The variable FILEERROR is set accordingly. If the optional parameter "silent" is true, error messages are suppressed.

copyfile

Syntax: copyfile sourcefilename destfilename

This command copies the file "sourcefilename" to "destfilename". Both filenames must be fully-qualified. The variable FILEERROR is set accordingly.

appendfiles

Syntax: appendfiles appendedfilename inputfilename1 inputfilename2

This command copies the appends the files "inputfilename1" and "inputfilename2" to "appendedfilename". All filenames must be fully-qualified. The variable FILEERROR is set accordingly.

renamefile

Syntax: renamefile currentfilename newfilename

This command renames the file "currentfilename" to "newfilename". Both filenames must be fully-qualified. The variable FILEERROR is set accordingly.

getfilelines

Syntax: getfilelines filename

This command counts the number of text lines in the file "filename" and sets the variable FILELINES with the number of lines. "filename" must be fully-qualified. The variable FILEERROR is set accordingly.

getfileline

Syntax: getfileline filename line_no

This command sets the variable FILELINE to the text contained on line number "line_no" of the file "filename". "filename" must be fully-qualified. The variable FILEERROR is set accordingly.

getfile

Syntax: getfile filename

This command sets the variable FILELINE to the contents of the file "filename". "filename" must be fully-qualified. The variable FILEERROR is set accordingly.

findfileline

Syntax: findfileline filename string

This command searches every line in the file "filename" for the character sequence ‘string’ and sets the variable FILELINENO with the line number of the first occurrence, or zero if the sequence is not found. "filename" must be fully-qualified. The variable FILEERROR is set accordingly.

putfileline

Syntax: putfileline filename linetext <flag>

This command writes the line of text (‘linetext’), followed by the return and linefeed characters, to the file "filename", which must be fully-qualified. If the file does not exist, it is created, otherwise the line is appended to the end of the file. If the optional parameter "flag" is "true" the return and linefeed characters are omitted. The variable FILEERROR is set accordingly.

getfileexists

Syntax: getfileexists filename

This command check to see if the file "filename" exists (must be fully-qualified). The variable FILEERROR is set to "true" if the file exists and false if it does not.

validatefilename

Syntax: validatefilename variable

This command validates the filename contained in the variable "variable". The validation process removes characters not allowed in a Windows filename or web link. These include: <  >  : " / \ | ? * #. If nothing is left after removing invalid characters, the result is set to "NULLFILENAMEERROR".

getfilename

Syntax: getfilename fully_qualified_filename

This command extracts the file and extension part of  a "fully_qualified_filename" and stores the result in the variable FILENAME.

getfileextension

Syntax: getfileextension filename

This command extracts the extension part of  a "filename" and stores the result in the variable FILENAME. This included the "." character. If there is no extension, the result is a null string.

findfile

Syntax: findfile filemask <flag>

This command is used to find the names of files or directories that match the "filemask" parameter. If "flag" is "true" the search is for directories instead of files. If the "filemask" specified is not fully-qualified, the variable IMAGEDIRECTORY is pre-pended. The first time this command is used in a sequence, the "filemask" parameter must be used, but it can be omitted afterwards. The FINDFILENAME variable is set to the filename or directory that is found with its fully qualified directory. The variable FILEERROR is set to "true" if the first or subsequent file is not found.

findfileoff

Syntax: findfileoff

This command ends the current findfile command sequence. This command must be used if the findfile sequence did not completed normally (until all matching files were found).

zip

Syntax: zip zipfile.zip files*.fit

This command creates a new zip archive named "zipfile.zip" (specify the full path name) and then adds the files "files*.fit" (specify the full pathname and use the * and ? wildcard characters) to the archive. The variable ZIPERROR is set accordingly and EXITCODE is set to the exit code returned by the zip utility.

unzip

Syntax: unzip zipfile.zip extract_directory

This command extracts the files from "zipfile.zip" (specify the full path name) to the diretory "extract_directory". The variable ZIPERROR is set accordingly and EXITCODE is set to the exit code returned by the unzip utility.

ftp

Syntax: ftp host username password destination_directory upload_file <timeout>

This command is used to upload the file "upload_file" (specify the full path name) to an "ftp" server on the internet. The "upload_file" can include wildcards (*,?) to specify more than one file to be transferred. The “host” parameter is the internet domain name of the server or IP address. The "username" and "password" form the "credentials" for the account. The "destination_directory" is the directory on the server where the file is to be uploaded - it must currently exist on the server. If the default directory is desired used the parameter ".". The optional “timeout” parameter (maximum 7200 seconds) sets the maximum time that command will wait for the ftp operation to complete. The variables FTPERROR and EXITCODE are set accordingly. If EXITCODE=1 the connection to the server failed; if EXITCODE=2 changing to the specified directory failed; if EXITCODE=3, the file upload failed; and if EXITCODE=4, closing the connection with the server failed.

scp

Syntax: scp profile file.zip <timeout>

This command is used to upload the file "file.zip" (specify the full path name) to an "scp" server on the internet. "scp" servers are similar to ftp servers but use a secure encrypted communications. This command uses the WinSCP program. To use this command you will have to have previously setup a "profile" in WinSCP which includes the hostname, username and password, and destination directory. The optional “timeout” parameter (maximum 3600 seconds) sets the maximum time that command will wait for the scp operation to complete. The variable SCPERROR is set accordingly and EXITCODE is set to the exit code returned by the scp program.

httpgetfile

Syntax: httpgetfile url filename <timeout>

This command downloads the "url" from an internet web server and saves it in the file "filename". The "timeout" in seconds can be optionally specified. If not specified the timeout is 60 seconds. In addition to this timeout, it allows up to 5 seconds to connect to the web server. Secured (https) and unsecured (http) servers are supported. The variable HTTPERROR is set accordingly

Note: in secure mode, the web server must support one of the following SSL modes: SSLv3, TLS 1.0, TLS 1.1, TLS 1.2

getinistring

Syntax: getinistring variable filename section key <default>

This command reads a key from a Window ini file. Key "key" in section "section" in file "filename" is stored in variable "variable". "filename" must be fully-qualified. If the file, section or key does not exist and the optional parameter "default" is provided, then "variable" is set to "default" otherwise it is set to a blank string.

putinistring

Syntax: putinistring filename section key value

This command writes string "value" to key "key" in section "section" to the Window ini file "filename", which must be fully-qualified. The variable FILEERROR is set accordingly.

deleteinisection

Syntax: deleteinisection filename section

This command deletes the section "section" from the Window ini file "filename", which must be fully-qualified. The variable FILEERROR is set accordingly.

deleteinikey

Syntax: deleteinikey filename section key

This command deletes the key "key" from the Window ini file "filename", which must be fully-qualified. The variable FILEERROR is set accordingly.

inisectionexists

Syntax: inisectionexists filename section

This command tests if section "section" exists in the Window ini file "filename", which must be fully-qualified. The variable FILEERROR is set to "false" if it exists or "true" if it does not exist.

inikeyexists

Syntax: inikeyexists filename section key

This command tests if key "key" in section "section" exists in the Window ini file "filename", which must be fully-qualified. The variable FILEERROR is set to "false" if it exists or "true" if it does not exist.

email

Syntax:email to@address.com subjectline bodytext <attachmentfilename>

This command sends an internet e-mail to "to@address.com" with the subject set to "subjectline" and the body of the message set to "bodytext". An optional file attachment "attachmentfilename" can be specifed. If it is not a fully-qualified file, the variable IMAGEDIRECTORY is pre-pended to it.

The variable OUTGOINGEMAIL is used to specify the "from" address of the email. If the variable EMAILMESSAGEID is set, the message's InReplyTo header (used for email threading by the recipient's email client program). To send the message to more than one address, separate the individual addresses with a comma. The email settings must be set up before this command can be used (the SMTPSERVER, SMTPPORT, SMTPUSER, and SMTPPASSWORD variables). Unencrypted and SSL/TLS connections are supported. If an error occurs, the variable EMAILERROR is set to "true".

Note: in secure mode, the SMTP server must support one of the following SSL modes: SSLv3, TLS 1.0, TLS 1.1, TLS 1.2

emailfile

Syntax: emailfile to@address.com subjectline bodyfilename

This command sends an internet e-mail to "to@address.com" with the subject set to "subjectline" and the body of the message set to the contents of the text file "bodyfilename". The variable OUTGOINGEMAIL is used to specify the "from" address of the email. To send the message to more than one address, separate the individual addresses with a comma. The email settings must be set up before this command can be used (the SMTPSERVER, SMTPPORT, SMTPUSER, and SMTPPASSWORD variables). Unencrypted and SSL/TLS connections are supported. If an error occurs, the variable EMAILERROR is set to "true".

Note: in secure mode, the SMTP server must support one of the following SSL modes: SSLv3, TLS 1.0, TLS 1.1, TLS 1.2

checkemail

Syntax: checkemail <delele>

This command checks for incoming mail on a POP3 internet e-mail account. The email settings must be set up before this command can be used (the POP3SERVER, POP3PORT, POP3USER, and POP3PASSWORD variables). Unencrypted and SSL/TLS connections are supported. The oldest e-mail in the user's in box is read each time this command is used. If an e-mail has been received, the variable EMAILRECEIVED is "true" and the following variables are set:

  • EMAILFROMADDRESS: the e-mail address of the sender
  • EMAILREPLYTOADDRESS: the e-mail "Reply-To" header value
  • EMAILMESSAGEID: the unique e-mail message id value
  • EMAILSUBJECT: the e-mail subject line
  • EMAILBODY: the e-mail message body
  • EMAILATTACHMENT: the filename of the first attachment. Attachments are stored in the temporary directory (the TEMPDIRECTORY variable). If there were no attachments, this variable is empty. Note that only the first attachment can be accessed.

If the optional parameter "delete" is "true", the message is deleted from the inbox after it is read. If an error occurs, the variable EMAILERROR is set to "true".

Note: in secure mode, the POP3 server must support one of the following SSL modes: SSLv3, TLS 1.0, TLS 1.1