ExceptQ

Thu Feb 23 18:42:06 2023 Steven H. Levine <steve53@earthlink.net> * exceptq.dll v7.11.6.1-shl Dump Exception Registration Record Chain

_______________________________________________________________________________ _______________________________________________________________________________ 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 _______________________________________________________________________________