DOCUMENT:Q122488  07-MAY-2001  [visualc]
TITLE   :PRB: How to Use Automation Error Code & Help from Visual Basic
PRODUCT :Microsoft C Compiler
PROD/VER:WINDOWS:1.0,1.5,3.0; winnt:2.0
OPER/SYS:
KEYWORDS:kbinterop kbtshoot kbAutomation kbCOMt kbMFC kbVBp300 kbVC100 kbVC150 kbVC200 kbGrpDSMF

======================================================================
-------------------------------------------------------------------------------
The information in this article applies to:

 - Microsoft Visual Basic Standard Edition for Windows, version 3.0 
 - Microsoft Visual Basic Professional Edition for Windows, version 3.0 
 - The Microsoft Foundation Classes (MFC), used with:
    - Microsoft Visual C++ for Windows, 16-bit edition, versions 1.0, 1.5 
    - Microsoft Visual C++, 32-bit Editions, version 2.0 
-------------------------------------------------------------------------------


SYMPTOMS
========

Visual Basic version 3.0 does not report automation errors that result from OLE
automation exceptions. Instead, it reports an err value of 440 and a description
string of "OLE Automation exception." The actual wCode passed by the automation
server is lost.

STATUS
======

This behavior is by design in Visual Basic version 3.0. Visual Basic for
Applications, included in Excel version 5.0, Visual Basic 4.x and later, and
other Microsoft products, returns the wCode correctly.

MORE INFORMATION
================

When an MFC automation server throws an OLE dispatch exception by calling
AfxThrowOleDispatchException, an object of class COleDispatchException is built.
Its member variables include an OLE SCODE, a help context, string error
description, and wCode (an integer code used by Visual Basic).

The only information that the Visual Basic automation controller preserves is the
string description. However, the MFC OLE automation server can preserve the
information used in the call to AfxThrowOleDispatchException() and expose an
additional "Help" method that uses this information to provide help to the user.
From within the Visual Basic error handling code, Err is 440, Error(Err) is "OLE
Dispatch Exception" and Error$ is the actual string passed by the server.

Sample Code Snippets
--------------------

   /* Compile options needed:
      standard MFC OLE project generated by AppWizard*/ 

1. The method in the Automation server that throws the dispatch exception should
   retain the help context and wCode as member variable of the automation object
   as in this function:

      void CMyObject::Exception()
      {
         m_nIDContext = <some context>;
         m_nSomeCode = <some code>;
         AfxThrowOleDispatchException(m_nSomeCode,"String",m_nIDContext);
      }

2. The Automation server should expose a method that uses those member variables
   to start WinHelp or another help engine with the actual context from the
   exception as in this code:

      short CMyObject::GetError()
      {
         // From here you can use the member variable code
         // and context to start WinHelp or do whatever
         // help code you need to do ...
         AfxGetApp()->WinHelp(m_nIDContext);
         return m_nSomeCode;
      }

3. The Visual Basic error handling routine should call the exposed error method
   in the Automation server when a dispatch exception occurs. Here is example
   Visual Basic code:

      Sub Command1_Click ()
         On Error GoTo EHandle
         Dim a As object
         Set a = CreateObject("TestAuto")
         ' Next line causes exception:
         a.exception
      EHandle:
         Msg = "The error message for error number "
         Msg = Msg & Err & " is:" & NL & NL
         Msg = Msg & """" & Error(Err) & """"
         MsgBox Msg  ' Display message.
         ' Next line starts WinHelp engine by calling method in server.
         a.GetError
         Exit Sub
      End Sub

Additional query words: 1.00 1.50 2.00 2.50 3.00

======================================================================
Keywords          : kbinterop kbtshoot kbAutomation kbCOMt kbMFC kbVBp300 kbVC100 kbVC150 kbVC200 kbGrpDSMFCATL 
Technology        : kbVBSearch kbAudDeveloper kbPTNotAssigned kbMFC kbZNotKeyword2
Version           : WINDOWS:1.0,1.5,3.0; winnt:2.0
Issue type        : kbprb

=============================================================================

THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS
PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.  MICROSOFT DISCLAIMS
ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  IN NO
EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR
ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL,
CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF
MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.  SOME STATES DO NOT ALLOW THE EXCLUSION
OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES
SO THE FOREGOING LIMITATION MAY NOT APPLY.

Copyright Microsoft Corporation 2001.