New, changed, unchanged and discontinued events with XMLSS:
- You can migrate your programs to use XMLPARSE(XMLSS) once 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 Table 1.
XML-TEXT or XML-NTEXT contains the single
character that corresponds with the predefined entity reference in the
attribute value. The predefined entity references
are shown in table Table 1.
Character entity references are signaled as
ATTRIBUTE-NATIONAL-CHARACTER events.
- To migrate to 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 and 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 an entity reference.
- COMPAT: XML-TEXT and XML-NTEXT have only a substring of the value
for the ATTRIBUTE-CHARACTERS event when the value contains an entity reference.
- To migrate to 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 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)
- ATTRIBUTE-NATIONAL-CHARACTER event (discontinued)
- XMLSS: The ATTRIBUTE-NATIONAL-CHARACTER event no longer occurs.
All resolved 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.
The five predefined entity references are shown in
table Table 1.
- 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 XMLSS: Remove references to the ATTRIBUTE-NATIONAL-CHARACTER
event and integrate any actions for this event into your ATTRIBUTE-CHARACTERS
event handling.
- COMMENT event (changed)
- XMLSS: XML-TEXT and XML-NTEXT could have a substring of the
value for the COMMENT event.
- COMPAT: XML-TEXT and XML-NTEXT always have the complete string of the
value for the COMMENT event.
- To migrate to 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.
- 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, in which case an EXCEPTION or an UNRESOLVED-REFERENCE
event is signaled.
- COMPAT: The CONTENT-CHARACTER event occurs for predefined entity
references only. The five predefined entity references
are shown in table Table 1.
- To migrate to 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 and XML-NTEXT could have a substring of the value
for the CONTENT-CHARACTERS event. XML-TEXT or XML-NTEXT could also contain
a complete string of the value even if the value contains an entity reference.
- COMPAT: XML-TEXT and XML-NTEXT have only a substring of the value
for the CONTENT-CHARACTERS event when the value contains an entity reference.
- To migrate to 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 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 (discontinued)
- XMLSS: The CONTENT-NATIONAL-CHARACTER event no longer occurs.
All entity references, including character references, are now
included in the CONTENT-CHARACTERS event, unless there is an
unresolved entity, in which case an EXCEPTION or UNRESOLVED-REFERENCE
event is signaled.
- 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 XMLSS: Remove references to the CONTENT-NATIONAL-CHARACTER
event and integrate any actions for this event into your CONTENT-CHARACTERS
event handling.
- 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(DTD).
The parser scans the internal DTD for entity declarations and
default attribute values, processes them, and ignores the rest of
the text in the section.
- COMPAT: XML-TEXT or XML-NTEXT contains the entire declaration.
- To migrate to XMLSS: 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 complete encoding declaration
from the XML declaration. The encoding declaration is not used by the parser,
so you can get bad characters passed through that might cause the parser to signal
an EXCEPTION event from which you can't recover.
- COMPAT: XML-TEXT or XML-NTEXT contains the complete encoding declaration
from the XML declaration. If there are errors in encoding you would get
an EXCEPTION event from which you might be able to recover and continue.
- To migrate to 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
and XML-CODE are empty, with length zero.
- COMPAT: XML-TEXT or XML-NTEXT always contains the string "]]>".
- To migrate to 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 (for example, with VALUE "]]>" clause).
- END-OF-DOCUMENT event (no change)
- XMLSS and COMPAT have the same behavior for the END-OF-DOCUMENT event.
- To migrate to 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 it is 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 is 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 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 re-create the complete element name from
the 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 XMLSS: With XMLPARSE(COMPAT) your document
is in one segment, so no change is required to change to XMLPARSE(XMLSS).
- EXCEPTION event (changed)
- XMLSS: XML-CODE contains the unique error 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 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 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 both are empty with length zero.
- COMPAT: The NAMESPACE-DECLARATION event does not occur.
- To migrate to 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 and XML-NTEXT could have a substring of the value
for the PROCESSING-INSTRUCTION-DATA event.
- COMPAT: XML-TEXT and XML-NTEXT always have the complete string of the
value for the PROCESSING-INSTRUCTION-DATA event.
- To migrate to 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 and you would concatenate strings
together to re-create the complete string of the value.
- PROCESSING-INSTRUCTION-TARGET event (no change)
- XMLSS and COMPAT have the same behavior for the
PROCESSING-INSTRUCTION-TARGET event.
- To migrate to XMLSS: No change required.
- STANDALONE-DECLARATION event (no change)
- XMLSS and COMPAT have the same behavior for the
STANDALONE-DECLARATION event.
- To migrate to XMLSS: No change required.
- START-OF-CDATA-SECTION event (changed)
- XMLSS: All XML special registers except XML-EVENT
and XML-CODE are empty with length zero.
- COMPAT: XML-TEXT or XML-NTEXT always contains the string "![CDATA[".
- To migrate to 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 (for example, with a VALUE "![CDATA[" clause).
- START-OF-DOCUMENT event (changed)
- XMLSS: All XML special registers except XML-EVENT and XML-CODE
are empty with length zero.
- COMPAT: XML-TEXT or XML-NTEXT contains the entire document.
- To migrate to 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 is 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 is 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 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 re-create the complete element name from
the NAMESPACE special registers.
- UNKNOWN-REFERENCE-IN-ATTRIBUTE event (discontinued)
- UNKNOWN-REFERENCE-IN-CONTENT event (discontinued)
- XMLSS: Does not occur.
- COMPAT: XML-TEXT or XML-NTEXT contains the entity reference name,
not including the "&" and ";" delimiters.
- To migrate to XMLSS: Eliminate from your XML
documents any unresolved references in attribute values.
- 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 XMLSS: See UNKNOWN-REFERENCE-IN-CONTENT and
UNKNOWN-REFERENCE-IN-ATTRIBUTE.
- VERSION-INFORMATION event (no change)
- XMLSS and COMPAT have the same behavior for the
VERSION-INFORMATION event.
- To migrate to XMLSS: No change required.
More differences between COMPAT and XMLSS:
- 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 and look the return code and reason code up
in the XMLSS manual: z/OS XML System Services Users Guide and Reference
- COMPAT: XML-CODE values are described in decimal in the
COBOL Programming Guide.
- To migrate to XMLSS: If your program tests for specific XML-CODE values
for EXCEPTION events, you may have to change those values in your code.
Table 1. The predefined entity references| Predefined entity |
Character |
| < |
< |
| > |
> |
| & |
& |
| ' |
' |
| " |
" |