


	Version 2.05 Gold © 2005 by CapeSoft Software (Pty) Ltd www.capesoft.com Updated 27 September 2005

Products Required for GPFReporter
		HyperActive
		WinEvent

Contents

	Introduction
	Features
	Support
	Installation
	Adding GPFReporter to your Application
	Options for the GPFReporter template
	Properties for the GPFRep class
	Methods for the GPFRep class
	Distribution
	Examples
	Tips & FAQ
	License & Copyright
	Version History

Introduction

The CapeSoft GPFReporter allows you to trap program "illegal operations" and offers the user the opportunity to email a short report to the developer detailing the illegal operation.

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

Features

Simple to add to your program (literally takes 10 seconds or less)
Identifies the line number in your application source code where the illegal operation occurred.
Reveals the chain of procedure calls which preceded the illegal operation.

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	support@capesoft.com
	Telephone	+27 21 715 4000
	Fax	+27 21 715 2535
	Post	PO Box 511, Plumstead, 7801, Cape Town, South Africa

GPFReporter is available for purchase at $149 from:

CapeSoft Sales
	Web	www.capesoft.com
	Email	sales@capesoft.com
	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

Installation

1. Run the supplied installation file.

Adding GPFReporter to your Application

Adding GPFReporter to your Application is easy.

1.	While the App is Open go to the Global Extensions. Click on Insert.
2.	Select Activate CapeSoft's GPF Reporter from the Class CapeSoftGPF.
3.	Fill in the email address(es) to which you would like GPF reports sent.
4.	Fill in your program title. This will appear on the GPF messagebox title bar.
5.	Give your program a version number. This is so that you can identify which version of your program has the problem.
6.	Select Activate CapeSoft's HyperActive from the Class HyperActive. (Only if not already Active)
7.	Select Enable the WinEvent functions in your app from the Class WinEvent. (Only if not already Active)
8.	Close and save the window.

NOTE : For multi-DLL applications only add GPFReporter to the main (EXE). See FAQ for more info.

Options for the GPFReporter Template

General Tab

Disable all CapeSoft GPF Reported features : This option is used to remove all GPFReporter code from this application. Useful for debugging template clashes etc.

Settings Tab

Email GPF Report to : Provide an email address to which the GPF report is to be emailed. Use the format "Name <actual email address>".
GPF Window Title : Text to appear on the GPF messagebox title bar.
Use resource version : The version number from the resource info is used as the version number.
This Program Version : Give your program a version number. This is so that you can identify which version of your program has the problem.
You may use 'quotes' to provide a string constant or you may use an equate or variable name.
NOTE : If you use a variable then it should be set before the GPF Reporter comes into scope. (Setting the initial value works).
GPF Logfile Name : Defaults to "ApplicationName GPF report.txt". This log file is handy where the client does not have email installed.
Append to Log File : Defaults to over-write. If this flag is set then the report is appended to the end of the log file.
Email Options - Default : Where the GPF report text is too long to be passed to the email client as one block then the report text is copied to the clipboard and the mail client is called with the following text in the body.

Edit|Paste the report here (CTL+V) or attach the logfile.
\\MyMachineName\Clarion 6\3rdParty\examples\GPFRep\GPFDemo GPF report.txt
[END]
Email Options - Split Email if too long : Where the GPF report text is too long to be passed to the email client as one block then the report is split into parts and sent as multiple eMails.
Email Options - Always use Paste Method : The the GPF report text is always copied to the clipboard and the mail client is called with the following text in the body as above.
Messagebox Options - Details Only (Skip first messagebox) : When set the first message "This program...." is skipped and the details message is displayed.
Messagebox Options - Email only (no messagebox) : When set both message box windows are skipped and the report is eMailed without user input.
Messagebox Options - Close Quietly (no messagebox) : When set both message box windows are skipped program is terminated without user input.
Restart Program : Defaults FALSE. When set the application is restarted. The message is modified to say "restarted" instead of "terminated".
Close Quietly on Exit : Defaults FALSE. When set then the "Close Quietly" option is enabled during program exit. This can be used to mask exit problems.
Show Stack Details : Defaults FALSE. When set then the registers and a full stack dump is included in the report.

