Ixia Custom Engineering: FAQs

ICE Scripts Script Search FAQ's


FAQ's

ICE Frequently Asked Questions

This FAQ is intended to assist you in writing and debugging Tcl scripts for the Ixia platform, it has been created to help Tcl programmers with common problem solutions.
Select from the links below:

Common Mistakes/Issues

Error Message - writePortsToHardware: No ports in port list/map

<any command> : No ports in port list/map startTx: Error starting Transmission for port group
The port list created and passed to the routine is not setup correctly, or a $ is being used on the port list variable. See Chapter 6 in the Ixia Tcl Developers Guide for details on creating port lists. assume:
set portList {{1 5 1} {1 5 2} {1 6 1} {1 6 2}}
Correct:
ixWriteConfigToHardware portList
Incorrect:
ixWriteConfigToHardware $portList
ixWriteConfigToHardware {{1 5 1} {1 5 2} {1 6 1} {1 6 2}}

"Everything gets configured except my {route ranges, udfs, filters, streams, tcp}!!!"

If you try to configure something in a stream, port or other low-level Ixia command (the ones with the configs and cgets) with an incorrect value, the value is accepted but your set command will fail.

set ena 8
stream config -enable $ena
stream set 1 1 1 1

In this example, stream's enable option should be either a 1 or a 0. Here it was accidentally set to 8. The stream config command will accept the incorrect value of 8 initially. However, when the 'stream set' command comes, it notices it has an 8 value where it should have a 0 or a 1, and it will then return an error message. In this example, our chassis would be configured, but streams would be missing. To catch this, check the return value of the stream set command:

if {[stream set 1 1 1 1] } {
  puts "Error setting stream 1 on 1 1 1"
  return
}

Then run your script again and if it fails, you want to check every stream option that gets configured between stream setDefault and stream set and try to understand what values might be in variables. Sanity check them against the Tcl Developers guide and make sure that is a legal value for that option. If there is alot of logic inbetween, you can sprinkle the following line in the code and it will output the settings for a command (stream in this example) at various points in the script:

showCmd stream

or even better, put another text line in before you show the values so you can tell where you are in the script:

puts "After setting factory defaults:"
showCmd stream
.....
puts "Before configuring UDFs:"
showCmd stream

"Everything else gets configured except my abc setting on all {ports, streams, udfs}!!"

stream config -frameSize 64 stream
set 1 1 1 1

Doesn't do exactly what you think. The -frameSize option is actually -framesize. When you set a non-existant variable name, Tcl does not return an error but instead outputs:
Invalid configure option. Must be { -name -enable -region -numBursts -numFrames -ifg -ifgType -ifgMIN -ifgMAX -ibg -enableIbg -isg -enableIsg -gapUnit -percentPacketRate -rateMode -preambleSize -sa -saRepeatCounter -saMaskValue -saMaskSelect -da -daRepeatCounter -daMaskValue -daMaskSelect -framesize -frameSizeType -frameSizeMIN -frameSizeMAX -fir -fcs -patternType -dataPattern -pattern -frameType -numDA -numSA -dma -rxTriggerEnable -asyncIntEnable -loopCount -returnToId }

But! The 'stream set' will succeed. So even if you were checking the return value of stream set, your script would appear to run correctly but one item will not be configured correctly.

IF EVERYTHING IN A SCRIPT CONFIGURES EXCEPT ONE ITEM, CHECK THE SPELLING/CaPTiaLiZATioN OF THAT -OPTION IN THE DEVELOPERS GUIDE.

"I looked at the sample scripts but what does 'floss start' do? It's not documented anywhere!!"

Our sample scripts that come with ScriptMate aren't really useful to new users trying to learn Ixia Tcl. The problem is the samples set a bunch of stuff in an array called testConf, some other configuration, then at the end all you get is 'floss start' or 'tput start'. That is the ScriptMate design. Different parameters, same test logic. To trace the Tcl after this point:

Lets say we want to trace the Frame Loss script.
Open ixia/tclscripts/samplesstd/testFloss.tcl
At the bottom, you will see the 'floss start' command.
Since this was in samplesStd and it is an RFC 2544 test, we go to ixia/tclscripts/lib/ixtcl1.0/rfc2544/
And look for a script with a similar name. We find: frameloss.tcl
Open frameloss.tcl and scroll down to find a proc called floss_start.
That is the command that gets called when we call floss start.

ixia/tclscripts/samples*/test*.tcl These are all "parameter scripts" ixia/tclscripts/lib/ixTcl1.0.tcl This is the test logic that uses those parameters.



 Problem: The ITM application doesn't work. "When I execute the file, it pops up a window and justs sits there."

Some ITM Applications go into the test manager mode. Which looks like this:



This means that the the manger is opened but the actual script is not. To open the script, click on the icon with the 3 boxes together. Then click on the button that says “Launch selected tree item” which should be on the upper left hand corner. The icon looks like a window with a star close to the bottom. This will open up the actual application.

Tips and Tricks

Integrating Expect with Ixia Tcl Scripts

