Testing Utility Functions¶

sth::test_config¶

Purpose¶

Sets parameters for logging, debugging, and improving the performance of the entire Spirent HLTAPI.

Because each implementation of HLTAPI differs among vendors, debugging a script in HLTAPI can be a daunting task. HLTAPI implementations often are wrappers around the native vendors API and may not include much assistance for tracking down issues. The Spirent TestCenter HLTAPI contains extensive capabilities for tracking issues in the API as well as for optimizing the HLTAPI run-time execution. This document explains how to enable logging and optimize Spirent TestCenter HLTAPI functions as well as considerations for when to use the various options.

Synopsis¶

Note

M indicates that the argument is Mandatory .

sth::test_config
     [-log {1|0}  M]
     [-custom_path <path>]
     [-logfile <demoLogfile>]
     [-log_level <0-7>]
     [-vendorlogfile <string>]
     [-vendorlog {1|0}]
     [-hltlog {1|0}]
     [-hltlogfile <string>]
     [-hlt2stcmappingfile <string>]
     [-hlt2stcmapping {1|0}]

Arguments¶

-custom_path¶

Spirent Extension (for Spirent HLTAPI only).

Specifies a custom path for the traffic DB file, log files of Spirent HLTAPI, and .csv and XML configuration files (created by sth::create_csv_file and sth::savexml). For example:

sth::test_config\
 -log                      1\
 -logfile                  hlapiGen_bgp_logfile\
 -vendorlogfile            hlapiGen_bgp_stcExport\
 -vendorlog                1\
 -hltlog                   1\
 -hltlogfile               hlapiGen_bgp_hltExport\
 -hlt2stcmappingfile       hlapiGen_bgp_hlt2StcMapping\
 -hlt2stcmapping           1\
 -log_level                7\
 -custom_path             "c:/Tcl/lib/HLTAPI/TestBug/Untitled"

-hlt2stcmapping¶

Spirent Extension (for Spirent HLTAPI only).

Enables or disables the creation of a hlt2stcmapping.txt file. Valid values are 1 and 0. Specify the value 1 to generate a mapping file. Specify the value 0 if you do not want to generate this file. The default is 0.

-hlt2stcmappingfile¶

Spirent Extension (for Spirent HLTAPI only).

Specifies the name of the file into which to capture the mapping from each executed HLTAPI command to all commands that are Mandatory to implement that HLTAPI command. The default file name is “hlt2stcmapping.txt”. You can change the name of the mapping file to anything you like.

-hltlog¶: Enables or disables the creation of an hltlog.txt file. Valid values are 1 and 0. Specify the value 1 to generate an hltlog.txt file. For Spirent HLTAPI, this file contains all of the HLTAPI commands executed. Specify the value 0 if you do not want to generate this file. The default is 0. The hltlog.txt file contains all executed commands (both HLTAPI and Spirent HLTAPI) and up to seven levels of log messages, depending on your setting for the -log_level argument. You can change the name of the log file using the -hltlogfile argument.

-hltlogfile¶: Specifies the name of the file into which to capture all HLTAPI commands executed during your test run. The default file name is “hltlog.txt”. You can change the name of this file to anything you like.

-log¶: Enables or disables logging. Valid values are 1 and 0. Specify the value 1 to generate a log.txt file. Specify the value 0 to disable logging. If you disable logging, all logging features are also disabled. The default is 0. The log.txt file contains all executed commands (both HLTAPI and Spirent HLTAPI) and up to seven levels of log messages, depending on your setting for the -log_level argument (see -log_level).

-logfile¶: Specifies the name of the file into which to capture both HLTAPI and Spirent HLTAPI executed commands as well as other log messages determined by the log level you set in the -log_level argument. The default file name is “log.txt”. You can change the name of the log file to anything you like.

-log_level¶

Specifies the level of messages to be captured in the hltlog.txt file. These levels, as defined by the Cisco HLTAPI specification, are:

