Skip to main content

Specifying Schema-dependent Paths for XML Virtual Documents

This chapter describes how to specify schema-dependent paths for XML virtual documents.

You can use these paths to access values and to set values.

The examples in this chapter use the schema shown in the previous chapter.

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.

Syntax Refers to
element_name Contents of the given element. element_name must be a child of the root element.
parent.element_name Contents of the given element. parent is the full path to an element — that is, any syntax shown in this table. In this case, element_name is a child of the element referred to by parent.
parent.element_name(n) Contents of the nth element with the name element_name within the given parent.
parent.element_name(-) Contents of the last element with the name element_name within the given parent.

Consider the following XML document:

<?xml version="1.0" ?>
<Patient MRN='000111222' xmlns=''>
    <Name>Georgina Hampton</Name>
        <Street>86 Bateson Way</Street>
        <City>Fall River</City>
        <Name>Dr. Randolph</Name>

The following table shows some example paths for this document:

Example Path Current Path Value
Name Georgina Hampton
FavoriteColors(1) Red
FavoriteColors(2) Green
FavoriteColors(-) Green
Address 86 Bateson WayFall River
Address.Street 86 Bateson Way
Doctor Dr. Randolph

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.

Syntax Refers to
element_reference.attribute_name Value of the attribute_name attribute of the element indicated by element_reference.

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

Example Path Current Path Value
MRN 000111222

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:

Syntax Refers to
element_reference.# Text of the first comment of the given element.
element_reference.#(n) Text of the nth comment of the given element.
element_reference.#(-) Text of the last comment.

InterSystems IRIS removes all comments when it reads in XML files. The only comments that can be present are comments that have been added since the XML file was read. To add a comment, use SetValueAt() with a path like one shown in the preceding table.

Using Mixed Content When Setting Schema-dependent Paths

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

 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:

Path Refers to How InterSystems IRIS Handles the Mixed Content
element or comment InterSystems IRIS replaces the current contents of the element or comment with the given mixed content
attribute Not supported

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%".


InterSystems IRIS does not automatically escape left angle bracket characters when you set DOM-style paths.

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=''>
    <Name>Georgina Hampton</Name>
        <FavoriteColor>REPLACED COLOR</FavoriteColor>
        <FavoriteColor>REPLACED COLOR</FavoriteColor>
        <Street>86 Bateson Way</Street>
        <City>Fall River</City>
        <Name>Dr. Randolph</Name>

Counting Elements

If the path refers to a repeating element, you can use the following syntax to return the number of elements.

Syntax Refers to
element_name(*) Number of elements of the given name, within the given context. This syntax is valid only if the schema defines element_name as a repeating element.
element_name.* Number of elements of the given name, within the given context. This syntax is valid for any element_name.

The following table shows example paths for the document shown previously in this chapter:

Example Path Current Path Value
FavoriteColors.* 2
FavoriteColors(*) 2

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:

    MyApp:Patient listed under the XML Document Structure/Document Type Definition header

    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=''>"
    _"<Name>Jack Brown</Name>"
    _"<Address><Street>233 Main St</Street></Address>"
    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.