_______________________________________________________________________________
_______________________________________________________________________________

  Exceptq v7.1 Readme

  Portions of Exceptq are
    Copyright (c) 2000-2010 Steven Levine and Associates, Inc.
    Copyright (c) 2010-2011 Richard L Walsh
  The remainder of Exceptq is
    Copyright (c) 1992-2000 Marc Fiammante et al.
  Sample code in this file and in exceptq.h are
    Placed in the Public Domain by the author, Richard L Walsh

_______________________________________________________________________________

  Contents
_______________________________________________________________________________

  * Overview
  * New in Exceptq v7.1
  * Adding Exceptq to Your App
  * Exceptq v7.1 Options
  * Miscellanea
  * Sample Code
  * Files

_______________________________________________________________________________

  Overview
_______________________________________________________________________________

Exceptq v7.1 creates a debugging report whenever your program encounters
an unhandled fatal exception, for example an access violation.  It ignores
exceptions that result from a program's normal operation such as signal
exceptions.  It is designed to be the last handler in the chain before
the exception is passed to the system or runtime handler which terminates
the process.

Its report provides the information needed to identify the location of the
fault, and hopefully, enough to identify its cause as well.  Included in
the report are:  the call stack, disassembly of the faulting instruction,
a stack dump, a listing of dlls loaded into the process, and more.  To see
everything the report offers, review the included sample ('006C_01.TRP').

v7.1 is also able to create debugging reports at any point in a program's
execution by raising a non-fatal EXCEPTQ_DEBUG_EXCEPTION.  These reports
can include additional debugging data provided by the app.  After the
report is created, the program will continue to execute.

The report is created in the same directory as the .exe, and is given
a name based on the PID and TID of the thread that caused the exception.
For example, '006C_01.TRP' details a trap in thread 1 of process 6C.  The
amount of detail included in the report can be set by your program when
it loads Exceptq or by an environment variable.

Exceptq will use embedded debug data, dbg, sym, or xqs files, if available,
to label functions and variables included in the report.  Debug data must be
in either IBM HLL debug format (created by VACPP and by GCC with the '-Zomf'
flag) or in CodeView format (generated by older 16-bit compilers).  For non-
debug versions of your app, you can distribute .xqs files created by mapxqs
or .sym files created by mapsym.  Exceptq can handle .sym files with up to
131,000 symbols and .xqs files of any size.

_______________________________________________________________________________

  New in Exceptq v7.1
_______________________________________________________________________________

* Support for symbol files in the XQS format.  XQS files overcome the size
  limitations of .sym files, and identify the module containing each symbol.
  MapXQS.exe, included in the package, can generate them from .map files
  created by the IBM, GCC, OpenWatcom, and Borland linkers.

* Support for the non-fatal EXCEPTQ_DEBUG_EXCEPTION.  It can be used to
  create Exceptq debugging reports at any point in the program's execution
  without causing the app to terminate.  An option to enable or disable this
  feature at runtime has also been added.

* Support for an application-provided string containing version or build
  information that will appear at the top of the report.

* Better identification of addresses contained in registers.  The report
  identifies whether an address lies within one of the program's segments,
  on the thread's stack, or in memory allocated by a specified module.

* Additional system information:  total memory, virtual address limit, and
  number of processors.

* Exceptq's report has been reformatted to make it more compatible when
  viewed in email and on the web.

_______________________________________________________________________________

  Adding Exceptq to Your App
_______________________________________________________________________________

Including Exceptq v7.1 in an application requires minimal effort from the
developer:  three lines of code in main() and in each thread procedure you
write, plus a few lines in your makefile to generate the .sym or .xqs files
you'll distribute with non-debug versions of your app.

To be effective and provide maximum coverage, Exceptq must be installed on
every thread your program creates.  This should be the first thing your
program does in main() and in each thread procedure (see the example below).
You must also uninstall Exceptq immediately before exiting main() and each
threadproc.  Failure to do so will cause an exception (check popuplog.os2).

If your program provides its own exception handler, be sure to install it
after Exceptq and uninstall it before Exceptq to avoid generating reports
for traps your code has handled.

Although you can link directly to exceptq.dll at build-time, we recommend
that you load it dynamically instead.  This ensures your app will run if
the dll isn't present or some conflict arises that requires its removal.
Exceptq.h contains a sample procedure, LoadExceptq(), that you can copy
or #include into your code to handle this task.

Exceptq v7.x introduces a new function, InstallExceptq(), to set the
exception handler.  While you could set the handler yourself, the function
offers two benefits:  it lets you set v7.x's new options, and it acts as
a version check that ensures you're getting the capabilities v7.x offers.
v7.x also introduces a macro, UninstallExceptq() to unset the handler.

_______________________________________________________________________________

  Exceptq v7.1 Options
_______________________________________________________________________________

Exceptq v7.1 offers options that control how verbose its report should be,
whether it should beep when it generates a report, and whether it should
generate debugging reports or any report at all.

Options can be set by the program when calling InstallExceptq(), or by
the 'EXCEPTQ' environment variable.  Options set in the environment always
override conflicting options set by the program.  In either case, the format
is the same:  a string of letters representing the options.  For example,
both 'InstallExceptq(pExRegRec, "vq", "")' and 'SET EXCEPTQ=VQ' produce the
same result.  To use the default options, pass a null string or a null pointer
to InstallExceptq().

Note:  we recommend that your program use the default options and that you
have your user change them via the environment variable when necessary.

