XmlEvaluate Function

Reference Guide > X–Z Routines > XmlEvaluate Function

Evaluates an XPATH expression and returns the selected nodes or by default returns all nodes in the XML document.

Usage

result = XmlEvaluate(document_id, [query])

Input Parameters

document_id—The handle returned by XmlParse or XmlNewDoc.

query—An optional string containing an XPATH statement to execute on the XML document. If no query is provided all of the XML document will be parsed.

Returned Value

result—A PV‑WAVE table containing the result of the XPATH command. This table has five columns as shown below. If no results are processed then a scalar value of -1 is returned.

name—Name of the node selected.

value—Content of the node.

xpath—A string representing the location of the node.

nodeid—An ID for the node.

ntype—Type of the Node.

Keywords

Context_ID—ID of the context that was returned by the XmlSetContext if it was used to specify a subset of the document tree.

Discussion

XmlEvaluate is the most important routine in the PV‑WAVE:XML Toolkit. It uses the XPATH syntax defined for XML to select all or part of an XML document. A good introduction to this language can be found at
http://www.w3.org. See the examples below for some common expressions.

The result of XmlEvaluate is a PV‑WAVE Table variable that contains the name, value, and type of selected nodes, as well as path information, which is useful in understanding where the node exists in the node tree hierarchy. Also returned is an ID for the node, which can be used to set attributes of the node (XmlSetAttr), change the content of (XmlSetContent), and add child nodes to (XmlAddNode).

Here is an example of the results returned from XmlEvaluate. The XML entry might look like this:

<Dept>

   <Employee> John Smith </Employee>

   <Employee> Jane Doe </Employee>

</Dept>

The returned table from XmlEvaluate would include the rows shown in Example Employee Table.

Table 20-1: Example Employee Table
Name	Value	XPath	NodeID	NType
Employee	John Smith	/Dept/Employee[1]	18276465	1
Employee	Jane Doe	/Dept/Employee[2]	28376473	1

Notes

Because there are more than one node with the name “Employee” at the same level in the node tree (in this case under “Dept”), the XML parser adds a suffix to the node path to make it unique, for example “[1]”.

Returned Node Types are the definitions of the node types returned in the result table.

Table 20-2: Returned Node Types
NType	Description
1	Element
2	Attribute
3	Text
4	CDATA
5	Entity reference
6	Entity
7	Processing instruction
8	Comment
9	Root XML document

Example 1

This example queries the entire node tree.

; Retrieve all the elements in the tree.

entire_tree = XmlEvaluate(doc_id)

Example 2

This example queries all the “value” attributes in the chart.xml file.

; get all the 'value' attributes.

att_table = XmlEvaluate(doc_id,'//@value')

Example 3

This example queries a sub-tree defined by the context_id.

; Build a DOM tree.

doc_id = XmlParse('chart.xml', /File)

; Changes the start location for XPATH query.

context_id = XmlSetContext(doc_id, Path='/Chart/CharTitle')

; Use the relative path to the Attribute node.

subtree = XmlEvaluate(doc_id, 'Attribute', $

   Context_id=context_id)

Example 4

This example shows how to use the path returned from XmlEvaluate to access the attributes of a particular node. We also show how multiple nodes at the same level with the same name are given a unique path.

doc_id = XmlParse('chart.xml', /File)

table = XmlEvaluate(doc_id, '//*')

FOR i=0L, N_ELEMENTS(table)-1 DO PRINT,table(i)

; Print all of the node information for an XML file.

; The following is the result of this query:

; { Chart  /Chart    26395416           1}

; { ChartTitle  /Chart/ChartTitle    26427072   1}

; { Attribute Line Chart /Chart/ChartTitle/Attribute[1] 26480152

;   1}

; { Attribute  /Chart/ChartTitle/Attribute[2] 26480464 1}

; { Attribute  /Chart/ChartTitle/Attribute[3] 26442656 1}

; { AxisXY  /Chart/AxisXY    26443032           1}

; { Data  /Chart/AxisXY/Data[1]    26443128           1}

; { Attribute  /Chart/AxisXY/Data[1]/Attribute[1]

;  26470416       1}

; { Attribute  /Chart/AxisXY/Data[1]/Attribute[2]

;   26470776       1}

; { Attribute  /Chart/AxisXY/Data[1]/Attribute[3]

;   26471176       1}

; { Attribute  /Chart/AxisXY/Data[1]/Attribute[4]

;   26480736       1}

; { Attribute  /Chart/AxisXY/Data[1]/Attribute[5]

;   26481136       1}

; { Data  /Chart/AxisXY/Data[2]    26481512           1}

; { Attribute  /Chart/AxisXY/Data[2]/Attribute[1]

;   26481784       1}

; { Attribute  /Chart/AxisXY/Data[2]/Attribute[2]

;   26482168       1}

; { Attribute  /Chart/AxisXY/Data[2]/Attribute[3]

;   26482552       1}

; { Attribute  /Chart/AxisXY/Data[2]/Attribute[4]

;   26482944       1}

; Print the attribute value for the first node named 'Data'.

attribute_node = XmlEvaluate(doc_id, '/Chart/AxisXY/Data[1]/@*')

PRINT, attribute_node.value

; PV-WAVE prints:

;  {6,5,7,1}

; Print the attribute value for the second node named 'Data'.

attribute_node = XmlEvaluate(doc_id, '/Chart/AxisXY/Data[2]/@*')

PRINT, attribute_node.value

; PV-WAVE prints:

;  {1,3,6,8}

Version 2017.1