emergency  0
alert      1
critical   2
error      3
warn       4
notify     5
info       6
debug      7

Set the log level to n, where 0 <= n <= 7.

-vendorlog¶: Enables or disables the creation of an vendorlog.txt file. Valid values are 1 and 0. Specify the value 1 to generate an vendorlog.txt file. Specify the value 0 if you do not want to generate this file. The default is 0.

-vendorlogfile¶: Specifies the name of the file into which to capture all Spirent HLTAPI commands executed during your test run. The default file name is “vendorlog.txt”. You can change the name of the vendor log file to anything you like.

Arguments Unsupported by Save as HLTAPI¶

None

Return Values¶

Depending on the specific language that HLTAPI uses, the function returns a keyed list/dictionary/hash (See Introduction for more information on return value formats) using the following keys (with corresponding data):

status         Success (1) or failure (0) of the operation.
log            An error message (if the operation failed).

Description¶

The sth::test_config function enables you to set logging options for capturing commands executed by HLTAPI, Spirent TestCenter, or both. It also enables you to capture the following types of messages: alerts, critical, error, warning, notification, information, and debug.

The following sth::test_config function captures each HLTAPI function executed in a script, along with its parameters, and saves it to a log file:

sth::test_config -log 1 -hltlog 1 -hltlogfile <mylogfile >

You must set log to 1 to enable logging. Set the hltlog parameter to 1 to capture the HLTAPI API calls (both vendor-specific and standard) in your test script. Use the -hltlogfile parameter to specify the name of the file to contain a log of the HLTAPI functions executed during the test run. The log file name is automatically appended with the suffix “.txt” and written to the current working directory. Each time you use this function, it overwrites the previously generated log file.

Note

This function does not capture the logic flow of the executed functions. Each function is recorded as it is invoked. To record the process flow, use the function described in “Capturing and Logging the Logic Flow” below.

Examples¶

Sample Input:

sth::test_config    -log 1\
                -logfile demoLogfile \
                -log_level 7\
                -vendorlogfile stcExport\
                -vendorlog 1\
                -hltlog 1\
                -hltlogfile hltExport\
                -hlt2stcmappingfile hlt2StcMapping\
                -hlt2stcmapping 1

Sample contents of an HLT log file:

puts "source hltapi_5.10_stc_2.10.tcl"
source  hltapi_5.10_stc_2.10.tcl
#puts "package require SpirentHltApi"
#package require SpirentHltApi

puts "sth::connect -device 10.6.2.68 -port_list {1/1 1/2}"
set status [sth::connect -device 10.6.2.68 -port_list {1/1 1/2}]
puts $status

puts "after 2000"
set status [after 2000]
puts $status

Use the following function to capture each Spirent TestCenter API executed in a script, along with its parameters, and save it to a log file:

sth::test_config -log 1 -vendorlog 1 -vendorlogfile <abc>

You must set -log to 1 to enable logging. Set the -vendorlog parameter to 1 to capture the Spirent TestCenter API calls in your test script. Use the -vendorlogfile parameter to specify the name of the file to contain the logged functions. The log file name is automatically appended with the suffix “.txt” and written to the current working directory. Each time you use this function, it overwrites the previously generated log file.

Note

This function does not capture the logic flow of the executed

functions. Each function is recorded as it is invoked. To record the process flow, use the function described in “Capturing and Logging the Logic Flow.”

Sample vendor log file contents:

puts "package require SpirentTestCenter"
package require SpirentTestCenter
#puts "source SpirentTestCenter.tcl"
#source SpirentTestCenter.tcl

::stc::create project -under system1

puts "::stc::connect 10.6.2.68"
set status [::stc::connect 10.6.2.68]
puts $status

puts "::stc::create Port -under project1 -location 10.6.2.68/1/1 -name
10.6.2.68-1-1"
set status [::stc::create Port -under project1 -location 10.6.2.68/1/1
-name 10.6.2.68-1-1]
puts $status

