 |
|
 |
|
|
|
The CCI Debug and Profiler Classes
by Dave Harms
Published 1999-03-08 Printer-friendly version
DevCon
'99 Presentation and 1.1 beta
You can download the version of the profiler which I used for my DevCon '99 presentation
but for now you're on your own as far as documentation goes (although the example app and
PowerPoint presentation are included).
Usage Documentation
Articles
- Article: Debugging Without The
Debugger
Posted on March 29, 1999
NOTE: This document covers version 1.1 of cciDebugClass and cciProfilerClass. The 1.0 documentation is still available: click here.
cciDebugClass Usage
I wrote cciDebugClass as a supplement to the much-maligned Clarion debugger. Even if I had a good debugger it wouldn't always serve my purposes because a debugger gives you a snapshot of the current state of the program. What I often need is a log of what's happened during program execution.
The cciDebugClass lets me log messages (by calls to the trace method, unless I'm using the cciProfilerClass which will create some log messages automatically) and view the log on screen in a window, in a toolbox, or write the log to a file.
To use cciDebugClass with an application first unzip files ending in .INC and .CLW into the libsrc directory, and files ending in .TP? into the template directory.
Close any open application, choose Setup|Template Registry, and register CCIPROF.TPL. Close the registry.
Open your application. Click on Global, then Extensions, and add the cciProfilerDebuggerClassGlobals extension. On the extension properties select cciDebugClass as the base class. You may also want to check Automatically Add Source Files To Project, although this is NOT recommended when using cciProfilerClass (see below).
You can leave the rest of the settings as they are. This will create a global object called dbg, and will initialize the object at program startup and clean it up at program shutdown. I don't generally advocate short variable names but as this is a global and often-used object I think it's okay.
That's all you need to do! When your application runs a trace file called trace.log will be created. To put messages in this file, call the trace method with your message:
dbg.trace('whatever you want to appear in the log file')
To view the trace log you can call the ViewTrace() method. If you want to bring up a toolbox on its own thread so you can see messages as they appear, call ShowTraceToolbox().
If you want the trace log to record all of the events that occur in your program, go to the Options tab and check Record All Events. This will generate code into all procedures which have windows to log the events received by the accept loops.
Trace messages are cached so that you're not constantly writing to the disk. If you're getting a GPF somewhere in your program cached messages will be lost. You can set the CacheSize property to 1 so that messages are written out immediately.
cciProfilerClass Usage
Having a debug class was great, but what I really needed was a way to automatically generate a procedure call tree. Happily Clarion provides a mechanism in its profiler hooks (and yes, one of the future applications of this class is execution profiling).
To use the profiler class follow the same instructions as for cciDebugClass but choose cciProfilerClass as the base class.
Next, make sure that Automatically Add Source Files To Project is NOT checked. You have to add the source to the project manually when using profiling because you have to set some compiler pragmas, and if you add them automatically the pragmas will be overwritten the next time you do a global generation. The LINK attribute isn't an option because it doesn't allow you to set pragmas on automatically linked files.
Add cciDebug.clw and cciProf.clw to your application's external file list.
cciProf.clw contains prototypes for two internal Clarion functions: EnterProc and LeaveProc. You need to enable these functions so that the profiler class can use them to automatically log the procedure calls via its parent class, cciDebugClass.
While you're in the project editor, highlight the top line of the project tree (the line that starts "Project:") and click on Properties. Click on the Defines tab and type
profile
in the text box. Close the properties window. Now in turn highlight cciProf.clw and cciDebug.clw and for each of these files type the text
profile=>off
in the Defines text box. You have now turned profiling on for the entire application, and off for the two source files, which is essential if you're to avoid an endless recursion when the profiling class or debugging class methods are themselves profiled.
Run the application! It will create a trace log of all of the procedure and method calls. You can call the Trace method to add your own messages, and you can also call the ViewTrace or ShowTraceToolbox methods to see the results of the trace while the program is running.
NOTE: I've only been able to get the profiler to work within single EXEs because of exporting problems. If you want to use the profiler hooks in a DLL you will probably need to split that code out into its own EXE.
As of version 1.1 there are now also code templates to view the trace log and open the trace toolbox. The trace toolbox lets you see messages as they appear. You may want to look at the Alert Toolbox setting on the global extensions Options tab. If checked the toolbox will be told to redisplay the last record each time a new trace record is added. This can interfere with the application and so is left off by default when using the template.
