Testing Utility Functions

test config

Execute Tester Command ${rt_handle} command=test_control <additional key=value arguments>

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 runtime 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 the argument is `Mandatory`.

   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 savexml). For example::


                 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 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 test config function captures each HLTAPI function executed in a script, along with its parameters, and saves it to a log file:

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 vendorspecific 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:

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 "connect device=10.6.2.68 port_list {1/1 1/2}"
set status 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:

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:

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]
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: tasmanialinux SPIRENT_STH JMcLendon ::connect device=
10.6.2.68
port_list= {1/1 1/2}}
Wed Sep 10 10:58:59 AM Eastern Daylight Time 2008 [hltcall] ::connect
{device 10.6.2.68 port_list= {1/1 1/2}}
Wed Sep 10 10:58:59 AM Eastern Daylight Time 2008 [error] ::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
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:
::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]
{::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:

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

test control

Execute Tester Command ${rt_handle} command=test_control <additional key=value arguments>

Purpose:

Sets parameters for optimization and parsing.

Synopsis:

Note: M indicates the argument is `Mandatory`.

   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 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 precompilation 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:

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 builtin 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:

test control action=enable;    //To turn off the implicit apply
test control action=disable:   //To allow implicit apply
test control action=sync;      //To call apply explicitly
test control parser=CISCO;     //to use CISCO parser
test control parser=spirent;   //to use Spirent parser

Sample Output:

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

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

Note:

A Special Note on utracker

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