uCon supports the ability to run scripts.  This means that you can create command files that allow you to programmatically automate interaction with the device uCon is connected to.  The Scripts menu item supports the ability to create, edit, run, halt, pause, resume and even single-step a script.  The script can be run full speed or at a debug rate, where each non-comment line in the script must be approved by the user through a simple dialog box interaction.  A script can be run from the menu item Scripts->Run or through a function key or button whose "script" checkbox has been set.

CREATING A SCRIPT:
 A script is simply a file, so any editor that allows you to create  a non-formatted text file (like notepad, or vi or emacs) can be used  to create the script.  Within uCon the Scripts->Edit  and Scripts->New menu items will open up an editor on a current or new script respectively.  The default editor is Notepad; however, this  can be changed through the dialog box opened by the menu item Config->Miscellaneous  by modifying  the content of the "Editor" item within that dialog.   A script is simply a set of commands that build up some type of   interaction with the target connection (COM port, telnet, ssh, etc...).  The most typically used command is likely to be "SEND" because this is the command that sends  a string to the target.   For more information on each of the script commands, refer to the following list.  For a few quick examples refer to the examples below.

RUNNING A SCRIPT:
A script can be run through the Scripts->Run dialog box, or through a function key or button configured to access a script.  In either case, when the filename is specified, it can be a full path or just a filename.  If a full path is specified, the uCon will look for the script in the specified directory path.  If only a filename is specified, then uCon will look for that file under the scripts directory below the directory under which uCon was installed.  Typically this is X:/program files/ucon (with 'X' being a drive specification).
A script can also be paused.  This simply allows the user to tell the script runner to stop prior to starting the next command in the script.  Then, when in the paused state, the script can either be resumed or stepped.  Resume simply allows the script to continue and step tells the script running to execute the next command in the script and return to a paused state.

TRACING A RUNNING SCRIPT:
uCon's system trace facility allows the user to monitor the execution of the script.  Click the Config->SystemTrace menu item to open the system trace dialog box, and check the SCRIPTS check box.  Then, if the trace window is not visible (refer to main window for view of trace window), click the Toggle button in that dialog box to enable it.

---

