OLESPY User's Guide

OLESPY User's Guide

Contents

What is OLESPY *
Overview *

Getting Started *

Program Package *

System Requirements *

Installation Instructions *

How to run OLESPY * Starting the Program *

Tracing Options *

What are Tracing Options? *

Opening COM Objects Tracing Options window *

Opening COM/DCOM API Tracing Options window *

Opening Display Options window *

Selecting COM Interface for tracing *

Selecting the COM /DCOM API functions for tracing *

How to select functions? *

Selecting process for tracing *

Selecting tracing presentation *

Closing Tracing Options window *

Tracing Window *

Overview *

File Operations *

New *

Saving trace to a file *

Opening trace from a file *

Edit Operations *

Toolbar and Windows *

Toolbar *

Windows *

What is OLESPY

Overview

When COM clients communicate to COM servers they make two types of COM-related calls:

Calls to COM/DCOM library

Interface calls based on interface pointers obtained via calls to COM/DCOM library or other interface calls

These calls are explicit for 3GL-written applications, such as "C" or "C++" (if not using special libraries, like ATL, for example). 4GL-written applications, such as Visual Basic and Powerbuilder and 3GL applications using libraries make these call implicitly, through specialized language constructs or library objects.

The task of tracing COM-related calls the application is making becomes very important for:

Debugging COM clients and servers

Testing applications using COM

Resolving performance problems

For simple 3GL-written applications the tracing can be done by inserting tracing statements for every call. If the 3GL application is very complex this strategy is usually not acceptable, as inserting tracing statements becomes a project by itself. For 4GL situations and libraries inserting trace statements for low level calls is usually not an option.
OLESPY can trace COM API functions as well as interface methods for any COM client application launched by OLESPY.
Trace information includes:

COM function or interface method’s name

Return code

Timestamp

Values of arguments

Execution time

Getting Started

Program Package

The OLESPY program package includes the following documentation and software:

3^1/2 - inch installation disks

OLESPY User's Guide

System Requirements

The OLESPY program requires the following hardware and software configuration:

PC with Intel 386 or higher processor

MS Windows NT3.51/4.0 or 95/98

Installation Instructions

The installation procedure has to be used in order to install the program. You cannot simply copy the program files from the installation disk to your hard drive.

Insert the Installation Disk into a floppy drive.

Using Windows Explorer, Program Manager or File Manager start the SETUP.EXE program from your floppy drive (typically, A: or B:).

Follow the installation instructions in your screen.

How to run OLESPY

Starting the Program

To start the program click on the OLESPY
icon:

You can also run the OLESPY.EXE from Windows Explorer, Program Manager or File Manager.

The start-up screen has one open empty sheet:

Note: To launch an application automatically, on OLESPY startup run OLESPY with parameter( location and name of tracing program): OLESPY [Filename]

OLESPY is an MDI application. Multiple tracing sheets can be opened at the same time. Depending on the display options a new sheet will be opened for each thread of a traced process or the active sheet will capture calls from all traced processes.

Tracing Options

What are Tracing Options?

OLESPY lets you trace interface methods and COM/DCOM API functions without having to make any modifications to the source code.

Tracing options are set in the following Tracing Options dialogs:

COM Objects

COM/DCOM API Functions

Display Options

COM Objects window presents a choice of: interface functions selectable through type libraries or interfaces.

COM/DCOM API Functions window contains the list of functions from COM/DCOM library .

Display Options window contains the display options: Autotile, Separate sheet per thread and Log to file.

Notes:

Tracing options can be changed at any time during the session and become effective immediately after "OK"-ing out of the window

On exit from OLESPY all tracing options

( except log file settings) will be saved in the registry and automatically restored in the next session.
Opening COM Objects Tracing Options window

From the Options menu, choose COM Objects , or use the ‘Magnet’ Toolbar button:

This will display ‘COM objects’ window.

