Using %XML.TextReader

Overall Structure

Your method should do some or all of the following:

1. Specify a document source, via the first argument of one of the following methods:

   Method	First Argument
   ParseFile()	A file name, with complete path. Note that the filename and path must contain only ASCII characters.
   ParseStream()	A stream
   ParseString()	A string
   ParseURL()	A URL

   In any case, the source document must be a well-formed XML document; that is, it must obey the basic rules of XML syntax. Each of these methods returns a status ($$$OK or a failure code) to indicate whether the result was successful. You can test the status with the usual mechanisms; in particular, you can use $System.Status.DisplayError(status) to see the text of the error message.

   For each of these methods, if the method returns $$$OK, it returns by reference (its second argument) the text reader object that contains the information in the XML document.

   Additional arguments let you control entity resolution, validation, which items are found, and so on. See Argument Lists for the Parse Methods.

2. Check the status returned by the parse method and quit if appropriate.

   If the parse method returned $$$OK, you have an text reader object that corresponds to the source XML document. You can navigate this object.

   Your document is likely to contain nodes such as "element", "endelement", "startprefixmapping", and so on. The node types are listed in Node Types.

   Important:

   In the case of any validation errors, your document contains "error" or "warning" nodes. Your code should check for such nodes. See Performing Validation.

3. Use one of the following instance methods to start reading the document.

   • Use Read() to navigate to the first node of the document.

   • Use ReadStartElement() to navigate to the first element of a specific type.

   • Use MoveToContent() to navigate to the first node of type "chars".

   See Navigating the Document.

4. Get the values of the properties of interest for this node, if any. Available properties include Name, Value, Depth, and so on. See Node Properties.

5. Continue to navigate through the document as needed and get property values.

   If the current node is an element, you can use the MoveToAttributeIndex() or MoveToAttributeName() methods to move the focus to attributes of that element. To return to the element, if applicable, use MoveToElement().

6. If needed, use the Rewind() method to return to the start of the document (before the first node). This is the only method that can go backward in the source.

After your method runs, the text reader object is destroyed and all related temporary storage is cleaned up.

Example 1

Here is a simple method that reads any XML file and shows the sequence number, type, name, and value of every node:

ClassMethod WriteNodes(myfile As %String)
{
    set status=##class(%XML.TextReader).ParseFile(myfile,.textreader)
    //check status
    if $$$ISERR(status) {do $System.Status.DisplayError(status) quit}
    //iterate through document, node by node
    while textreader.Read()
    {
        Write !, "Node ", textreader.seq, " is a(n) "
        Write textreader.NodeType," "
        If textreader.Name'=""
        {
            Write "named: ", textreader.Name
            }
            Else
            {
                Write "and has no name"
                }
        Write !, "    path: ",textreader.Path
        If textreader.Value'="" 
        {
            Write !, "    value: ", textreader.Value
            }
        }
}

This example does the following:

1. It calls the ParseFile() class method. This reads the source file, creates a text reader object, and returns that in the variable doc by reference.

2. If ParseFile() is successful, the method then invokes the Read() method to find each successive node within the document.

3. For each node, the method writes output lines that contain the sequence number of the node, the node type, the node name (if any), the node path, and the node value (if any). Output is written to the current device.

Consider the following example source document:

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/css" href="mystyles.css"?>
<Root>
   <s01:Person xmlns:s01="http://www.root.org">
      <Name attr="xyz">Willeke,Clint B.</Name>
      <DOB>1925-10-01</DOB>
   </s01:Person>
</Root>

For this source document, the preceding method generates the following output:

Node 1 is a(n) processinginstruction named: xml-stylesheet
    path:
    value: type="text/css" href="mystyles.css"
Node 2 is a(n) element named: Root
    path: /Root
Node 3 is a(n) startprefixmapping named: s01
    path: /Root
    value: s01 http://www.root.org
Node 4 is a(n) element named: s01:Person
    path: /Root/s01:Person
Node 5 is a(n) element named: Name
    path: /Root/s01:Person/Name
Node 6 is a(n) chars and has no name
    path: /Root/s01:Person/Name
    value: Willeke,Clint B.
