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_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