Using the Chariot

TCL API to Create a

Chariot Test
Application Note
Contents
Methodology/Approach............. 2
Creating the Test ....................... 2
An Example TCL Script............ 5
Conclusions ................................ 7

by James E. Robinson, III

North Carolina State Universitys Centennial Networking Lab
The TCL API (Tool Command Language Application
Programming Interface) for Chariot allows you to create custom
TCL scripts to automate Chariot test execution. The API allows
you to fully specify test parameters available in the Chariot
console. The objective of this application note is to demonstrate
how easy it is to create a Chariot test using the Chariot TCL API
and to begin the process of fully automating your testing tasks.

Using the Chariot TCL API

Methodology/Approach
We begin by describing the tools necessary to create and execute TCL scripts. Next, we examine the
criteria for creating a test. And finally, we look at a full example and cover it in moderate detail.

The Environment
As with any application development, you must first prepare your development environment. The
development environment consists of three things:
1. TCL Software Distribution
2. NetIQ Chariot TCL Library (Chariot is required to actually run the test)
3. Text Editor.
First, you need TCL, the Tool Command Language first developed by Sun Microsystems, and later
spun off as a startup company called Scriptics. The software is available free from
dev.scriptics.com/software/tcltk/8.0.html. Download TCL version 8.0.5 executable and follow the
installation instructions. The installation associates all files with .tcl and .tk file extensions with
the TCL interpreter. By naming your TCL scripts with a .tcl or .tk file extension, a simple doubleclick on a TCL script file will start execution.
Next, install the NetIQ Chariot TCL programming library, which is on the Chariot CD-ROM. Simply
copy the entire TCL library directory to a convenient place on your computers hard drive, such as
the directory where NetIQs Chariot is installed.
The last item you need is a text editor. You may use any editor that can write a plain text file. In
addition to many commercial editors, you may use notepad or wordpad, which are available with
the Microsoft Windows NT/2000 installation.

Goals Achieved
The goal of this application note is to demonstrate how easy it is to use the Chariot TCL API to create
and run a simple Chariot test. You will find that even a novice programmer will have no difficulty
creating a TCL script that will generate the same valuable results that are available from the GUIbased Chariot console.

Creating the Test

There are seven steps to creating and running a TCL Chariot test script.
1.
2.
3.
4.
5.
6.
7.

Load the Chariot TCL library.

Create a test.
Specify test run options.
Create pairs.
Run the test.
Save the test.
Execute the TCL test script.

2 Application Note, Copyright ? NetIQ Corporation 1999-2000.

Load the Chariot TCL Library

You load the Chariot TCL library by adding the installation directory to the TCL auto_path. Auto_path
is a TCL list that consists of directories that are searched when you request a library.
# Where you installed NetIQs Chariot
set NetIQ d:/netiq
# the library resides in d:/netiq/Chariot
lappend auto_path $NetIQ/Chariot
package require Chariot
global auto_index
eval $auto_index(Chariot)
Auto_index is a TCL array that is indexed by package name. The package name is added as an array
index during the package loading process. Evaluating the array index pre-loads all necessary files
required to use the library. Once loaded, all Chariot TCL API commands will be available for use.
Chariot requires TCL version 8.0.2 through 8.0.5; higher versions are not supported. Changes to later
versions of Tcl are not compatible with Chariots TCL extensions to C. (Two separate TCL Chariot
DLLs would need to be supported; that is, two separately-compiled TCL Chariot API DLLs would be
included in the distribution because of the drastic changes in Tcl between 8.0.5 and higher versions,
which is a little awkward and why it has not been done yet.)
Chariot allows dynamically loadable TCL extensions. The Chariot API for TCL is an extension for
TCL. If you are considering coexistence with other extensions (such as Expect), there should be no
problem in having other TCL extensions loaded at the same time.

Create a Test
Creating a test is very straightforward.
set mytest [chrTest new]
You now have a variable, mytest, which contains the handle, or identifier, of the new test. It is then
good practice to assign a filename to which the test configuration and results can be saved.
chrTest set $mytest FILENAME d:/netiq/results.tst

Specify Test Run Options

After you create a test, you can specify test options such as test duration as follows:
# first, get the handle/identifier for the tests run options
set runOpts [chrTest getRunOpts $mytest]
# then set the run options specifying a name/value pair
# we first change the test to run for a duration
chrRunOpts set $runOpts TEST_END DURATION
# next we specify the duration in seconds
chrRunOpts set $runOpts TEST_DURATION 60
With the test options set, you are ready for the next step adding endpoint pairs.

3 Application Note, Copyright ? NetIQ Corporation 1999-2000.

Create Endpoint Pairs

Recall that a Chariot test consists of endpoint pairs. An endpoint pair is fully specified by the
following:
??
??
??
??
??

