Manipulating messages in the XMLNS domain

This topic provides information specific to dealing with messages that belong to the XMLNS domain, and that are parsed by the generic XML parser. The XMLNS domain is an extension of the XML domain and provides namespace support. 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.

The following example shows how to use ESQL to work with namespaces. The example declares namespace constants at the start of the main module so that you can use prefixes in the ESQL statements instead of the full namespace URIs.

The namespace constants affect only the ESQL; they do not control the prefixes generated in the output message. The prefixes in the generated output message are controlled by namespace declarations. You can include namespace declarations in the tree using the XML.NamespaceDecl correlation name. These elements are then used to generate namespace declarations in the output message.

If, when the output message is generated, the namespace with which an element or attribute is qualified has no corresponding namespace declaration, one is automatically generated using prefixes of the form NSn where n is a positive integer.

CREATE COMPUTE MODULE xmlns_doc_flow_Compute
CREATE FUNCTION Main() RETURNS BOOLEAN
BEGIN
CALL CopyMessageHeaders();

-- Declaration of namespace constants
DECLARE sp1 NAMESPACE 'http://www.ibm.com/space1';
DECLARE sp2 NAMESPACE 'http://www.ibm.com/space2';
DECLARE sp3 NAMESPACE 'http://www.ibm.com/space3';

-- Namespace declaration to associate prefix 'space1' with the namespace
SET OutputRoot.XMLNS.message.(XML.NamespaceDecl)xmlns:space1 = 'http://www.ibm.com/space1';  
SET OutputRoot.XMLNS.message.sp1:data1 = 'Hello!';      
 
-- Default Namespace declaration
SET OutputRoot.XMLNS.message.sp2:data2.(XML.NamespaceDecl)xmlns = 'http://www.ibm.com/space2';
SET OutputRoot.XMLNS.message.sp2:data2.sp2:subData1 = 'Hola!';
SET OutputRoot.XMLNS.message.sp2:data2.sp2:subData2 = 'Guten Tag!';

SET OutputRoot.XMLNS.message.sp3:data3 = 'Bonjour!';

SET OutputRoot.Properties.MessageDomain = 'XMLNS';

RETURN TRUE;
END;

CREATE PROCEDURE CopyMessageHeaders() BEGIN
DECLARE I INTEGER 1;
DECLARE J INTEGER CARDINALITY(InputRoot.*[]);
WHILE I < J DO
SET OutputRoot.*[I] = InputRoot.*[I];
SET I = I + 1;
END WHILE;
END;

END MODULE;
When this ESQL is processed, the following output message is generated:
<message xmlns:space1="http://www.ibm.com/space1">
 <space1:data1>Hello!</space1:data1>
 <data2 xmlns="http://www.ibm.com/space2">
  <subData1>Hola!</subData1>
  <subData2>Guten Tag!</subData2>
 </data2>
 <NS1:data3 xmlns:NS1="http://www.ibm.com/space3">Bonjour!</NS1:data3>
</message>

You can also specify that a named XML element (and its descendents, if it is a complex element) is parsed opaquely. That is, a single named element is created in the message tree with a value (encoded in UTF-16) that contains the actual XML bit stream that is contained between the start and end tags of the opaque element. This option can provide performance benefits if the contents of an element are not significant within your message flow.

To specify that an XML element is to be parsed opaquely, use an ESQL CREATE statement with a PARSE clause to parse the XML document. Set the FORMAT qualifier of the PARSE clause to the constant, case-sensitive string 'XMLNS_OPAQUE' and set the TYPE qualifier of the PARSE clause to the name of the XML element which is to be parsed in an opaque manner. The TYPE clause can specify the element name with no namespace (to match any namespace), or with a namespace prefix or full namespace URI (to match a specific namespace).

Consider the following example:

DECLARE soap NAMESPACE 'http://schemas.xmlsoap.org/soap/envelope/';

DECLARE BitStream BLOB ASBITSTREAM(InputRoot.XMLNS
                                   ENCODING InputRoot.Properties.Encoding
                                   CCSID InputRoot.Properties.CodedCharSetId);
--No Namespace
  CREATE LASTCHILD OF OutputRoot
    DOMAIN('XMLNS')	
          PARSE (BitStream
                 ENCODING InputRoot.Properties.Encoding
                 CCSID InputRoot.Properties.CodedCharSetId
                 FORMAT 'XMLNS_OPAQUE'
                 TYPE 'Body');

--Namespace Prefix
  CREATE LASTCHILD OF OutputRoot
    DOMAIN('XMLNS')
          PARSE (BitStream
                 ENCODING InputRoot.Properties.Encoding
                 CCSID InputRoot.Properties.CodedCharSetId
                 FORMAT 'XMLNS_OPAQUE'
                 TYPE 'soap:Body');

--Namespace URI
  CREATE LASTCHILD OF OutputRoot
    DOMAIN('XMLNS')
          PARSE (BitStream
                 ENCODING InputRoot.Properties.Encoding
                 CCSID InputRoot.Properties.CodedCharSetId
                 FORMAT 'XMLNS_OPAQUE'
                 TYPE '{http://schemas.xmlsoap.org/soap/envelope/}Body');

Opaque parsing of XML elements is only available in the XMLNS domain; and the control over how this is specified is subject to change in later releases.

For further information about CREATE and examples of its use, see the CREATE statement.

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
DECLARE statement
SET statement