XMLParserCallbacks Class Improves Processing of Large XML Documents
Formerly, parsing large XML documents may have overflowed available memory. This version of OpenROAD includes a new user class, XMLParserCallbacks, which enables the parsing of very large XML documents by processing individual elements during parsing rather than after the entire document is finished parsing.
Element-level processing happens through callback mechanisms; OpenROAD calls a user-defined 4GL handler procedure when the start or end of an XML element occurs during parsing. This approach enables parsing large documents that do not fit into memory to be processed, preventing out-of-memory situations. During parsing, the called, user-defined 4GL procedure can process the parsed element and then remove the XMLElement from its parent (ParentElement).
You use the XMLDocument.ParserCallbacks attribute to reference the XMLParserCallbacks object that contains references to user-defined 4GL procedures that OpenROAD calls at specific points during parsing. You specify these points by setting at least one of the following handler attributes:
• EndDocumentHandler
• EndElementHandler
• StartDocumentHandler
• StartElementHandler
These attributes have a data type of ProcHandle, which may be set to a user-defined 4GL procedure. This procedure definition must have a named parameter called ParserCallbacks that has a data type of XMLParserCallbacks. OpenROAD then passes the correct value to this procedure while parsing the XML document. This allows the user-defined 4GL procedures to access attributes that contain the current XML document (CurDocument) and XML element (CurElement) during the parsing.
When the ParserCallbacks attribute of an XMLDocument is set to an XMLParserCallbacks object and that XMLParserCallbacks object contains references to one or more ProcHandles representing user-defined 4GL procedures, while executing the XMLDocument methods ParseURL or ParseString, OpenROAD calls these handlers at appropriate points during parsing of the XML document with a statement such as this:
ProcHandle.Call(ParserCallbacks = XMLParserCallbacks);
XMLParserCallbacks has no methods but has the following attributes:
CurDocument Attribute
Data Type: XMLDocument
4GL Access: R
The CurDocument attribute specifies the current XML document that OpenROAD is parsing.
CurElement Attribute
Data Type: XMLElement
4GL Access: R
The CurElement attribute specifies the current XML element that OpenROAD is parsing.
EndDocumentHandler Attribute
Data Type: ProcHandle
4GL Access: RW
The EndDocumentHandler attribute specifies the ProcHandle of the user-defined 4GL procedure to call after parsing of the XML document is finished.
EndElementHandler Attribute
Data Type: ProcHandle
4GL Access: RW
The EndElementHandler attribute specifies the ProcHandle of the user-defined 4GL procedure to call after parsing the end tag of an XML element.
Errortext Attribute
Data Type: varchar(2000)
4GL Access: RW
While parsing a XMLDocument, the Errortext attribute specifies the text to be set in XMLDocument's Errortext only if a called, user-defined handler procedure returns ER_FAIL and the ParseReturnValue has been set to ER_FAIL.
ParseReturnValue Attribute
Data Type: integer
4GL Access: RW
Specifies the return value of the invoked parsing method, XMLDocument.ParseString() or XMLDocument.ParseURL(), when parsing has been aborted.
If any called 4GL handler procedure aborts parsing by returning ER_FAIL, the ParseReturnValue setting is returned back to the caller of the XMLDocument parsing method.
If the called procedure indicates success by returning ER_OK, ParseReturnValue is not used.
StartDocumentHandler
Data Type: ProcHandle
4GL Access: RW
The StartDocumentHandler attribute specifies the ProcHandle of the user-defined 4GL procedure to call after starting to parse the XML document.
StartElementHandler
Data Type: ProcHandle
4GL Access: RW
The StartElementHandler attribute specifies the ProcHandle of the user-defined 4GL procedure to call after parsing the start tag of an XML element.
For more information, see the Language Reference Guide.