Manipulating messages using the XMLNSC parser

The XMLNSC domain is an extension of the XMLNS domain, which in turn, is an extension of the original XML domain.

The XMLNS domain adds namespace support. The new XMLNSC domain builds a more compact tree and, therefore, use less memory when handling large messages. A new domain has been added so that existing applications are not affected.

Message tree structure

The XMLNSC parser obtains its more compact tree by using a single name-value element to represent tagged text, rather than the separate name and value elements used by the XML and XMLNS parsers. Consider the following message:
    <Folder1>
        <Folder2 Attribute1='AttributeValue1'>
            <Field1><Value1></Field1>
            <Field2 Attribute2='AttributeValue2'><Value2></Field2>  
        </Folder2> 
    </Folder1>

In the XMLNSC domain, this is represented by two name elements (Folder1 and Folder2) and four name-value elements, which are Attribute1, Field1, Field2, and Attribute2.

Start of changeThe XML and XMLNS domains differ in that the two fields (Field1 and Field2) are eachEnd of change represented by a name element with a child value element. This might seem to be a small difference, but messages often have many such leaf fields; for example:
    <Folder1>
        <Folder2>
            <Field1><Value1></Field1>
            <Field2><Value2></Field2>
            ....
            <Field100><Value100></Field100>
        </Folder2> 
    </Folder1>

In this case, the XMLNSC parser represents the message by two name and 100 name-value elements, whereas the XML and XMLNS parsers would use 102 name elements and 100 value elements, plus a further 103 value elements to represent the white-space implicit in formatted messages.

Start of changeThe XML and XMLNS domains create name-value elements for the white-space formatting characters between the close and open of each folder or field. These white-space elements have an empty name and a value for the space, tab, line feed or other characters used in the formatting of the XML document. These elements have no useful value and can therefore be discarded to improve the compaction. For the same reason, the default behavior is to discard any XML processing instructions and comments in the input stream and to create no elements in the compact domain tree.End of change

Attributes and tagged text

As both attributes and tagged text are represented by name-value elements, they are distinguished by the use of the element types. If you do not specify a type, tagged text is assumed. Therefore, the first example message above might be produced by the SQL statements:
    SET Origin.Folder1.Folder2.(XMLNSC.Attribute)Attribute1 = 
       'AttributeValue1';
    SET Origin.Folder1.Folder2.Field1 = ‘Value1’;
    SET Origin.Folder1.Folder2.(XMLNSC.Attribute)Attribute2 = 
       'AttributeValue2';
    SET Origin.Folder1.Folder2.Field2 = ‘Value2’;

Although the preceding ESQL looks almost identical to that used with the XML parser, note particularly that the type constants belong to the XMLNSC parser. The use of constants that belong to other parsers, for example XML, leads to unexpected results because similarly named constants, for example XML.Attribute, have different values.

Start of changeThe following constants are defined in the XMLNSC domain for creating attributes:
   XMLNSC.SingleAttribute
   XMLNSC.DoubleAttribute
End of change
Start of changeThe following constant is defined in the XMLNSC domain for selection of attributes:
   XMLNSC.Attribute
End of change
Start of changeConsider the following XML input message:
    <Folder1 Item='ValueA'>
        <Item>Value1</Item>
    </Folder1>
End of change
Start of changeTo remove the ambiguity of the name Item used as both an attribute name and as a field name in Folder01, the following ESQL can be used:
    SET ItemAttributeValueHolder = InputRoot.XMLNSC.Folder1.(XMLNSC.Attribute)Item;
    SET ItemFieldValueHolder = InputRoot.XMLNSC.Folder1.(XMLNSC.Field)Item;
End of change

This method has an advantage over using an array index selection with Folder1 as it is unaffected if the attribute is not present in the input stream.

Handling mixed text

Start of changeBy default, mixed text is simply discarded on the grounds that, if present, it is generally simply formatting white-space and has no business meaning.End of change

