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:
*INTERNAL_SUBSETEvent to handle the internal subset of an XML document.
*ENTITY_DECLEvent to handle entities in an XML document.
*NOTATION_DECLEvent to handle XML notation.
*ATTRIBUTE_DECLEvent to handle attribute-list declaration within the XML document.
*ELEMENT_DECLEvent to handle element type declaration within the XML document.
*UNPARSE_ENTITY_DECLEvent to handle external entities that cannot be parsed.
*START_DOCUMENTEvent to handle when parsing of the document is started.
*END_ELEMENTEvent to handle when end of the element is encountered.
*END_DOCUMENTEvent to handle when parsing of the document is finished.
*START_ELEMENTEvent to handle when start of the element is encountered.
*CHARACTERSEvent to handle for character data outside of the XML tags. For example, the content of a node.
*PROCESSING_INSTRUCTIONEvent to handle when any instructions to other computers are embedded in an XML document.
*COMMENTEvent to handle when comments are encountered in an XML document.
*WARNINGEvent to handle any warnings while parsing an XML document.
*ERROREvent to handle any errors while parsing an XML document.
*FATAL_ERROREvent for fatal errors.
*CDATA_BLOCKEvent to handle when a section of an XML document is marked to be not scanned as markup.
*EXTERNAL_SUBSETEvent 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