Advanced Tab

Debug eMail (Make "AppName DebugEmail.txt") : Defaults FALSE. When set then the email text is logged to "ApplicationName DebugEmail.txt"
Debug GPF Reporter (Make "AppName DebugLog.txt") : Defaults FALSE. When set then the GPF Reporter progress logged to "ApplicationName DebugEmail.txt"

Class Tab

Object Name : Provide a name for this instance of the GPFReporter object. The default name is "ThisGPF".
Base Class : Select which base class to use. The default base class is "GPFReporterClass".

GPFRep Class Properties

CloseQuietly (byte) : When set then the exception handler terminates the process without any message. This is useful for services which can be restarted without first closing the exception message window. The Report is still sent to the GPF dumpfile.

Disable (byte) : When set this disables the GPF Reporter exception handler. Exceptions will go the the default windows exception handler.

DumpFileName (string) : A copy of the exception report text is placed in this file. The GPF Report text overwrites this file (unless DumpFileAppend is set).

ReportText : This string is appended to the bottom of the GPF Report. This is intended for use with the ExtraReportText method (below).
Embedded CR/LF ('<13,10>') will format the text on multiple lines.

TextForMessage1 : Default= 'This program has performed an illegal operation and will now end.'
TextForMessage2 : Default= 'This program has performed an illegal operation and will now end.'
TextForOKButton : Default= 'OK'
TextForDetailsButton : Default= '&Details'
TextForEmailButton : Default= '&Email Report'
TextForPasteInstructions : Default= 'Edit|Paste the report here (CTL+V) or attach the logfile.'
TextForProgram : Default= 'Program'
TextForVersion : Default= 'Version'
TextForTime : Default= 'At'
TextForDate : Default= 'on'
DateFormat : Default= '@d10'
TextForReportedError : Default= 'Reported error'
TextForAccessViolation : Default= 'EXCEPTION_ACCESS_VIOLATION'
TextForErrorReadingData : Default= 'Error reading data at'
TextForErrorWritingData : Default= 'Error writing data at'
TextForOS : Default= 'Windows'
TextForClarion : Default= 'Clarion'
TextForThread : Default= 'Thread'
TextForErrorAtAddress : Default= 'Error at address'
TextForStackTrace : Default= 'Stack Trace'
TextForStackDump : Default= 'Stack Dump'
TextForDLLMissing : Default= 'Please copy DBGHELP.DLL into the application directory.<13,10>This will enable GPF Reporter to provide more information (Win98/NT only).'
TextForStackCorrupt : Default= '*** Error Stack corrupt ***'
TextForStackTraceStopped : Default= 'Stack Trace stopped, too many levels'
TextForEnd : Default= 'END'
TextForPart : Default= 'PART'
TextForLine : Default= 'Line'
TextForProc : Default= 'Proc'
TextForSrc : Default= 'Src'
TextForModule : Default= 'Module'
TextForDebugInfoNotFound : Default= 'no debug info'
TextForModuleNotFound : Default= 'no module'
TextForLineNotFound : Default= 'no line number'
TextForPleaseWait : Default= 'Please wait, reading debug information'
TextForPleaseWait2 : Default= 'Please wait, loading email program'
TextForField : Default= 'Field'
TextForEvent : Default= 'Event'
TextForKeycode : Default= 'Keycode'
TextForTopWindow : Default= 'Top Window'
TextForTruncated : Default= '***Truncated***'
TextForNoProc : Default= 'no proc'

GPFRep Class Methods

DeleteDumpFile : This method deletes the current GPF report log file. This may be useful if appending to dumpfile is selected.

ExtraReportText : This method is called after the program has performed an exception.
You may provide extra debugging info in the GPF Report by setting the ReportText property here. Example:

self.ReportText = 'User=' & clip(CurrentUser) & '<13,10>This text is on a new line.'

