


	Version 1.00 beta © 2006 by CapeSoft Software (Pty) Ltd www.capesoft.com Updated 24 November 2005

Contents

	Introduction
	Features
	Support
	Overview
	Installation
	Preparing your Application for profiling
	Using the Profiler
	Examples
	Tips & FAQ
	License & Copyright
	Version History

Introduction

The CapeSoft Profiler allows you to locate the "slow" points in your application code.

Note : Now supports Win95, Win98, WinNT, Win2k and WinXP

Features

Simple to "add" to your program (just turn on full debugging and compile)
Gathers useful statistics such as the number of times that a source line is executed and the CPU time taken to execute.
Reveals "slow" sections in your application that appear even in "well written code".

Support

Your questions, comments and suggestions are welcome. Check our web page (www.capesoft.com) for new versions. You can also contact us in one of the following ways.

CapeSoft Support
	Email
	Telephone	+27 21 715 4000
	Fax	+27 21 715 2535
	Post	PO Box 511, Plumstead, 7801, Cape Town, South Africa

Profiler is available for purchase from:

CapeSoft Sales
	Web	www.capesoft.com
	Email
	Telephone	+27 21 715 4000
	Fax	+27 21 715 2535
	Post	PO Box 511, Plumstead, 7801, Cape Town, South Africa

Buy Online
	Web	www.clarionshop.com

Overview

The Profiler is a tool to show you which parts of your code are using the most CPU time. The Profiler can be used to highlight the "slow" points in your code however it is up to you to assess if the time taken is reasonable or not.

The method that the Profiler uses to compute the CPU time for each line of your source code adds a huge overhead to the work that the CPU has to do. This means that your program will run very slowly in the sections of code being profiled. The good news is that you do not usually have to complete the whole process to find the "slow" points. By running the process and watching where the time is being spent you can often pinpoint the problem areas without waiting hours for complete profiling of your application.

The CapeSoft Profiler will run your application as a child process. This is done in the same way as running your application under the clarion debugger. You will notice that if you quit the Profiler then your application will be terminated.

The GoFaster demo application code is supplied with Profiler. See your \ClarionX\3rdParty\Examples\Profiler folder. This is an ordinary clarion application. You may recompile GoFaster in LOCAL or STANDALONE modes if you would like to. The Profiler will work with either.

Installation

1. Run the supplied installation file.

Preparing your Application for profiling

Preparing your Application is easy.

1.	While the App is Open go to the Project Editor. Click on Properties.
2.	Ensure that the "Build Release System" option is OFF.
3.	In the "Debug Information" section select the "Mode" as "Full".
4.	Click on the OK button. (Close the Global Options)
5.	Close the Project Editor.
6.	Compile the Application.

Using the Profiler

Profiling your Application is easy.

Run the Profiler. It will open on the "Select File to Profile" window.
Type the full path and filename of the Application to be profiled into the "File to Profile" entry box. You may use the file selector button.
Optionally enter any required command line switches into the "Command Line Parameters" entry box.
Optionally enter a start in folder. The default is the Application folder.
Click "Next" to proceed to the "Source Search Directories" window.
Enter the Clarion folder used to compile your Application in the "Clarion Directory" entry box. The Profiler will search here for source files that are not found in your Application folder.
Optionally specify a folder to be searched if the source file has not been located. This is useful for profiling DLL's used that are compiled elsewhere.
Click "Launch" to run your Application under the Profiler. This opens the "Add Source Lines to be profiled" window.
Select the Modules / Procedures that are to be profiled.
Click "Continue" to proceed with the profiling.
Every time you click on a column header then the Profiler will re-sort the data in that column order. Use this to locate the "slow" lines of code by clicking on the "Total Time" column.
If you click on a profiled line then the procedure containing that line will be shown in the list box below the profiler data. Use this to locate where in your code the source line is.

The Time Taken is the sum total for all instructions executed (converted to real time - as if the program was running outside the Profiler environment). This excludes idle time.
The Process Time is the time that the program has been running for within the Profiler environment.

Examples

There is an example in your \ClarionX\3rdParty\Examples\Profiler directory.

This is used with the Profiler "Run Tutorial" option.

Tips & FAQ

Clarion Versions : Profiler works with Applications compiled in Clarion 5, 5.5 and 6.

TIP 1	Place an EXIT statement at the end of each routine. This does not change your code (the compiler adds this if you omit the EXIT) however it makes interpreting the profiler data much easier.
TIP 2	Place a RETURN at the end of each procedure. This does not change your code (the compiler adds this if you omit the RETURN) however it makes interpreting the profiler data much easier.

FAQ 1

Q) Why does the Profiler show some of my procedure variables and class declarations as being executed when the procedure is profiled?

A) This occurs where the variables are declared, locally or inside your class, and are initialized to some value. What happens is that the clarion compiler adds code to the beginning of your application which initializes these variables to zero or spaces as required. Using the AUTO attribute may be an option for your application however you might then need to initialize these variable yourself.

FAQ 2

Q) Why does lots of time get allocated to the last line of my routine? I expect the RETURN to be quick.

A) The Profiler allocates all the CPU time from the start of a profiled line to the start of the next profiled line. This can be confusing.

As an example if routine A calls routine B.
If you profile routine A but not routine B then all the CPU time for routine B is allocated to the "DO routine B" line in routine A.
If you profile both routines then the "DO routine B" line is quick and each line of routine B gets its own CPU time.
If you only profile routine B then all the CPU time outside of routine B is allocated to the last line of routine B.

What the Users are saying

Jim Kane (article on the softvelocity.clarion.third_party news group), 13 April 2006:

....I ran the profiler first and it showed me that a call to a com method was taking virtually 99% of the time for a procedure to run. Optimizing queue vs array would have been pointless. Sometimes knowing what not to do is as important as what to do.

Highly recommended. Beats the heck out of flying blind.

Gregory Bailey (article on the softvelocity.clarion.third_party news group), 13 April 2006:

I found that using it made a huge difference in the wall clock timing of a large piece of code that I inherited from another long gone developer....Rewriting those bits of code allowed the process to complete in 1 - 3 hours a night. The customer is estatic with the results. Sure this could have been done without Profiler, but I still would be looking for code to optimize and might not have connected the 5 places in different portions of the code that read that same file.

License & Copyright

You are not allowed to copy any of the files, including but not limited to, csProfiler.exe and documentation files.

None of the included files may be distributed.

Each developer needs his own license to use Profiler. (Need to buy more licenses?)

This product is provided as-is. Use it entirely at your own risk. Use of this product implies your acceptance of this, along with the recognition of copyright stated above. In no way will CapeSoft Software (Pty) Ltd, their employees or affiliates be liable in any way for any damages or business losses you may incur as a direct or indirect result of using this product.

Version History

Version 1.00 Beta: (24 November 2005)

[End of document]

meatloaf@capesoft.com