The parser sets an exception code in the XML-CODE special register when it encounters an anomaly or error during parsing. The specific exception codes and subsequent actions that you can take vary depending on the setting of the XMLPARSE compiler option.
For XMLPARSE(XMLSS)
The exception code that the parser returns in the XML-CODE special register is formed from the return code and reason code that the z/OS XML System Services parser generates. The return code and the reason code are each a halfword binary value. The value in XML-CODE is a concatenation of those two values. For 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 from the z/OS XML System Services parser for this document is 12 (hexadecimal 000C). The reason code is hexadecimal 3035 (XRSN_ENDTAG_NAME_MISMATCH). The concatenation of these two values, hexadecimal 000C3035, is returned to the processing procedure in special register XML-CODE.
The parser return codes and reason codes are documented as hexadecimal values in the appendices of the z/OS XML System Services Users Guide and Reference.
Your processing procedure cannot handle the exception event and cannot resume parsing. When the processing procedure returns to the parser from an EXCEPTION event, the parser signals no further events. The parser transfers control to the statement that you specify in the ON EXCEPTION phrase of the XML PARSE statement. If you do not code an ON EXCEPTION phrase, control is transferred to the end of the XML PARSE statement. XML-CODE contains the original exception code set by the parser.
For XMLPARSE(COMPAT)
If the exception code that the XML parser passes in XML-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 event in your processing procedure, do these steps:
You can handle exceptions this way only if the exception code that is passed in XML-CODE is within one of the following ranges, which indicate that an encoding conflict was detected:
You can do limited handling of exceptions for which the exception code passed in XML-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 be useful as a way of discovering multiple errors in the document.
At the end of parsing after an exception in this range, control is passed to the statement that you specify in the ON EXCEPTION phrase, if any; otherwise to the end of the XML PARSE statement. The special register XML-CODE contains the code for the most recent exception set by the parser.
For all other exceptions, the parser signals no further events, and passes control to the statement that you specify in the ON EXCEPTION phrase. In this case, XML-CODE contains the original exception number even if you reset 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 that you specify in the ON EXCEPTION phrase. If you do 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 that you specify in the NOT ON EXCEPTION phrase (normal end of parsing). If you do not code a NOT ON EXCEPTION phrase, control is passed to the end of the XML PARSE statement. The special register XML-CODE contains zero.
related concepts
How the XML parser handles errors
XML-CODE