documentLocator Property (Visual Basic)

MSXML 5.0 SDK

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

documentLocator Property (Visual Basic)

Receives an interface pointer to the IVBSAXLocator interface, which provides methods for returning the column number, line number, public ID, or system ID for a current document event.

The reader supplies a Locator object to the application by invoking this property before invoking any other methods in the IVBSAXContentHandler interface. This locator allows the application to determine the end position of any document-related event, even if the parser is not reporting an error. Typically, the application uses this information for reporting its own errors (for example, if the character content does not match the business rules of the application).

Implementation Syntax

Property documentLocator As IVBSAXLocator

Return Values

If failed, the ContentHandler raises a trappable error.

Example

The following example shows how to set and use the documentLocator property in a typical ContentHandler class implementation. The line and column information can be used to support the implementation of log event details by the reader.

Implements IVBSAXContentHandler
Implements IVBSAXLocator

'Declare a variable for setting the locator.
Private oLocator As IVBSAXLocator

Private Property Set IVBSAXContentHandler_documentLocator(ByVal RHS As _
MSXML2.IVBSAXLocator)
    'Invoke the locator by setting it here before the document is read.
    Set oLocator = RHS
End Property

Private Sub IVBSAXContentHandler_startElement(strNamespaceURI As _
String, strLocalName As String, strQName As String, _
ByVal oAttributes As MSXML2.IVBSAXAttributes)
    'When the element starts, write its line/column position in file 
    'back to the text box on the application form.
    Form1.Text1.Text = Form1.Text1.Text + _
                       "Starting <" + strLocalName + "> at " + _
                       "Line " & Str(oLocator.lineNumber) + _
                       ", Column " & Str(oLocator.columnNumber) + vbCrLf
End Sub

Remarks

The Locator object returns the correct information only during the invocation of events in this interface. The application should not attempt to use this method at any other time.

See Also

IVBSAXLocator Interface | startDocument Method

Applies to: IVBSAXContentHandler Interface