However, a mode is provided in which, when parsing, any text that occurs other than between an opening tag and a closing tag (that is, open->open, close->close, and close->open) Start of changeis represented by a single unnamed Value element.End of change The value element types support PCDATA, CDATA, and hybrid which is a mixture of the preceding two.

There is still no special syntax element behavior regarding the getting and setting of values. Value elements can only be accessed from the SQL by explicitly addressing them. The following extra constants are provided for this purpose:
   XMLNSC.Value
   XMLNSC.PCDataValue
   XMLNSC.CDataValue
   XMLNSC.HybridValue
Start of changeThe mode is controlled by the setting of the Mixed Content Retain Mode in the XMLNSC Parser Options properties dialog navigator on all message parsing nodes, for example, the MQInput node. For programmatic control using message options, the following constants are provided:End of change
   XMLNSC.MixedContentRetainNone = 0x0000000000000000
   XMLNSC.MixedContentRetainAll  = 0x0001000000000000
These constants can be used in the Option clauses of both the SQL CREATE statement (PARSE section) and the ASBITSTREAM function. For example:
   DECLARE X BLOB ASBITSTREAM(InputRoot.XMLNSC.Data OPTIONS 
   XMLNSC.MixedContentRetainAll);
   ...
   CREATE LASTCHILD OF outputRoot PARSE(X OPTIONS 
   XMLNSC.MixedContentRetainNone);

Handling comments

By default, comments are also simply discarded on the grounds that, if present, they are simply auxiliary information with no meaning.

Start of changeHowever, a mode is provided in which, when parsing, any comments that occur in the document (other than in the document description itself) are represented by a name-value element with the name Comment. The following extra constant is provided for this purpose.
   XMLNSC.Comment
End of change
Start of changeThe mode is controlled by the setting of the Comments Retain Mode in the XMLNSC Parser Options properties dialog navigator on all message parsing nodes, for example, the MQInput node. For programmatic control using message options the following constants are provided:End of change
   XMLNSC.CommentsRetainNone = 0x0000000000000000
   XMLNSC.CommentsRetainAll  = 0x0002000000000000
For example:
   DECLARE X BLOB ASBITSTREAM(InputRoot.XMLNSC.Data OPTIONS 
   XMLNSC.CommentsRetainAll);
   ...
   CREATE LASTCHILD OF outputRoot PARSE(X OPTIONS XMLNSC.CommentsRetainNone);

Handling processing instructions

By default, processing instructions are also simply discarded on the grounds that, if present, they are simply auxiliary information with no meaning.

However, a mode is provided in which, when parsing, any processing instructions that occur in the document (other than in the document description itself) are represented by a name-value element with the appropriate name and value. The following extra constant is provided for this purpose:
    XMLNSC.ProcessingInstruction
Start of changeThe mode is controlled by the setting of Processing Instructions Retain Mode in the XMLNSC Parser Options properties dialog navigator on all message parsing nodes, for example, the MQInput node. For programmatic control using message options the following constants are provided:End of change
    XMLNSC.ProcessingInstructionsRetainNone = 0x0000000000000000
    XMLNSC.ProcessingInstructionsRetainAll  = 0x0004000000000000
For example:
    DECLARE X BLOB ASBITSTREAM(InputRoot.XMLNSC.Data 
    OPTIONS XMLNSC.ProcessingInstructionsRetainAll);
    ...
    CREATE LASTCHILD OF outputRoot PARSE(X OPTIONS 
    XMLNSC.ProcessingInstructionsRetainNone);

Migrating an existing flow

Start of changeIn order to use the new XMLNSC domain and parser you must re-code your ESQL to use XMLNSC in your paths. Consider the following ESQL statements:
SET OutputRoot.XML.Person.Salary    = 
               CAST(InputRoot.XML.Person.Salary AS INTEGER) * 3;
