Working with binary data

If you need to include binary data or non-valid characters in your XML documents, the safest method is to encode the data as a binary string.

About this task

Binary encodings for XML

There are two methods of encoding binary data in an XML document. 
hexBinary:	<nonXMLChars>0001020304050607080B0C0E0F</nonXMLChars>

base64Binary:	<nonXMLChars>AAECAwQFBgcICwwODw==</nonXMLChars>

The base64Binary encoding makes better use of the available XML characters, and on average a base64-encoded binary field is 2/3 the size of its hexBinary equivalent. Base64Binary is widely used by the MIME format and by various XML-based standards.

You might prefer to use the simpler hexBinary encoding if you are sending data to applications that cannot decode base64 data, and if the increase in message size is not important.

Parsing binary data

The most straightforward way to parse any binary data is to use the XMLNSC parser with a message model:
  1. Locate or construct an XML Schema that describes your input XML.
  2. In your message flow, set the node properties as follows:
    • On the Default page, set Message Domain to XMLNSC.
    • On the Validation page, set Validation to Content and Value.
    • In the XMLNSC properties, select the check box option Build tree using XML Schema types.

The XMLNSC parser automatically decodes your hexBinary or base64Binary data, being guided by the simple type of the element or attribute that contains the binary data. The message tree will contain the decoded BLOB value.

If you are using the XMLNS domain, you must parse the binary data as a string. It appears in the message tree as a CHARACTER value. If the data is encoded as hexBinary, you can use the ESQL CAST function to convert it to a BLOB value. If the data is encoded as base64Binary, the easiest approach is to use the function BASE64DECODE. For more information, see BASE64DECODE function.

Generating binary data

You can generate binary data in your output XML in either hexBinary or base64Binary encoding.

For hexBinary, use the ESQL CAST statement to convert your BLOB data to a hexBinary string.

For base64Binary, you have two options:
  • Call the function BASE64ENCODE. For more information, see BASE64ENCODE function.
  • Use the XMLNSC parser, and modify the type field on the syntax element, as shown in this example:
    -- ESQL code to generate base64-encoded binary data
DECLARE myBLOB BLOB;
-- Populate myBLOB with your binary data
CREATE LASTCHILD OF OutputRoot.XMLNSC.message
       TYPE BITOR(XMLNSC.Attribute, XMLNSC.base64Binary)
       NAME myBase64Element
       VALUE myBLOB;

    Note that setting the field type to XMLNSC.base64Binary does not change the logical value in the message tree. In your message flow, it is still a BLOB, and if you ask for its string representation, it is reported as a hexBinary string. However, when the message tree is converted to a bit stream ( in an output node, or by a call to ASBITSTREAM ) the base64 conversion is performed automatically, and the output XML contains the correct base64 string.