Background :
Expect is an incredibly useful tool that allows scripted applications to communicate with various command line interfaces to servers, switches and routers. Expect is popular with network administrators and QA test engineers for it's ability to automate network device configuration. Expect was born on Unix and it is only by the generous efforts of a few netizens that we can run Expect in Windows. Today, there are a few versioning problems one can run into trying to get Expect working with the latest versions of Windows. Here are the dependencies:

  • Tcl 8.0 is not supported on Windows 2000 and later Microsoft OSs.
  • Expect is not built for Windows for anything after Tcl 8.0.
  • Ixia chassis now ship with Windows 2000.
  • Ixia only runs supported TCL, meaning Tcl 8.3.

So if you install Expect for Windows, it will come 'built against' Tcl 8.0. If you try to move the Ixia ixTclHal1.0 library to the expect library directory, Expect will find ixTclHal, try to load it, and see that ixTclHal.dll requires tcl83.dll, which clashes with the tcl80.dll already in Expect. You will run into similar issues trying to move Expect libraries to the ixia/tclscripts/lib directory.

Even with those limitations however it is possible to have test scripts configure both the DUT and the Ixia chassis.

Quick Overview
The trick to getting Expect/Tcl8.0 to play with Ixia/Tcl8.3 is to use the Tcl exec command. Expect is actually run in another process. Ixia is running in Tcl8.3, it starts expect externally (via exec tclsh80.exe) so there are no library problems. The command line is used to pass arguments from one script to the other:

==Ixia Tcl Script==
# Load Ixia Package
# Connect to chassis
# exec tclsh80.exe to run your expect script.
# configure Ixia
# run test
# done

Detailed Overview
Install expect for Windows. I use the following. Although Expect is not formally supported in Win2k, I have used basic send/expect scripts on Win2k some time now with out problems.

Expect : http://bmrc.berkeley.edu/ftp/pub/winnt/tcltk/expect/expect-5.21r1b1-setup.exe

Add the expect bin directory to the PATH in System Properties.
After doing this step, you should be able to go to a MS-DOS prompt and type:
c:\>tclsh80

If you get the % prompt, the system can find Expect and so can Ixia's Tcl.

Create your Tcl script as normal. Even a ScriptMate test can be made to send configuration to the DUT before it runs.

Typical Ixia Script:
===========================


package req IxTclHal
ixInitialize 400-3895676

exec tclsh80.exe myexpectscript.exp param1 param2 param3
...
#rest of Ixia configuration + running the test
...
#end
===========================

Sample myexpectscript.exp:
===========================
# no IxTclHal needed here
# get command line arguments into variable
set vlanName [lindex $argv 0]
set vlanId [lindex $argv 1]
set ipAddress [lindex $argv 2]
# set some useful internal variables
set dutIp 192.168.3.33
set prompt "# "
spawn telnet $dutIp
expect "Login: "
send "admin\r"
expect "word: "
send "lab\r"
expect $prompt
send "create vlan $vlanName $vlanId $ipAddress"
expect $prompt
# continue configuring

NOTES

It is preferable to invoke expect with the expect tclsh80.exe for maximum compatibility. I have seen 'exec expect myscript.exp' work in Windows NT but not in Windows 2000. Changing to 'exec tclsh80 myscript.exp' seems to be the most compatible way.

It is possible to install TCL 8.0 on Win2k if you absolutely must, contact Ixia Support for details. Note that Ixia is not aware of any problems or any potential problems with this configuration, user assumes all risk, and Ixia does not officially support this configuration.

Adding Expect to the system PATH variable can sometimes interfere with TCLServer. TCLServer will report that it cannot find the Ixia TCL package. TCLServer seems to find the expect bin and lib directories first. Ixia is looking into this matter. However, if you are using TCLServer, you are typically already on Unix where there are no restrictions on using Expect and TCL together, i.e. you can start Ixia's TCL and load in the Expect package or you can start Expect and load in the Ixia package.

How can I put a custom payload into my packets from TCL?

It is possible to control the payload of the IP frame. The following TCL code will do that, untagged ethernet. If you have higher-layer protocols, the user pattern will be inserted after all protocol headers. The payload in the example is ICE in ASCII.



set hexData "49 43 45"

stream setDefault
stream config -dataPattern userpattern
stream config -patternType nonRepeat
stream config -pattern $hexData
stream config -framesize [expr [llength $hexData] + 12 + 4]

...

stream set $chas $card $port 1

Note you will need to change the [expr function] for the -framesize option if you want it to be correct for something besides untagged ethernet. This code auto-calculates the framesized based on the size of $hexData.

How can I get the data of a captured frame from TCL?

We can get to the frame payload from TCL once the frame is in our capture buffer. The frame contents are returned as a TCL list of bytes. Here is a sample that will print out the hex of the first 10 frames in the capture buffer, and decode out some fields. With TCL's lindex and lrange commands, it is possible to get portions of the frame at specific offsets very easily. Plus Ixia supports several decoders for common protocols like ip, tcp, udp, icmp, and more.

