Projecting Objects to XML
Controlling Transformations of Values
[Back] [Next]
Go to:

This chapter discusses how values are transformed as you export objects to XML and import XML into objects, and it discusses your options for controlling those transformations.

The XML examples in this chapter are in literal format.
The following chapter discusses null values and missing values.
Class and Property Parameters Discussed in This Chapter
An XML-enabled object typically includes properties defined by Caché data types. Each data type class defines the LogicalToXSD() and XSDToLogical() methods. Whenever XML output is requested for the object, the Caché XML tools automatically call the LogicalToXSD() method for each property, to convert the data to the appropriate format for use in XML. Similarly, whenever an XML document is used as input, the Caché XML tools call the XSDToLogical() method to convert the data into the correct format for Caché.
For example, in the %Binary data type class, the LogicalToXSD() method converts the outbound value using the $SYSTEM.Encryption.Base64Encode() method. Similarly, the XSDToLogical() method converts the inbound value using the $SYSTEM.Encryption.Base64Decode() method.
A Caché class can also include stream-valued properties, but the stream classes do not define the LogicalToXSD() and XSDToLogical() methods. Instead, the XML tools treat stream classes specially when they are used as properties of an XML-enabled class. Specifically:
When you use XML-enabled objects, it is sometimes necessary to consider the special cases of values that cannot be directly projected to XML or values that you want to transform for other reasons. The rest of this chapter discusses these cases.
Handling Special XML Characters
Depending on the context, Caché XML support escapes the ampersand character (&) and certain other characters, when it finds those characters within a property of type string or character stream.
The ESCAPE property parameter controls which characters are recognized as special. This parameter is either "XML" (the default) or "HTML" (not discussed in this book). In the examples in this book, ESCAPE is "XML".
For these special characters, you can control how the escaping is performed by setting the CONTENT property parameter. The details are different for literal and encoded formats, as follows:
Form of Escaping for Literal and SOAP-encoded Formats
Value of CONTENT (Case-insensitive) XML Document in Literal Format XML Document in SOAP-encoded Format
"STRING" (the default) CData CData
"ESCAPE" XML entity XML entity
"ESCAPE-C14N" XML entity* XML entity*
"MIXED" No escaping is done CData
*For "ESCAPE-C14N", the escaping is done in accordance with the XML Canonicalization standard. The main difference is that a carriage return is escaped as 
Consider the following class:
Class ResearchXForms.CONTENT Extends (%RegisteredObject, %XML.Adaptor)

Parameter XMLNAME = "Demo";

Property String1 As %String;

Property String2 As %String(CONTENT = "STRING");

Property String3 As %String(CONTENT = "ESCAPE");

Property String4 As %String(CONTENT = "MIXED");

String2 and String1 are always treated in the same way, because String2 uses the default value for CONTENT.
Literal XML output for this class might look like the following:
<?xml version="1.0" encoding="UTF-8"?>
  <String1><![CDATA[value 1 & value 2]]></String1>
  <String2><![CDATA[value 1 & value 2]]></String2>
  <String3>value 1 &amp; value 2</String3>
  <String4>value 1 & value 2</String4>
SOAP-encoded XML output would be as follows instead:
<?xml version="1.0" encoding="UTF-8"?>
xmlns:s="" xmlns:xsi="">
  <String1><![CDATA[value 1 & value 2]]></String1>
  <String2><![CDATA[value 1 & value 2]]></String2>
  <String3>value 1 &amp; value 2</String3>
  <String4><![CDATA[value 1 & value 2]]></String4>