Node 7 is a(n) endelement named: Name
    path: /Root/s01:Person/Name
Node 8 is a(n) element named: DOB
    path: /Root/s01:Person/DOB
Node 9 is a(n) chars and has no name
    path: /Root/s01:Person/DOB
    value: 1925-10-01
Node 10 is a(n) endelement named: DOB
    path: /Root/s01:Person/DOB
Node 11 is a(n) endelement named: s01:Person
    path: /Root/s01:Person
Node 12 is a(n) endprefixmapping named: s01
    path: /Root
    value: s01
Node 13 is a(n) endelement named: Root
    path: /Root

Notice that the comment has been ignored; by default, the %XML.TextReaderOpens in a new tab class ignores comments. For information on changing this, see Argument Lists for the Parse Methods.

Example 2

The following example reads an XML file and lists every element in it:

ClassMethod ShowElements(myfile As %String)
{
    set status = ##class(%XML.TextReader).ParseFile(myfile,.textreader)
    //check status
    if $$$ISERR(status) {do $System.Status.DisplayError(status) quit}
    //iterate through document, node by node
    while textreader.Read()
    {
        if (textreader.NodeType = "element") 
        {
            write textreader.Name,!
            }
        }
}

This method checks the type of each node, by using the NodeType property. If the node is an element, the method prints its name to the current device. For the XML source document shown earlier, this method generates the following output:

Root
s01:Person
Name
DOB

Navigating to the Next Node

To move to the next node in a document, use the Read() method. The Read() method returns a true value until there are no more nodes to read (that is, until the end of the document is reached). The previous examples used this method in a loop like the following:

 While (textreader.Read()) {

...

 }

Navigating to the First Occurrence of a Specific Element

You can move to the first occurrence of a specific element within a document. To do so, use the ReadStartElement() method. This method returns true unless the element is not found. If the element is not found, the method reaches the end of the file.

The ReadStartElement() method takes two arguments: the name of the element and (optionally) the namespace URI. Note that the %XML.TextReaderOpens in a new tab class does not do any processing of namespace prefixes. Therefore the ReadStartElement() method regards the following two elements as having different names:

<Person>Smith,Ellen W. xmlns="http://www.person.org"</Person>

<s01:Person>Smith,Ellen W. xmlns:s01="http://www.person.org"</s01:Person>

Navigating to an Attribute

When you navigate to an element, if that element has attributes, you can navigate to them, in either of two ways:

• Use the MoveToAttributeIndex() method to move to a specific attribute by index (ordinal position of the attribute within the element). This method takes one argument: the index number of the attribute. You can use the AttributeCount property to learn how many attributes a given element has; see Node Properties for a list of all properties.

• Use the MoveToAttributeName() method to move to a specific attribute by name. This method takes two arguments: the name of the attribute and (optionally) the namespace URI. Note that the %XML.TextReaderOpens in a new tab class does not do any processing of namespace prefixes; if an attribute has a prefix, that prefix is considered part of the attribute name.

When you are finished with the attributes for the current element, you can move to the next element in the document by invoking one of the navigation methods such as Read(). Alternatively, you can invoke the MoveToElement() method to return to the element that contains the current attribute.

For example, the following code lists all the attributes for the current node by index number:

 If (textreader.NodeType = "element") {
     // list attributes for this node
     For a = 1:1:textreader.AttributeCount {
         Do textreader.MoveToAttributeIndex(a)
         Write textreader.LocalName," = ",textreader.Value,!
     }
 }

The following code finds the value of the color attribute for the current node:

 If (textreader.NodeType = "element") {
     // find color attribute for this node
     If (textreader.MoveToAttributeName("color")) {
         Write "color = ",textreader.Value,!
     }
 }

Navigating to the Next Node with Content

The MoveToContent() method helps you find content. Specifically:

• If the node is of any type other than "chars", this method advances to the next node of type "chars".

• If the node is of type "chars", this method does not advance in the file.

Rewinding

All the methods described here go forward in a document, except for the Rewind() method, which navigates to the start of the document and resets all properties.