Specifying XML Function Parameters

Most XML API functions require that you specify the XML element and a query. You can also indicate if you want to retrieve all results or a single one.

Defining the XML Element

For defining the XML element to query, you can specify a literal string of the XML element, or a parameter that contains the XML. The following example shows the XML input string defined as a literal string,


Alternatively, the XML string can be a parameter containing the XML data. For example:


Querying an XML Tree

Suppose you want to find a value within an XML tag, for example, an employee's extension. You formulate a query for the desired value. The query indicates the location of the element and which element you want to retrieve or set. The path that you specify limits the scope of the search to a specific tag. You can also search for all elements of a specific type under all nodes below the root.

For a specific path, use "Query=/full_xml_path_name/element_name"

For the same element name under all nodes, use "Query=//element_name"

In the VuGen implementation of XML functions, the scope of a query is the entire XML tree. The tree information is sent to the Vuser API functions as the value of the xml argument.

Multiple Query Matching

When you perform a query on an XML element, by default VuGen returns only the first match. To retrieve multiple values from a query, you specify the "SelectAll=yes" attribute within your functions. VuGen adds a suffix of _index to indicate multiple parameters. For example, if you defined a parameter by the name EmployeeName, VuGen creates EmployeeName_1, EmployeeName_2, EmployeeName_3, and so on.

"ResultParam=NewXmlParam", "ValueParam=ExtensionParam",
"SelectAll=yes", "Query=//extension", LAST);

With functions that write to a parameter, the values written to the parameter can then be evaluated. For example, the following code retrieves and prints multiple matches of a query:

NumOfValues = lr_xml_get_values("Xml={XmlParam}", "Query=//name",
           "SelectAll=yes", "ValueParam=EmployeeName", LAST);

For functions that read from parameters, the values of the parameters must be pre-defined. The parameter must also use the convention ParamName_IndexNumber, for example Param_1, Param_2, Param_3, and so on. This collection of parameters is also known as a parameter set.

In the following example, lr_xml_set_values reads values from the parameter set and then uses those values in the XPath query. The parameter set that represents the employee extensions, is called ExtensionParam. It has two members: ExtensionParam_1 and ExtensionParam_2. The lr_xml_set_values function queries the XML input string and sets the value of the first match to 1111 and the second match to 2222.

lr_save_string("1111", "ExtensionParam_1");
lr_save_string("2222", "ExtensionParam_2");

    "ResultParam=NewXmlParam", "ValueParam=ExtensionParam",
    "SelectAll=yes", "Query=//extension", LAST);