How To Use madExcept

Integrating madExcept into your projects...

In order to integrate madExcept into a project please open the project in Delphi. Then in Delphi's "Project" menu enter the madExcept settings and enable madExcept there. Now the only thing left is to recompile your project. After the successful recompile madExcept is fully integrated into your project.

If you want your dlls to handle their own exceptions, you should put a "try [..] except" around each exported function and message handler. But normally you don't need to. If your dll raises an exception and doesn't handle it, the application does.

procedure DllExportedFunction;
// you only need to do this, if the application (which uses your dll)
// is not compiled with madExcept
    // real code here
  except HandleException end;

exports DllExportedFunction;

Customizing madExcept...

You don't need to, but you can customize the behaviour of madExcept. Please look at the madExcept settings dialog to see all the possibilities you have. One thing you should customize is the email address in the madExcept settings. If you do that, your customers can send you bug reports directly from the exception box.

Main thread freeze checking...

If the settings say so, madExcept checks periodically, whether your main thread is not frozen yet, that is, whether it is still responding to messages. Sometimes such a check makes no sense. E.g. console applications often don't handle messages at all. In such a case please do not enable the freeze checking option in the madExcept settings.

Sometimes your application's main thread normally responds to messages, but stops doing that in special situations for a specific period of time, e.g. when printing or something like that. In that case you should temporarily disable the freeze checking by calling PauseFreezeCheck to avoid false alarms. Also you can call ImNotFrozen at any time to reset the freeze check timer.

Multi threaded projects...

In case your project uses multiple threads, sometimes the bug reports look a bit confusing. The main thread is named "main thread", but other threads can sometimes be hard to identify. You can make your bug reports better readable/understandable by giving names to your secondary threads. Please call NameThread for that purpose.

Command line compiling/linking...

If you're using Delphi's command line tools to build your projects, please have a look at the tool "madExceptPatch.exe", which you can find in the "tools" directory. This tool does all the necessary patching to give madExcept its full power. When building your projects inside of the IDE, madExcept's IDE wizard does the necessary patches automatically in the background. But when compiling through command line the wizard isn't running, of course. So in that case please let "madExceptPatch.exe" do its work after your project is linked.

The tool "madExceptPatch.exe" needs a detailed map file for your project (in BCB it needs a full "tds" debug information file instead). So please tell the command line compiler to produce the needed information. A detailed map file can be forced by using the "-gd" switch.

Custom exception handlers...

Maybe you want to install your own exception handler. The usual exception handlers ("ErrorProc" and "TApplication.OnException") won't work anymore, when using madExcept. Instead you can either use the TMadExceptionHandler.OnException event or directly call RegisterExceptionHandler.

The following example is a little unit, which you can add to any of your projects. The unit registers an exception handler, which does nothing but remove the header field "command line" from the bug report. If you use this little unit, the exception box is shown, nevertheless. If you don't want that, set the variable "handled" to true. In that case no other exception handler is called anymore, and no exception box is shown, either...

unit RemoveCmdLine;



uses madExcept;

procedure RemoveCommandLineHeaderInfo(const exceptIntf : IMEException;
                                      var handled      : boolean);
  exceptIntf.BugReportHeader['command line'] := '';

  RegisterExceptionHandler(RemoveCommandLineHeaderInfo, stDontSync);