Skip to main content
Previous sectionNext section

Special Topics

This topic describes the following additional special topics:

The XML examples in this topic are in literal format.

Class and Property Parameters Discussed in This Topic
  • XMLNAME
  • XMLSEQUENCE
  • XMLUNSWIZZLE
  • XMLPREFIX
  • XMLIGNOREINVALIDTAG
  • XMLIGNOREINVALIDATTRIBUTE

Controlling the Closing of Elements

In XML, an element that contains only attributes can be represented in either of the following ways:

<tag attribute="value" attribute="value" attribute="value"></tag>
<tag attribute="value" attribute="value" attribute="value"/>

Caché recognizes these forms as equivalent. When you export objects with %XML.Writer, you can control the closing form, but not by modifying the XML projection itself. See “Controlling the Closing of Elements” in the topic “Writing XML Output from Caché Objects” in Using Caché XML Tools.

Handling a Document with Multiple Tags with the Same Name

A given element in XML can contain multiple elements that have the same name; these elements are distinguished from each other by their order. For example, the following is a legitimate XML document:

<?xml version="1.0" encoding="UTF-8"?>
<Root>
   <Person>
      <Name>Able, Andrew</Name>
      <DOB>1977-10-06</DOB>
      <Address>
         <Street>6218 Clinton Drive</Street>
         <City>Reston</City>
         <State>TN</State>
         <Zip>87639</Zip>
      </Address>
      <Address>
         <Street>110 High Street</Street>
         <City>Zanesville</City>
         <State>OR</State>
         <Zip>80719</Zip>
      </Address>
   </Person>
</Root>
Copy code to clipboard

It is slightly tricky to map such a document to a Caché class, because each class property must have a unique name.

To map such a document to a Caché class, do the following:

  • Set the XMLNAME property parameter as needed to map different class properties to the same XML name.

  • Set the XMLSEQUENCE class parameter equal to 1. As a precaution, this ensures that the mapping respects the order of the properties as listed in the class definition.

  • Make sure that the properties are listed in the class definition in the same order as in the XML document.

For example, consider the following class definition:

Class GXML.TestSequence.Person Extends (%Persistent, %XML.Adaptor)
{

Property Name As %Name [ Required ];
Property DOB As %Date(FORMAT = 5, MAXVAL = "+$h") [ Required ];
Property HomeAddress As GXML.TestSequence.Address(XMLNAME = "Address");
Property WorkAddress As GXML.TestSequence.Address(XMLNAME = "Address");

/// If the XMLSEQUENCE = 1, then the order of the XML elements must match the 
/// order of the class properties.  This allows us to deal with XML where the 
/// same field appears multiple times and is distinguished by the order.
Parameter XMLSEQUENCE = 1;

}
Copy code to clipboard

This class definition maps to the XML document shown previously.

Note:

If XMLSEQUENCE is 1, the XMLIGNOREINVALIDTAG parameter is ignored.

Controlling Unswizzling After Export

When you use Caché XML tools to export a persistent XML-enabled object, the system automatically swizzles all needed information into memory as usual; this information includes object-valued properties. After exporting the object, Caché unswizzles any lists of objects but does not (by default) unswizzle single object references. In the case of large objects, this can result in <STORE> errors.

To cause any single object references to be unswizzled in this scenario, set the XMLUNSWIZZLE parameter in your XML-enabled class as follows:

Parameter XMLUNSWIZZLE = 1;
Copy code to clipboard

The default for this parameter is 0.

Projecting Caché IDs for Export

When you project a Caché object at the top level (rather than as a property of another object), its internal ID, OID, and globally unique ID are not available as object properties, and these IDs are thus are not projected. However, in some cases, you might want to use an object ID as the unique identifier. Then, for example, you can match an incoming (changed) object to the corresponding stored object, before updating the stored object.

Caché XML support provides several helper classes that you can use to project Caché object identifiers to XML documents: %XML.Id (for the internal ID), %XML.Oid (for the OID), and %XML.GUID (for the globally unique ID).

To use these classes, add a special property to your XML-enabled class whose purpose is to contain the ID that you will export. The property must be of type %XML.Id, %XML.Oid, or %XML.GUID. Make sure that this property is projected, and mark it as transient so that it is not included in the SQL projection of the class.

When you are exporting to XML, you bring an object of your XML-enabled class into memory. When the object is in memory, the special property you added retrieves the requested ID from Caché internal storage and contains that value (so that you can export it).

For example, consider the following class:

Class MyApp4.Obj.Person4 Extends (%Persistent,%Populate,%XML.Adaptor) 
{

Property IdForExport As %XML.Id
(XMLNAME="CacheID", XMLPROJECTION="ELEMENT") [Private, Transient];

Property Name As %Name;

Property DOB As %Date(FORMAT = 5, MAXVAL = "+$h");

}
Copy code to clipboard

In this class, the special property is IdForExport. This property is specifically projected with the XML element name of CacheID.

Example output for this class is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<Root>
   <Person>
      <CacheID>1</CacheID>
      <Name>Marks,Jules F.</Name>
      <DOB>1989-04-02</DOB>
   </Person>
   <Person>
      <CacheID>2</CacheID>
      <Name>Palmer,Angelo O.</Name>
      <DOB>1937-11-15</DOB>
   </Person>
...
Copy code to clipboard

Controlling the Namespace Prefix on Export

When you generate XML output for an object, the system generates namespace prefixes as needed, but you can specify the prefixes if needed. To do so, set the following parameter in the class definitions for the XML-enabled objects:

XMLPREFIX

Specifies the prefix to associate with the namespace for this class.

For details, see “Writing XML Output from Caché Objects,” in Using Caché XML Tools.

Handling Unexpected Elements and Attributes on Import

Because the source XML documents might contain unexpected elements and attributes, your XML-enabled classes provide two parameters to specify how to react when you import such a document. For example, consider the following class definition:

Class GXML.TestImportParms.Person Extends (%Persistent,%XML.Adaptor) 
{

Property Name As %Name [ Required ];
Property DOB As %Date(FORMAT = 5, MAXVAL = "+$h") [ Required ];
}
Copy code to clipboard

Also consider the following XML document:

<?xml version="1.0" encoding="UTF-8"?>
<Root>
   <Person employeeID="450">
      <Name>Dillard, Daniel</Name>
      <DOB>1962-09-18</DOB>
      <UserID>fr0078</UserID>
      <Address>
         <Street>810 Main Street</Street>
         <City>Reston</City>
         <State>NJ</State>
         <Zip>02641</Zip>
      </Address>
   </Person>
</Root>
Copy code to clipboard

The employeeID attribute and the <Address> element do not correspond to properties in the class and are therefore unexpected.

To specify how to handle unexpected attributes and elements, use the following parameters of your XML-enabled classes:

XMLIGNOREINVALIDATTRIBUTE

Controls how to handle attributes that are unexpected. If this parameter is 1 (the default), such attributes are ignored. If it is 0, they are treated as errors, and import fails.

XMLIGNOREINVALIDTAG

Controls how to handle elements that are unexpected. If this parameter is 1, such elements are ignored. If it is 0 (the default), they are treated as errors, and import fails.

These parameters affect only import.

Note:

The xmlns attribute, array key name attribute, and schema instance (xsi) attribute are always ignored.

Also, if XMLSEQUENCE is 1, the XMLIGNOREINVALIDTAG parameter is ignored. See the section “Handling a Document with Multiple Tags with the Same Name,” earlier in this topic.