SET OutputRoot.XMLNS.Person.Salary  = 
               CAST(InputRoot.XMLNS.Person.Salary AS INTEGER) * 3;
SET OutputRoot.XMLNSC.Person.Salary = 
               CAST(InputRoot.XMLNSC.Person.Salary AS INTEGER) * 3;
End of change
Start of changeIn each case the XML bit-stream expected at the input queue and written to the output queue is of the form:
    <Person><Salary>42</Salary></Person>
End of change

Start of changeThe three ESQL examples differ because they use different parsers to own these elements. The owning parser can be set either by the incoming message, with an MQRFH2 header with a <mcd> folder specifying the message set domain, or by the message set domain defined in the Default properties of the flow input node. If both of these domain definitions are present the value for the message set domain in the MQRFH2 header <mcd> folder takes precedence. End of change

Start of changeIf you want to migrate to the XMLNSC domain, when using MQRFH2 headers, the new domain name is required in the <Msd> field of the <mcd> folder. Note that the new domain name appears in the MQRFH2 header of the outgoing message. To protect external applications from these changes, the Use XMLNSC Compact Parser for XMLNS Domain property can be specified on the flow's input node and Compute or Mapping node. With these properties set, the input and output messages are unchanged, allowing the <Msd> field value to remain as XMLNS. The flow now uses the compact parser and the ESQL paths are coded using XMLNSC.End of change

Start of changeIf the incoming messages do not contain MQRFH2 headers and the input node's message domain property is used to specify the domain, you can migrate to the XMLNSC domain by setting the flow's input node domain property directly to XMLNSC, or leave it as XMLNS and set the Use XMLNSC Compact Parser for XMLNS Domain property. The Compact parser is used in the flow and the ESQL paths must be coded using XMLNSC with either of these settings.End of change

Start of changeIf outgoing messages do not contain MQRFH2 headers, the domain does not appear anywhere in the output messages and the setting of the Compute node's Use XMLNSC Compact Parser for XMLNS Domain property has no effect.End of change

Constructing XML headers

The following ESQL is valid in the XML domain:
SET OutputRoot.XML.(XML.XmlDecl)*.(XML.Version)* = '1.0';
To migrate to XMLNS, simply changing the root is enough to make this work:
SET OutputRoot.XMLNS.(XML.XmlDecl)*.(XML.Version)* = '1.0';

Note that although the XMLNS parser is being used, the element type constants are those belonging to the XML parser. This works because the type values used by the XML and XMLNS parsers are the same. For the XMLNSC parser, however, the type values are different and, therefore, you must always use its own type constants.

In the XMLNSC domain there is no special type for the XML version; it is simply treated as an attribute of the XML declaration. The equivalent syntax for the above example is:
SET OutputRoot.XMLNSC.(XMLNSC.XmlDeclaration)*.(XMLNSC.Attribute)Version = '1.0';
Start of changeIn a similar way in the XMLNSC domain the XML encoding type and XML standalone mode are also processed simply as attributes of the XML declaration and can be set up in ESQL as follows:
SET OutputRoot.XMLNSC.(XMLNSC.XmlDeclaration)*.(XMLNSC.Attribute)Encoding = 'UTF-8';
SET OutputRoot.XMLNSC.(XMLNSC.XmlDeclaration)*.(XMLNSC.Attribute)StandAlone = 'Yes';
End of change

Copying message trees

When copying trees, the broker regards XML and XMLNSC as unlike parsers, which means that all attributes in the source tree get mapped to elements in the target tree. This situation arises only if you are using both parsers in the same flow - one for input and one for output; in this situation use the compact parser for both flows.

If different parsers must be used for the input flow and output flow, you might need to explicitly specify the types of elements in the paths or use the FIELDVALUE function to ensure a copy of scalar values rather than of sub-trees.

Follow the guidance provided for XML messages in Manipulating messages in the XML domain, in conjunction with the information in the topic Manipulating message body content.

Accessing syntax elements in the XMLNSC domain using correlation names

