Ensemble XML Virtual Document Development Guide
Specifying Schema-dependent Paths for XML Virtual Documents
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

This chapter describes how to specify schema-dependent paths for XML virtual documents. It discusses the following:

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='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:
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
Ensemble 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.
Note:
Ensemble 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 Paths
When you use setValueAt(), you can specify a value that consists of mixed content (that is, a value that consists of a mix of element and text nodes). For example:
 set mixed="SOME TEXT<HOMETOWN>BELMONT</HOMETOWN>"
 set status=target.SetValueAt(mixed,"Address")
The following table describes how Ensemble handles the value in different scenarios:
Path Refers to How Ensemble Handles the Mixed Content
element or comment Ensemble replaces the current contents of the element or comment with the given mixed content
attribute Not supported
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>
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 Ensemble. 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
}
The following shows output from this method:
ENSDEMO>d ##class(Demo.CheckPaths).TestSchemaPath()
233 Main St
For additional options for GetValueAt(), see The pFormat Argument,” later in this book.