API function calls contain references that identify objects, object attributes, and relations. Depending on the circumstance, use one of the following syntax elements:
Relation References
NOTE: When you work with test case parameters, you must also read the Parameters object section of the Landslide Tcl API Object and Perform Function Reference document. The Parameters object is a special case that includes some unique features that are not described in this section. |
When you create Landslide objects, you specify a child object name. For example:
set myTest [ls::create TestSession]
This call to create produces a single object (type TestSession) and returns a handle to that object.
To obtain information about the descendant (child) object(s), use the get function to retrieve the object handles:
set testChildren [ls::get $myTest -children]
The get function call returns the list of children of the TestSession object. In this case, since it is a default new test, it is just the handle to the ReportOptions object:
{ ReportOptions java0x4 }
You can create additional children objects using the -under argument:
set tsGroup0 [ls::create TsGroup -under $myTest -tsId 5 ]
The call to the create function creates a TsGroup object with its tsId attribute set to 5, under the myTest TestSession object. Most user-created children are lists of similar type objects.
An object handle is a string value that identifies a Landslide Tcl API object. Object handles are the links between the application and the object hierarchy maintained by Landslide Tcl API. The following sections describe how to create and use object handles.
NOTE: In most circumstances, Landslide will create objects for you. Each object description in the Landslide Tcl API Object and Perform Function Reference lists the associated objects and whether they are user created or auto created. |
Landslide API creates handles when it creates the objects in your object hierarchy. When you call the create function, the object handle is the return value from the function:
set report_handle [ls::create ReportOptions -format $ls::FORMAT_CSV]
When the create function returns, the variable report_handle is set to the value of the object handle for the newly created ReportOptions object. The application uses the object handle in other calls to Landslide API functions.
You use object handles in the following circumstances:
To identify the parent/owner for a new object: With the exception of the top-level objects, you must specify a parent when you create an object. For example:
set test_step0 [ls::create Step -under $myTest]
In this example, the -under attribute specifies the TestSession object handle as the parent for the new Step object. The create function returns the handle for the Step object.
To gain access to object attributes: You provide a handle when you call get to retrieve an attribute value, or when you call config to modify an attribute value. You may also use handles to execute a command with the perform function (if the command requires access to an object). For example:
set savedTest [ls::retrieve TestSession \
-systemLibraryName Global "Saved Test"]
ls::perform run -TestSession $mySavedTest
You can use path name notation to reference objects and object attributes in the test hierarchy. The path name references shorten the command line and reduce the need to obtain handles to access objects.
When you use the Landslide API, a function call identifies an object, or it identifies an object and one (or more) of its attributes. For example:
ls::config $sut -ManagementIp “10.100.0.1”
Landslide API supports the use of path names for both object and attribute identification; the context determines the type of notation. To specify a path name, use one of the following notations:
Use Direct-Descendant Notation (DDN) as an object reference in a function call to identify an object without having to retrieve its handle. DDN is a dotted path name sequence beginning with an object handle, followed by one or more child object names.
handle.type[.type...]
The child object names in the sequence must represent objects in a valid parent-child descendant path in your test hierarchy (extending from the object associated with the object handle). For example:
ls::config $myTest.ReportOptions -AutoSaveInterval 4
ls::config $myTest.TsGroup -tsId 12
The $myTest.ReportOptions object reference identifies the ReportOptions child of the $myTest object; the -AutoSaveInterval value is applied to the ReportOptions object. The myTest.TsGroup object reference identifies the first TsGroup child of the $myTest object; the -tsId value is applied to the TsGroup object (See Indexed Notation (DDN and DAN) for information about identifying one of multiple children of the same type.)
DDN is particularly useful when changing multiple attributes for a single descendant object:
ls::config $dmf.PasteBuffer(2) -Name "Username" -InitialValue "admin"
In the example above, both -Name and -InitialValue attribute values are applied to the third PasteBuffer child of the $dmf Dmf object.
Use Descendant-Attribute Notation (DAN) to identify attributes of descendant objects. DAN combines both object and attribute portions of a function call to resolve the attribute reference. The object portion identifies the beginning of the descendant path. The attribute specification is a dotted path name beginning with a dash (-), followed by a sequence of one or more child object name, and ending with an attribute name. A DAN reference uses the following syntax:
-type[.type...].attribute
The first name of the sequence must specify a type of one of the children of the object part of the function call. For example:
ls::config $myTest -ReportOptions.L3PerSession true
Using DAN, the attribute path name (-ReportOptions.L3PerSession) identifies the L3PerSession attribute for the ReportOptions child of the $myTest object. DAN is particularly useful when changing an attribute in two or more different descendants:
ls::config $dmf -PasteBuffer(0).size 10 -PasteBuffer(1).size 10
In the example above, the attribute references (-PasteBuffer(0).size and -PasteBuffer(1).size) specify the size attribute for two PasteBuffer children of the $dmf object. The example uses indexed notation to identify the descendant objects. See Indexed Notation (DDN and DAN) for information about indexed notation.
Both direct-descendant and descendant-attribute notations support indexing to identify one of a set or list of descendants of the same type. Under a particular parent, for a set of child objects of the same type, Landslide assigns sequential indices starting with the index value 0. In the following function call, the reference to the Step object identifies the first Step created. (A reference without an index identifies the first object of the specified type.)
ls::config $myTest.Step -activity $ls::STEP_ACTIVITY_INIT
To identify one of multiple children of the same type, specify the index of the desired child in parenthesis. The following examples show the use of indices in both DDN and DAN paths.
ls::config $myTest.Step(2) -delaySec 25
set predecessorState [ls::get $myTest -Step(2).predecessorState]
set step2 [ls::get $myTest -children-Step(2)]
When you use a relation reference in a call to the get function, Landslide returns one or more name-object handle pairs. For example:
ls::get $myTest -children
{ReportOptions java0x4} {Step0 java0x9}
This function call returns a list containing the object handles for all of the children of the specified TestSession object. When you use a relation to retrieve the handles of child objects, you can specify an object type to filter the set of objects. For example:
ls::get $myTest -children-Step
{Step0 java0x9}
This function call returns the handle(s) for the Step child object(s) of the $myTest object. When you use a relation to retrieve the handles of child objects, you can specify an object type and Index Notation to return just one object handle. For example:
ls::get $myTest -children-Step(0)
java0xa
There are only a few objects that allow you to modify a child. When you modify a child relation (set a child object for a parent object), you provide an object handle for the specified side of the relation. To add a child, use -children and the child object name and the handle you want to add:
-children-NAME handle
-DANPath.children-NAME handle
For example:
ls::config $myTest -TsGroup(0).Tc $tc0
Although you can use child references to modify some children and to retrieve object handles for the child objects, you cannot use a relation reference to get or set an attribute for the resulting object(s). In order to manipulate attributes in a child object, you must use either a DAN path or first obtain the handle then use the handle to directly access the attribute. For example:
set tcType [ls::get $myTest.TsGroup(0) -Tc(0).type
set tc0 [ls::get $myTest.TsGroup(0) -children-Tc(0)]
set tcType [ls::get $tc0 -type]
The first call to the get function retrieves the type attribute of the first Tc/TestCase object using DDN and DAN paths. The second call to the get function retrieves the handle to the Tc/TestCase child object. The third call retrieves the value of the type attribute from the Tc/TestCase object directly.
ls::determineChildrenListSize CHILD_NAME LIST, can be used to determine how many of a given child type are in an object. This only works for multi-element children.
% ls::determineChildrenListSize Chart [ls::get $test -children-Chart]
5
% ls::determineChildrenListSize Tc [ls::get $test.TsGroup -children-Tc]
1
%
ls::alwaysReturnList CHILD_NAME LIST, can be used to make sure you always get your children objects in a list. Currently when you do an ls::get $handle –children-CHILD_NAME, and there is only one child, you get the one child back as a tuple.
% ls::get $test.TsGroup -children-Tc
Tc0 java0x1d
But if there is more than one child you get a list of tuples.
% ls::get $test -children-Chart
{Chart0 java0x1e} {Chart1 java0x1f} {Chart2 java0x20} {Chart3 java0x21} {Chart4 java0x22}
%
And if the child is not part of a list, you just get back the Handle.
% set list [ls::alwaysReturnList Chart [ls::get $test -children-Favorites]]
java0x1b
By using alwaysReturnList, you can bring consistency to retrieving lists of same children. You must always pass in the Child’s name and the list made up of only the same children:
% set list [ls::alwaysReturnList Tc [ls::get $test.TsGroup -children-Tc]]
{Tc0 java0x1a}
% set list [ls::alwaysReturnList Chart [ls::get $test -children-Chart]]
{Chart0 java0x23} {Chart1 java0x24} {Chart2 java0x25} {Chart3 java0x26} {Chart4 java0x27}