The following table provides the correlation names for each XML syntax element. When working in the XMLNSC domain, use these names to refer to the elements in input messages, and to set elements, attributes, and values in output messages.
Table 1. Correlation names for XML syntax elements
Syntax element Correlation name Constant value
Folder XMLNSC.Folder 0x01000000
Document type 1 XMLNSC.DocumentType 0x01000300
XML declaration 2 XMLNSC.XmlDeclaration 0x01000400
     
Field or Attr Value XMLNSC.Value 0x02000000
PCData value XMLNSC.PCDataValue 0x02000000
CData value XMLNSC.CDataValue 0x02000001
Hybrid value XMLNSC.HybridValue 0x02000002
     
Entity Reference XMLNSC.EntityReference 0x02000100
     
Field XMLNSC.Field 0x03000000
PCData XMLNSC.PCDataField 0x03000000
CData XMLNSC.CDataField 0x03000001
Hybrid XMLNSC.HybridField 0x03000002
     
Attribute XMLNSC.Attribute 0x03000100
Single quote XMLNSC.SingleAttribute 0x03000101
Double quote XMLNSC.DoubleAttribute 0x03000100
     
Namespace declaration XMLNSC.NamespaceDecl 0x03000102
Single quote XMLNSC.SingleNamespaceDecl 0x03000103
Double quote XMLNSC.DoubleNamespaceDecl 0x03000102
     
Bitstream data XMLNSC.BitStream 0x03000200
     
Entity definition 1 XMLNSC.EntityDefinition 0x03000300
Single quote XMLNSC.SingleEntityDefinition 0x03000301
Double quote XMLNSC.DoubleEntityDefinition 0x03000300
     
Comment XMLNSC.Comment 0x03000400
     
Processing instruction XMLNSC.ProcessingInstruction 0x03000401
Notes:
  1. Document Type is only used for entity definitions. For example:
    SET OutputRoot.XMLNSC.(XMLNSC.DocumentType)BodyDocument
                  .(XMLNSC.EntityDefinition)TestDef =
     		          'Compact Tree Parser XML Test Module Version 1.0';
  2. The XML declaration is a special folder type that contains child elements for version, and so on. For example:
    -- Create the XML declaration 		
    SET OutputRoot.XMLNSC.(XMLNSC.XmlDeclaration)*.Version = 1.0;
    SET OutputRoot.XMLNSC.(XMLNSC.XmlDeclaration)*.Encoding = 'UTF8';
    SET OutputRoot.XMLNSC.(XMLNSC.XmlDeclaration)*.Standalone = 'yes';

Start of changeHow to use EntityDefintion and EntityReference with the XMLNSC parserEnd of change

Start of changeTwo examples are provided to demonstrate how to use EntityDefintion and EntityReference with the XMLNSC parser using ESQL. Both of the examples use the same input message:
<BookInfo dtn="BookInfo" edn="author" edv="A.N.Other">
<Identifier>ES39B103T6</Identifier>
</BookInfo>
End of change
Start of changeThe first example shows a way to use EntityDefintion and EntityReference with the XMLNSC parser. This is the output message generated by the example:
<!DOCTYPE BookInfo [<!ENTITY author "A.N.Other">]>
<BookInfo><Identifier>ES39B103T7</Identifier><entref>&author;</entref></BookInfo>
End of change
Start of changeIn the following ESQL XMLNSC.EntityDefinition is used to define the hard coded entity author with a value of A.N.Other derived from edv from the input message. XMLNSC.EntityReference is used to create a reference to the entity author in the XML message body.
SET OutputRoot.MQMD = InputRoot.MQMD;
DECLARE cursor REFERENCE TO InputRoot.XMLNSC.BookInfo;
SET OutputRoot.XMLNSC.BookInfo.Identifier = cursor.Identifier;
SET OutputRoot.XMLNSC.(XMLNSC.DocumentType)* NAME = cursor.dtn;
SET OutputRoot.XMLNSC.(XMLNSC.DocumentType)*.(XMLNSC.EntityDefinition)* NAME = 'author';
SET OutputRoot.XMLNSC.(XMLNSC.DocumentType)*.(XMLNSC.EntityDefinition)author VALUE = cursor.edv;
SET OutputRoot.XMLNSC.(XMLNSC.BookInfo).entref.(XMLNSC.EntityReference)* = 'author';
End of change