puts "stc::sleep 2"
set status [stc::sleep 2]
puts $status

puts "stc::get system1 -children-physicalChassisManager"
set status [stc::get system1 -children-physicalChassisManager]
puts $status

puts "stc::get physicalchassismanager1 -children-physicalChassis"
set status [stc::get physicalchassismanager1 -children-physicalChassis]
puts $status

puts "stc::get physicalchassis1 -hostname"
set status [stc::get physicalchassis1 -hostname]
puts $status

Use the following function to capture the internal processing steps of each function in a Spirent TestCenter API script, and save it to a log file:

sth::test_config -log 1 -logfile <abc>

Set the log parameter to 1 to enable logging Spirent TestCenter API functions. Set it to 0 to disable logging. Use the logfile parameter to specify the name of the file to contain the processing steps. The log file name is automatically appended with the suffix “.txt” and written to the current working directory. Each time you use this function, it overwrites the previously generated log file.

Note

This function does not capture the logic flow of the executed HLTAPI functions. It only records the internal processing steps in the order in which they occur.

Sample Output:

Sample processing log file contents::

############# Spirent HLTAPI Log File #############
Wed Sep 10 10:58:59 AM Eastern Daylight Time 2008 [debug]
sth::connect -device 10.6.2.68 -port_list {1/1 1/2}
Wed Sep 10 10:58:59 AM Eastern Daylight Time 2008 [warn] Utracker
package not loaded!!. Message not sent.
Wed Sep 10 10:58:59 AM Eastern Daylight Time 2008 [debug] Sent utraker
Msg: tasmania-linux SPIRENT_STH JMcLendon ::sth::connect {-device
10.6.2.68
-port_list {1/1 1/2}}
Wed Sep 10 10:58:59 AM Eastern Daylight Time 2008 [hltcall] ::sth::connect
{-device 10.6.2.68 -port_list {1/1 1/2}}
Wed Sep 10 10:58:59 AM Eastern Daylight Time 2008 [error] ::sth::connect
{-device 10.6.2.68 -port_list {1/1 1/2}}
Wed Sep 10 10:58:59 AM Eastern Daylight Time 2008 [debug] {Calling
sth::connect}
Wed Sep 10 10:58:59 AM Eastern Daylight Time 2008 [info] {Generating
session table}
Wed Sep 10 10:58:59 AM Eastern Daylight Time 2008 [info] {Calling:
::sth::Session::processConnectDevice}
Wed Sep 10 10:58:59 AM Eastern Daylight Time 2008 [info] {Calling
processConnectDevice}
Wed Sep 10 10:58:59 AM Eastern Daylight Time 2008 [stccall] ::stc::connect
10.6.2.68
Wed Sep 10 10:58:59 AM Eastern Daylight Time 2008 [error] ::stc::connect
10.6.2.68
Wed Sep 10 10:58:59 AM Eastern Daylight Time 2008 [debug] ::stc::connect
10.6.2.68
Wed Sep 10 10:59:02 AM Eastern Daylight Time 2008 [info] [doStcConnect]
::stc::connect 10.6.2.68 PASSED.
Wed Sep 10 10:59:02 AM Eastern Daylight Time 2008 [debug]
{::sth::sthCore::doStcConnect: Chassis: 10.6.2.68: Status: 1}
Wed Sep 10 10:59:02 AM Eastern Daylight Time 2008 [debug] Connected to
chassis: 10.6.2.68
Wed Sep 10 10:59:02 AM Eastern Daylight Time 2008 [info] {Successfully
completed processing switch: device for HltCmd: Connect}

When using the logging functions described in this document, you may notice that several other log files are created by Spirent TestCenter. Before reporting bugs, put the following statement at the beginning of your script and execute the script:

sth::test_config -log 1 -vendorlog 1 -hltlog 1 -log_level 7

After the error occurs, open a service request (SR), attach all of the following files to it, and email it to the person responsible for handling the SR.

