Specifying Schema-dependent Paths for XML Virtual Documents

Getting or Setting the Contents of an XML Element

To access the contents of an element, you can use one of the following schema-dependent paths. You also use these paths when you create more complex schema-dependent paths as discussed in later subsections.

Consider the following XML document:

<?xml version="1.0" ?>
<Patient MRN='000111222' xmlns='http://myapp.com'>
    <Name>Georgina Hampton</Name>
    <FavoriteColors>
        <FavoriteColor>Red</FavoriteColor>
        <FavoriteColor>Green</FavoriteColor>
    </FavoriteColors>
    <Address>
        <Street>86 Bateson Way</Street>
        <City>Fall River</City>
    </Address>
    <Doctor>
        <Name>Dr. Randolph</Name>
    </Doctor>
</Patient>

The following table shows some example paths for this document:

Getting or Setting the Value of an XML Attribute

To access the value of an attribute, you can use one of the following schema-dependent paths. Here (and in the rest of this section), element_reference is a complete schema-dependent path as described in the previous table.

The following table shows an example path for the previous document:

Comments and Descriptions

InterSystems IRIS® removes the comments when it reads XML files. Consequently, you should not use comments to document the schema. Instead of using comments, you can use the description or altdesc attributes available on most schema elements.

Although it is not useful in most cases, you can access a comment by using one of the following schema-dependent paths:

Using Mixed Content When Setting Schema-dependent Paths

You can set paths to values that include both element and text nodes, for example:

 set mixed="SOME TEXT<HOMETOWN>BELMONT</HOMETOWN>"
 set status=target.SetValueAt(mixed,"Address")

A combination of element and text nodes is called mixed content.

For schema-dependent paths, InterSystems IRIS determines that a value is mixed content if it contains a left angle bracket (<) character followed by one of the following sets of characters:

• forward slash and right angle bracket (/>)

• left angle bracket and forward slash (</)

The following table describes how InterSystems IRIS handles mixed content for different types of schema-dependent paths:

For information about mixed content in DOM-style paths, see Using Mixed Content When Setting DOM-style Paths.

Character Escaping When Setting Schema-dependent Paths

If you set a schema-dependent path to a value that includes a left angle bracket (<) character and the value does not meet the criteria for mixed content, InterSystems IRIS replaces the character with the corresponding character entity reference (&lt; ). You do not need to explicitly escape left angle brackets. For example, if you specify the value of a schema-dependent path as "sample value < 20%", the system sets the path to "sample value &lt; 20%".

Special Variations for Repeating Elements

This section describes variations of virtual property paths that apply when you are referring to a repeating element.

Iterating Through the Repeating Elements

If the path refers to a repeating element, you can use the following syntax to iterate through every instance of that element.

Syntax	Refers to
element_name()	Iterates through the elements of the given name, within the given context.

Suppose that we now use a data transformation that contains only the following code:

 set status=target.SetValueAt("REPLACED COLOR","FavoriteColors()")
 if 'status {do $system.Status.DisplayError(status) quit}

This line of code transforms the document shown previously in this chapter to the following:

<?xml version="1.0" ?>
<Patient MRN='000111222' xmlns='http://myapp.com'>
    <Name>Georgina Hampton</Name>
    <FavoriteColors>
        <FavoriteColor>REPLACED COLOR</FavoriteColor>
        <FavoriteColor>REPLACED COLOR</FavoriteColor>
    </FavoriteColors>
    <Address>
        <Street>86 Bateson Way</Street>
        <City>Fall River</City>
    </Address>
    <Doctor>
        <Name>Dr. Randolph</Name>
    </Doctor>
</Patient>

Testing Schema-dependent Paths in the Terminal

It can be useful to test virtual document property paths in the Terminal before using them in business processes, data transformations, and so on, particularly when you are getting familiar with the syntax. To do so for schema-dependent XML paths, do the following:

1. Load the corresponding XML schema or schemas into InterSystems IRIS. To do so, use the XML Schema Structures page, described in the chapter “Available Tools.”

2. Use the Management Portal to find the DocType value for the root element of the documents that you plan to test. For example:

   

   See “Viewing Path Units for XML Virtual Documents,” earlier in this book.

3. In the Terminal or in test code:

   1. Create a string that contains the text of a suitable XML document.

   2. Use the ImportFromString() method of EnsLib.EDI.XML.DocumentOpens in a new tab to create an instance of an XML virtual document from this string.

   3. Set the DocType property of this instance.

   4. Use the GetValueAt() and SetValueAt() methods of this instance.

The following method demonstrates step 3:

ClassMethod TestSchemaPath()
{
    set string="<Patient xmlns='http://myapp.com'>"
    _"<Name>Jack Brown</Name>"
    _"<Address><Street>233 Main St</Street></Address>"
    _"</Patient>"
    set target=##class(EnsLib.EDI.XML.Document).ImportFromString(string,.status)
    if 'status {do $system.Status.DisplayError(status)  quit}
    
    //Use the DocType displayed in the Management Portal
    set target.DocType="MyApp:Patient"
    
    set pathvalue=target.GetValueAt("Address.Street",,.status)
    if 'status {do $system.Status.DisplayError(status)  quit}
    write pathvalue
}

The following shows output from this method:

SAMPLES>d ##class(Demo.CheckPaths).TestSchemaPath()
233 Main St

For additional options for GetValueAt(), see “The pFormat Argument,” later in this book.