Obtaining additional error information

The default behavior when there is an XML document error is the z/OS® XML parser returns a reason code which identifies the error, and an offset into the original document which is being parsed. In many cases, this is insufficient as XML documents are commonly transcoded in transit. Such transcodings can cause offsets to change in the document, rendering the offsets less useful.

The type of error information that can be provided will necessarily vary by the particular error encountered. The following are examples of additional error information that may be made available when an error is encountered:

A bit indicator which identifies the general location within the document. This can be XML declaration, DTD, element, miscellaneous, or an attribute which is a namespace declaration. If the error occurs in entity replacement text, an additional bit will be set.
A location string which represents a path-like expression for the ancestor element node(s) at the point of the error. This will be only applicable when the error occurs within the XPath addressable portion of the document. There also will be an associated namespace context provided in order to assist in correctly identifying the failing location.
A failed string which represents information taken from the document. For example, this could be an incorrect element name or an invalid Unicode character.
A string which is expected to be present but is missing.

Because element occurrences can be repeated with the same names, it is possible to also include position information in the path-like expression. However, tracking element positions will be detrimental to performance even when there is no error.

This additional error information may be obtained for a validating parse by using the XEC_CTL_ERROR_HANDLING control option along with the XERR structure which is mapped by GXLHERR in gxlhctl.h to enable this feature. The XERR_ENH_ERROR_INFORMATION flag will cause additional auxiliary records to be returned which may contain information on the location of the error, the string which is in error and also possibly an expected string. The XERR_XD_PTR is where the service will store the address of the diagnostic area, which is mapped by GXLHXD in the gxlhxd.h file. The XD_LastOutput field is a pointer to the data area containing these records. This data area is within the PIMA and is formatted in the same manner as a normal output buffer. It will have a buffer information record followed by one or more additional records. This data area will be overlaid on a subsequent call to the z/OS XML parser.

The XERR_ENH_ERROR_LOCATION feature flag may also be specified to request that position indexes be returned in the XPath expression which represents the error location. Enabling this feature will impact performance.

In order to explain how element position indexes are tracked, the concept of an expanded QName needs to be explained. See the following example:

<?xml version="1.0"?>
<root>
<pre:elem1 xmlns:pre=”http://w3.pok.ibm.com”>
</pre:elem1>
<pfx:elem1 xmlns:pre=”http://w3.pok.ibm.com”>
</pfx:elem1>
</root>

For the first non-root element, the QName would be pre:elem1 and the second pfx:elem1. However, an expanded QName consists of the namespace URI and the local name. Two expanded QNames are equal if their namespace URIs and local names are equal (even if the prefixes are not equal). So in this case, if an error occurred on the pfx:elem1, the index would be "[2]" since both expanded QNames are http://w3.pok.ibm.com:elem1. This is a simple example. With default namespaces, the situation can be more complicated.