CapeSoft BreakIn
Documentation

• General Information
  • Introduction
  • Features
  • License and Copyright
  • Free Upgrade Policy
  • Screenshots
• Installation
  • System Requirements
  • Installation Instructions
• Operation
  • Loading your Application
    • Application Details
    • Source Details
    • Loading Source Files
  • Breaking In
    • Monitoring
    • Breaking In
    • Closing your Program
• FAQ
• Purchase and Support
• Download
• Installation
• History

Find the root of your Clarion program's non-responsiveness.

Is your Clarion program croaking on you for no reason? Don't you hate it when there is no gpf screen or error message, and nothing but a non-responsive program taking over your computer screen? Normally you would eventually be driven to open your task manager and kill the process in frustration, leaving you with no clue as to what might be causing your program to hang like that. CapeSoft BreakIn is designed to help you find out where your program is getting stuck quickly and easily. It's great for those multi-threaded programs where swimming through your application code in order to locate the problem may not only be a nightmare, but impossible. Note: Does not run on 64 bit operating systems.

The good news is that BreakIn allows you to inspect current source lines in the source files used by your program at runtime. In addition, it uses virtually no CPU time while sitting in the background monitoring your program.

CapeSoft BreakIn Provides:

• Find out where your Clarion program is hanging with no mess and no fuss - just specify your application folder, your Clarion directory, an extra source directory if so desired and Launch to start your program!

• It gives you the power to specify which source files should be monitored while your application is running. This is great for when you suspect that some source code other than your own might be causing the problem.

• Does your program need command line parameters to run? No problem!! BreakIn lets you enter these along with the program name, and takes care of the rest.

• Sits in the background using no CPU time while your program is doing its thing, until you decide to break into the program and see what its doing.

• Displays the stack in a neat tree format for easy access and analysis. Displays the CPU time used by each thread of your program to aid your analysis.

This program is protected by copyright law and international treaties.

This program is copyright © 2000-2013 by CapeSoft Software. Each developer needs his own license to use CapeSoft BreakIn.

License Agreement

CapeSoft Software, employees of CapeSoft Software and Dealers of CapeSoft Software products explicitly accept no liability for any loss or damages which may occur from using this package. This package is used entirely at your own risk. Use of this package constitutes agreement with this license. Please contact should you have any queries.

Downloads

Click here to Download CapeSoft BreakIn.



Note: You must have downloaded CapeSoft Safe Reader 2.19 or later to unlock this product.

Once you have downloaded the file, please unlock it using CapeSoft Safe Reader, run the executable file, and the install program will guide you through the installation.
For further information please consult the Installation section in this documentation.

The same setup program installs the full version and upgrades older installations to the latest version.

Free Upgrades Policy
CapeSoft products have always had a free upgrade policy. i.e. You pay for the product once and then all the new upgrades and features are free. At the moment this is policy for CapeSoft BreakIn. It could change in future, but this has been the case for the past 10 years.

Loading your Program

Loading your program is a quick and easy process:

Source Directories

Next, you specify your Source Directories, and with this done, you can launch your program!

The Main Window

The main BreakIn window, from where you monitor your program, is shown below. It hangs around in the background while your program runs normally.

Breaking In

When you want to see what exactly your program is doing at a given point in time, press the break button, and the details appear on your BreakIn window!

System Requirements

• Windows 2000, XP, 2003, Vista or newer

Installation Instructions

Once you have downloaded the file, please run the executable file and the install program will guide you through the installation.

First-time Installation

• Install CapeSoft BreakIn on the machine you want to test your application on.

Subsequent Upgrades

• Shut down CapeSoft BreakIn.
• Run the CapeSoft BreakIn setup program.

Loading your Application

Application Details

When starting up CapeSoft BreakIn, the first window you are confronted with asks you to enter the details of the Clarion program you want to monitor. It looks like this:



You are expected to provide the following information:

• Application to Monitor: The name, including the path, of the Clarion program you want to monitor. Note: For optimal use of BreakIn, make sure that your program was compiled in debug mode. If this is not the case, you may find that the information available in the Stack Trace and Procedure Source upon Breaking In will be very limited.
• Command Line Parameters: If your program runs from the command line and needs command line parameters, enter these here.
• Start in Directory: Enter the directory in which you would like BreakIn to start your Clarion program in.

When you have entered all of these details, click next. You will be taken to the Source Details window.

Source Details

You will encounter this window after filling in the Application Details. The main goal here is to fill in the path to your Clarion directory. The window looks like this:



You are required to provide the following information:

• Clarion Directory: Fill in the path to your Clarion directory.
• Extra Source Directory (Optional): This field is optional and is rarely used. Use it only if your program makes use of a DLL for which you have the source available, but where that source resides in a directory other than the Clarion directory. If this is the case, fill in the path to this directory here. Note: If certain source lines are not being displayed in the Stack Trace and Procedure Source list boxes on the main BreakIn window and you think they should be, you may want to check whether those source files reside in your Clarion directory. If not, fill in the location here.

Upon completing the above field(s), you can choose to press one of the following two buttons:

• Back: Oops, you must have suddenly remembered that something you filled in on the Application Details window was incorrect or incomplete. Press this button to take you back there.
• Launch: All's done and its a-for-away! Press this button to start up your Clarion Program.

When you press the Launch button, the Loading Source Files window will appear.

Loading Source Files

When pressing the Launch Button on the Source Details window, you will be confronted with the following window:



You can sit back and relax for a second or two - the loading happens automatically, and when it is done you will be taken to the Monitor window.

Monitoring your Program

After pressing the Launch Button, and after your source files have finished loading, the main BreakIn window appears on your screen along with the application you told it to launch:



