HOWTO: Testing OLE Applications with Outline

ID: Q131154

The information in this article applies to:

Microsoft Win32 Software Development Kit (SDK) for Windows NT version 3.5
Microsoft OLE Libraries for Windows and Win32s, versions 2.01, 2.02, and 2.03
Microsoft OLE Libraries included with: - Microsoft Windows NT version 3.5 - Microsoft Windows 95

SUMMARY

To understand how an OLE application should handle an OLE scenario, you may find it helpful to examine an existing application that handles that scenario correctly.

The OUTLINE series of OLE sample applications can provide a log of debug output. This log shows all of the OLE calls that the OUTLINE application handles and the OLE calls that it makes. Examining this log is a useful OLE problem-solving tool, and an excellent way to learn about OLE programming.

MORE INFORMATION

The OUTLINE series consists of four different applications: CNTROUTL (OLE container), SVROUTL (OLE server), ICNTROTL (in-place editing-capable OLE container), and ISVROTL (in-place editing-capable OLE server). The OUTLINE series is included as sample code with the OLE SDK and with the Win32 SDK.

Each of the four OUTLINE applications implements a Debug Level dialog box. The following table show the debugging information produced by each debug level value:

Debug Level   Debugging Information Produced

   0          No debug messages (default).
   1          Print message when a Document or Application is destroyed.
   2          Trace every OLE API and method call.
   3          Give a more OUTLINE app specific context to the OLE calls.
   4          Track all memory reference counts (AddRef/Release).

The debug output forms a log of all the incoming and outgoing OLE method calls that OUTLINE handles. Use the DBWIN tool to capture and display this output. Note that although there are both 16-bit and 32-bit versions of the OUTLINE samples, DBWIN can currently only be used to capture output from the 16-bit samples.

Benefits to Examining the Watch Log

The first benefit to examining the watch log produced by one of the OUTLINE samples is that it shows the series of calls that an OLE application needs to make in order to handle a given OLE scenario. For example, to see what calls an OLE container application needs to make when transitioning an embedded object from the loaded to the running state, double-click an object embedded into a CNTROUTL document to run that object; then examine the log that CNTROUTL produces.

The next benefit arises from the fact that the source code to the OUTLINE samples is included with Microsoft Visual C++. The watch log shows you the key calls that OUTLINE makes to handle some particular scenario. Using a GREP utility, you can search the OUTLINE source code for those calls, and then examine that code. The OUTLINE source code is a very thorough implementation of OLE functionality.

In addition, you can run the OUTLINE application under a debugger, setting break points before the key calls, and then stepping through that code.

Finally, the OUTLINE source code contains many source code comments labeled "OLE2NOTE." These comments contain in-depth discussions of some of the more detailed aspects of OLE programming.

Keywords          : kbole kbtshoot LeTwoTls 
Version           : 2.01 2.02 2.03 3.5 4.0
Platform          : NT WINDOWS
Issue type        : kbhowto

Last Reviewed: April 9, 1997