Opening COM/DCOM API Tracing Options window From the Options menu, choose COM/DCOM API Functions , or use the ‘Functions’ Toolbar button:

This will open ‘COM API Selection’ window.

Opening Display Options window

From the Options menu, choose Display

Options , or use the ‘Display’ Toolbar button:

This will open ‘Display Options’ window.

Selecting COM Interface for tracing

There are three interface tracing options :

All calls

Include selected calls

Exclude selected calls

Note:
Even if you chose Interface Tracing Options ‘All Calls’, you will still be able to select interfaces or methods into the right panel. This can be useful if, during the process of tracing, you decide to switch from 'All' to 'Include selected' or 'Exclude selected' without reselecting the methods. OLESPY will remember your methods selection.

How to select all COM Interfaces

To select all COM Interfaces for tracing click on radio button ‘All Calls’ in ‘COM Objects’ window.

How to include/exclude a subset of COM Interfaces

There are two ways to include/exclude COM interface methods for tracing:

Interfaces subtree

Type libraries subtree

Note:
The first method allows to select only complete interfaces , i.e. all the methods in the interfaces. To be more selective you will have to use the second method of selection: through type libraries. Including/Excluding COM Interface methods through interface subtree.

Follow these steps:

Click radio button ‘Include/Exclude selected’

Expand the ‘Interfaces’ folder in the left panel

Select an interface

Click 'Move' button:

Repeat these steps for all Interfaces you want to trace.

To trace IUnknown Interface methods check or uncheck ‘QueryInterface’ ,’ AddRef’ and ‘Release’ check boxes.

Including/Excluding COM Interface methods through type libraries.

Follow these steps:

Check radio button ‘Include/Exclude selected’

Expand the ‘Type Libraries’ folder in the left panel. You will see the list of all Type libraries available for selection.

Expand the current Type Library folder. You can trace the whole interface or select an interface method. In order to select an interface method, expand current interface.

Select an interfaces or one of interface methods

Click 'Move' button:

The selected methods or interfaces will be added to the right panel ‘Selected Methods'.

Notes:

IUnknown methods are not available for selection from the left panel.

When you select complete interface for tracing in the right panel -- ‘Selected Methods’, you will see a "*" in 'Member id' and 'Member name' fields

Unselecting methods or interface

To unselect an interface or interface method from tracing highlight it in the right panel ‘Selected Methods’ and click on the 'Move to the left' button:

Selecting the COM /DCOM API functions for tracing

In order to select a COM/DCOM library function for tracing you have to move it from the ‘COM API Functions’ panel to the ‘Selected Functions’ panel.

How to select functions?

Selecting a function to trace can be done in several ways:

‘move selected’ method
‘move all’ method

‘Move Selected’ Method

Select a function or a group of functions (extended selection using Shift or

Control Keys) and click on the 'Move' button:

‘Move All’ Method

Select all functions by clicking on the 'Move All' button to move all functions from ‘Com API Functions’ box to ‘Selected Functions’ box.

Unselecting functions

Unselecting functions is similar to selection, except that all transfers are from the right panel (‘Selected Functions’ box) to the left panel (‘COM API Functions’ box).

Example: To unselect all function(s) click

on button.

Selecting process for tracing

In order to select an application for tracing you have to launch it from OLESPY. To do so choose Launch Process from the Options menu or use the 'Shuttle’ Toolbar button:

It will open a standard 'Open File' dialog where you can choose an application for tracing.

Note:
The application will be killed after OLESPY is closed.

Selecting tracing presentation

To select presentation attributes for trace information use the Options menu, choose Display Options, or use the ‘Display’ Toolbar button:

This settings allow to specify sheets arrangement, separate sheet per thread and if and where the tracing information should be logged.

Note:
These settings affect only the visible presentation of the trace

Autotile

To arrange the sheets contained in an MDI frame. Tile the sheets that are not minimized so that they do not overlap and arrange icons of minimized sheets in a row at the bottom of the frame .

Separate sheet per thread

