SaxInit Procedure
Parses an XML document and registers the event handler function for execution.
Usage
SaxInit, event_handler, xml_buffer
Input Parameters
event_handler—This is a string with the name of the user defined event handler procedure.
xml_buffer—A file name or an input string variable is required for parsing an XML document. By default, this parameter is assumed to be a string and will be processed as an in memory XML document. See the File keyword, which is used to indicate that this string is a file path.
Keywords
Events—An integer array containing the events that are to be handled by PV‑WAVE. By default all events will be registered to execute the event handler function. By including the line:
@xmlevents
in your code you can use the named events as are described in the file:
<RW_DIR>/xml-1_0/lib/xmlevents.pro.File—If present, the second input argument is processed as a file.
Discussion
The entire XML document will be processed when SaxInit is called and the user provided event handler will be called multiple times as events of interest are encountered. Data returned to the handler functions will be an event type and a Wave variable containing the content or attribute values.
The following default events are defined in the file:
xml-1_0/lib/xmlevents.pro:
xml-1_0/lib/xmlevents.pro:
INTERNAL_SUBSET—Event to handle the internal subset of an XML document. ENTITY_DECL—Event to handle entities in an XML document.NOTATION_DECL—Event to handle XML notation. ATTRIBUTE_DECL—Event to handle attribute-list declaration within the XML document.ELEMENT_DECL—Event to handle element type declaration within the XML document.UNPARSE_ENTITY_DECL—Event to handle external entities that cannot be parsed.START_DOCUMENT—Event to handle when parsing of the document is started.END_ELEMENT—Event to handle when end of the element is encountered. END_DOCUMENT—Event to handle when parsing of the document is finished.START_ELEMENT—Event to handle when start of the element is encountered.CHARACTERS—Event to handle for character data outside of the XML tags. For example, the content of a node.PROCESSING_INSTRUCTION—Event to handle when any instructions to other computers are embedded in an XML document.COMMENT—Event to handle when comments are encountered in an XML document.WARNING—Event to handle any warnings while parsing an XML document.ERROR—Event to handle any errors while parsing an XML document.FATAL_ERROR—Event for fatal errors.CDATA_BLOCK—Event to handle when a section of an XML document is marked to be not scanned as markup.EXTERNAL_SUBSET—Event to handle for external subset. For example, a DTD is defined in an external file.The callback routine for SAX event handling should accept two parameters as in this example and described below:
PRO event_handler, event, data
Event—An integer describing the event type. The file <RW_DIR>/xml-1_0/lib/xmlevents.pro contains descriptions of all of the values that can be returned.
Data—A variable containing the data for the event. This can take a number of forms depending on the event type:
String | Content and element name |
|---|---|
CHARACTER, END_ELEMENT | |
String Array | Prolog Information |
INTERNAL_SUBSET, EXTERNAL_SUBSET | |
Associative Array | Node Attributes |
START_ELEMENT | |
Integer | 1 is returned for events with no real data to return |
Example
This example will parse an XML document and report when any of two types of events are encountered.
PRO event_handler, event, data
@xmlevents
CASE EVENT OF
START_ELEMENT: $
PRINT, 'Event=', STRTRIM(event,2), $
' (START_ELEMENT) Data=[', data, ']'
CHARACTERS: $
PRINT, 'Event=', STRTRIM(event,2), $
' (CHARACTERS) Data=[', data, ']'
ENDCASE
END
PRO SaxInit_ex1
xml_init
@xmlevents
buffer = GETENV('RW_DIR') + '/xml-1_0/data/chart.xml'SaxInit, 'event_handler', buffer, /File, $
Events=[START_ELEMENT, CHARACTERS]
END
