XML Query

This section describes the structure of a basic XML query. For examples, see XML query examples.

In this topic:

XPath

The XML Path Language (XPath) provides basic facilities for manipulation of strings, numbers, boolean values, and addresses in an XML document.

XPath defines an XML document as a tree of tags, or nodes. For example, the following XML fragment describes an organization, Acme, with one employee and one manager. "acme_org", "employee" and "name" are examples of tags.

<acme_org>

    <accounts_dept>

        <employee level="manager">

            <name>John Smith</name>

            <cubicle label="Welcome">227</cubicle>

            <extension>2145</extension>

        </employee>

    </accounts_dept>

    <engineering_dept>

        <employee>

            <name>Sue Jones</name>

            <extension>2375</extension>

        </employee>

    </engineering_dept>

</acme_org>

The standard XPath functions work by pattern matching the query with the XML document tree using a particular tag as a context. That is, the area of the search will be within the scope of that particular tag only. However, in all XML functions, the scope of a query is the entire XML tree. This tree is sent to XML functions as string in the "xml=string" argument.

An element is a sub-field within a tag. In the above example, the tag name is an element of employee. Each element has a value. An example of a name element's value is the string "John Smith".

Back to top

Attributes

Elements may have optional attributes which provide further information about the element. You can also indicate element attributes in your queries. In this example, level is an attribute of employee.

<employee level="manager">

To find elements with a specific attribute name, use @attribute_name

To find elements with a known attribute name and value, use element[@attribute_name=\"value\"].

Note that the quotation marks are escaped to indicate that the search string contains quote marks. Were they not escaped, the quotes would indicate the end of the argument string and either the function would not compile, or the results would be unpredictable.

For example, the search string below matches any cubicle element with a sign attribute whose value is "Fidelity".

//cubicle[@sign=\"Fidelity\"]"

This search string matches a cubicle element like this one:

     "<employee>"

         "<name>Henry Crawford</name>"

         "<cubicle sign=\"Fidelity\">227</cubicle>"

Back to top

Sample query string expressions

The scripts below can be run to illustrate XML queries. To run the examples, paste the segments into the Actions section of your script. Make sure the enable the Extended Log in the Runtime Settings with Parameter substitution, so that you can view the values of the result parameter, ResultParam, in the Execution log. For details, see the VuGen Online Help Center.

To comply with the XML parser engine follow these guidelines:

• If your nodes include namespaces, you must include them in the XPath query expression.

• If your XPath includes nodes with the default namespace, you must use the wildcard notation "*". For details, see the online XML Namespaces documentation and the example below.

Full node name example

char *xml_namespace =
                    "<s:Envelope xmlns:s=\"http://www.w3.org/2003/05/soap-envelope\" xmlns:a=\"http://www.w3.org/2005/08/addressing\">"
                    "<s:Header>"
                    "<a:Action s:mustUnderstand=\"1\">http://tempuri.org/ICalculator/AddResponse</a:Action>"
                    "<a:RelatesTo>urn:uuid:d8200b8b-90dc-4dcb-8ebc-d4aa5eaa65b3</a:RelatesTo>"
                    "</s:Header>"
                    "<s:Body>"
                    "<r:AddResponse xmlns:r=\"http://tempuri.org/\">"
                    "<r:AddResult>75</r:AddResult>"
                    "</r:AddResponse>"
                    "</s:Body>"
                    "</s:Envelope>";

                    Action()
                    {
                    // Find adding result from xml_namespace string
                    int find_cnt;    
                    lr_save_string(xml_namespace, "XML_Namespace");
    
                    find_cnt = lr_xml_find("XML={XML_Namespace}",
                    "Query=/s:Envelope/s:Body/r:AddResponse/r:AddResult", 
                    "Value=75", 
                    LAST );    
                lr_output_message("Found Adding Result: %d", find_cnt);

Default namespaces

If you define a default namespace, make sure to use the wildcard (*) in the expression. For example:

char *xml_default_namespace =
                "<acme_org xmlns=\"http://www.w3.org/1999/xhtml\">"
                "<employee level=\"manager\">John Smith"
                "<cubicle>227</cubicle>"
                "</employee>"
                "</acme_org>";

                Action()
                {
                // Extract Employ fragment from xml_default_namespace
                lr_save_string(xml_default_namespace, "XML_Default_Namespace");

                lr_xml_extract("XML={XML_Default_Namespace}",
                "XMLFragmentParam=Result", 
                "Query=/*[local-name()\='acme_org']/*[local-name()\='employee']",
                LAST );
                lr_output_message(lr_eval_string("Employee extracted: {Result}"));

                return 0;
                }