Please note that there are some limitations on code that may be executed from inside an exception handler (here).
1) You may not use NEW (allocate memory).
2) You may not execute code that will generate an exception (such as calling OutputDebugString without a debugger present).

Distribution

For Win95, Win98 and WinNT the redistributable DBGHELP.DLL is used to create the stack trace.
Please place this DLL in the application directory (not the windows directory).
You will find a copy in your \clarion X\3rdParty\bin directory.

Examples

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

Tips & FAQ

Clarion Versions : GPFReporter is available for Clarion 5, 5.5 and 6. There is no upgrade charge. However you will need the correct version to match the version of Clarion that you are using. Download the correct version from www.capesoft.com .

My application gives me an "index out of range" error. How do I locate the error line?
My application is a large multi DLL application, do I have to enable debugging and recompile all the DLL's.
How do I add GPFReporter to a multi-DLL application.
The GPF Report says that the error occurred on a line past the end of my source. Why.
How do I interperet the Stack Trace?
The GPF Reporter says that the exception occurred at address : XXXXXXXXh no module. What does this mean?
The GPF Report Stack Trace is empty. Why?
Which exceptions are handled by the GPF Reporter?
The GPF Reporter reports that the exception occurred in the "Library state". What does this mean?
My stack trace shows lines prefixed with ???. What does this signify.
My GPF report contains the expression "Line ?=XXXX" Is the GPF Reporter unsure?
Will using "min" or "full" debug settings slow my program load / execution time?
I am using Armadillo and now the GPF Reporter no longer works. Is there a work around?
I am using Eudora and GPF Reports containing & or ? do not eMail correctly. What can I do?
I know there was a GPF but the GPF reporter never executed.
I get the " Assertion failed on line: 303 in file abfile.clw. Message: You are calling CLOSE(thefile) instead of FileManager.close().
When we try to run your demo, instead of Outlook client opening up, we have 32 web pages pop up with the following URL:
mailto:Jim%20<jim_zetterberg@simonton.com>...etc