BreakIn runs your Clarion application as a child process and does not slow your application down in any way. It hovers in the background while monitoring your program. On the BreakIn window you will see two list boxes with the following information:

• Stack Trace: At the moment, this lists the each thread started up with your application. For each thread, the following information is displayed:
  • Thread ID: The thread ID.
  • CPU Time Usage: This is the number displayed to the left of the thread ID. It is the CPU time currently used by this thread.
  • Procedure Source: This list box only becomes useful when the Break button is pressed.

Besides the list boxes, you will also see the following buttons on this window:

• Exit: If you've had enough of this for now, press this to exit BreakIn. Note that as soon as BreakIn is closed, it will close the Clarion application it started, too.
• Break: Press this at any time to "break into" your program. See the Breaking In section for more.

Your program will run normally until it hangs, gets stuck in an infinite loop or does something else inexplicable. Whereas before you may have been tempted to pull your hair out by the roots or throw your keyboard at the dog, this has now become a perfect opportunity to hit the Break button. At this point you will be Breaking In to your program - click on the link for more.

Breaking In

This is where the real magic happens. After pressing the Break button when your program hangs (or for any other reason), your BreakIn window will change slightly and will look as follows:



You will see that once you have pressed the Break button, your application is rendered entirely non-responsive and non-active. It in fact stops your program dead in mid-operation. But now there is more information available in the list boxes:

• Stack Trace: The Stack Trace box still displays all the information as explained in the Monitoring your Program section. In addition, it now lists the
  return stack procedures for each thread of your application. You will notice that this list now has a tree structure, with the top-level items being the threads of your application. If you click to expand an item, you will get the stack trace for that thread.
  • The top item of the trace gives you library and the address at which the thread was executing at the time you pressed the Break button.
  • The rest of the stack for that thread is displayed underneath. For every item in the stack you get the address it was executing at, and either the line of source code that was being executed, or the name of the library that was being executed.
  • The source for a module will only be displayed if it is available. If the source is not in your specified Clarion directory, you would have had to specify its location in the Extra Source entry on the Source Details window. You also need to make sure that your program was compiled in debug mode.

• Procedure Source: When clicking on an item in the stack trace of a thread that contains a source line, this list box will be populated with information regarding the procedure that the source line belongs to:
  • Image: The executable or DLL calling the procedure.
  • Module: The source module that the line belongs to.
  • Procedure: The name of the procedure that the source line belongs to.
  • Source Lines: Depending on whether the source code is available (see the notes under Stack Trace above), this will list the source code for the entire procedure to which the source line belongs

There have been some changes to the buttons on the window as well:

• Resume: Once you have studied the list boxes above, you may want your program to continue running as normal. If so, press this button.

Note that the two list boxes on this window can be resized by clicking and dragging on the gap between them, for your convenience.

Closing your Program

You can close your program at any time in the normal fashion (except when you have pressed the Break button and not Resumed, in which case you will not be able to do anything with it). If you do, BreakIn looks like this:



Now you only really have three choices:

• Exit: You've had enough of BreakIn.
• New: Load a new program to BreakIn to.
• About: Find out what BreakIn is all about.

Note: You should compile your application in stand-alone mode when using Break-In to get useful information from the BreakIn window.

1. Question: Why am I getting *** Source not found *** and *** Next failed, Compiler added line? *** errors in the Stack Trace and Procedure Source boxes when BreakIn to my program?
   
   Answer: More than likely it is because the source of the DLL that is being executed is not available. There are at least two possible reasons for this:
   • Your Clarion program was not compiled in debug mode, and therefore BreakIn cannot extract the information needed to locate the source modules from your application.
   • The source files of this particular DLL do not reside in your Clarion directory. If this is the case, you need to specify the location of these files using the Extra Source entry on the Source Details window.
2. Question: My EXE locks up when running in the BreakIn environment. What am I doing wrong?
   
   Answer: Check that you are not running another program (using the RUN() command or a 3rdparty tool like PowerRun). BreakIn is not able to run other programs from within it's own environment.
3. Question: I get a Stop: "LoadStackQ Error, ReadProcessMemory failed: Only part of a ReadProcessMemory or WriteProcessMemory request was completed"
   
   Answer: That message is indicative that there's a section of memory that BreakIn does not have access to (and so it cannot continue running the application). Generally this is as a result of your program running external components (like OCXs or COM objects) - that BreakIn does not have permitted access to the stack for the memory required to continue running you application.
   
   The only way around this is to avoid running those parts of your application (from within BreakIn) that will force BreakIn to attempt to access those memory slices on the stack.

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

CapeSoft BreakIn may be purchased from:

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

Buy Online
Web	www.clarionshop.com

Click here to Download CapeSoft BreakIn



Note: You must have downloaded CapeSoft Safe Reader 2.19 or later to unlock this product.

Once you have downloaded the file, please unlock it using CapeSoft Safe Reader, run the executable file, and the install program will guide you through the installation. For further information please consult the Installation section in this documentation.

The same setup program installs the full version and upgrades older installations to the latest version.

Once you have downloaded the file, please run the executable file and the install program will guide you through the installation.

First-time Installation

• Install CapeSoft BreakIn on the machine you want to test your application on.

Subsequent Upgrades

• Shut down CapeSoft BreakIn.
• Run the CapeSoft BreakIn setup program.

Think something is missing from CapeSoft BreakIn? Can't live without a feature? Need to report a bug? Just email !

Version 1.02 (18 August 2012)

• Works when running on a 64 bit OS.
  

Version 1.01 (January 2006)

• Removed TWSDImageHeader stop.
• Removed stop from code

Version BreakIn 1.00 (December 2005)

• First release.