This is exception filter dialog which is used to add or edit exception filters.

Dialog consists of two pages:

•	Exception Identification page contains filter options which are used to find matched exception.

•	Altering Behavior page contains filter options which alters exceptions. These options are applied to exception altering its properties and/or behavior. Options are applied only for matched filter.

Exception Identification

Exception Identification page

Exception Identification page contains filter options which are used to find matched exception. When exception occurs:

1.	EurekaLog walks through all available exception filters.

2.	Each filter is compared against current exception.

3.	If current exception matches "identification" properties of exception filter - search is over and filter is applied to (current/outer) exception.

Available options are:

1. "Exception Class" option specifies exception class name. This is mandatory option. Filter will be applied only for exceptions of the specified class. You can pick predefined classes from combo-box (such as EAbort or EAccessViolation) or enter your own classes (such as EMyException). If you want to catch all exceptions - specify "Exception" class. See also "Include child classes" option below.

Important Notes:

•	You can not use exception filters to alter behavior for leaks (e.g. EMemoryLeak/EResourceLeak), because exception filters are already finalized when leaks checking is running. See also.

•	Your exception classes must be real classes. You can not use aliases. For example:

type
EMyException1 = class(Exception);
EMyException2 = Exception;

You can specify 'EMyException1' as exception class name. However, 'EMyException2' will not work. Because there is no such class: it is an alias. You should use 'Exception' instead.

2. "Include child classes" option alters behavior of "Exception Class" option.

Checked: match specified class name and any descendant classes. For example, 'Exception' class will match any exception.

Unchecked: match exact class name only. For example, 'Exception' class will match only raise Exception.Create('...') constructs.

3. "Use inner exception" option alters behavior of "Exception Class" option. By default, filter checks the current exception:

try

// inner exception
raise EAccessViolation.Create('...');
except

// current (outer) exception
raise EFileError.CreateFmt('Unable to load document %s', [AFileName]);
end;

By checking this option you will ask EurekaLog to check base (e.g. innermost) exception instead.

This option has no effect if there are no chained exceptions - which is a typical case.

Note: this option affects only matching/identification aspect of the filter. Behavior modifications (see below) will still be applied to current (outermost) exception.

4. "Exception Kind" option specifies whenever this filter will be applicable to unhandled exceptions, handled exceptions, SafeCall exceptions or all of them. This is mandatory option.

Tip: Filter is applicable for all exceptions by default. Different processing for handled and unhandled exceptions may be confusing, so it's recommended to avoid it when possible.

Notes:

•	This option is ignored if your application do not process handled or SafeCall exceptions.

•	SafeCall exceptions are considered to be handled exceptions. "Handled" value will catch any kind of handled exception - regardless of it being SafeCall exception. "SafeCall" value will catch only SafeCall exceptions, but no other handled exceptions.

5. "Exception Handler" option specifies exception hook that had caught the exception. For example, you can use this option to separate exceptions from background threads, or separate exceptions from DLLs.

If you are handling exceptions manually - you can specify handler as third argument to EBase.HandleException function. For example:

Thread.WaitFor;
if Assigned(Thread.FatalException) then

begin
HandleException(Thread.FatalException, False, atThread { atXYZ constant from ETypes } );

Abort;

end;

See also: how to handle exception.

6. "Exception Message" option specifies exception message to match. The "Exact match" sub-option indicates how EurekaLog should match exception message:

•	If "Exact match" option is checked: Filter.Message = Exception.Message;

•	If "Exact match" option is unchecked: Pos(Filter.Message, Exception.Message) > 0;

Important Notes:

•	We do not recommend to use this option, because exception messages may change due to localization. Never use this option to filter exceptions coming from operating system (such as EOSError).

•	When using "Exact match": pay close attention to the last character in the exception message. Exception messages typically do not include trailing full stop (period) symbol (e.g. '.'). Full stop / period is usually added by dialogs.

