The z/OS XML parser is built to handle documents that may be larger than any single buffer the caller can pass to the z/OS XML parser. When buffers need to be spanned (because either the text in the input buffer is consumed, or the parsed data stream fills the output buffer), the z/OS XML parser returns a conditional success return code (XRC_WARNING), and a reason code that indicates which buffer caused the spanning condition. The caller then should handle the spanning buffer, and can optionally manage the other buffer as well.
For example, if the z/OS XML parser indicates that the output buffer is full on a return to the caller after saving and refreshing the output buffer pointers, the caller may choose to refill the input buffer with more text to parse before calling the parse service again to continue the parse process. This will require either moving the unparsed text to the front of the current input buffer, or to a new input buffer, and filling in the remainder with more unparsed text. In this way, the caller potentially reduces the number of times the z/OS XML parser has to return to the caller because of a spanned buffer during the parse of a document.
The z/OS XML parser will advance the input and output pointers to the byte after the last byte that the parser processed in each buffer. Similarly, it will update the bytes_left parameters to indicate the number of unprocessed or unused bytes in each buffer. The caller must use the reason code returned from the z/OS XML parser to tell which buffer must be handled and which buffer may optionally be handled. The caller cannot rely on either the address values or the bytes_left values to tell which buffer has spanned.