FAQ 1	My application gives me an "index out of range" error. How do I locate the error line? Answer: If you enable array index range checking (project property) then the range checker will ask "Do you want to GPF?" If you select "Yes" then the GPFReporter will report that your application GPF'd in the clarion runtime (range checker). The actual line where the error occurred is lost however the stack trace shows where that procedure was called from. This usually narrows your search down to one procedure.
FAQ 2	My application is a large multi DLL application, do I have to enable debugging and recompile all the DLL's. Answer: No, the GPFReporter will identify the module in which the GPF occurred and only that module need be recompiled with the "Debug Information" mode set to FULL or MIN (not OFF). This will provide the source module line number where the GPF occurred.
FAQ 3	How do I add GPFReporter to a multi-DLL application. Answer: The GPFReporter should only be added to the EXE. The GPFReporter is installed as the default exception handler and will work for all threads including DLL calls.
FAQ 4	The GPF Report says that the error occurred on a line past the end of my source. Why. Answer: The GPF Reporter line numbers are for the CLW modules, not the embedded source. In the clarion IDE right-click and select MODULE not SOURCE.
FAQ 5	How do I interperet the Stack Trace? Answer: The Stack trace is "upside down". The most recently used procedures are at the top. The "main" should be at the bottom unless this exception occurred on closing the application.
FAQ 6	The GPF Reporter says that the exception occurred at address : XXXXXXXXh no module. What does this mean? Answer: This means that the program is executing outside of the code space of any of its modules. This can happen when your program calls an invalid procedure pointer.
FAQ 7	The GPF Report Stack Trace is empty. Why? Answer: Possibly your program has caused an exception while loading or exiting the clarion runtime code. This is unlikely. Usually what has happened is that the program has trashed the return stack and so the Stack Trace is garbage. A very common programming error that results in a trashed stack is to use string slicing with reversed position numbers. Example : IF SomeString[6 : 3] = 'ABC' .... Unfortunately the debug "array range checking" tests that the positions fall in the string but fails to test for illegal position numbers.
FAQ 8	Which exceptions are handled by the GPF Reporter? Answer: Any exception that would usually end your application with the windows exception handler. The following are defined: EXCEPTION_ACCESS_VIOLATION (0C0000005h) EXCEPTION_DATATYPE_MISALIGNMENT (080000002h) EXCEPTION_BREAKPOINT (080000003h) EXCEPTION_SINGLE_STEP (080000004h) EXCEPTION_ARRAY_BOUNDS_EXCEEDED (0C000008Ch) EXCEPTION_FLT_DENORMAL_OPERAND (0C000008Dh) EXCEPTION_FLT_DIVIDE_BY_ZERO (0C000008Eh) EXCEPTION_FLT_INEXACT_RESULT (0C000008Fh) EXCEPTION_FLT_INVALID_OPERATION (0C0000090h) EXCEPTION_FLT_OVERFLOW (0C0000091h) EXCEPTION_FLT_STACK_CHECK (0C0000092h) EXCEPTION_FLT_UNDERFLOW (0C0000093h) EXCEPTION_INT_DIVIDE_BY_ZERO (0C0000094h) EXCEPTION_INT_OVERFLOW (0C0000095h) EXCEPTION_PRIV_INSTRUCTION (0C0000096h) EXCEPTION_IN_PAGE_ERROR (0C0000006h) EXCEPTION_ILLEGAL_INSTRUCTION (0C000001Dh) EXCEPTION_NONCONTINUABLE_EXCEPTION (0C0000025h) EXCEPTION_STACK_OVERFLOW (0C00000FDh) EXCEPTION_INVALID_DISPOSITION (0C0000026h) EXCEPTION_GUARD_PAGE (080000001h) EXCEPTION_INVALID_HANDLE (0C0000008h)
FAQ 9	The GPF Reporter reports that the exception occurred in the "Library state". What does this mean? Answer: "Library state" is the label given by the clarion compiler to code inside the clarion RTL (C60RUNX.DLL) or LIB. This is where most exceptions occur (as your program code is a series of calls to clarion functions). Before you send a bug report to SV please read on. You need to locate where in YOUR code you called this clarion library code from. Once you have established where your code called the library then you must find the reason for the exception (usually something done, not done or done too soon). The stack trace is there to show you where in YOUR code the clarion library was called from. See FAQ 5 & 7.
FAQ 10	My stack trace shows lines prefixed with ???. What does this signify. Answer: These are addresses on the stack which might be part of the calling chain. If a procedure makes a call to another procedure then it may (optionally) push the EBP ("Stack Frame Pointer") onto the stack and then copy the ESP ("Stack Pointer") over the EBP. This allows us to "walk" back down the stack using the pushed EBP / EIP ("return address") pairs. If the called procedure does not push the EBP and then calls a 3rd procedure which does push the EBP then it appears, from the stack trace, that the first procedure called the 3rd procedure. The second is "lost".
FAQ 11	My GPF report contains the expression "Line ?=XXXX" Is the GPF Reporter unsure? Answer: Yes. This occurs where "min" debug info is compiled into the program / DLL. If possible compile the module with "full" debug info. The GPF Reporter can then verify the ?= line numbers.
FAQ 12	Will using "min" or "full" debug settings slow my program load / execution time? Answer: Yes the program will take longer to load and will execute more code. However the change is usually not noticable. Please note that although the EXE / DLL might increase in size by a large amount (often from 1mByte to 10mBytes) this does not affect the load / execution speed. The debug info added to the EXE / DLL file is not loaded into program memory. The program is however not optimized by the compiler in debug mode and index range checking etc adds extra code which accounts for the slower load / execution times.
FAQ 13	I am using Armadillo and now the GPF Reporter no longer works. Is there a work around? Answer: Yes. In the Armadillo options you will need to set the "Data after program" option to "Fake original data location". This is only available in the Armadillo Professional edition. The GPF Reporter then works correctly.
FAQ 14	I am using Eudora and GPF Reports containing & or ? do not eMail correctly. What can I do? Answer: Select the "Always use Paste Method" Email option.
FAQ 15	I know there was a GPF but the GPF reporter never executed. Answer: Uncheck the "Enable Wait Window" option. Often after a GPF the clarion runtime library (in memory) is not able to open the wait window. The GPF Reporter then GPF's while opening this window and as it is installed as the GPF handler.... If the above does not resolve the problem then try setting the "close quietly" option. Look in the GPF Report Log for the report.
FAQ 16	I've added GPF Reporter to my program. This requires that debugging be switched on. Now I get the " Assertion failed on line: 303 in file abfile.clw. Message: You are calling CLOSE(thefile) instead of FileManager.close(). Shall I GPF?" error! How can GPF Reporter and FM3 co-exist? Answer: GPF Reporter Clarion's Debug mode to be switched on. As most of you know, ABC has an over sensitive assert warning when you've used a legacy close() instead on an Access:File.close() (see GQxx for more info). The only way to allow FM2/3 and GPF Reporter to co-exist in an application is to comment our the assert in your abfile.clw in your Clarion\libsrc directory.
FAQ 17	When we try to run your demo, instead of Outlook client opening up, we have 32 web pages pop up with the following URL: mailto:Jim%20<jim_zetterberg@simonton.com>...etc Answer: Have you just changed mail servers GroupWise to Exchange - and maybe the client install didn't go as smoothly as it should have? Solution: In the IE browser, go to Tools, Internet Options, Programs Tab a. Changed E-mail from Microsoft Office Outlook to Outlook Express. b. Changed it back to Microsoft Office Outlook. Problem was solved.

