JumpStart for Creating a SAX2 Application with Visual Basic

Microsoft Corporation

Updated November 2000

Download Vbsax2jumpstart.exe.

Don't have Acrobat? Download it from the Adobe Web site.

Summary: This article helps you get started building Simple API for XML (SAX2) applications with Microsoft Visual Basic. This document shows you how to quickly build an application that uses SAX2 to read an XML document and print the document's contents to a text box. (10 printed pages)

Note To run this tutorial, you need the latest production version of the Microsoft XML Parser (MSXML), available from MSDN's XML/XSL Home Page.

Contents

Overview of the JumpStart Application (Visual Basic)
Implementing the ContentHandler
Implementing the ErrorHandler
Creating the Main Form

Overview of the JumpStart Application (Visual Basic)

SAX2 is a push-model parser. When SAX2 parses a document, SAXXMLReader (the SAX2 reader) reads the document and passes a series of events to the implemented event handlers. The SAX2 reader generates several categories of events, including:

• Those that occur in the content of an XML document.
• Those that occur in the document type definition (DTD).
• Those that occur as errors.

To handle such events, you implement a corresponding handler class that contains methods to process the appropriate events. You only have to implement handlers for those events you wish to process. If you do not implement a handler for a specific type of event, the reader simply ignores that event.

The JumpStart application covered in this section contains the three components that you most often implement for SAX2 applications in Microsoft® Visual Basic®.

Implementing the ContentHandler

For the JumpStart application, you create the ContentHandler by adding a class that implements the IVBSAXContentHandler interface. Although creating a class may sound complex, Visual Basic automates most of the process.

Opening a New Project

Before you can create a class based on the IVBSAXContentHandler interface, you must create a new project and then reference that project to MSXML.

Creating a new project

Open Visual Basic 6.0 and, in the New Project dialog box, double-click Standard EXE.

Referencing MSXML

You must now instruct your application to use the MSXML2 type library provided with MSXML 3.0.

Creating a reference to MSXML 3.0

On the Project menu, click References. In the Available References list, select Microsoft XML, v3.0, and then click OK.

Creating and Implementing the Handler Class

You are now ready to create and implement the new ContentHandler class.

Creating a new class

1. On the Project menu, click Add Class Module.
2. In the Add Class Module dialog box, double-click Class Module.
3. On the View menu, select Properties Window.
4. In the Properties window, enter ContentHandlerImpl for the Name property.

Implementing the ContentHandlerImpl Class

1. In the Class Window, type Implements, and then press the space bar.
2. A drop-down list appears with the all the available classes. (This list includes interfaces that are actually abstract classes.) In the drop-down list, double-click IVBSAXContentHandler. This is the interface you implement to create the ContentHandlerImpl class.
3. In the Object drop-down list on the left side of the Class Window, click IVBSAXContentHandler. This automatically adds code to the Class Window.
4. In the Procedure drop-down list on the right-hand side of the Class Window, select the IVBSAXContentHandler method or property that you want to add to this class.

For example, select startElement to add this method to the ContentHandlerImpl class. (When parsing an XML document, the reader will invoke this method each time it encounters a new element in the document.) After you select startElement from the list, the following code appears in the Class Window:

Private Sub IVBSAXContentHandler_startElement(strNamespaceURI As _
String, strLocalName As String, strQName As String, ByVal oAttributes _
As MSXML2.IVBSAXAttributes)
End Sub

