Specifying Schema-dependent Paths for XML Virtual Documents
This topic describes how to specify schema-dependent XML virtual property paths (property paths for XML virtual documents).
You can use these paths to access values and to set values.
The examples in this topic use the schema shown in the previous topic.
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
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 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:
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 (< ). 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 < 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 topic 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 topic:
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:
-
Load the corresponding XML schema or schemas into InterSystems IRIS. To do so, use the XML Schema Structures page.
-
Use the Management Portal to find the DocType value for the root element of the documents that you plan to test. For example:
-
In the Terminal or in test code:
-
Create a string that contains the text of a suitable XML document.
-
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.
-
Set the DocType property of this instance.
-
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.