Parser Compatibilities and Error Codes

Introduction

Websydian TransacXML uses XML parsers from different vendors in order to support XML processing on the Java and Windows platforms. Currently the Websydian TransacXML implementation uses the Xerces2 Java parser from Apache Organization and the Microsoft XML Parser.

Even though both parsers conform to the DOM standard there are some differences in the behavior of the two implementations. Websydian TransacXML tries to hide these changes for the developer but this is unfortunately not always possible.

This document describes the platform dependent aspects of using the TransacXML patterns. Usually this document applies when an application that uses TransacXML is moved from one platform to another - and thereby uses another parser.

White Spaces

White spaces is the term for the tab, space, and newline characters that occur in a document. White spaces that occurs between elements are also part of the XML document. This means that white spaces are treated as text nodes in the document (see example).

...
<Elem>Text data 1</Elem>
<Elem>Text data 2</Elem>
...

If an XML document contains the above text it will result in the following nodes being created in the XML tree structure:

The above figure shows that the newline character between the two Elem elements is treated as an independent node. Typically this is not what is intended as the newline character is only inserted for readability.

...
<Elem>Text data 1</Elem><Elem>Text data 2</Elem>
...

To give a correct node tree the XML file should contain the text above.

The parser can be configured to ignore or preserve these white spaces. Currently the two parsers are not setup by default to behave in the same way regarding handling of white spaces. Please refer to the following sections for details.

Java Parser

By default the parsers are set to not to validate documents. For the Java parser this implies that it is not capable of ignoring white spaces since the ignore white space option requires that the validation option is set to true.

To enable ignoring of white spaces the following options should be set:

• ValidateOnParse: True
• PreserveWhiteSpace: False

See the documentation of XmlParsers.JavaParser.SetOption for information on how to do this.

MSXML Parser

The parser ignores white spaces by default. To change this set the option PreserveWhiteSpace to True.

See the documentation of XmlParsers.MSXML.SetOption for information on how to do this.

Namespaces

Websydian TransacXML contains functions that support namespaces as specified by the DOM Level 2 standard. Unfortunately the MSXML parser does not support namespaces as specified by the DOM standard, and this gives some differences in how Websydian TransacXML supports namespaces on the Java platform and on Windows.

The table below explains where the MSXML parser does not conform to the DOM Level 2 standard regarding namespaces.

NamedNodeMap

The NamedNodeMap interface is used to hold a collection of nodes. However, since the DOM specification does not define any specific order of the nodes in this collection, code that indexes a NamedNodeMap collection should not rely on the order of the nodes.

If this advice is not followed then please remember that the behavior of the application might change if the application is changed to use another parser, e.g. from MSXML to the Java parser.

The DOM specification also defines a NodeList collection where the order of the nodes is part of the specification, so in these cases it is safe to write code that relies upon the order of the nodes in the NodeList collection.

Null Values

According to the DOM specification some methods can return a Null value. CA Plex cannot represent Null values so TransacXML uses alternative methods. Please see the following sections on how Null values are handled by TransacXML.

Node Null Values

Many methods in the DOM specification can return a node; e.g. Element.getAttributeNode(). However in some cases it is not possible to return a node, e.g. if the specified attribute node does not exist, and then the DOM specification states that a null value should be returned.

In Websydian DOM this null value translates to the number 0 and the value object NULL contains this literal value when comparing the return value. E.g.

if DomInterfaces.Element.getAttributeNode/Output<objectattr> != <ObjectAttr.NULL>

... do something with the attribute node...

String Null Values

For methods that return a string value some of these will return a null value if the string object does not exist. This happens for the Notation.publicId attribute. In TransacXML string null values are not supported so the Notation.publicId_get function returns the empty string in this case.

The reason for this is that the CA Plex runtime does not support null values for string objects, but also that the MSXML parser on this issue does not conform with the DOM specification, because it returns the empty string when a null should be returned.

Error Codes

All call to DOM functions return a status code in the field ExceptionCode. A value of 0 means that the call succeeded. Any other value indicates an error.

DOM Error Codes

The DOM error codes is in the range 1 - 15 and a description of each of the DOM error codes can be found here.

If a function returns an error code in the above range, the function can be looked up here in order to find out why the call failed.

E.g. if DomInterfaces.Document.createEntityReference returned error code 5 one looks up here and finds that this is the error INVALID_CHARACTER_ERR. In the specification for createEntityReference it can be seen that this error occurs if the name parameter contains an illegal character.

Java Error Codes

Windows Error Codes