COMMANDS:
 Following is the list of commands currently available for scripts (refer to uCon's built-in help text for more information):

·    BMPVIEW [-h:l:m:R:rT:t:w:] {imagefile name} {viewer tag}

·    CLS [-t]

·    COMPORT ['command']

·    CONNECT {connection_type} {connection-specific arguments}

·    DIALOG {dialog type} {user_message_string}

·    ECHO {any string}

·    EXIT [UCON]

·    FKEY [-bs] {1-16} {label} {text}

·    FILE {sub-command} {filename} [args] ...

·    FSEND [-d] {filename}

·    GOSUB {tag}

·    GOTO {tag}

·    IF {var1} {test} {var2} {ACTION} [else ACTION]

·    LOG {on|off|append} [file to log to]

·    MONCMD [-p:vw:] {target_ip_address} {"string_to_target"}

·    NEWMON [-A:B:b:p:vw:] {target_ip_address} {binary_image_file}

·    REGEX [-bcin] {regular expression} {test string}

·    RETURN

·    RUN {scriptname}

·    SEND [-cnp:rt:Tx] ["string_to_target"]

·    SET [-e] {VAR} {VAL | =EXPRESSION}

·    SLEEP {msecs}

·    SYSTEM {"cmdline"}

·    SOCKET [-acf:t:T:] {OPEN|CLOSE|READ|WRITE|FLUSH} {args}
         Interact with other socket based servers (superset of TCP command).

 ·    TCP [-ch:p:r]

·    TIME [-ef:s]

·    TITLE [string]

·    TFTP [-r:v] {server_ip} {get | put} {srcfile} {destfile} {netascii | octet}

·    XMODEM [-dnp:t:] {send | send1k | recv | recvcrc} {xmodem cmdline} {filename}

---

SHELL VARIABLES:
Shell variables are used in uCon's scripts the same way shell variables would be used in any other shell.  A variable is established either intrinsically (see below) or with the SET command, then the content of that variable can be accessed later by prefixing the name of the variable with a dollar sign ($).

Some variable names are dedicated to certain commands...


Some variable names are initialized at uCon startup...


Note that it is likely that the value of INSTALLDIR will contain the string "Program Files"; hence, when using $INSTALLDIR as an argument to a command, you will probably need to wrap it with double quotes so that it is treated as a single argument.

Most of the examples below use shell variables in some way, particularly, EXAMPLE_4 shows how shell variables can be nested to allow you to treat a set of variables as a table.

Note that the current set of established shell variables can be dumped to the console using the Scripts->Environment menu item.

---

SYMBOLS:
An extension to shell variables is the script runner's ability to process symbols.  Similar to the way a '$' is used to indicate a shell variable, a '%' (percent sign) is used to indicate a symbol.  Symbols are simply strings found in a symbol file (named by the content of the SYMFILE shell variable).  The format of the content of the symbol file is simply...


With this file pointed to by the SYMFILE shell variable, a script can include "%symbol" and it will be replaced with "replacement-text" at runtime.  Note this level of command line processing is only performed if the SYMFILE shell variable is set and points to a valid file.

---

---

---

EXAMPLES:
In each of the following examples, the content of the script is in  blue, fixed-width font  and the output of
the script is green, fixed-width font to distinguish it from the descriptive text (hopefully your browser will display it this way!).  Also refer to each of the various command's help text (within uCon) for additional examples applicable to that command.

---

EXAMPLE_1:
This first example demonstrates how a script is used to automate a login process using the SEND command and its ability to wait for a specified string (or prompt).  We assume that the target connected to the COM port is waiting for a login or user name, and after that username is entered the user must enter a password and if the password is correct, a system prompt will be presented.  The prompt used for the password is "Password:" and the system prompt  generated after the password has been entered is "CLI:". 

---

EXAMPLE_2:
The "programmability" mentioned earlier is provided by the "IF" command and the script's ability to deal with subroutines and branches.  Here is a simple example that will count (and echo that count) up to five...


The '#' is used in the script in two ways:

·    it indicates that all text after (and including) the '#" is not to be processed as a command
·    it is  used as GOTO and GOSUB labels.

Notice in example #1 that the '#' does not have to be at the beginning of a line, it can be at any point in the line to let the command parser know that no further processing of that line should be done.  If used as a label for GOTO or GOSUB, then it must be the first character of a new line and the label is the first block of non-whitespace after the initial '#' character.

This example also demonstrates the expression evaluation capability of the SET command.

The output of this script would be...

---

EXAMPLE_3:
This script demonstrates the use of the DIALOG command.  Assume we want to interact with the user to query for some number between 0 and 4..  This script will query the user, and respond if the input is out of range...

---

EXAMPLE_4:
This script demonstrates the use of nested shell variables.  It allows you to establish a set of shell variables and then use another variable as an index into the set (as if it was a table in 'C').


In the above script, the variables VAR[1-5] are created, and can be thought of as a 5-element table of words.  The loop below it uses $IDX to step through the table.  The output of this script would be...

---

EXAMPLE_5:
This script demonstrates the use of the FILE command and its ability to query file information and content for use in a script.  The script assumes that the target is running MicroMonitor, and that there are a few files in the monitor's file system.  In the nutshell, this script dumps the output of the MicroMonitor "tfs ls" command to a file (C:/tmp/log).  The presence of that file is verified by the first FILE command, then the content of that file is is queried by the second FILE command and acted upon using IF.


The ouput of the above script depends on the set of files currently in TFS; however, here is an example...


Note1: Some of the output is generated by the target and some is generated by the ECHO command in the script.

Note2: The "token" subcommand of FILE is useful for parsing whitespace delimited strings within a file.  If you need to parse something a bit more complicated, refer to the REGEX command.