To display each thread’s activity in a separate sheet. During the tracing process new window(sheet) will be open automatically for each new thread .

If this option is unchecked call tree will not be build in the left tracing panel, only start and end of the function calls or interface methods will be displayed.

Gray color indicates the end of function calls or interface methods.

Logging to File

To set up the ‘Log to’ display options window click on ‘Log to’ check box. It will allow you to type the name of the file and file format directly into the edit box or use the ‘Save as’ button to open the standard ‘Save as ’ dialog window.

Closing Tracing Options window

You can close all of the Options windows by clicking on the "OK" or "Cancel" buttons.

If "Cancel" button is clicked all changes made in Options window will be lost.

If "OK" button is clicked tracing selections will be stored in the registry and will be effective for the current and following sessions.

Tracing Window

Overview

Multiple tracing sheets can be opened at the same time during the session of OLESPY. Each window(sheet) has two panels:

Left panel contains a list of traced functions from COM API libraries and interface methods
Right panel contains detail information for
Selected function or interface method from
The left panel

To get detail information about any function or interface method in any window (sheet) – click on it in the left panel.

File Operations

File operations of OLESPY are straightforward. You can open a new sheet window, aave a trace and later open it again in the application.

Note:

Logged traces can also be opened.

New

To open New trace sheet window from File menu, choose New or use the ‘New’ Toolbar button:

Note:

Unless you uncheck separate sheet per thread this command will not effect tracing display.

Saving trace to a file

Saving trace to a file is functionally similar to logging to a file. The only difference is that logging will do it one line at a time while saving takes all data from the active sheet window.

To save any Trace sheet window to a file:

Select the sheet window you want to save to a file
From the File menu, choose Save as, or use the Frame Toolbar button:

It will open standard window Save as dialog where you can choose the directory and type the name of the file.

Note:

You can open saved or logged files in any text editor.

Opening trace from a file

Any valid file saved from OLESPY application options such as ‘Logging to a file’, ‘Saving trace to a file ’ can be opened into a new tracing sheet window.

To open a previously saved file into a new sheet window from the File menu, choose Open or press Ctrl+ O keys or use or use the ‘Open’ Toolbar button:

It will open standard window dialog where you can choose the directory and the file .

Note:
This new window opened from a file becomes a valid trace window with all functions available in OLESPY .

Edit Operations
Find

To find text within active Tracing window you can use ‘Find ‘ dialog.

To activate it, choose ‘Find…’ from the Edit menu or use the Toolbar button:

It will display a ‘Find ’ window.

Note:

‘Find Next ’ button will be enabled after you start typing intot ‘Find what’ field.

OLESPY starts to search from the current item on the left panel (by default, it will search starting from the root item). Type the substring of the item you want to find and click ‘Find Next’. OLESPY will start searching, opening every function and interface and showing (highlighting) the first item that matches your criteria. OLESPY will indicate the detailed information about every match in the right panel. The next search result will be displayed when you press ‘Find Next’ again without changing the search text. To cancel the search, press ‘Cancel’ button in the ‘Find’ window.

If more then one sheet are open the search will be performed in the active sheet.

Toolbar and Windows
Toolbar

OLESPY has a toolbar which can be used for quick access to many features.

If no sheets are opened some buttons on the toolbar will be disabled.

You can show, hide and move toolbar.

How to show/ hide toolbar

On the View menu, click Toolbar to enable or disable it.

How to move toolbar

Click and hold down left mouse button on the border of the toolbar and drag it to its new position.

The toolbars buttons

Toolbar

Windows
Multiple tracing sheets can be opened at the same time during a session. To see all open windows (sheets) choose one of the options in Window Menu:

Cascade

Tile

Arrange Icons

Note:

The Tile command resizes and arranges the open group windows side by side. The Cascade command resizes and layers the open group windows so that each title bar is visible.

Tiled Sheet Layout

Copyright © 1997, Kogosoft Corporation. All Rights Reserved.