Start of changeThe variable cursor is used to point to the following variables: dtn, the document type name; edv, the entity definition value; and the value for Identifier. The values for these variables are derived from the input message.End of change

Start of changeThis second example demonstrates how to create an output message containing an entity definition and a reference to that entity based on the content of the same input message. This is the output message generated by the example showing an entity definition called author and a reference to the entity in the XML message body:
<!DOCTYPE BookInfo [<!ENTITY author "Book 1">]>
<BookInfo Identifier="ES39B103T6">&author;</BookInfo>
End of change
Start of changeThe following ESQL uses EntityDefintion and EntityReference with the XMLNSC parser to generate the preceding output message:
SET OutputRoot.MQMD = InputRoot.MQMD;
DECLARE cursor REFERENCE TO InputRoot.XMLNSC.BookInfo;
CREATE FIELD OutputRoot.XMLNSC.BookInfo;
SET OutputRoot.XMLNSC.(XMLNSC.DocumentType)* NAME = cursor.dtn;
SET OutputRoot.XMLNSC.(XMLNSC.DocumentType)*.(XMLNSC.EntityDefinition)* NAME = cursor.edn;
SET OutputRoot.XMLNSC.(XMLNSC.DocumentType)*.(XMLNSC.EntityDefinition)* VALUE = 'Book 1';
SET OutputRoot.XMLNSC.(XMLNSC.Folder)*[<].(XMLNSC.EntityReference)* = cursor.edn;
SET OutputRoot.XMLNSC.Identifier.(XMLNSC.DoubleAttribute)Identifier = cursor.Identifier;
End of change

Start of changeXMLNSC.EntityDefinition is used to define the entity author with a value of Book 1. A reference to the author entity is then created in the message using XMLNSC.EntityReference. The variable cursor is used to point to the variables: dtn, the document type name; edn, the entity definition name; and the value for Identifier. These variables are all derived from the input message. The XMLNSC.DoubleAttribute code is used to add double quotes to the Identifier. To add only single quotes to the Identifier then XMLNSC.SingleAttribute can be used.End of change

XMLNSC parser modes

By default, the XMLNSC parser discards document elements that typically carry no business meaning. However, parser modes are available to force retention of these elements. You can configure these modes on the properties of the node that specifies the message is to be parsed in the XMLNSC domain.

The valid parser modes for the XMLNSC parser are:
XMLNSC.MixedContentRetainNone
XMLNSC.MixedContentRetainAll
XMLNSC.CommentsRetainNone
XMLNSC.CommentsRetainAll
XMLNSC.ProcessingInstructionsRetainNone
XMLNSC.ProcessingInstructionsRetainAll
The following example uses the XMLNSC.ProcessingInstructionsRetainAll and XMLNSC.ProcessingInstructionsRetainNone modes to retain document processing instructions while parsing:
DECLARE X BLOB ASBITSTREAM(InputRoot.XMLNSC.Data OPTIONS XMLNSC
                          .ProcessingInstructionsRetainAll);
...     
CREATE LASTCHILD OF outputRoot PARSE(X OPTIONS XMLNSC
                          .ProcessingInstructionsRetainNone);
Related concepts
Message flows overview
XML parsers and domains
ESQL overview
Related tasks
Designing a message flow
Defining message flow content
Manipulating messages in the XML domain
Related reference
ESQL reference
SET statement
FIELDVALUE function
ASBITSTREAM function
CREATE statement