log.txt
vendorlog.txt
hltlog.txt
bll.log
<chassis_ip_address>.log

End of Procedure Header

sth::test_control¶

Purpose¶

Sets parameters for optimization and parsing.

Synopsis¶

Note

M indicates that the argument is Mandatory .

sth::test_control
     [-action {enable|disable|sync}  M]
     [-parser {cisco|spirent}]

Arguments¶

-action¶

Specifies the action to take on the specified port handles. Possible values are:

enable     Enable optimization (that is, disable the
           implicit "apply" inside of each HLTAPI
           command).

disable    Do not enable optimization (that is, allow
           the implicit "apply" inside of each HLTAPI
           command).

sync       Applies the configuration created in HLTAPI to
           the card.

You must specify an action. There is no default.

-parser¶

Specifies which parser you want Spirent HLTAPI to use. Possible values are:

cisco    Use the Cisco parser function (parse_dashed_arg)
         for parsing. It is  slower but more sophisticated
         than the Spirent parser.

spirent  Use the Spirent parser function
         (parse_dashed_args) for parsing. It is simpler and
         faster than the Cisco parser.

The default is “cisco”.

Arguments Unsupported by Save as HLTAPI¶

None

Return Values¶

Depending on the specific language that HLTAPI uses, the function returns a keyed list/dictionary/hash (See Introduction for more information on return value formats) using the following keys (with corresponding data):

status         Success (1) or failure (0) of the operation.
log            An error message (if the operation failed).

Description¶

The sth::test_control function enables you to control optimization settings and choose whether to use the Cisco or Spirent parser during test runs.

The function returns a status value (1 for success). If there is an error, the function returns the status value (0) and an error message.

You can speed up the execution of your HLTAPI test script in two ways. In some cases, these methods provide substantial reductions in test times.

Using the Spirent Parser

Cisco Test Technologies supplies all HLTAPI vendors with a command line parser for use in their implementations of HLTAPI. Spirent has developed an equivalent parser that uses a pre-compilation technique to reduce the amount of time spent parsing the command line parameters.

To use the Spirent parser, add the following command to your test script:

sth::test_control -parser spirent

Using Command Caching

Most HLTAPI vendors have a control to enable command caching. Command caching reduces test times by caching commands until they are needed by the test system. When command caching is enabled, a command may not be sent to the ports until several subsequent command have been issued. Therefore, we recommend that you use command caching only on scripts that have been debugged and are working correctly.

To enable command caching, use the following function:

sth:test_control -action enable

Debugging a Test Script

If you do not use an HLTAPI function properly, the system returns an error. Each error description usually explains that the function failed and indicates the correct usage of the function.

When you are running a test script, it can be difficult to detect which function failed. Including “puts” statements in the test script can narrow the problem area, because you can see the output at each point in the script where a puts statement occurs. You can also use the built-in stack trace by calling set errorInfo, or type in the functions one at a time.

Currently, each API function returns an appropriate error message indicating if it encountered a problem but also returns a 1 if the operation completed successfully. So, you can write code around each HLTAPI function call that tests to see if it completed successfully.

Examples¶

Sample Input:

sth::test_control -action enable;    //To turn off the implicit apply
sth::test_control -action disable:   //To allow implicit apply
sth::test_control -action sync;      //To call apply explicitly
sth::test_control -parser CISCO;     //to use CISCO parser
sth::test_control -parser spirent;   //to use Spirent parser

Sample Output:

#On success
{status 1} {log {}}

#On failure
{status 0} {log {<errorMsg>}}

Utracker is a command utility supplied by Cisco Test Technologies that does internal usage tracking of HTLAPI. When you start Spirent TestCenter HLTAPI, you may see an error message indicating that the utracker package is not installed. The presence or absence of the utracker package does not affect the processing within Spirent TestCenter HLTAPI. Please ignore this message.

End of Procedure Header