The Table below lists the Tcl API commands and their usage.
|
(Additional Information in Object, Attribute, and Relation References) |
Additional Information in Object, Attribute, and Relation References) |
ALL CAPS (upper case) indicates a parameter (i.e. an argument of specific type or list of literal values).
Mixed upper and lower case indicates literal text.
Brackets [ ] indicate required arguments. (e.g. [ only | one | of | these | is | required ] )
Less than and greater than symbols < > indicate optional arguments.
Within [ ] or < >, the | symbol indicates the OR operator.
Slash indicates continues on next line.
Three dots (...) indicate a repeating pattern of previous elements.
command REQUIRED_PARAMETER <OPTION_PARAMETER>
ls::multiLine -RequiredLiteralText RequiredLiteralText \
[ OneOfThese | IsRequired | THIS_ONE_IS_PARAMETER]
ls:command < -optionalLiteral > < -nextOneRequiredIfThisIncluded VALUE >
command REQUIRED < OPTIONAL_REPEATED_PARAMETER &. >
This command sets or modifies one or more object attributes, or a relation.
config HANDLE -ATTR VALUE < <-ATTR VALUE > ...>
config HANDLE -DAN_PATH VALUE
< <-DAN_PATH VALUE > ...>
config DDN_PATH -ATTR VALUE < <-ATTR
VALUE > ...>
config DDN_PATH -DAN_PATH VALUE < <-DAN_PATH
VALUE > ...>
config HANDLE | DDN_PATH -child-NAME HANDLE2
Parameter |
Description |
HANDLE |
The object handle that identifies the object to be modified. |
-ATTR VALUE |
An attribute name-value pair. The -ATTR portion of the pair is the name of the attribute to be modified. The attribute name must start with a dash (-). The VALUE portion specifies the new value. You can specify one or more name-value pairs in a single function call. The attribute name and value must be separated by a space; each name-value pair in a sequence must be separated by a space.
|
DDN_PATH |
A dotted path name sequence that begins with an object handle, followed by one or more child object names. The path must identify a valid sequence of objects in your test hierarchy. Landslide returns data for the object identified by the last name in the sequence. Use index values to identify one of a set of children of the same type. Index values are assigned in order of creation. An unqualified type name (a name with no index value) indicates the first child object of that type for the parent.
|
DAN_PATH |
A dotted path name beginning with a sequence of one or more child object names, and ending with an attribute name. Landslide combines the objectHandle (or the directDescendantPath) with the descendantAttributePath to resolve the attribute reference.
|
-children-NAME HANDLE2 |
Assigns the object referenced by HANDLE2 as the NAMEd child of this object (HANDLE). The reference can include a DAN path (-DAN_PATH.children-NAME).
|
The config function sets or modifies the value of one or more object attributes. You can also use the config function to modify relations. Note that if you attempt to modify an attribute for a read-only object, the config function raises an exception. When you modify object attributes, use name-value pairs and specify the attribute name with a dash (-) prefix. For example:
ls::config $myTest -duration 240
You can use Direct Descendant Notation (DDN) to identify the object, and Descendant Attribute Notation (DAN) to identify the attribute. For example:
ls::config $myTest.ReportOptions -format $ls::FORMAT_XLS
ls::config $myTest -ReportOptions.PerSession false
A DDN path is a dotted path name sequence. The sequence begins with an object handle, followed by one or more child object names. The path must identify a valid sequence of objects in your test hierarchy.
A DAN path is a dotted path name beginning with a dash (-), followed by a sequence of one or more child object names, and ending with an attribute name. Landslide combines the handle (or the DDN_PATH) with the DAN_PATH to resolve the attribute reference. The path must identify a valid sequence of objects in your test hierarchy. In both DDN and DAN paths, a child object name may have an index suffix (an integer in parenthesis) to reference one of multiple children of the same type. For example:
ls::config $myTest.Step(0) -tsIndex 0
ls::config $myTest -Step(2).tcIndex 1
For more information about these notations, see Referencing Objects: Object Paths.
None. Errors are raised as exceptions; encoded as string values that describe the error condition.
ls::config $myTest -duration 1000
ls::config ApiOptions -LogLevel $ls::LOG_MINOR -StdOutLogging true
ls::config $myTest.TsGroup(1).Tc(3) -name "MIP 1000 Sessions TC"
This command creates one or more Landslide Tcl API objects.
create [ TOP_LEVEL_OBJECT_TYPE ] <[-ATTR VALUE] ...>
create [ OBJECT_TYPE | CHILD_NAME ] -under HANDLE <[-ATTR VALUE] ...>
create [ OBJECT_TYPE | CHILD_NAME ] -under
DDN_PATH <[-ATTR VALUE] ...>
create OBJECT_TYPE -under HANDLE <[-DAN_PATH VALUE] ...>
create <-PARAM_TYPE->PARAM_NAME -under [ PARAMETERS_HANDLE |
PARAMETERS_OBJECT_PATH ]
Parameter |
Description |
OBJECT_TYPE or CHILD_NAME |
The name of the type of object(s) to be created. (For the names of the objects, see the diagram of the Landslide object hierarchy.) You can specify a path name in place of a single child object name. The path name is a sequence of child object names, separated by dots (.). The sequence must describe valid parent-child relationships in your test hierarchy. When you specify a path name, Landslide creates all of the objects specified in the path sequence. For more information, see Object, Attribute, and Relation References. |
-under HANDLE |
Specifies the handle of the parent for the newly created object. The type of object that you create must be appropriate for the parent object. You must specify the -under attribute when you create any object except for the top level objects. When you are creating a child object, use the -under attribute to specify the handle to the parent object. |
-ATTR VALUE -DAN_PATH.ATTR VALUE
|
An attribute name-value pair. The -attr portion the pair is the name of the attribute to be modified. The attribute name must start with a dash (-). The value portion specifies the new value. You can specify one or more name-value pairs in a single value pair function call. The attribute name and value must be separated by a space; each name-value pair in a sequence must be separated by a space. You can specify a Descendant Attribute Notation (DAN) path ending in an attribute name-value pair. The path name is a sequence of child object names (ending with an attribute name), separated by dots (.). The sequence must describe valid parent-child relationships in your test hierarchy, ending with the name of an attribute for the last object in the path. When you specify a path name, Landslide creates all of the objects specified in the path sequence and sets the attribute. For more information about path specification, see Object, Attribute, and Relation References. For detailed information on object definitions, including the valid parent-child relations, refer to the Landslide Tcl API Object and Perform Function Reference.
|
<-PARAM_TYPE->PARAM_NAME |
A test case parameter type/class and parameter name. If the parameter type/class is not specified, a basic parameter is created. See the Parameters object section in the Landslide Tcl API Object and Perform Function Reference for more detailed information.
|
The create function creates one or more Landslide API objects. When you call the create function, you specify the type(s) of one or more objects to be created. You can specify:
An object type (such as the TestSession object or the Dmf object). For example:
ls::create TestSession
ls::create Step -under $myTest
A DDN Path. To specify a path name, use dotted notation. A path name is a sequence of child object names that form valid parent-child relationships in your test hierarchy, extending from the object identified by handle. In the following example, Landslide creates an AutoFill object as the child of a DMF Message object.
ls::create Command(2).ClientMessage.AutoFill -under $dmf
For information about path name specification, see Object, Attribute, and Relation References. Usually, when you create an object, you must specify the -under attribute to supply a parent for the newly created object. (The TestSession and Dmf objects, shown in the syntax specification above, are the exception to this rule.) The value of the -under attribute is the object handle returned by the create call that created the parent object, or a handle retrieved by calling get. The parent object must be the correct type for the object that you create. (If you specify a DDN path, the parent object must be the correct type for the first object type in the path sequence.) When you create an object, you can also set the object attributes at the same time. To set attributes, specify one or more attribute name-value pairs.
If you specify name-value pairs when you also specify a DDN path, Landslide applies the attribute values to the object associated with the last name specified in the DDN path. In the following example, Landslide creates an AutoFill object as a child of the ClientMessage object. When Landslide creates the AutoFill object, it sets the -typeId to 4, the formatId attribute to 4 and the offset attribute to 33.
ls::create AutoFill -under $dmf.Command(2).ClientMessage -typeId 4 \
-formatId 4 -offset 33
You can specify a Descendant Attribute Notation (DAN) path as part of the attribute reference. Landslide uses the specified child object name to create the primary object, and the DAN path to modify the attributes of any additional child objects. The path must specify a valid descendant path extending from the primary object. Landslide will create the primary object, the objects identified in the path, and then set the referenced attribute of the last object in the path. In the following example, Landslide creates a Command object (the primary object), then it also sets the auto-created ClientMessage object's type attribute.
ls::create Command -under $dmf -ClientMessage.type ls::DMF_MSG_TYPE_REQUEST
For information about path name specification, see Object, Attribute, and Relation References.
The create function returns the object handle for the object specified in the function call. (The create function returns only the handle for the primary object that is created. To obtain the handles for any descendant objects that are created, use the get function to retrieve the child objects.)
set test [ls::create TestSession -name test1]
set step [ls::create Step -under $myTest]
set tsgroup1 [ls::create TsGroup -under $myTest]
set start_subflow [ls::create SendEvent -under $dmf.Command(2)
\
-eventId 1 -targetId 2 ]
ls::create -TestNode-NetworkHostLocalAddr -under $parameters
This command deletes / removes a child object from a parent object. Auto-created child objects cannot be deleted. When you delete items in a collection, any handles that you have to the remaining items may become invalid. You should use the get command to refresh those handles.
delete CHILD -under HANDLE
delete CHILD -under DDN_PATH
delete [ TestSession | TestCase | Dmf ] LIBRARY_TYPE LIBRARY_VALUE NAME
Parameter |
Description |
CHILD |
The name of the child object. Index notation is allowed to specify which object in a collection to remove. |
-under HANDLE |
Specifies the handle of the parent for the child object. You must specify the -under attribute when you delete any object. |
-under DDN_PATH |
Specifies the DDN Path to the handle of the parent for the child object. You must specify the -under attribute when you delete any object. |
LIBRARY_TYPE |
The library identification, which can be one of the following: -customLibraryName -systemLibraryName -userLibraryName -libraryId |
LIBRARY_VALUE |
The name or id of the library, based on LIBRARY_TYPE, where the test suite items will be imported. Required for user created test suites, not allowed for official test suites. |
The delete command returns nothing if the command is successful.
ls::delete Tc -under $test.TsGroup(1)
ls::delete AutoFill(5) -under $command.ClientMessage
ls::delete Route -under $portReservationEntry
This command deregisters the callback for a specific event.
ls::deregister EVENT [ [ -TYPE HANDLE ] <&> ]
ls::deregister EVENT -TestSession TEST_SESSION_HANDLE
This table lists the events for which you can register:
Event |
Description |
TestStateChanged |
Called when the overall test state or step changes. |
TestCaseStateChanged |
Called when a test case changes state. |
TestCompleted |
Called when a test completes. |
IntervalOccurred |
Called when an interval occurs. |
None, if successful; returns a Tcl error on failure.
%ls::deregister Testcompleted -testSession $myTest
%ls::deregister TestCaseStateChanged -TestSession TEST_SESSION_HANDLE \
-ts TS_INDEX -tc TC_INDEX
This command disconnects from a running test.
ls::disconnect -TestSession TEST_SESSION_HANDLE
None, if the disconnect is successful; returns a Tcl error on failure.
% ls::disconnect -TestSession $myTest
%
This command returns the value(s) of one or more object attributes or a set of object handles.
get [ HANDLE | DDN_PATH ] < -ATTR <...>>
get [ HANDLE | DDN_PATH ] < -DAN_PATH <...>>
get [ HANDLE | DDN_PATH ] -children <...>
get [ HANDLE | DDN_PATH ] [ -children-NAME | -children-NAME(INDEX) ]
Parameter |
Description |
HANDLE |
The object handle that identifies the object to be modified.
|
-ATTR |
An attribute name. The attribute name must start with a dash (-).
|
DDN_PATH |
A dotted path name sequence that begins with an object handle, followed by one or more child object names. The path must identify a valid sequence of objects in the object hierarchy. Landslide returns data for the object identified by the last name in the sequence. Use index values to identify one of a set of children of the same type. Index values are assigned in order of creation, 0-based. An unqualified type or child name (a name with no index value) indicates the first child object of that type for the parent.
|
DAN_PATH |
A dotted path name beginning with a sequence of one or more child names, and ending with an attribute name. Landslide combines the HANDLE (or the DDN_PATH) with the DAN_PATH to resolve the attribute reference.
|
-children-NAME |
The name of the child object. This form returns all the objects that have the same name/type. In most cases the child object's name is the same as its type. For example a ReportOptions child of a TestSession object is of type ReportOptions. However, the PhySubnet child of the Reservation object is of type TsPhyInfo and for this you would use PhySubnet to get the TsPhyInfo child. (See the Landslide Tcl API Object and Perform Function Reference for more information).
|
The get function returns the value of one or more object attributes, or, in the case of child references, one or more object handles.
The handle identifies the object from which data will be retrieved. If you do not specify any attributes, Landslide returns the values for all attributes defined for the object.
NOTE: If you specify a DDN path, you must specify one or more attributes. |
The ATTR identifies an attribute for the specified object.
The DAN_PATH (Descendant Attribute Notation path) is a dotted path name beginning with a dash (-), followed by a sequence of one or more child object names, and ending with an attribute name. A child object name may have an index suffix (an integer in parenthesis) to reference one of multiple children of the same type. Landslide combines the handle (or the DDN_PATH) with the DAN_PATH to resolve the attribute reference. The path must identify a valid sequence of objects in your test hierarchy.
For example:
ls::config $myTest -ReportOptions.perInterval false
Landslide combines the object and attribute specifications to retrieve the value of the active attribute for the first Port object child of $myTest.
The DDN_PATH (Direct Descendant Notation path) is a dotted path name sequence. The sequence begins with an object handle, followed by one or more child object names. The path must identify a valid sequence of objects in your test hierarchy. When you use DDN, you must specify one or more attributes. Landslide returns data for the object identified by the last name in the sequence. For example:
ls::get $myTest.TsGroup(0).Tc(1).Parameters.StartRate Value
In this case, Landslide returns the value of the Value attribute for the StartRate parameter of the second test case on the first test server group of the TestSession object $myTest.
If there is more than one instance of a particular named child of the specified object, you can use index notation. Landslide assigns index values in order of object creation. For example:
ls::get $myTest.TsGroup(2)
Landslide returns the attributes for the third TsGroup object child of the specified TestSession object. If no index is specified when referencing a child path that has multiple instances, index 0 is implied. For example:
ls::get $myTest.TsGroup
When you use a relation to retrieve the handles of child objects, you can specify a child object name to filter the set of objects, including indexes. For example:
ls::get $myTest.TsGroup(0) -children-Tc
This function call returns a list of name-handle(s) for all the Tc (TestCase) child object(s) of the first TsGroup of the $myTest TestSession object. Or:
ls::get $myTest.TsGroup(0) -children-Tc(1)
This function call returns the handle for the second Tc (TestCase) child object of the first TsGroup of the $myTest TestSession object.
When you specifically retrieve one attribute, get returns just the value. If you retrieve more than one attribute, get returns a list of name-value pairs of all attributes and values. If you do not specify any attributes, the get function will return all attributes and child references for the object.
When the get function returns a list of name-value pairs, Landslide returns a list of lists of two strings. Each attribute name and its value is in its own list:
{ {Name user1} {Type eth} .. {Version 1.4.5 } }
If there are any child objects, the last item in the outermost list will be a list starting with "children" and ending with a sublist of name-handle lists:
{ {Name name}.. { children {{ ReportOptions java0x9 }{ Step0 java0xa } { Step1 java0xb } { TsGroup0 java0xc }}}
When you specify the "-children" reference, the get function returns a list of name-handle pairs:
{{ ReportOptions java0x9 }{ Step0 java0xa } { Step1 java0xb } { TsGroup0 java0xc }}
If you specify a single child, (e.g. -children-TsGroup(0)), the get function returns just the handle:
java0xc
Errors are raised as exceptions, encoded as string values describing the error condition.
ls::get $myTest -name
ls::get $myTest -TsGroup.Tc(1). -StreamBlock(2).state
ls::get $port -children
ls::get $myTest.TsGroup(2) -children
This function displays Help for Tcl commands.
ls::help < COMMAND_NAME | commands > < ARGUMENTS >
Descriptive help text.
% ls::help commands
config: -Sets or modifies the value of an attribute
create: -Creates an object
deregister: -Deregisters the callback for an event
disconnect: -Disconnects from a running test session
get: -Retrieves the value of an attribute or attributes
help: -This message
log: -Writes a message to the set log file or stdout
login: -Establishes a connection with a Landslide TAS
logout: -Disconnects from the Landslide TAS
perform: -Invokes an operation
query: -Queries information from an object
reconnect: -Reconnects to a running test session
retrieve: -Retrieves an object from the TAS
register: -Registers a callback for an event
save: -Saves an object to the TAS
sleep: -Suspends application execution
% ls::help get
Usage: get HANDLE < < ATTRIBUTE > ... >
This function informs if you are connected to a TAS.
% ls::isConnected
1
%
ls::isConnected returns 0 if not connected/logged in,
and 1 if connected/logged in to a TAS.
This function writes a message to a file or standard output. The log function writes a diagnostic message to a log file or to standard output. Landslide Tcl API provides this function so that your application can insert a message into the log file. The log capability uses the values defined for the ApiOptions object to determine its behavior. By modifying the ApiOptions attributes, you can:
Set the default log level for system messages.
Send the output to a file. (By default, messages are directed to standard output.)
Suppress Tcl errors (change the error mechanism from raised exceptions to returned errors).
See the ApiOptions in the Landslide Tcl API Object and Perform Function Reference for more information.
ls::log < LOG_LEVEL > log
None, if successful; returns a Tcl error on failure.
% ls::log $ls::LOG_WARNING "Something bad happened"
%
This function connects the Tcl client to a specific TAS and logs in as a particular user. Most commands require the user to be logged in. You can call ls::get Client1 -warnings after logging in to see if there were any issues.
ls::login [TASIP] [USERNAME] [PASSWORD]
Client object handle on success or Tcl error.
% ls::login 10.71.30.120 tester abcdefg
%
Turns on/off logging service messages to Standard output.
ls::setStdOutLogginOn/ls::setStdOutLoggingOff, toggles printing Tcl API logging service messages to Standard Output.
ls::setFileLoggingOn FILE_PATHNAME, turns on printing Tcl API Logging service messages to a specific file.
ls::setFilLoggingOff, turns off printing Tcl API Logging service messages to a specific file.
ls::print, sends a message as to the Tcl API Logging service as level LOG.
ls::dumpClientLog, prints the Client Logger output to standard output, the equivalent of Shift-Alt-L in the GUI.
This function disconnects the Tcl client from the TAS, if it is not already disconnected.
ls::logout
None, if logout is successful; returns a Tcl error on failure.
% ls::logout
%
This function queries for data based on a search criteria. The Query parameters return the actual values associated with each parameter and not just the object handle (the Get command returns a list of name-object pairs).
ls::query measurements TEST_SESSION_HANDLE < -tab TAB >
< -ts TS_INDEX> < -tc TC_INDEX> < -raw | -formatted>
< -name NAME > < -perInterval > < -lastInterval >
< -subtotal_tab SUBTOTAL_TAB_NAME>
ls::query parameters TEST_CASE_HANDLE < -convert >
ls::query TsId TS_NAME
ls::query TsName TS_ID
ls::query SutInfo [ -name SUT_NAME | -id SUT_ID]
ls::query SutInfo
ls::query SutInfo -AsStrings
ls::query LibraryInfo LIBRARY_TYPE LIBRARY_VALUE
ls::query LibraryInfo
ls::query LibraryInfo -AsStrings
ls::query LibraryInfo < -AsStrings >
ls::query LibraryInfo < -customLibraryName CUSTOM_LIBRARY_NAME | \
-systemLibraryName SYSTEM_LIBRARY_NAME | \
-userLibraryName USERNAME | \
-libraryId LIBRARY_ID >
%
Parameter |
Description |
TYPE |
The library information object, which indicates one of the following: System Custom User |
LIBRARY_TYPE |
The library identification, which can be one of the following: -customLibraryName -systemLibraryName -userLibraryName -libraryId |
LIBRARY_VALUE |
The name or id of the library where the test suite items will be imported. Required for user created test suites not allowed for official test suites. |
NAME |
The name of the measurement Tcl variable name from CLI API) |
SUBTOTAL_TAB_NAME |
The name of the subtotal tab, e.g. DMF_1, SESS_4. You do not need to specify the Totals tab. |
SUT_ID |
The id of the system under test |
SUT_NAME |
The name of the system under test |
TS_ID |
The ID of the test server |
TS_NAME |
The name of the test server |
TEST_CASE_HANDLE <-convert> |
The handle or DDN path to the test case. When you include the optional -convert flag, the command returns a list of tab names containing a list of label-value pairs. |
TEST_SESSION_HANDLE |
The handle of the test session to query for measurements |
TAB |
The tab the measurement is on. Subtabs are separated with |, like this: TAB|SUBTAB (See About the Measurement Reference for a description of sub tabs) |
TS_INDEX/TC_INDEX |
The test server index and test case instance include these parameters to see measurement values for individual test case. For Summary view, do not include them |
The query function retrieves information from objects in the Client. TsId, TsName, SutInfo, and LibraryInfo should be straightforward.
The query parameters function provides a more in-depth view of a test cases parameters than using the ls::get $tc.Parameters. The get command will return a list of name-object pairs, but the query parameters returns the actual values associated with each parameter not just the object handle.
The query measurements function provides visibility of the current interval and the last saved interval of reported measurements. To view a whole tab of measurements, you provide just the tab and not the name argument. To view a single measurement, you include the name. The lastInterval argument will return the value(s) for the last recorded interval, as opposed to the default current interval, which may or may not be populated yet. For viewing per-interval values, the lastInterval argument is recommended, since the current interval may not be populated enough yet to provide an accurate per-interval value. This can be observed in the GUI by watching the current interval column of a per-interval measurement in a running test.
The SutInfo and LibraryInfo with no arguments will return a list of all Objects (SutInfo or LibraryInfo). The SutInfo -AsStrings and LibraryInfo -AsStrings will return a de-referenced list of all objects with all attributes.
Tcl error on failure, otherwise it depends upon the usage:
For Measurements, returns a list of measurements, or returns a single measurement when using the name argument.
For Parameters, returns a list of lists of parameter attributes and sub-object attributes
For TsId, returns the test server ID.
For TsName, returns the test server name.
For SutInfo and LibraryInfo, returns an object handle.
% ls::query TsId testserver
3
% ls::query measurements $test -Tab "Test Summary" -name "Elapsed Time"
16 Min(s) 58 Sec(s)
% ls::query measurements $test -Tab "Test Summary" -name "Elapsed Time" -raw
1020
% ls::query measurements $test -Tab "Test Summary" -name "Iteration"
2
% ls::query measurements $test -Tab "Test Summary" -name "Interval"
68
% ls::query measurements $test -Tab "L3 Client" -name "Total Packets" perInterval
0
% ls::query measurements $test -Tab "L3 Client" -name "Total Packets" -perInterval -lastInterval
54000
% ls::query measurements $test -tab "Test Summary"
{{} {Elapsed Time} {1 Hr(s) 27 Min(s) 30 Sec(s) }} {{Test Summary} {Start Time} {Wed Mar 25 12:41:49 UTC 2009}} {{Test Summary} {Attempted Connect Rate (Sessions/Second)} 200} {{Test Summary} {Attempted Disconnect Rate (Sessions/Second)} 200} {{Test Summary} {Actual Connect Rate Sessions/Second)} 400} {{Test Summary} {Actual Disconnect Rate Sessions/Second)} 400} {{Test Summary} {Sessions Established} 4000} {{Test Summary} {Sessions Pending} 4000} {{Test Summary} {Attempted Session Connects} 1049797} {{Test Summary} {Attempted Session Disconnects} 1047797} {{Test Summary} {Actual Session Connects} 2099794} {{Test Summary} {Actual Session Disconnects} 2095794} {{Test Summary} {Session Errors} 0} {{Test Summary} {Average Session Connect Time} {223 us}} {{Test Summary} {Average Session Disconnect Time} {191 us}}
%
% set libs [ls::query LibraryInfo]
java0x34 java0x35 java0x36 java0x37 java0x38 java0x39 java0x3a java0x3b java0x3c java0x3d java0x3e java0x3f java0x40 java0x41 java0x42 java0x43 java0x44 java0x45 java0x46
% ls::get [lindex $libs 1]
{Id 0} {Name Global} {Rules {}} {Type System}
% ls::query LibraryInfo -AsStrings
{{Id -3} {Name Basic} {Rules {}} {Type System}} {{Id 0} {Name Global} {Rules {}} {Type System}} {{Id -54} {Name {Archive 1}} {Rules all} {Type Custom}} {{Id -53} {Name {Archive 2}} {Rules all} {Type Custom}} {{Id -14} {Name Bugs} {Rules all} {Type Custom}} {{Id -12} {Name DCCA} {Rules all} {Type Custom}} {{Id -52} {Name ExportTests} {Rules {}} {Type Custom}} {{Id -51} {Name ImportTest1} {Rules {}} {Type Custom}} {{Id -50} {Name ImportTest2} {Rules {}} {Type Custom}} {{Id -13} {Name {My All Library.-1}} {Rules all} {Type Custom}} {{Id -11} {Name Temp} {Rules {}} {Type Custom}} {{Id 29227} {Name baduser} {Rules {}} {Type User}} {{Id 13642} {Name dmorgan} {Rules {}} {Type User}} {{Id 7726} {Name lauristephens} {Rules {}} {Type User}} {{Id 23628} {Name mikeludwig} {Rules {}} {Type User}} {{Id29468} {Name sbankert} {Rules {}} {Type User}} {{Id 342} {Name sms} {Rules {}} {Type User}} {{Id 18115} {Name stevestest} {Rules {}} {Type User}} {{Id 17640} {Name Test} {Rules {}} {Type User}}
% ls::help query SutInfo
Usage: query SutInfo < -asStrings >
query SutInfo [ -name NAME | -id ID ]
% ls::help query LibraryInfo
This function executes an API function. See Perform Functions section of the Landslide Tcl API Object and Perform Function Reference for list of functions and their details.
NOTES:
|
ls::perform FUNCTION < FUNCTION_ARGUMENTS >
Depends on the function; returns a Tcl error on failure.
% ls::perform Validate -TestSession $myTest
Invalid
%
This function lists the disconnected tests or reconnects to a running test.
ls::reconnect < -RunID RUN_ID >
With no arguments, returns a list of available disconnected tests, or Tcl error on failure. Otherwise, a handle to the reconnected test session or Tcl error on failure. The ls::perform ShowLastCommandDetails command will provide further details.
%ls::reconnect
{{RunId 9} {Test {My Test Name}} {StartTime {Fri Oct 03 15:29:24 EDT 2008}} {UsedTestServers TestServerName1 TestServerName2}}
%set test [ls::reconnect -RunId 9]
java0x3
This function registers a callback for a specific event. There can only be one callback registered per object. Callbacks are called on the TCL vwait.
ls::register EVENT [ [ ATTRIBUTE VALUE ] <&> ] CALLBACK
ls::register EVENT -TestSession TEST_SESSION_HANDLE CALLBACK
ls::register TestCaseStateChanged -TestSession TEST_SESSION_HANDLE \
-ts TS_INDEX -tc TC_INDEX CALLBACK
This table lists the events for which you can register:
Event |
Callback Signature |
Description |
TestStateChanged |
Callback { state log } |
Called when the overall test state or step changes. (See About Criterion State Machines). |
TestCaseStateChanged |
Callback { ts tc state } |
Called when a test case changes state. (See About Criterion State Machines). |
TestCompleted |
Callback { final_state } |
Called when a test completes. |
IntervalOccurred |
Callback { interval time } |
Called when an interval occurs. |
None, if successful; returns a Tcl error on failure.
% proc myTestcompletedFunction { final_state } {
% }
% ls::register Testcompleted -testSession $myTest myTestcompletedFunction
################################################################
## Registering Callbacks for Event Driven Script
##
## Node test will be
started/stopped sequencially
##
## Nodal test will be
handled with events. It
will be stopped
## 30 seconds after
it reachs the RUNNING state
##
################################################################
## Start the node
ls::perform start -testsession $node
## Wait for it to reach running
set i 0
while { [ls::get $node -teststateorstep] != "RUNNING" } {
ls::sleep 1
incr i
if { $i > 60 } {
puts "Waited
1 minute and Node didn't reach running"
break
}
}
puts "Node has reach Running, starting nodal"
variable done 0
global done
variable reachedRunning false
## DEFINE THE CALLBACK FUNCTIONS
# TestStateChanged callback has two arguments
proc testStateChg { state extra_info } {
variable done
variable reachedRunning
puts "Nodal Test
Changed State : $state : $extra_info"
## Once the test reaches
running, wait 30s then stop it
if { $state == "RUNNING"
} {
set reachedRunning
true
after 30000
{
variable
done
puts
"Stopping Nodal"
if
{[catch "ls::perform stop -testSession $nodal" cmdReturn] }
{
puts
"Unable to stop the test"
set
done 1
}
}
}
}
# IntervalOccurred callback has 2 arguments
proc intervalOccurred { interval time } {
puts "Interval
Occurred: $interval $time"
}
# TestCaseStateChanged callback has 3 arguments
proc testCaseStateChg { ts_index tc_index state } {
puts "Nodal Test
Case Changed State : ts$ts_index:\:tc$tc_index == $state"
}
# TestCompleted callback has 1 argument
proc testComplete { final_state } {
variable done
puts "Nodal Test
Complete, Final State: $final_state"
set done 1
}
variable tmp 0
puts "Registering event callbacks"
ls::register TestStateChanged -testSession $nodal testStateChg
ls::register TestCaseStateChanged -testSession $nodal -ts 0 -tc 0 testCaseStateChg
ls::register TestCompleted -testSession $nodal testComplete
ls::register IntervalOccurred -testSession $nodal intervalOccurred
puts "Starting test"
ls::perform start -testSession $nodal
### A timer-event in case the test never reaches RUNNING
after 240000 {
variable done
variable reachedRunning
if { $reachedRunning
== false } {
puts "Test
Has Not Reached Running after 240s"
set done
1
}
}
## Enter the TCL Event Loop
puts "Waiting for events on Nodal Test"
vwait done
###
if { [ls::get $nodal -isRunning] == true } {
puts "Nodal Test
is still running, stopping now"
ls::perform stop -testsession
$nodal
}
## Wait for nodal to stop
set i 0
while { [ls::get $nodal -isRunning] == true } {
ls::sleep 1
incr i
if { $i > 240 }
{
puts "Waited
4 minutes and the Nodal didn't stop"
break
}
}
puts "Nodal has stopped, stopping node"
ls::perform stop -testsession $node
puts "COMPLETE, printing logs and measurements"
# Print the run log
ls::get $node -unviewedrunlogs
# Print the Test Summary Tab on each test
ls::query $nodal -tab "Test Summary"
ls::query $node -tab "Test Summary"
#Print the Sessions Established measurement
ls::query $nodal -tab "Test Summary" -name "Sessions Established"
This function retrieves an object or graph-friendly measurement data from the TAS.
ls::retrieve [ TestSession | TestCase | Dmf | MessageEditor ] \
LIBRARY_TYPE LIBRARY_VALUE NAME
ls::retrieve TsInfo [ -name NAME | -id ID ]
ls::retrieve GraphPoints TEST_SESSION_HANDLE -tab TAB -name NAME \
< -ts TS -tc TC > < -perInterval > \
< -subtotal_tab SUBTOTAL_TAB_NAME
Parameter |
Description |
LIBRARY_TYPE |
The library identification, which can be one of the following: -customLibraryName -systemLibraryName -userLibraryName -libraryId |
LIBRARY_VALUE |
The name or id of the library in which the object is located |
NAME |
The name of the measurement, object or test server |
ID |
The ID of the test server |
TEST_SESSION_HANDLE |
The handle of the test session to query for graph data |
TAB |
The tab the measurement is on. Subtabs are separated with |, for example: TAB|SUBTAB |
TS/TC |
The test server index and test case instance of the individual measurement. For Summary view, do not include these. |
SUBTOTAL_TAB_NAME |
The name of the subtotal tab, for graphing a specific subtotal, e.g. DMF_1, SESS_4. You do not need to specify the Totals tab. |
The retrieve function retrieves information from the TAS. The main items retrieved are: the test session, test cases, and DMFs. This function also retrieves test server information and the graph data points for a single measurement.
In addition to the graph data points, Landslide Tcl API also provides a utility to prepare the graph data for use in a Gnuplot graph. With Gnuplot you can generate a graph as a jpg or other image file format. Gnuplot is freely available at http://www.gnuplot.info/index.html and Linux binaries/rpms can be found elsewhere on the web.
| NOTE: Landslide generated Gnuplot file works with Gnuplot version 4.2.6. |
The utility to prepare the data is automatically included in the Tcl API, and it is defined in convertToGnuPlot.tcl so users can have a base point from which to create their own converter.
ls::addGnuplotMeasurements — DataPoints Label Adds a line to graph
ls::setGraphTitle — Title of the graph
ls::setGraphFile — Pathname of the graph file to create
ls::setTmpGnuplotFile — Pathname of the Gnuplot file generated, defaulted to TempGnuplotInput.plt
ls::setGnuplotExecutable — Pathname of the Gnuplot executable
ls::writeGnuplotFile — Generates the Gnuplot input file
ls::executeGnuplot — Executes Gnuplot using the generated input file
ls::resetGraphPoints — Resets the internal variables to create a new graph
#Make sure the Tcl API Gnuplotter is clear
% ls::resetGraphPoints
#Point the Tcl API to where you installed the Gnuplot executable (only done once)
% ls::setGnuplotExecutable C:/gnuplot/bin/wgnuplot.exe
C:/gnuplot/bin/wgnuplot.exe
% ls::setGraphTitle "My Graph" #Sets the title for the graph
My Graph
% ls::setGraphFile D:/api/graph.jpg #Sets the location/name of the jpg file to generate
D:/api/graph.jpg
#Retrieve the graph data points
% set gp1 [ls::retrieve graphPoints $test -tab "Test Summary" \
-name "Sessions Pending" ]
... {4770.0 1996.0} {4785.0 2005.0} {4800.0 1995.0} {4810.0 2010.0} ...
% set gp2 [ls::retrieve graphPoints $test -tab "Test Summary" \
-name "Sessions Established" ]
{15.0 153.0} {30.0 300.0} {45.0 246.0} {60.0 100.0} {75.0 153.0} {90.0 299 ...
#Add the two measurements' graph points to the current graph
% ls::addGnuplotMeasurement $gp1 "Sessions Pending"
{Sessions Pending}
% ls::addGnuplotMeasurement $gp2 "Sessions Established"
{Sessions Pending} {Sessions Established}
% ls::writeGnuplotFile #Write out the Gnuplot input file
% ls::executeGnuplot #Execute the generated input file in gnuplot
Calling gnuplot....
% #The graph file should now be generated where you asked.
The requested object handle or the graph data points on success; returns a Tcl error on failure.
% set test [ls::retrieve TestSession -userLibraryName sms "My Test"]
java0x3
% set ts [ls::retrieve TsInfo -name "testserver1"]
java0x10
% set gp2 [ls::retrieve GraphPoints $test -tab "Test Summary" \
-name "Sessions Established" ]
{15.0 153.0} {30.0 300.0} {45.0 246.0} {60.0 100.0} {75.0 153.0} {90.0 299 ...
This function saves a TestSession, TestCase, Dmf, or MessageEditor object to the TAS. This assumes you have already set the libraryId and name of the object.
ls::save [ TEST_SESSION_HANDLE | TEST_CASE_HANDLE | DMF_HANDLE | MESSAGE_EDITOR_HANDLE ] \
< -overwrite >
None, if successful; returns a Tcl error on failure. The ls::perform showLastCommandDetails command will provide further details.
%ls::save $myTest1
This function suspends Tcl application execution. The sleep function suspends your application for the specified duration (expressed as the number of seconds). This does not suspend the Tcl event loop; Landslide internal processing will continue, regardless of the state of the Tcl event loop.
ls::sleep DURATION_SECONDS
None, if successful; returns a Tcl error on failure.
% ls::sleep 5
%
This function prints the detailed progress of previously executed command. Not supported on every command however it can be useful when troubleshooting.
% ls::showLastCommandDetails
Action: OpenTestSessionAction lib=dan name=HSS Nodal Cx3
Progress:
12:11:41.263:0% : Progress for Opening Test Session:lib=sms name=HSS Nodal Cx3
12:11:41.264:0% : Querying test session id from TAS
12:11:42.173:25% : Requesting Data from TAS
12:11:42.622:50% : Test Session Data Received, Processing...
12:11:42.626:75% : Validating...
12:11:43.192:95% : Validated ErrorsOrWarnings:false
12:11:43.192:100% : done
Result: Success
%