License & Copyright

You are not allowed to copy any of the files, including but not limited to, csGPF.tpl, csGPF.tpw, csGPF.clw, csGPF.inc and documentation files.

None of the included files may be distributed. Your programs which use GPFReporter can be distributed without any GPFReporter royalties.

Each developer needs his own license to use GPFReporter. (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 2.05 Gold: (12 January 2006)

1)	Removed Help buttons from the template.

Version 2.04 Gold: (27 September 2005)

1)	Added check for GPF after runtime message "Do you want to GPF?"
2)	Added Enable "Wait Window" option. See FAQ 15. This defaults to OFF as this is our recomendation.
3)	Modified to work nicely with SelfService. (Thank you Jono)
4)	Removed window title from report - sometimes causes GPF in the GPF Reporter.

Version 2.03 Gold: (18 January 2005)

1)	Fixed bug in 2.01 / 2.02 where Armadillo detected code always returned "no debug info"

Version 2.02 Gold: (13 January 2005)

1)	Modified "Close quietly on Exit" to disable "Restart application".
2)	Fixed bug in 2.01 template where template variables were missing.

Version 2.01 Gold: (12 January 2005)

1)	Added a new option to force eMail Paste Method. See Options. NB The old "Split eMails if report too long" selection is lost so please re-select as required.
2)	Added a line break between reports while appending to log file.
3)	Added GPFRepBuild and GPFRep:Version equates to the csGPF.TPL template. These can be used to test the GPF Reporter version.
4)	Added a few more FAQ's See FAQ .

Version 2.00 Gold: (4 January 2005)

1)	Fixed bug where & in the Window title truncated the email report.
2)	Hid the progress counter from the "Please wait loading eMail" window.

Version 1.14 Beta: (10 December 2004)

1)	Changed options to use radio buttons. See Options. NB The old "Skip first messagebox" selection is lost so please re-select as required.
2)	Fixed bug where long reports overflowed the string buffers and were truncated.
3)	Fixed bug where "min" debug info did not report line numbers. See FAQ 10 for more info.
4)	Fixed bug where locating the debug info sometimes cause a GPF in GPF Reporter (non WinXP)
5)	Added FAQ 10 & 11
6)	Modified the "Program Restart" procedure to use ShellExecute for faster restarting.
7)	Added various options to suppress the messagebox. See Options
8)	Fixed bug where email under Win2003 were split into very small blocks. Requires WinEvent 3.27

