Some variable names are initialized at uCon startup...

- MYIP is loaded with the "dot" formatted IP address of the PC running uCon.

- INSTALLDIR is loaded with the directory into which uCon was installed.

- LINES is loaded (and reloaded when size changes) with the size (height in lines) of the console window.

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...

symbol relacement-text

symbol1 relacement-text1

symbol2 relacement-text2

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. Also refer to each of the various command help text 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:".

SET PROMPT Password:

SEND "els"# Send "els" and wait for the string "Password": to

# be sent by the target system.

SET PROMPT CLI:

SEND "els_pswd"# With the PROMPT shellvar changed, this SEND command

# waits for the string "CLI:" to complete.

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...

SET COUNT 0

# TOP_OF_LOOP:

GOSUB SHOW_COUNT

SET COUNT=$COUNT+1

IF $COUNT le 5 GOTO TOP_OF_LOOP

EXIT

# SHOW_COUNT:

ECHO Hello, the count is now $COUNT

RETURN

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...

Hello, the count is now 0

Hello, the count is now 1

Hello, the count is now 2

Hello, the count is now 3

Hello, the count is now 4

Hello, the count is now 5

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...

# TOP:

DIALOG Q_AND_A "Please enter a number between 1 and 4:"

IF $DIALOG lt 1 GOTO ERROR

IF $DIALOG gt 4 GOTO ERROR

DIALOG OK "Thanks!"

EXIT

# ERROR:

DIALOG YES_NO "Out of range, want to try again?"

IF $DIALOG seq YES GOTO TOP

DIALOG OK "Fine, just click OK to exit."

EXIT

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').

SET VAR1 Hello,

SET VAR2 my

SET VAR3 name

SET VAR4 is

SET VAR5 Fred

SET IDX 1

# NEXT:

ECHO $<}>

SET IDX=$IDX+1

IF $IDX lt 6 GOTO NEXT

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...

Hello,

my

name

is

Fred

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.

SET LOGFILE C:/tmp/log

SET PROMPT "uMON>"

LOG on $LOGFILE

SEND "tfs ls"

LOG off

FILE fstat $LOGFILE

IF $FSTAT sne FILE GOTO ERROR_1

SET LINE 3

SET COUNT 1

ECHO

# DUMP_FILES:

FILE token $LOGFILE 1 $LINE

IF $TOKEN seq \$TOKEN GOTO DUMP_DONE

ECHO " "FILE$COUNT: $TOKEN

SET LINE=$LINE+1

SET COUNT=$COUNT+1

GOTO DUMP_FILES

# DUMP_DONE:

ECHO OK, all finished!

EXIT

# ERROR_1:

ECHO Log file $LOGFILE not found

EXIT

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

uMON>tfs ls

Name Size Location Flags Info

app_01 196752 0xffe2412c Ec

app_go 68844 0xffe0005c bEc

monrc 354 0xffe10eac e

symtbl 77918 0xffe5421c

try 158 0xffe10dac e

Total: 5 items listed (344026 bytes).

uMON>

FILE1: app_01

FILE2: app_go

FILE3: monrc

FILE4: symtbl

FILE5: try

OK, all finished!

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.

EXAMPLE_6:

This example shows you how to make some noise when uCon starts up. We will build a script called startup_sound, and to make the script execute when uCon starts up we add that script name to the "StartScr" text box in the Config->Miscellaneous dialog. We also have to make a few assumptions about the environment for this...

The tool sndrec32 is located under C:\windows\system32 and some system .wav files are found under C:\windows\media (refer to the script below, and make appropriate changes if needed).

SET SOUND C:\windows\system32\sndrec32

SET MEDIA C:\windows\media\tada.wav

SYSTEM -pw "$<}>/embedding /play /close \"$<{>MEDIA<}>\""

As far as scripting goes, this is a simple example; however, it does demonstrate the use of the SYSTEM command, and provides a cute way to generate whatever sound is in a .wav file on your system.

Just in keeping with the examples above, now lets do something that uses the "FILE" command to step through all of the .wav files found in the C:\windows\media directory...

SET SOUND C:\windows\system32\sndrec32

SET MEDIA C:\windows\media\*.wav

FILE first $MEDIA

# NEXTFILE:

FILE next

if "$FILE" seq \$FILE EXIT

SYSTEM -pw "$<}>/embedding /play /close \"C:\windows\media\\$<}>\""

GOTO NEXTFILE

The output of the above script is audible. You'll hear the playing of each .wav file in the media directory. The important point here is to note that the "FILE first" and "FILE next" commands provide the ability to walk through a directory of files with a name filter (the above case uses *.wav).