Comment (optional): COMMENT

Endpoint 1 address: E1_ADDR
Endpoint 2 address: E2_ADDR
Network protocol type: PROTOCOL
Application script name

First, you create a endpoint pair handle.

set mypair [chrPair new]
With a endpoint pair handle created, you can then define the attributes of the pair. Assign the first
four values as follows:
chrPair
chrPair
chrPair
chrPair

set
set
set
set

$mypair
$mypair
$mypair
$mypair

COMMENT My first endpoint pair

E1_ADDR 10.1.1.10
E2_ADDR 10.1.2.10
PROTOCOL TCP

Next, you must specify the application script name. This is not the name of the TCL script; it is the
name of the Chariot application script. These script files have a .scr extension and fully specify the
traffic flow between two endpoints in a pair. You must supply the complete path to the application
script file.
chrPair useScript $mypair d:/netiq/Chariot/scripts/filesnds.scr
Lastly, you must add the pair to the test.
chrTest addPair $mytest $mypair
With the test defined and a pair associated with it, you are now ready to run the test.

Run the Test

To begin test execution, simply start the test with the following command.
chrTest start $mytest
The test will begin execution immediately.

Save the Test

You must wait until the test completes before you store the results. This can be accomplished by
creating a loop that periodically checks to see if the test has stopped before continuing.

4 Application Note, Copyright ? NetIQ Corporation 1999-2000.

set done

[chrTest isStopped $mytest]

# if it is not complete, wait on it

while { ! $done } {
# wait 5 seconds to see if it stops
set done [chrTest isStopped $mytest 5]
}
# then, save the test
chrTest save $mytest
With the test complete, you can save the results to the results.tst file specified when the test was
created. With the results saved, your basic TCL script is complete. You can use other commands to
query the results of the test. To free all resources associated with the test, one last command is
necessary.
chrTest delete $mytest
# exit the TCL script with success code (0)
exit 0
The TCL script is complete.

Execute the TCL Test Script

After completing the TCL test script, use the Windows Explorer to find the TCL script, and doubleclick on the name/icon. Assuming you havent made any typographical errors, when the TCL script
finishes execution you should be left with a Chariot test file that contains the test results. You can
then open this file using the Chariot console. If you are not familiar with the Chariot console, you
will see that in addition to the test results, also preserved in the test file is the complete test setup as
you specified in the TCL script! If you wish, you can run the test again from the Chariot console just
by clicking the Run Test icon.

An Example TCL Script

The entire TCL test script defined above is included in its entirety below:

5 Application Note, Copyright ? NetIQ Corporation 1999-2000.

# Where you installed NetIQs Chariot

set NetIQ d:/netiq
# the library resides in d:/netiq/Chariot
lappend auto_path $NetIQ/Chariot
package require Chariot
global auto_index
eval $auto_index(Chariot)
# create new test
set mytest [chrTest new]
# set filename for results file
chrTest set $mytest FILENAME d:/netiq/results.tst
# first, get the handle/identifier for the tests run options
set runOpts [chrTest getRunOpts $mytest]
# then set the run options specifying a name/value pair
# change the test to run for a duration
chrRunOpts set $runOpts TEST_END DURATION
# next specify the duration in seconds
chrRunOpts set $runOpts TEST_DURATION 60
set mypair [chrPair new]
chrPair
chrPair
chrPair
chrPair

set
set
set
set

$mypair
$mypair
$mypair
$mypair

COMMENT My first endpoint pair

E1_ADDR 10.1.1.10
E2_ADDR 10.1.2.10
PROTOCOL TCP

chrPair useScript $mypair d:/netiq/Chariot/scripts/filesnds.scr

chrTest addPair $mytest $mypair
chrTest start $mytest
set done

[chrTest isStopped $mytest]

# if it is not complete, wait on it

while { ! $done } {
# wait 5 seconds to see if it stops
set done [chrTest isStopped $mytest 5]
}
# then, save the test
chrTest save $mytest
chrTest delete $mytest
# exit the TCL script with success code (0)
exit 0

6 Application Note, Copyright ? NetIQ Corporation 1999-2000.

Conclusions
With a few lines of TCL, you can create a powerful test script that can fully automate tasks usually
performed using the Chariot console. For more information on the TCL commands available, refer to
the Chariot Programming Reference on the Chariot CD-ROM and in the Chariot Online Help. For
more sample TCL scripts, refer to the SDK directory on the Chariot CD-ROM.

This application note was created by James E. Robinson, III. James is a Senior Technical Staff Member
of North Carolina State Universitys Centennial Networking Lab in Raleigh, NC.
Technical assistance was provided by Scott Kavanaugh.

7 Application Note, Copyright ? NetIQ Corporation 1999-2000.