SAX-PARSE-NEXT( ) returns after the parser finds the next XML token in the XML source and the AVM invokes the corresponding callback, if it exists.
When SAX-PARSE-NEXT( ) starts, an error is raised if the PARSE-STATUS attribute is anything other than SAX-RUNNING. This might occur if:
SAX-PARSE-NEXT( ) is called before SAX-PARSE-FIRST( ) is called
STOP-PARSING( ) is called
Eventually, SAX-PARSE-NEXT( ) fails to find another XML token (assuming the parse does not stop early). When this happens, the AVM sets the PARSE-STATUS attribute to SAX-COMPLETE. If SAX-PARSE-NEXT( ) is called at that point, an error is raised.
Note: SAX-PARSE-NEXT( ) does not have a return value. To detect if an error has occurred, add NO-ERROR to the call and when it returns, check ERROR-STATUS:ERROR.
To stop a progressive-scan parse, you can refraining from calling SAX-PARSE-NEXT( ). However, when you detect that it is time to stop, you will most likely be in a callback, so you need a way to communicate that it is time to stop to the driver (where SAX-PARSE-NEXT( ) is called). A convenient way to do that is to call SELF:STOP-PARSING( ), since that causes the AVM to set the value of PARSE-STATUS to SAX-COMPLETE.
SAX-PARSE-NEXT( ) is called before SAX-PARSE-FIRST( ) is called