Version 1.13 Beta: (3 December 2004)

1)	Fixed bug introduced in 1.12 where no open window causes the GPF Reporter to GPF on an exception. Please don't laugh....
2)	Added "Debug eMail" option. See Options.

Version 1.12 Beta: (2 December 2004)

1)	Added a "Please wait loading eMail" window.
2)	Now needs WinEvent 3.25, modified ds_GetVersionInfo().
3)	Added the procedure name to the reported details. Included tabs between items to improve readability.
4)	Fixed bug where code in between procedures (in procs with no debug info) was reported as last line of preceeding procedure.
5)	Added a Show Stack details option. See Options.
6)	Fixed bug in "New class properties" where the string size was not generated.
7)	The Stack Trace now shows other possible calls - prefixed with ???
8)	Added Field(), Event(), Keycode() and Current window title to the report.

Version 1.11 Beta: (4 November 2004)

1)	Added option to restart program. See Options.
2)	Added the display of the resource version number of called DLL's onto the DLL name in the stack trace.
3)	Added a "Please wait loading.." window, opens while debug info is read from the files.

Version 1.10 Beta: (2 November 2004)

1)	Fixed regression where SkipInitalMessage was ignored.
2)	Added option to use the resource version number as the version number. See Options. (Needs WinEvent 3.23)
3)	Added properties for all text. This is to allow for language translation. See Properties

Version 1.09 Beta: (1 November 2004)

1)	Fixed bug where & in the filename truncated the email report.
2)	Added property DumpFileAppend. Sets append mode for writing to the Log file. See Options (Needs WinEvent 3.22)
3)	Modified the template to allow for a variable to be used as the version number. See Options
4)	Added method DeleteDumpFile. This methods deletes the current dumpfile. See Methods
5)	Removed the "Try continue" button. (Popular demand.)
6)	Documented the ReportText and ExtraReportText method / property. See Methods & Properties
7)	Replaced FAQ 9.
8)	Fixed bug where " was encoded as (. Thank you Jim.
9)	Upgraded to the new super cool CapeSoft look.
10)	Added help button to the template

Version 1.08 Beta: (11 October 2004)

1)	Fixed bug where the email text was not compatible with outlook.
2)	Added property SkipInitalMessage. Skip first message, display details message. See Options

Version 1.07 Beta: (7 October 2004)

1)	Fixed bug where GPF Reporter required WinEvent version 3.22. Should be WinEvent 3.21.
2)	Added the Thread number to the report.

Version 1.06 Beta: (6 October 2004)

1)	Modified the template to generate a warning where a old (non-compatible) version of WinEvent is installed.
2)	Fixed bug where the GPF Report log file was not generated when the "email" button was pressed.
3)	Fixed bug where a corrupted stack caused the GPF Reporter to stop with some debug info.

Version 1.05 Beta: (4 October 2004)

1)	Modified the template to generate a warning where the GPF Reporter is added to a non EXE.
2)	Removed the _GPFRep_ project define as only needed for DLL objects.

Version 1.04 Beta: (30 September 2004)

1)	Extended GPFReporter to support Win95.
2)	Fixed bug where WinNT split eMail reports where corrupted.
3)	Made the splitting of eMails into parts optional. See Options
4)	Added a GPF logfile. See Options
5)	Added some GPFRep class properties. See GPFRepClassProperties
6)	Added lots of FAQ's. See Tips
7)	Added support for multi-proj (another fine CapeSoft product).

Version 1.03 Beta: (20 September 2004)

1)	Extended GPFReporter to support Win98, WinNT and newer versions of windows.
2)	DBGHELP.DLL needed for stack trace under Win98 & WinNT. Should be in the application directory.

Version 1.02 Beta: (13 September 2004)

Version 1.01 Beta: (8 September 2004)

Version 1.00 Beta: (11 August 2004)

[End of document]

meatloaf@capesoft.com