XMLNSC: Working with CData

A CData section can be used to embed an XML document within another XML document.

About this task

What is a CData section?

An XML element can contain text content:

<element>text content</element>

However, some characters cannot appear in that content. In particular, '<' and '&' both have special meaning to an XML parser. If they are included in the text content of an element, they change the meaning of the XML document.

For example, this is a badly formed XML document:

<element><text><content></element>

There are two ways to make the XML well-formed:

Use character entities:

<element>&lt;text&gt;&lt;content&gt;</element>

Use a CData section:

<element><![CDATA[<text><content>]]></element>

What can you use a CData section for?

In a CData section, you can include XML markup in the value of an element. However, non-valid XML characters cannot be included. Binary data also cannot be included in a CData section.

The most common use for CData is to embed one XML document within another. For example:

<outer>
    <embedXML>
        <![CDATA[<innerMsg></innerMsg>]]>
    </embedXML>
</outer>

You can even embed a badly-formed XML document in this way, because the XML parser does not attempt to parse the content of a CData section.

<outer>
    <embedXML>
        <![CDATA[<badXML></wrongClosingTag>]]>
    </embedXML>
</outer>

The following items are not valid within a CData section:

Non-valid XML characters (see http://www.w3.org/TR/2006/REC-xml-20060816/#charsets)
The text string ']]>' (because this terminates the CData section)

Because of these restrictions, do not use a CData section to include arbitrary text in your XML document, and do not try to use a CData section to hold binary data ( unless it is encoded as hexBinary or base64Binary ).

How do you add a CData section to an output XML message?

Consider the following input message :

 <TestCase>
    <Folder>
       <Field1>Value1</Field1>
       <Field2>Value2</Field2>
       <Field3>Value3</Field3>
    </Folder>
 </TestCase>

The following ESQL shows how to serialize a whole message:

 DECLARE wholeMsgBlob BLOB
   ASBITSTREAM(InputRoot.XMLNSC,
               InputRoot.Properties.Encoding,
               InputRoot.Properties.CodedCharSetId );
  DECLARE wholeMsgChar CHAR 
   CAST(wholeMsgBlob AS CHAR CCSID InputRoot.Properties.CodedCharSetId);
 SET OutputRoot.XMLNSC.Output.(XMLNSC.CDataField)Field1 = wholeMsgChar;

This example serializes the InputRoot.XMLNSC.TestCase.Folder portion of the message tree.

If the output message tree were examined before an MQOutput node, this would show :

(0x01000010):XML        = (
  (0x01000000):Output = (
    (0x01000000):Field1 = (
      (0x02000001): = '<TestCase><Folder><Field1>Value1</Field1><Field2>Value2</Field2>
                       <Field3>Value3</Field3></Folder><Folder2><Field1>Value1</Field1>
                       <Field2>Value2</Field2><Field3>Value3</Field3><Folder2></TestCase>'
       )
       )
   )

As can be seen, each CData section contains a single scalar value that is the character representation of the portion of the XML message that is required.

This tree produces the following XML output message :

<Output>
 <Field1><![CDATA[<TestCase><Folder><Field1>Value 1</Field1>
                                    <Field2>Value 2</Field2>
                                    <Field3>Value 3</Field3></Folder>
                            <Folder2><Field1>Value 1</Field1>
                                     <Field2>Value 2</Field2>
                                     <Field3>Value 3</Field3></Folder2>
                  </TestCase>]]</Field1>
 </Output>

CData section handling

Use the XMLNSC parser to merge CData sections into a single element in the message tree. Run the following command, where integrationNodeName is the name of your integration node and integrationServerName is the name of your integration server:

mqsichangeproperties integrationNodeName -e integrationServerName  -o ComIbmGenericXmlParserFactory  -n cdataFieldMerging -v option

option can be one of the following values:

Table 1. Options for the -v flag
Value	Description
no	Split the CData section in the message tree based on the "]" character and amount of data. This is the default value.
yes	Merge CData section into a single element in the message tree