Alternative Way to Prevent the Escaping
There is another way to prevent the escaping of special XML characters. You can define the property as one of the special XML types: %XML.String, %XML.FileCharacterStream, or %XML.GlobalCharacterStream. For these data type classes, CONTENT is "MIXED".
Note that your application is responsible for ensuring that the property value is valid for the scenario in which it will be used; the %XML.String and other classes do not provide this validation.
Handling the UTC Time Zone Indicator
For XML-enabled classes, you can specify whether to use the UTC time zone indicator when importing from XML documents. Similarly, you can specify whether to include the UTC time zone indicator on export.
To do so, specify the XMLTIMEZONE parameter. Use one of the following values:
On export, UTC time is always used. The XMLTIMEZONE parameter controls the UTC zone indicator is included.
Consider the following class:
Class ResearchXForms.UTC Extends (%Persistent, %XML.Adaptor)

Parameter XMLNAME = "Demo";

Property Time1 As %Time;

Property Time2 As %Time(XMLTIMEZONE = "IGNORE");

Property TimeStamp1 As %TimeStamp;

Property TimeStamp2 As %TimeStamp(XMLTIMEZONE = "IGNORE");

XML output for this class might be as follows:
<?xml version="1.0" encoding="UTF-8"?>
Projecting the Value in DISPLAYLIST
For properties of type %String (or any subclass), the XML projection can use the DISPLAYLIST parameter.
Simple properties can specify the DISPLAYLIST and VALUELIST parameters. The VALUELIST parameter specifies a list of possible values for the property; this defines an enumerated property . Often you also specify the DISPLAYLIST parameter, which specifies the corresponding values to display.
By default, the XML projection uses the value contained in the object, which is one of the values specified by VALUELIST. For properties of type %String, the XMLLISTPARAMETER parameter is meant to indicate which parameter contains the list of alternative values to use in the projection. Typically, you set this equal to "DISPLAYLIST". For example, consider the following data type class:
Class xmldisplaylist.MyEnumString Extends %String

Parameter VALUELIST = ",a,b,c";

Parameter DISPLAYLIST = ",apples,bananas,chocolate";


Also consider the following class, which uses the preceding data type class:
Class xmldisplaylist.Demo Extends (%RegisteredObject, %XML.Adaptor)

Property Property1 As MyEnumString;

Property Property2 As MyEnumString(DISPLAYLIST = ",red,green,blue", VALUELIST = ",r,g,b");

The following shows an example of the XML representation of an instance of this class:
In contrast, if the data type class did not specify the XMLLISTPARAMETER parameter, the XML representation would be as follows:
Controlling the Line Endings of Imported Stream Properties
For each property that is a character stream, you can control the line endings in the stream when you import from XML. To do so, you set the XMLSTREAMMODE property parameter, which can have either of the following values (not case-sensitive):
For example, suppose that we have the following data:
<![CDATA[this is a line
this is another line
this is another line
We import this data into an object that has a Stream1 property of type %Stream.GlobalCharacter. By default, XMLSTREAMMODE is "block" for the property. After we import data, this property will contain the following data:
this is a line
              this is another line
                                  this is another line
If we set XMLSTREAMMODE equal to "line" for this property, and reimported the data, this property would contain the following data:
this is a line
this is another line
this is another line
In this case, the line endings are determined by the LineTerminator property of the stream class. This property equals $char(13,10) for %Stream.GlobalCharacter.
Specifying a Default Date/Time Value
For the %TimeStamp and %DateTime data type classes, the XMLDEFAULTVALUE parameter specifies the value to use if the date fails validity check by $zdatetimeh. By default, in such a case, a null string is used, and this results in an error when you import data via XMLImport(). Specify a date in YYYY-MM-DD HH:MM:SS.nnnnnnnnn format, starting with any year after 1841 (so that the date is valid). For example: 1841-01-1 00:00:00
Projecting Nonprinting Characters to XML
XML does not permit nonprinting characters, specifically characters below ASCII 32 (except for carriage return, line feed, and tab).
If you need to project a property to XML and that property contains any of these nonprinting characters, that property must be of type %Binary or %xsd.base64Binary (which is equivalent). This value is automatically converted to base–64 encoding on export to XML (or automatically converted from base–64 encoding on import).