# get frames 1-10 from port 1 2 1
if {[captureBuffer get 1 2 1 1 10]} {
puts "Error getting frames 1-10 from port 1 2 1"
}
for {set i 1} {$i <=10} {incr i} {
# work with one frame out of the 10 we got from the port
captureBuffer getframe $i

# this copies the bytes of the frame to the TCL variable $frameData
set frameData captureBuffer cget -frame

puts "Frame $i:"
puts "$frameData"
puts "Dst MAC:[lrange $frameData 0 5]"
puts "Src MAC:[lrange $frameData 6 11]"
puts "Ethertype:[lrange $frameData 12 13]"
puts "First protocol byte:[lindex $frameData 14]"
}

When using Expect fork processing does not work correctly?

Forked processes exit via the exit command, just like the original process. Forked processes are allowed to write to the log files. If you do not disable debugging or logging in most of the processes, the result can be confusing.

Ixia takes over the exit proc and uses it to clean up only when done with any Ixia scripts. At the point we are done we put back the original exit procedure.

It is suggested not to use fork processing with the Ixia software. However if you do, you can use the exitOld command to end the child process clean.

How do run from an Icon scripts that source one or more other files ?

Here is a "useful" command line that should be included in scripts that source one or more other files:
cd [file dirname [info script]]
This will change to the directory where the main script resides, thus allowing you to run a script from an ICON on the desktop.

How do I configure a stream's rate with Interframe Gaps?

By default, -rateMode is set to useGap and the Gap Unit is in clock ticks. It's a good idea to set -rateMode anyways, then change the Gap Unit to gapSeconds, gapMilliSeconds, gapMicroSeconds, gapNanoSeconds, or gapClockTicks. With the right gap unit, now set -ifg with the gap unit you want.


stream get $chassis $card $port $streamId
stream config -rateMode useGap
stream config -gapUnit gapMilliSeconds
stream config -ifg 69.0


stream set $chassis $card $port $streamId
stream write $chassis $card $port $streamId

This will also work for the Inter-stream Gap (-isg) and the Inter-burst Gap (-ibg).

How do I configure a stream's rate using percent rate?

First set the rateMode for the stream to usePercentRate. Then specify the rate with the -percentPacketRate parameter.


stream get $chassis $card $port $streamId
stream config -rateMode usePercentRate
stream config -percentPacketRate 50.0


stream set $chassis $card $port $streamId
stream write $chassis $card $port $streamId

Natively, streams work in terms of gaps. -percentPacketRate is a convenient way to configure the framerate. It does the math and sets the IFG, ISG and IBG, factoring in the framesize, preamble size, and interface speed.



Connecting to the Chassis

After using ixInitialize to connect to a chassis, is it necessary to do an ixDisconnectFromChassis?

It's never necessary, just optional. There are several philosophies at hand here - if you're writing scripts that can be used either as stand-alone tests or in a batch-processing mode, then I would recommend that you preface each script as follows:

### this is my stand-alone OR batchable test script
package req IxTclHal
ixInitialize $myChassis
### here's my algorithm
cleanUp

In this case, you always connect to your chassis & at the end, you disconnect & clean up any extraneous Ixia globals that might be left hanging around.

However, if what you're doing is specifically writing scripts that will *always* be called in a batch fashion, then I would recommend that you connect just once, then source all your batch scripts (no ixInitialize req'd), then clean up at the end of the 'batch' script, ie:

### this is my batch file
package req ixTclHal
ixInitialize $myChassis
ixSource myNonBatchableTestFile1.tcl
ixSource myNonBatchableTestFile2.tcl
ixSource myNonBatchableTestFile3.tcl
cleanUp

and note that the files, "myNonBatchableTestFile1.tcl" (etc), do not require ixInitialize OR package req OR cleanUp. If I am running a set of scripts & ixInitialize is called at each script,can this cause any problem if ixDisconnectFromChassis is not used at the end of each script? Is there a limit on the number of connections that I can have from a tcl client to the server? This depends. If you're running on Unix/Linux, this could be a problem, as you will probably get a new ixTclServer connection for each ixInitialize. However, from a windows perspective, all ixInitialize does is chassis add (which doesn't do anything if you're already connected to the chassis) & then set the chassis ID to 1 (which would already be set by the previous ixInitialize). In other words, calling ixInitialize over & over again should have no affect on your overall system, assuming that you continue to connect to the same chassis over & over again.

That being said, if you do this:

ixInitialize chassis1
# do some stuff
ixInitialize chassis2

Now you could have some problems - ixInitialize currently assumes & sets the chassis id to 1; by not disconnecting from the chassis in between OR connecting to the chassis in a chain-like fashion (i.e., ixInitialize {chassis1 chassis2}), you 'step on' the first chassis id & now you can't ref it any more (i.e., you 'confuse' the underlying ixTclHal).

How to report an issue.

Is this a new script or something you have had for a while?

Did this script ever work? What was the last change you made?

Can you describe your problem in one sentence?

Can you write me a small script to demonstrate the problem? I need you to help me narrow this down.

What version of Ixia Software are you using?
What version of Tcl are you using?

Email support@ixiacom.com or call Ixia Support at 877.367.4942

Tcl Resources





 
 
Homepage | Sitemap | Contact Us | Privacy Policy | Terms Of Use | Ixia Suppliers