Migrating from XMLPARSE(COMPAT) to XMLPARSE(XMLSS)
You can migrate your programs to use XMLPARSE(XMLSS) after you understand the differences between XMLPARSE settings: XMLSS and COMPAT. Some of these differences are described in terms of new, changed, unchanged, and discontinued events when XMLPARSE(XMLSS) is in effect.
- ATTRIBUTE-CHARACTER event (discontinued)
- XMLSS: The ATTRIBUTE-CHARACTER event no longer occurs. All entity references, including predefined ones, are now included in the ATTRIBUTE-CHARACTERS event, unless there is an unresolved entity reference, in which case an EXCEPTION event is signaled.
- COMPAT: The ATTRIBUTE-CHARACTER event occurs for predefined entity references only. The five predefined entity references are shown in Table 1. XML-TEXT or XML-NTEXT contains the single character that corresponds with the predefined entity reference in the attribute value. Character references are signaled as ATTRIBUTE-NATIONAL-CHARACTER events.
- To migrate to XMLPARSE(XMLSS): Remove references to the ATTRIBUTE-CHARACTER event and integrate any actions for this event into your ATTRIBUTE-CHARACTERS event handling.
- ATTRIBUTE-CHARACTERS event (changed)
- XMLSS: XML-TEXT or XML-NTEXT could have a substring of the value for the ATTRIBUTE-CHARACTERS event. XML-TEXT or XML-NTEXT could also contain a complete string of the value even if the value contains a character reference or an entity reference.
- COMPAT: XML-TEXT or XML-NTEXT has only a substring of the value for the ATTRIBUTE-CHARACTERS event when the value contains a character reference or an entity reference.
- To migrate to XMLPARSE(XMLSS): You might have to modify your code that handles the ATTRIBUTE-CHARACTERS event to handle more than one event even if your attribute values do not contain character or entity references. You might also have to change your code to process ATTRIBUTE-CHARACTERS as a single event where your code was handling ATTRIBUTE-CHARACTERS as multiple events.
- ATTRIBUTE-NAME event (changed)
- XMLSS: For attribute names that are not in a namespace,
XML-TEXT or XML-NTEXT contains the attribute name, and the namespace
special registers are all empty and have length zero. Attributes
with names in a namespace are always prefixed and have the form:
XML-TEXT or XML-NTEXT contains the local-part, XML-NAMESPACE or XML-NNAMESPACE contains the namespace and XML-NAMESPACE-PREFIX or XML-NNAMESPACE-PREFIX contains the prefix.prefix:local-part = AttValue
- COMPAT: For all attribute names, XML-TEXT or XML-NTEXT contains the complete attribute name, even if the name is prefixed (indicating that the name belongs to a namespace).
- To migrate to XMLPARSE(XMLSS): Either change your code to process the separate parts of the namespace, or change your code to reconstruct the complete attribute name from the separate parts in XML-TEXT, XML-NAMESPACE-PREFIX, and XML-NAMESPACE, or XML-NTEXT, XML-NNAMESPACE-PREFIX, and XML-NNAMESPACE.
- XMLSS: For attribute names that are not in a namespace,
XML-TEXT or XML-NTEXT contains the attribute name, and the namespace
special registers are all empty and have length zero. Attributes
with names in a namespace are always prefixed and have the form:
- ATTRIBUTE-NATIONAL-CHARACTER event (changed)
- XMLSS: Character references that can be represented
in the EBCDIC encoding of the XML document are resolved and included
in the ATTRIBUTE-CHARACTERS event.
Unrepresentable character references are expressed as ATTRIBUTE-NATIONAL-CHARACTER events, as for COMPAT.
- COMPAT: Regardless of the type of the XML document specified by identifier-1 in the XML PARSE statement, XML-TEXT is empty and XML-NTEXT contains the single national character corresponding with the (numeric) character reference.
- To migrate to XMLPARSE(XMLSS): Possibly no change will be required, but be aware that with COMPAT, the national character might have an EBCDIC equivalent, whereas with XMLSS, the national character is known to have no representation in the EBCDIC encoding of the document.
- XMLSS: Character references that can be represented
in the EBCDIC encoding of the XML document are resolved and included
in the ATTRIBUTE-CHARACTERS event.
- COMMENT event (changed)
- XMLSS: XML-TEXT or XML-NTEXT could have a substring of the value for the COMMENT event.
- COMPAT: XML-TEXT or XML-NTEXT always has the complete string of the value for the COMMENT event.
- To migrate to XMLPARSE(XMLSS): You might have to modify your code that handles the COMMENT event to handle more than one event if you get a substring of the COMMENT value in XML-TEXT or XML-NTEXT. If that is the case, you get two or more COMMENT events in succession and you would concatenate strings together to re-create the complete string of the value. You cannot distinguish a comment that is split in this way from a sequence of distinct comments.
- CONTENT-CHARACTER event (discontinued)
- XMLSS: The CONTENT-CHARACTER event no longer occurs. All entity references, including predefined ones, are now included in the CONTENT-CHARACTERS event unless there is an unresolved entity reference, in which case an UNRESOLVED-REFERENCE event or an EXCEPTION event is signaled.
- COMPAT: The CONTENT-CHARACTER event occurs for predefined entity references only. The five predefined entity references are shown in Table 1. XML-TEXT or XML-NTEXT contains the single character that corresponds with the predefined entity reference in the attribute value. Character references are signaled as CONTENT-NATIONAL-CHARACTER events.
- To migrate to XMLPARSE(XMLSS): Remove references to the CONTENT-CHARACTER event and integrate any actions for this event into your CONTENT-CHARACTERS event handling.
- CONTENT-CHARACTERS event (changed)
- XMLSS: XML-TEXT or XML-NTEXT could have a substring of the content for the CONTENT-CHARACTERS event. XML-TEXT or XML-NTEXT could also contain a complete string of the content even if the content contains a character reference or an entity reference.
- COMPAT: XML-TEXT or XML-NTEXT has only a substring of the content for the CONTENT-CHARACTERS event when the content contains a character reference or an entity reference.
- To migrate to XMLPARSE(XMLSS): You might have to modify your code that handles the CONTENT-CHARACTERS event to handle more than one event even if your attribute values do not contain character or entity references. You might also have to change your code to process CONTENT-CHARACTERS as a single event where your code was handling CONTENT-CHARACTERS as multiple events.
- CONTENT-NATIONAL-CHARACTER event (changed)
- XMLSS: Character references that can be represented
in the EBCDIC encoding of the XML document are resolved and included
in the CONTENT-CHARACTERS event.
Unrepresentable character references are expressed as CONTENT-NATIONAL-CHARACTER events, as for COMPAT.
- COMPAT: Regardless of the type of the XML document specified by identifier-1 in the XML PARSE statement, XML-TEXT is empty, and XML-NTEXT contains the single national character corresponding with the (numeric) character reference.
- To migrate to XMLPARSE(XMLSS): Possibly no change will be required, but be aware that with COMPAT, the national character might have an EBCDIC equivalent, whereas with XMLSS, the national character is known to have no representation in the EBCDIC encoding of the document.
Note:The XML System Services parser transforms the following characters or character combinations to x'15' when parsing EBCDIC documents:
x'0D' CR x'15' NL x'25' LF x'0D15' (these two bytes together) x'0D25' (these two bytes together) Some of these characters might be produced when an in-memory image of an ASCII document is translated to EBCDIC. The COMPAT parser does none of these transforms. An application which depends on them not being done will need appropriate changes when using XMLPARSE(XMLSS).
- XMLSS: Character references that can be represented
in the EBCDIC encoding of the XML document are resolved and included
in the CONTENT-CHARACTERS event.
- DOCUMENT-TYPE-DECLARATION event (changed)
- XMLSS: XML-TEXT or XML-NTEXT contains the name of the root element, as specified in the document type declaration. The parser processes entity declarations and default attribute values in the internal DTD subset, and ignores the rest of the text in the document type declaration.
- COMPAT: XML-TEXT or XML-NTEXT contains the entire document type declaration.
- To migrate to XMLPARSE(XMLSS): If having the whole document type declaration is important, you might have to modify your code that handles the DOCUMENT-TYPE-DECLARATION event to acquire the information directly from your XML document.
- ENCODING-DECLARATION event (changed)
- XMLSS: XML-TEXT or XML-NTEXT contains the encoding name. The encoding declaration is not used by the parser, so you might get incorrect characters passed through that would cause the parser to signal an EXCEPTION event from which you can't recover.
- COMPAT: XML-TEXT or XML-NTEXT contains the encoding name. If there are errors in the encoding of the document, you would get an EXCEPTION event from which you might be able to recover and continue.
- To migrate to XMLPARSE(XMLSS): Check your document before parsing or specify your encoding using the CODEPAGE compiler option or by using the WITH ENCODING phrase on the XML PARSE statement.
- END-OF-CDATA-SECTION event (changed)
- XMLSS: All XML special registers except XML-EVENT, XML-CODE and XML-INFORMATION are empty with length zero.
- COMPAT: XML-TEXT or XML-NTEXT always contains the string "]]>".
- To migrate to XMLPARSE(XMLSS): If the string "]]>" is acquired from the END-OF-CDATA-SECTION event, change your code to manually return it using a literal, or data item initialized with the value "]]>".
- END-OF-DOCUMENT event (no change)
- The 2 parsers have the same behavior for the END-OF-DOCUMENT event.
- To migrate to XMLPARSE(XMLSS): No change required.
- END-OF-ELEMENT event (changed)
- XMLSS: XML-TEXT or XML-NTEXT contains the local part of the end element tag or empty element tag name. If the element name is in a namespace, XML-NAMESPACE or XML-NNAMESPACE contains the namespace, otherwise these special registers are empty with length zero. If the element name is in a namespace and is prefixed (of the form "prefix:local-part"), XML-NAMESPACE-PREFIX or XML-NNAMESPACE-PREFIX contains the prefix, otherwise these special registers are empty with length zero.
- COMPAT: XML-TEXT or XML-NTEXT contains the complete element tag name, including any prefix. If the element name is not in a namespace, there is no difference between COMPAT and XMLSS for END-OF-ELEMENT.
- To migrate to XMLPARSE(XMLSS): If the element name is not in a namespace, then no change is required. If the element name is in a namespace, change your code to not use the complete element name, or reconstruct the complete element name from the separate parts in the XML text and namespace special registers.
- END-OF-INPUT event (new)
- XMLSS: The END-OF-INPUT event indicates the end of a segment of an XML document.
- COMPAT: The END-OF-INPUT event does not occur.
- To migrate to XMLPARSE(XMLSS): With COMPAT, your document is in one segment, so no change is required to change to XMLSS.
- EXCEPTION event (changed)
- XMLSS: XML-CODE contains the unique return code and reason code identifying the exception. See the following section "Other differences" for a description of XML-CODE differences. XML-TEXT or XML-NTEXT contains the document fragment up to the point of the error or anomaly that caused the EXCEPTION event. All other XML special registers except XML-EVENT and XML-INFORMATION are empty with length zero. It is not possible to continue from any EXCEPTION event.
- COMPAT: XML-TEXT or XML-NTEXT contains the entire document that has been parsed up to the point of the EXCEPTION event. It is possible to continue from some EXCEPTION events.
- To migrate to XMLPARSE(XMLSS): You might have to change your code or documents if they depend on being able to recover from EXCEPTION events.
- NAMESPACE-DECLARATION event (new)
- XMLSS: XML-TEXT and XML-NTEXT are both empty with length zero. XML-NAMESPACE or XML-NNAMESPACE contains the declared namespace. If the namespace is "undeclared" by specifying the empty string, XML-NAMESPACE and XML-NNAMESPACE are empty with length zero. XML-NAMESPACE-PREFIX or XML-NNAMESPACE-PREFIX contains the prefix if the attribute name for the namespace declaration is of the form "xmlns:prefix", otherwise, if the declaration is for the default namespace and the attribute name is "xmlns", XML-NAMESPACE-PREFIX and XML-NNAMESPACE-PREFIX are both empty with length zero.
- COMPAT: The NAMESPACE-DECLARATION event does not occur.
- To migrate to XMLPARSE(XMLSS): If you get the NAMESPACE-DECLARATION event after migrating to XMLSS, see the descriptions in this table of ATTRIBUTE-NAME, END-OF-ELEMENT and START-OF-ELEMENT event changes.
- PROCESSING-INSTRUCTION-DATA event (changed)
- XMLSS: XML-TEXT or XML-NTEXT could have a substring of the value for the PROCESSING-INSTRUCTION-DATA event.
- COMPAT: XML-TEXT or XML-NTEXT always has the complete string of the value for the PROCESSING-INSTRUCTION-DATA event.
- To migrate to XMLPARSE(XMLSS): You might have to modify your code that handles the PROCESSING-INSTRUCTION-DATA event to handle more than one event if you get a substring of the PROCESSING-INSTRUCTION-DATA value in XML-TEXT or XML-NTEXT. If that is the case, you get two or more PROCESSING-INSTRUCTION-DATA events, each one preceded by its matching PROCESSING-INSTRUCTION-TARGET event. You would then concatenate the PROCESSING-INSTRUCTION-DATA substrings together to reconstitute the complete data string.
- PROCESSING-INSTRUCTION-TARGET event (changed)
- XMLSS: If the processing instruction data is split into substrings, the PROCESSING-INSTRUCTION-TARGET event is repeated before each instance of the PROCESSING-INSTRUCTION-DATA event for a given processing instruction.
- COMPAT: The PROCESSING-INSTRUCTION-TARGET event occurs only once for a given processing instruction.
- To migrate to XMLPARSE(XMLSS): You might have to modify your code to accommodate multiple occurrences of the PROCESSING-INSTRUCTION-TARGET event while accumulating processing instruction data.
- STANDALONE-DECLARATION event (no change)
- XMLSS and COMPAT have the same behavior for the STANDALONE-DECLARATION event.
- To migrate to XMLPARSE(XMLSS): No change required.
- START-OF-CDATA-SECTION event (changed)
- XMLSS: All XML special registers except XML-EVENT, XML-CODE and XML-INFORMATION are empty with length zero.
- COMPAT: XML-TEXT or XML-NTEXT always contains the string "![CDATA[".
- To migrate to XMLPARSE(XMLSS): If the string "![CDATA[" is acquired from the START-OF-CDATA-SECTION event, change your code to manually return it using a literal, or data item initialized with the value "![CDATA[".
- START-OF-DOCUMENT event (changed)
- XMLSS: All XML special registers except XML-EVENT, XML-CODE and XML-INFORMATION are empty with length zero.
- COMPAT: XML-TEXT or XML-NTEXT contains the entire document.
- To migrate to XMLPARSE(XMLSS): Change your code to not require the entire document for START-OF-DOCUMENT.
- START-OF-ELEMENT event (changed)
- XMLSS: XML-TEXT or XML-NTEXT contains the local part of the start element name or empty element name. If the element name is in a namespace, XML-NAMESPACE or XML-NNAMESPACE contains the namespace, otherwise these special registers are empty with length zero. If the element name is in a namespace and is prefixed (of the form "prefix:local-part"), XML-NAMESPACE-PREFIX or XML-NNAMESPACE-PREFIX contains the prefix, otherwise these special registers are empty with length zero.
- COMPAT: XML-TEXT or XML-NTEXT contains the complete start element name, including any prefix. If the element name is not in a namespace, there is no difference between COMPAT and XMLSS for START-OF-ELEMENT.
- To migrate to XMLPARSE(XMLSS): If the element name is not in a namespace, then no change is required. If the element name is in a namespace, change your code to not use the complete element name, or reconstruct the complete element name from the separate parts in the XML text and namespace special registers.
- UNKNOWN-REFERENCE-IN-ATTRIBUTE event (discontinued)
- XMLSS: Does not occur. The parser always signals an EXCEPTION event if, while processing an attribute value, it encounters a reference to an entity that has not been defined.
- COMPAT: XML-TEXT or XML-NTEXT contains the entity reference name, not including the "&" and ";" delimiters.
- To migrate to XMLPARSE(XMLSS): Ensure that your XML documents do not contain any undefined entity references in attribute values.
- UNKNOWN-REFERENCE-IN-CONTENT event (discontinued)
- XMLSS: Does not occur. Instead, an UNRESOLVED-REFERENCE or EXCEPTION event occurs.
- COMPAT: XML-TEXT or XML-NTEXT contains the entity reference name, not including the "&" and ";" delimiters.
- To migrate to XMLPARSE(XMLSS): Change your code
that processes UNKNOWN-REFERENCE-IN-CONTENT to process UNRESOLVED-REFERENCE
instead. The UNRESOLVED-REFERENCE event is signaled only if all of the following conditions are true:
- The unresolved reference is within element content, not an attribute value.
- The XML document starts with an XML declaration that specifies standalone="no".
- The XML document contains a document type declaration, for example:
<!DOCTYPE rootElementName>
- If the VALIDATING phrase is specified on the XML PARSE statement,
the document type declaration must also specify an external DTD subset,
for example:
<!DOCTYPE rootElementName SYSTEM "extSub.dtd">
- UNRESOLVED-REFERENCE event (new)
- XMLSS: XML-TEXT or XML-NTEXT contains the entity reference name, not including the "&" and ";" delimiters.
- COMPAT: The event does not occur. Instead an UNKNOWN-REFERENCE-IN-CONTENT event would occur.
- To migrate to XMLPARSE(XMLSS): See UNKNOWN-REFERENCE-IN-CONTENT.
- VERSION-INFORMATION event (no change)
- both parsers have the same behavior for the VERSION-INFORMATION event.
- To migrate to XMLPARSE(XMLSS): No change required.
More differences between XMLPARSE(XMLSS) and XMLPARSE(COMPAT):
- XML-CODE
- XMLSS: When XML-CODE is set by the parser for an EXCEPTION event, the first halfword is the return code and the last halfword is the reason code. Convert the value to hexadecimal. You can find common return code and reason code in the z/OS® XML System Services User's Guide and Reference. You can also find COBOL specific return code and reason code in the Enterprise COBOL for z/OS Programming Guide
- COMPAT: XML-CODE values are described in decimal in the Enterprise COBOL for z/OS Programming Guide, Version 4 Release 2.
- To migrate to XMLPARSE(XMLSS): If your program tests for specific XML-CODE values for EXCEPTION events, you might have to change those values in your source program.
- Condition handling, RESUME, and XML PARSE statements
- XMLSS: If a condition handling routine, registered by CEEHDLR
or runtime option USERHDLR, gets control while executing a processing
procedure due to an exception in the processing procedure and the
resume cursor is moved by CEEMRCE to a point in the program before
an XML PARSE statement, and RESUME is requested from the condition
manager, the second XML PARSE would result in the following severity
3 runtime error message:
IGZ0228S There was an invalid attempt to start an XML PARSE statement.
- COMPAT: If a condition handling routine (registered by CEEHDLR or runtime option USERHDLR) gets control while executing a processing procedure due to an exception in the processing procedure, and the resume cursor is moved by CEEMRCE to a point in the program before an XML PARSE statement, and RESUME is requested from the condition manage, the second XML PARSE would start sucessfully.
- To migrate to XMLPARSE(XMLSS): Move the call to CEE3SRP
to be within the processing procedure. Then at the resumption point,
if the condition handling routine is unable to recover from the exception,
terminate parsing by moving -1 to XML-CODE. If the condition handling
routine is able to make an effective recovery, you might be able to
continue parsing by leaving XML-CODE unchanged.
Alternatively, you can use CEEMRCR instead of CEEMRCE so that when execution is resumed, it is in the program that called the program that had the XML PARSE statement that got the exception in the processing procedure.
Either of these methods properly addresses the exception.
- XMLSS: If a condition handling routine, registered by CEEHDLR
or runtime option USERHDLR, gets control while executing a processing
procedure due to an exception in the processing procedure and the
resume cursor is moved by CEEMRCE to a point in the program before
an XML PARSE statement, and RESUME is requested from the condition
manager, the second XML PARSE would result in the following severity
3 runtime error message:
The following table shows the predefined entity references.
Predefined entity | Character |
---|---|
< | < |
> | > |
& | & |
' | ' |
" | " |