You can parse XML documents by passing the parser a segment of XML text at a time. Two major applications of this technique are:
To use this feature, you must compile your program with the XMLPARSE(XMLSS) compiler option in effect.
You parse an XML document a segment at a time by initializing the parse data item to the first segment of the XML document, and then executing the XML PARSE statement. The parser processes the XML text and returns XML events to your processing procedure as usual. At the end of the text segment, the parser signals an END-OF-INPUT XML event with XML-CODE set to zero. If there is another segment of the document to process, in your processing procedure move the next segment of XML data to the parse data item, set XML-CODE to one, and return to the parser. To signal the end of XML segments to the parser, return to the parser with XML-CODE still set to zero.
The length of the parse data item is evaluated for each segment, and determines the segment length.
Recommendation: If the XML document segments are variable length, specify a variable-length item for the parse data item. For example, for variable length XML segments, the parse data item can be:
When you send an XML document to the parser in multiple segments, document content is, in some cases, returned to the processing procedure in multiple fragments via multiple events, rather than as one large fragment in a single event.
For example, when the document is split into two segments with the split point in the middle of a string of content characters, the parser returns the content in two separate CONTENT-CHARACTERS events. Your processing procedure must reassemble the string of content as needed by the application. Start element tags, attribute names, namespace declarations, and end element tags are always delivered to the processing procedure with a single event, even if they are split between two segments of a document.
If a segment split occurs between the bytes of a multibyte character, the parser detects the split and reassembles the character for delivery in a single event.
XML documents stored in a QSAM or VSAM file can be processed as follows:
Usage note: The root element of an XML document might be followed by miscellaneous information: zero or more occurrences of a comment or processing instruction, in any order. However, when parsing the document one segment at a time, the parser signals an END-OF-INPUT XML event after processing the end tag of the root element only if the last item in the segment is incomplete. If the segment ends with a complete XML item (such as the root element end tag, or following that, a complete comment or processing instruction), the next XML event after the event for the item itself is the END-OF-DOCUMENT XML event.
Recommendation: To provide successive segments of XML data after the end of the root element, include at least the first nonspace character of an XML item at the end of each segment. Include a complete item only on the last segment that you want the parser to process. For instance, in the following sample, where each line represents a segment of an XML document, the segment that includes the text This comment ends this segment is the last segment to be parsed:
<Tagline> COBOL is the language of the future! </Tagline> < !--First comment-- > <?pi data?> <!- -This comment ends this segment--> <!-- This segment is not included in the parse-->