1. To enable the method or event selected in step 4 to handle the corresponding event, you must add the appropriate code to that method or property.

   For the startElement method added in step 4, enter the necessary code to make it look like the following:

   Copy

   Private Sub IVBSAXContentHandler_startElement(strNamespaceURI As _
   String, strLocalName As String, strQName As String, ByVal attributes _
   As MSXML2.IVBSAXAttributes)
   
       Dim i As Integer
   
       Form1.TextBox1.text = Form1.TextBox1.text & "<" & strLocalName
   
       For i = 0 To (attributes.length - 1)
           Form1.TextBox1.text = Form1.TextBox1.text & " " & _
           attributes.getLocalName(i) & "=""" & attributes.getValue(i) _
           & """"
       Next
   
       Form1.TextBox1.text = Form1.TextBox1.text & ">"
   
       If strLocalName = "qu" Then
           Err.Raise vbObjectError + 1, "ContentHandler.startElement", _
             "Found element <qu>"
       End If
   
   End Sub
   
   

2. To handle additional events passed by the reader, repeat steps 4 and 5 for each method or property that you want to add to the ContentHandlerImpl class.

Complete Code for the ContentHandlerImpl Class

The preceding instructions explain how to create a new project with a reference to Microsoft XML v3.0, and how to create a ContentHandler class called ContentHandlerImpl by implementing the IVBSAXContentHandler interface. The following shows the complete code for the ContentHandlerImpl class:

Option Explicit

Implements IVBSAXContentHandler

Private Sub IVBSAXContentHandler_startElement(strNamespaceURI As _
  String,_strLocalName As String, strQName As String, ByVal attributes As _
  MSXML2.IVBSAXAttributes)

    Dim i As Integer

    Form1.TextBox1.text = Form1.TextBox1.text & "<" & strLocalName

    For i = 0 To (attributes.length - 1)
        Form1.TextBox1.text = Form1.TextBox1.text & " " & _
        attributes.getLocalName(i) & "=""" & attributes.getValue(i) _
        & """"
    Next

    Form1.TextBox1.text = Form1.TextBox1.text & ">"

    If strLocalName = "qu" Then
        Err.Raise vbObjectError + 1, "ContentHandler.startElement", _
          "Found element <qu>"
    End If

End Sub

Private Sub IVBSAXContentHandler_endElement(strNamespaceURI As String, _
  strLocalName As String, strQName As String)

    Form1.TextBox1.text = Form1.TextBox1.text & "</" & strLocalName & ">"

End Sub

Private Sub IVBSAXContentHandler_characters(text As String)
    text = Replace(text, vbLf, vbCrLf)
    Form1.TextBox1.text = Form1.TextBox1.text & text

End Sub

Private Property Set IVBSAXContentHandler_documentLocator(ByVal RHS As _
  MSXML2.IVBSAXLocator)

End Property

Private Sub IVBSAXContentHandler_endDocument()

End Sub

Private Sub IVBSAXContentHandler_endPrefixMapping(strPrefix As String)

End Sub

Private Sub IVBSAXContentHandler_ignorableWhitespace(strChars As String)

End Sub

Private Sub IVBSAXContentHandler_processingInstruction(target As String, _
  data As String)

    Form1.TextBox1.text = Form1.TextBox1.text & "<?" & target & " " _
      & data & ">"

End Sub

Private Sub IVBSAXContentHandler_skippedEntity(strName As String)

End Sub

Private Sub IVBSAXContentHandler_startDocument()

End Sub

Private Sub IVBSAXContentHandler_startPrefixMapping(strPrefix As String, _
  strURI As String)

End Sub

As you can see from the sample code, not all methods or properties have custom code added to them. When you implement a handler for SAX2, you can choose to add only the methods or properties that you need.

Implementing the ErrorHandler

Using the material above as a foundation, you will now create the ErrorHandler for the JumpStart application. The ErrorHandler is created by implementing the IVBSAXErrorHandler interface, as described in the following procedures.

Creating the ErrorHandlerImpl class

1. On the Project menu, click Add Class Module.
2. In the Add Class Module dialog box, double-click Class Module.
3. On the View menu, select Properties Window.
4. In the Properties window, enter ErrorHandlerImpl for the Name property.

Implementing the ErrorHandlerImpl class

1. In the Class Window, type Implements, press the spacebar, and then double-click IVBSAXErrorHandler from the drop-down list that appears.
2. In the Object drop-down list on the left side of the Class Window, select IVBSAXErrorHandler.
3. In the Procedure drop-down list on the right side of the Class Window, select a method or property to add to the class.
4. Add the desired code to the selected method or property.
5. Repeat steps 3 and 4 until you have added the desired methods and properties.

Note If you have trouble implementing methods and procedures for the ErrorHandlerImpl class, refer back to Implementing the ContentHandler to see how methods and properties were implemented for the ContentHandlerImpl class.

Complete Code for the ErrorHandlerImpl Class

Here's the complete code for the ErrorHandlerImpl class of the JumpStart application:

Option Explicit

Implements IVBSAXErrorHandler

Private Sub IVBSAXErrorHandler_fatalError(ByVal lctr As IVBSAXLocator, _
  msg As String, ByVal errCode As Long)

    Form1.TextBox1.text = Form1.TextBox1.text & "*** error *** " & msg

End Sub

Private Sub IVBSAXErrorHandler_error(ByVal lctr As IVBSAXLocator, _
  msg As String, ByVal errCode As Long)

End Sub

Private Sub IVBSAXErrorHandler_ignorableWarning(ByVal oLocator As _
  MSXML2.IVBSAXLocator, strErrorMessage As String, ByVal nErrorCode _
  As Long)

End Sub

Private Sub IVBSAXErrorHandler_ignorableWarning(ByVal oLocator As _
  MSXML2.IVBSAXLocator, strErrorMessage As String, _
  ByVal nErrorCode As Long)

End Sub

In the preceding code, only the fatalError method contains code for handling events. For this version of MSXML, only the fatalError method is called for IVBSAXErrorHandler.

Creating the Main Form

The main form provides the user interface for the JumpStart application. The user interface consists of four elements.

Besides providing the interface elements, the main form also provides code that creates the necessary instances of the various classes and starts the parse process.

Dim reader As SAXXMLReader
Set reader = New SAXXMLReader

Dim contentHandler As ContentHandlerImpl
Set reader.contentHandler = contentHandler

Dim errorHandler As New ErrorHandlerImpl
Set reader.contentHandler = contentHandler

reader.parseURL (Text1.text) 

Complete Code for the Main Form

Here's the complete code for the main form of the JumpStart application:

Option Explicit

Private Sub Command1_Click()

    Dim reader As New SAXXMLReader    'Reads the XML document
    Dim contentHandler As New ContentHandlerImpl 'Receives parsing events
    Dim errorHandler As New ErrorHandlerImpl        'Receive error events
    TextBox1.text = ""
    Set reader.contentHandler = contentHandler    'They work together
    Set reader.errorHandler = errorHandler        'They also work together
    On Error GoTo 10
    reader.parseURL (Text1.text)               'Parse the document

    Exit Sub                                   'That's all, folks!

10: TextBox1.text = TextBox1.text & "*** Error *** " & Err.Number _
      & " : " & Err.Description
End Sub

Private Sub Command2_Click()
    End
End Sub

The Exit Sub and line marked 10: are required only if you want to handle processing outside the ErrorHandler. Otherwise, you can use On Error Resume Next.

Running the JumpStart application

1. On the Visual Basic toolbar, click the Start button.
2. In the File name box, type pathname\Test.xml, where pathname is the folder in which you installed the Visual Basic Jumpstart files.
3. Click Parse. The JumpStart application parses the file and displays the results in the TextBox1 text box.