Microsoft XML Core Services (MSXML) 5.0 for Microsoft Office - SAX2 Reference

parse Method

Parses an XML document or a DOMDocument object.

[Visual Basic]

An application can use this method to instruct the reader to begin parsing a document from any valid input source, including a DOMDocument object, character stream, byte stream, or Uniform Resource Identifier (URI). An application cannot invoke this method while a parsing is in progress. Instead, it should create a new instance of the reader for each nested XML document. After parsing is complete, an application can reuse the same reader object, possibly with a different input source.

Usage Syntax

oSAXXMLReader.parse(varInput)

Parameters

varInput
A variant (or a reference to one) containing the input source to parse from. The following VARIANT types are supported:
  • VT_BSTR, which can contain a value of BSTR type.
  • Either VT_ARRAY or VT_UI1, which can contain a value in the form of a safe array of bytes.
  • VT_UNKNOWN or VT_DISPATCH, which can contain a value in the form of either an IStream, ISequentialStream, or IXMLDOMDocument.

When using references (VT_BYREF), more than one level of indirection is permitted.

An application cannot invoke this method while parsing is in progress. Instead, it should create a new instance of the reader for each nested XML document. After parsing is complete, an application can reuse the same reader object, possibly with a different input source.

Remarks

During parsing, the reader provides information about the XML document through the registered event handlers. If an error occurs during parsing, the reader calls the appropriate method of the ErrorHandler. The ErrorHandler always returns the internal error code to the parse method, even if the ErrorHandler raises a user-defined error.

Example

The following example loads books.xml into a DOMDocument object, specifies the object as a parameter of the parse method, and then displays the result in a message box.

Sub Main()
'create the reader
Dim rdr As New SAXXMLReader50
'create the writer
Dim wrt As New MXXMLWriter50

On Error GoTo errorHandler

wrt.byteOrderMark = True
wrt.omitXMLDeclaration = False
wrt.indent = True

'set the writer to the content handler
Set rdr.contentHandler = wrt
Set rdr.dtdHandler = wrt
Set rdr.errorHandler = wrt
rdr.putProperty "http://xml.org/sax/properties/lexical-handler", wrt
rdr.putProperty "http://xml.org/sax/properties/declaration-handler", wrt

'parse the XML
rdr.parse "<catalog><book id='bk101'></book></catalog>"

'show the results in a message box
MsgBox wrt.output

Exit Sub

errorHandler:
    HandleErrors
End Sub

Private Function HandleErrors()
    MsgBox Err.Description
End Function
[C/C++]

The application can use this method to instruct the reader to begin parsing a document from a variety of sources. Supported VARIANT types are: VT_BSTR, which can contain a value of BSTR type; either VT_ARRAY or VT_UI1, which can contain a value in the form of a safe array of bytes; or VT_UNKNOWN, which can contain a value in the form of either an IStream, ISequentialStream or IXMLDOMDocument.

   VT_BYREF | VT_VARIANT -> VT_BSTR -> BSTR
   VT_BYREF | VT_VARIANT -> VT_UNKNOWN ->  VT_DISPATCH ->IStream |      ISequentialStream
   VT_BYREF | VT_VARIANT -> VT_UNKNOWN -> VT_DISPATCH -> IXMLDOMDocument
   VT_BYREF | VT_VARIANT -> VT_ARRAY | VT_UI1 -> SAFEARRAY

When using references (VT_BYREF). more than one level of indirection is permitted.

An application cannot invoke this method while parsing is in progress. Instead, it should create a new instance of the reader for each nested XML document. After parsing is complete, an application can reuse the same reader object, possibly with a different input source.

Syntax

HRESULT parse (
   [in] VARIANT varInput);

Parameters

varInput [in]
Either a variant (VT_VARIANT) or a reference to one containing the input source to parse from. Supported VARIANT types and their data types for actual values are:

VT_BSTR (BSTR)

VT_ARRAY or VT_UI1 (SafeArray of bytes)

VT_UNKNOWN or VT_DISPATCH (IStream, ISequentialStream, or IXMLDOMDocument).

Return Values

S_OK
The value returned if parsing is successful.
E_INVALIDARG
The value returned if varInput is not a recognized input source.
Other
The parser error code or the code returned by the custom ErrorHandler.

Remarks

During parsing, the reader provides information about the XML document through the registered event handlers. If an error occurs during parsing, the reader calls the appropriate method of the ISAXErrorHandler interface. If the ErrorHandler returns anything but S_OK, parsing is aborted and the parse method returns the internal error that stopped the parser. The ErrorHandler always returns the internal error code, even if the ErrorHandler returns a user-defined HRESULT to the parse method. The reader can return a number of return codes, including, but not limited to: E_ACCESSDENIED, INET_E_OBJECT_NOT_FOUND, INET_E_DOWNLOAD_FAILURE, MSG_E_BADSTARTNAMECHAR, or MSG_E_MISSINGSEMICOLON.

To view reference information for Visual Basic or C/C++ only, click the Language Filter button Language Filter in the upper-left corner of the page.

See Also

Convert DOM to SAX | DOMDocument | ISAXErrorHandler Interface | contentHandler Property (Visual Basic) | dtdHandler Property (Visual Basic) | entityResolver Property (Visual Basic) | errorHandler Property (Visual Basic) | putContentHandler Method (C/C++) | putDTDHandler Method (C/C++) | putEntityResolver Method (C/C++) | putErrorHandler Method (C/C++)

Applies to: ISAXXMLReader Interface