Specifying Schema-dependent Paths for XML Virtual Documents

Copy link to this sectionGetting 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>

Copy code to clipboard

The following table shows some example paths for this document:

Copy link to this sectionGetting 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:

Copy link to this sectionComments 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:

Copy link to this sectionUsing 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")

Copy code to clipboard

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.

Copy link to this sectionCharacter 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%".

Copy link to this sectionSpecial Variations for Repeating Elements

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

Copy link to this sectionIterating 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}

Copy code to clipboard

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>

Copy code to clipboard

Copy link to this sectionTesting 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.Document 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
}

Copy code to clipboard

The following shows output from this method:

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

Copy code to clipboard

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