Verbosity
---------
This primarily controls how much raw data is dumped into the report.  For
a complex app like Firefox, the default setting produces a 30-50kb report.
For a simpler app, it may be only 10-15kb.

  TT    "terribly terse"
  T     "terse"
  C     "concise" [default]
  V     "verbose"
  VV    "very verbose"

Beeps
-----
By default, Exceptq emits a pleasant-sounding two-tone beep which reminds
your users that there's an exception report they can send you.

  B     "beep" [default]
  Q     "quiet"

Generate Debugging Reports
--------------------------
Because EXCEPTQ_DEBUG_EXCEPTION can create a lot of unwanted output, it is
disabled by default.  Use this option in the environment to enable it when
needed.

  D     "debug and fatal exceptions"
  F     "fatal exceptions only" [default]

Generate Report
---------------
This can be used in a particular program's environment to disable Exceptq
for that app while leaving it available for other apps.  It may be needed
if there is a conflict between Exceptq and an app, or if the app is so
unstable that the reports are more of an annoyance than a help.

  Y     "yes" [default]
  N     "no"

Info String
-----------
This option is used by your program to tell Exceptq that the 3rd argument to
InstallExceptq() is an informational string to be printed at the top of the
report.  It is needed to maintain compatibility with Exceptq v7.0 which did
not support this feature.  It has no meaning if set in the environment.

  I     "info string is present"

_______________________________________________________________________________

  Miscellanea
_______________________________________________________________________________

* Additional documentation can be found in 'exceptq.h'.

* To generate .xqs files, use 'mapxqs.exe' which is included in the Exceptq
  developers' package.  MapXQS is compatible with mapfiles produced by IBM,
  GCC, OpenWatcom, and Borland linkers.  By default, it demangles C++ symbols
  created by GCC;  use its 'V' option to demangle symbols created by VACPP.

* To generate .sym files use 'mapsym.exe' which is included with the Warp
  Developer's Toolkit.  It may issue warnings that a segment is over 64k
  but you can ignore them.  Mapsym is compatible with mapfiles created by
  IBM and GCC linkers.

* Mapfiles generated by the OpenWatcom linker ('wl.exe') are not directly
  compatible with mapsym.  Use the scripts 'wat2map.cmd' or 'mapsymw.pl'
  by Steven Levine to convert them and generate your .sym files.

* While you are welcome to include exceptq.dll and distorm.dll with your
  app, it would probably be better to encourage your users to download
  it separately from hobbes and put it in a directory on their LIBPATH.

* If you recompile Exceptq to customize it for your app, please give
  your dll a different name so it doesn't conflict with the standard
  version.  If you have any changes that would improve Exceptq's
  performance or usefulness, please send them to:
    Rich Walsh <rich@e-vertise.com>
  or
    Steven Levine <steve53@earthlink.net>

_______________________________________________________________________________

  Sample Code
_______________________________________________________________________________

This sample code demonstrates how little effort is required to add
Exceptq v7.1 to a program.  The lines that start with a '+' are the
only ones you'll need to add.  First, some programming considerations:

 - The EXCEPTIONREGISTRATIONRECORD *must* be on the stack.
 - Exceptq should be installed as early as possible on each thread.
 - Exceptq must be uninstalled before terminating a thread, including
   cases where you make an early return (as in MyThreadProc() below).
 - You don't have to write code to load exceptq.dll or install its
   handler.  Just copy the function LoadExceptq() from exceptq.h into
   your source code or '#define INCL_LOADEXCEPTQ' to #include it.
 - To use Exceptq's default options, pass a null string or null ptr.
 - To include a version string in the report, use the 'I' option and
   pass a string of less than 80 characters to LoadExceptq().

  ...
  #include <string.h>
  #include <os2.h>
+ #define INCL_LOADEXCEPTQ
+ #include "exceptq.h"
  ...
  int main(int argc, char** argv)
  {
+   EXCEPTIONREGISTRATIONRECORD exRegRec;
    int foo;
    char* bar;
  
+   LoadExceptq(&exRegRec, "I", "MyApp v1.0.2");
    ...
    DoStuff(foo, bar);
    ...
+   UninstallExceptq(&exRegRec);
    return 0;
  }
  
  void MyThreadProc(void *arg)
  {
+   EXCEPTIONREGISTRATIONRECORD exRegRec;
    int baz;
  
+   LoadExceptq(&exRegRec, NULL, NULL);
    ...
    if (DoSomething(baz) == FALSE) {
+     UninstallExceptq(&exRegRec);
      return;
    }
    ...
+   UninstallExceptq(&exRegRec);
    return;
  }

_______________________________________________________________________________

  Files
_______________________________________________________________________________

The developers' distribution (exceptq71-dev.zip) contains the following files:

  exceptq.dll         the exception handler dll
  exceptq.xqs         exceptq's public symbols
  exceptq.h           exceptq's public header
  exceptq.txt         this readme file
  exceptq-src.zip     source code for Exceptq v7.1
  distorm.dll         the disassember used by exceptq
  distorm.xqs         distorm's public symbols
  mapxqs.exe          used to create XQS files
  mapxqs.xqs          mapxqs's public symbols
  mapxqs-src.zip      source code for MapXQS v1.0
  legacy.zip          source & examples from previous versions
  006C_01.TRP         a sample report generated using .xqs files

There is also a users' distribution (exceptq71.zip) with just these files:

  exceptq.dll         the exception handler dll
  exceptq.xqs         exceptq's public symbols
  distorm.dll         the disassember used by exceptq
  readme.exceptq      a user-level readme

_______________________________________________________________________________

Rich Walsh <rich@e-vertise.com>
March 1, 2011
_______________________________________________________________________________