7. "Exception Module Name" option specifies name of file for executable module. Such as 'Project1.exe' or 'BugDLL.dll'. This option is optional. Filter will be applied only to exceptions raised from the specified module.

Notes:

•	You must specify file name only without any file path.

•	Module name comparison follows case sensitivity of host OS.

•	This option uses ExceptionAddress property to determine module name.

•	This option does not require debug information to work.

8. "Exception Unit Name" option specifies unit name. Such as 'SysUtils', 'Unit1', 'Project1', etc. This option is optional. Filter will be applied only to exceptions raised from the specified unit.

Notes:

•	This option uses ExceptionAddress property to determine unit name.

•	This option requires debug information to work.

9. "Source Class Name" option specifies class name. Such as 'TFileStream', 'TForm1', etc. This option is optional. Filter will be applied only to exception raised by methods of the specified class.

Notes:

•	This option uses ExceptionAddress property to determine class name.

•	This option requires debug information to work.

10. "Procedure/Method Name" option specifies function or method name. Such as 'Create', 'Destroy', 'Read', 'Button1Click', etc. This option is optional. Filter will be applied only to exceptions raised by specified method or function.

Notes:

•	This option uses ExceptionAddress property to determine function/procedure/method name.

•	This option requires debug information to work.

11. "Exception Properties" option specifies set of properties to match. This option is optional. Filter will be applied to exceptions which have specified properties with exact the same values.

•	Properties should be entered as: one property on single line.

•	Each line must have "name=value" form (as indicated on the screenshot above).

•	String values must be enclosed in double quotes.

•	Use \q to insert double-quote inside string value.

•	Enumerated types must be entered as integers.

Important Note: this option can only work with Delphi/C++ Builder exceptions with RTTI info available!

•	Standard exception classes usually do not have RTTI information available (RAD Studio 2009 and lower), therefore you can filter properties only for custom exception classes with explicitly enabled RTTI information in RAD Studio 2009 and earlier.

•	RAD Studio 2010 and higher provide extended RTTI information for standard classes, therefore you can filter properties of standard exceptions in RAD Studio 2010 and above.

Altering Behaviour

Altering Behavior page

Altering Behavior page contains filter options which alters exceptions. These options are applied to exception altering its properties and/or behavior. Options are applied only for matched filter.

Note: at least one of the options on this tab must be changed. Otherwise filter will do nothing.

Available options are:

1. "Set Handler to" option allow you to define who should handle exception:

•	"None" handler will ignore exception. I.e. exception will not be handled at all. This handler will not allow you to edit any additional options. This case is used for such exceptions as EAbort.

•	"RTL" handler will pass exception to default processing. This is the same as if EurekaLog would be disabled. This handler will not allow you to edit any additional options. This case is used for "expected" exceptions, which do not require bug report creation.

•	"EurekaLog" handler will pass exception to EurekaLog. This is default in EurekaLog-enabled application. This handler also allow you to specify additional options (see below). This is default and recommended case for most exception classes.

Tip: if you want to switch handler to "RTL" - consider using "expected" fields (see below) instead.

See also: expected exceptions.

Warning: be EXTRA careful when using the "RTL" handler in a multi-threaded application. For example, default exception handler in a VCL Forms application is a message box. The problem is that old IDE versions call this code "as is", e.g. without any synchronization. And since VCL is generally not thread-safe - you can safely show this dialog only in a main thread of your application. It means that you can't call this code from a background thread - without having thread synchronization issues. On the other hand, modern IDE versions do schedule this code to be executed in the main thread, so it can be called from a background thread. Moral of the story: study default RTL handler's code for your type of application. Learn if it can be called safely from a background thread. Avoid using RTL handler if it is not thread-safe.

