Handling XML PARSE exceptions

If the XML parser encounters an anomaly or error during parsing, it sets an exception code in the XML-CODE special register and signals an XML exception event. The specific exception codes that can occur and the subsequent actions that you can take differ depending on the setting of the XMLPARSE compiler option.

About this task

For XMLPARSE(XMLSS):

Return code and reason code: The exception code is formed from the return code and the reason code that the parser generates. The return code and the reason code are each a halfword binary value. The value in XML-CODE is a concatenation of these two values.

As an example, the following XML document is not well formed because the element end tag mmsg does not match the element start tag msg:


<msg>Hello</mmsg>

The return code is hexadecimal 000C (XRC_NOT_WELL_FORMED), and the reason code is hexadecimal 3035 (XRSN_ENDTAG_NAME_MISMATCH), if you parse the document without validation. The concatenation of these two values, hexadecimal 000C3035, is returned to the processing procedure in the XML-CODE special register.

If you parse a document with validation, the values returned in XML-CODE for any well-formedness errors differ from the values returned for the same errors when you parse without validation. The return code generated by the z/OS® XML System Services parser for any validation error is 24 (hexadecimal 0018).

For more information about the return codes and reason codes that can be generated, see the related reference about exceptions with XMLPARSE(XMLSS) in effect.

If XMLPARSE(XMLSS) is in effect, processing procedures cannot handle exception events and cannot cause parsing to resume. When a processing procedure returns to the parser from an exception event, the parser does not signal any further events. The parser transfers control to the statement that is specified in the ON EXCEPTION phrase of the XML PARSE statement. If you did not code an ON EXCEPTION phrase, control is passed to the end of the XML PARSE statement. XML-CODE contains the original exception code set by the parser.

If no exception occurs during parsing, control is passed to the statement specified in the NOT ON EXCEPTION phrase. If you did not code a NOT ON EXCEPTION phrase, control is passed to the end of the XML PARSE statement. XML-CODE contains zero.

For XMLPARSE(COMPAT):

If the exception code is within a certain range, you might be able to handle the exception event within your processing procedure, and resume parsing.

To handle an exception in the processing procedure, follow these steps:

Procedure

  1. Check the contents of XML-CODE.
  2. Handle the exception appropriately.
  3. Set XML-CODE to zero to indicate that you handled the exception.
  4. Return control to the parser.

Results

The exception condition no longer exists.

You can handle exceptions in this way only if the exception code that is passed in XML-CODE is within one of the following ranges, which indicates that an encoding conflict was detected:

  • 50 - 99
  • 100,001 - 165,535

Exception codes 1 - 49: In the processing procedure, you can do limited handling of exceptions for which the exception code is within the range 1 - 49. After an exception in this range occurs, the parser does not signal any further normal events, except the END-OF-DOCUMENT event, even if you set XML-CODE to zero before returning. If you set XML-CODE to zero, the parser continues parsing the document and signals any exceptions that it finds. (Doing so can provide a useful way to discover multiple errors in the document.)

Restriction: The compatibility-mode COBOL XML parser might not signal all additional exception events. The number of exceptions is limited to the remaining space in the XML PARSE event token array, probably 8192 events.

At the end of parsing after an exception that has an exception code in the range 1 - 49, control is passed to the statement specified in the ON EXCEPTION phrase. If you did not code an ON EXCEPTION phrase, control is passed to the end of the XML PARSE statement. XML-CODE contains the code set by the parser for the most recent exception.

For all exceptions other than those having an exception code within one of the ranges described above, the parser does not signal any further events, but passes control to the statement specified in the ON EXCEPTION phrase. XML-CODE contains the original exception code even if you set XML-CODE in the processing procedure before returning control to the parser.

If you do not want to handle an exception, return control to the parser without changing the value of XML-CODE. The parser transfers control to the statement specified in the ON EXCEPTION phrase. If you did not code an ON EXCEPTION phrase, control is transferred to the end of the XML PARSE statement.

If no unhandled exceptions occur before the end of parsing, control is passed to the statement specified in the NOT ON EXCEPTION phrase. If you did not code a NOT ON EXCEPTION phrase, control is transferred to the end of the XML PARSE statement. XML-CODE contains zero.

Related concepts  
XML-CODE  
XML input document encoding  
How the XML parser handles errors  

Related tasks    
Writing procedures to process XML  
Parsing XML documents with validation  
Handling encoding conflicts  

Related references  
XMLPARSE (compiler option)  
The encoding of XML documents  
XML PARSE exceptions with XMLPARSE(XMLSS) in effect  
XML PARSE exceptions with XMLPARSE(COMPAT) in effect  
z/OS XML System Services User's Guide and Reference