2. "Override Exception Message" option allow you to override exception message. Leave this field empty to use original exception message. You can use this option to supply user-friendly error message (such as "Sorry, there was an error. Please, restart application") instead of low-level error message (such as "Access violation in module Project1.exe at address 123456"). This option affects only visual dialogs. Bug report will contain the original exception message. See also "Exception Message" option.

Note: you can use environment variables in this field, so you can also insert original exception message as part of your customized message (for example: "Sorry, there was an error. Please, restart application. Low-level error message: %_ExceptMsg%").

3. "Change Dialog to" option allow to change default dialog (as set in EurekaLog project options) to any available dialog class.

Tip: if you want to switch dialog to "RTL" or "MessageBox" - consider using "expected" fields (see below) instead.

See also: expected exceptions.

Warning: be EXTRA careful when using the "RTL" dialog in a multi-threaded application. For example, default exception handler in a VCL Forms application is a message box. The problem is that old IDE versions call this code "as is", e.g. without any synchronization. And since VCL is generally not thread-safe - you can safely show this dialog only in a main thread of your application. It means that you can't call this code from a background thread - without having thread synchronization issues. On the other hand, modern IDE versions do schedule this code to be executed in the main thread, so it can be called from a background thread. Moral of the story: study default RTL dialog's code for your type of application. Learn if it can be called safely from a background thread. Avoid using RTL dialog if it is not thread-safe.

Note: what is the difference between setting "handler" to "RTL" and "dialog" to "RTL"?

1.	Setting "handler" to "RTL" will disable EurekaLog for this exception. Exception will be handled by RTL only.

2.	Setting "dialog" to "RTL" will enable EurekaLog for this exception. Exception will be handled by both EurekaLog and RTL. It is not very useful in a typical VCL Forms app, but can be used in some application types. For example, RTL handler may feed error HTML page back to the client.

4. "Action after exception" option allow you to perform restart action after processing exception. This is useful for exceptions like access violation. You may want to terminate/restart your application after such exceptions to avoid induced exceptions.

5. "Expected Exception Context ID" option allow you to assign Context ID to exception. This is integer value which is expected to be ID of help topic describing exception.

Notes:

•	Setting this option to any positive value (or -1) will convert exception to an "expected" exception. Expected exception displays error dialogs, but does not generate bug reports. 0 (default) will not mark exception as "expected".

•	Set this property to a valid ID of help topic. If you do not have help topic for exception, but want to mark exception as "expected" - then set this option to -1.

•	Use either "Expected Exception Context ID" option or "Expected Exception URL" option, but not both.

•	Expected exception with valid Context ID (positive) or valid URL will cause "Help" button to be shown in error dialogs.

See also: expected exceptions.

6. "Expected Exception URL" option allow you to assign URL for the exception. This URL is expected to point to online help or Knowledge Base topic/article describing exception.

Notes:

•	Setting this option to any non-empty value will convert exception to an "expected" exception. Expected exception displays error dialogs, but does not generate bug reports.

•	Set this property to a valid URL of online help topic. If you do not have help topic for exception, but want to mark exception as "expected" - then use "Expected Exception Context ID" option and set it to -1, keep "Expected Exception URL" option empty.

•	Use either "Expected Exception Context ID" option or "Expected Exception URL" option, but not both.

•	Expected exception with valid Context ID (positive) or valid URL will cause "Help" button to be shown in error dialogs.

See also: expected exceptions.

7. "Exception BugID" option allow you to specify fixed BugID for this exception. If this value is 0 - BugID will be generated automatically. If this value is not 0 - automatic generation will be disabled. Specified BugID will be used.

Note: you can use both decimal (1234567890) and hexadecimal ($C7D40000) forms.

Warning: be extra careful when assigning this value. Your value may overlap with automatically generated BugIDs. Best strategy is to utilize user part of BugID (low word). See BugID for more info.

Root > Integral parts > Options > Advanced page > Exceptions filters page > Editing exception filter Editing exception filter

Editing exception filter

Exception Identification

Altering Behaviour