ErrHandler Help - Classes and Core Functions

Classes and Core Functions

The general-purpose ErrHandler programs reside in a class library and its supporting core functions. These programs make use of an include file of macro-defined constants, errhandl.h. There is also an accompanying demo application, described separately, but this is not required.

Classes

Class library errhandl.vcx contains classes that can be used by any application to support extended error handling features. The following ErrHandler classes are currently defined:

ErrHCustom
The ErrHandler foundation class based on VFP's Custom class. Subclass this to create a non-visual class with enhanced error handling.
- ErrHCustNoAbort
  Subclass of ErrHCustom that differs only by having its ehp_abortstopshere property set to .T. This class is provided as a convenience for creating passive objects whose only purpose is to receive error information via target indirection.
  - ErrHCustDiag
    Subclass of ErrHCustNoAbort that differs only by having its ehp_diagmode property set to .T. This is provided as a convenience for diagnostic purposes.
ErrHForm
The ErrHandler foundation class based on VFP's Form class. Subclass or base your form on this to create a form with enhanced error handling.
ErrHDiagDialog
The diagnostic message dialog class, used internally by errhshow.prg.

Each of the ErrHandler foundation classes shares a common set of custom properties and methods related to error handling, and identical logic for certain native VFP event methods (Error and Init). ErrHForm also has logic for the Activate, Deactivate, Refresh, and Unload events, which don't apply to Custom class objects.

Properties

The following custom properties are defined for all ErrHandler foundation classes.

ehp_aborted: Flag property indicating that this ErrHandler object should self-destruct because of a user Abort or abnormal error termination. This is always initialized to .F. and automatically set to .T. via the EHM_Abort method. This property is propagated under target indirection. The Destroy event can be customized to modify its usual cleanup logic when ehp_aborted indicates there was an abnormal termination.
ehp_abortstopshere: Flag property, used in errhcopy logic, indicating whether to suppress propagation of Aborts to this object. Leave this property set to .F. (the default) if you want this object to automatically self-destruct (via EHM_Abort) when a subordinate ErrHandler aborts. A "subordinate" ErrHandler is one that uses target indirection to return its error information directly into this object, so that methods of the subordinate object are symmetrical to those of the object itself with respect to error handling. On the other hand, set ehp_abortstopshere to .T. in a passive indirection target whose only purpose is to capture and retain error information (as in class ErrHCustNoAbort).
ehp_apperrcode: Property containing an application-specific error code, where 0 means no error. Additional generic VFP error info is placed into properties with names starting with "ehp_vfp". Normally this property is set via the EHM_ShowAppErr method, not by direct assignment. Error numbers should be unique within a given application (identified by ehp_apperrfrom), but these codes are not necessarily unique across different applications. (An include file of application-specific error codes and messages, like errhandl.h, is strongly recommended.)
ehp_apperrfrom: Property containing the application name from which the most recent error originated. This is automatically set to the value of ehp_appname when EHM_ShowAppErr is called, so it will normally be the same as that property. However, if another (nested) ErrHandler-based function uses target indirection to this (parent) object, the value of ehp_apperrfrom will be different. This allows a parent ErrHandler to distinguish easily between its own errors and those coming from sub-applications.
ehp_apperrmsg: Property containing an application-specific error message, if an error has been reported. This may or may not include additional context-specific details and/or generic VFP error info. Normally this property is set via the EHM_ShowAppErr method, not by direct assignment.
ehp_appname: Property containing the application name to be displayed in the messagebox window title or WAIT message prefix generated by method EHM_ShowAppErr. (If empty, use the method name last passed to the Error event.) Typically this would be initialized via the property sheet, and not subsequently altered. When an error is reported via EHM_ShowAppErr, the ehp_appname property is copied into the ehp_apperrfrom property, which is propagated along with other error details for target indirection.
ehp_diagforce: Flag property to force use of the diagnostic message dialog by EHM_ShowAppErr, even if quiet or non-interactive modes are in effect. This option is provided for convenience in the debugging of sub-applications. (Compare with ehp_diagmode, which doesn't override quiet and non-interactive modes.) This property can be toggled via a check box in the diagnostic message dialog. Automatically propagated by target indirection, i.e. it is initialized by copying the corresponding property from the ErrHandler specified by ehp_targobj.
ehp_diagmode: Flag property indicating that the diagnostic message dialog should be used for interactive messages generated by EHM_ShowAppErr. Unlike ehp_diagforce, this property will not force the use of the dialog if quiet or non-interactive modes are in effect. When ehp_diagmode = .T., the diagnostic message dialog is used instead of WAIT WINDOW or MESSAGEBOX( ) to display error and tracing messages. It is recommended that you turn this flag on (via property sheet) during development and testing of any ErrHandler application, so you will get the immediate benefit of its debugging features. This property can be toggled via a check box in the diagnostic message dialog. Automatically propagated by target indirection, i.e. it is initialized by copying the corresponding property from the ErrHandler specified by ehp_targobj.
ehp_diagresponse: Property for receiving the result of diagnostic message dialog invocations. This value is automatically set upon return from a call to EHM_ShowAppErr, indicating the user's reply (OK, Ignore, Retry, or Abort). If the diagnostic dialog was not used, this property will be set to the empty string, which means OK. (See include file errhandl.h for macro-defined codes, ERRH_DIAGRESP_...) This property is primarily intended for internal use.
ehp_echodebugout: Flag property indicating whether EHM_ShowAppErr should echo error and tracing messages to the VFP Debugger's output window, via DEBUGOUT. This property can be toggled via a check box in the diagnostic message dialog, but it requires the VFP Development System. Automatically propagated by target indirection, i.e. it is initialized by copying the corresponding property from the ErrHandler specified by ehp_targobj.
ehp_echologfile: Flag property indicating whether EHM_ShowAppErr should echo error and tracing messages to an ASCII text log file, whose path is specified by ehp_logfilepath. This property can be toggled via a check box in the diagnostic message dialog. Automatically propagated by target indirection, i.e. it is initialized by copying the corresponding property from the ErrHandler specified by ehp_targobj.
ehp_echoscreen: Flag property indicating whether EHM_ShowAppErr should echo error and tracing messages to the main VFP window, via ACTIVATE SCREEN and ? commands. This property can be toggled via a check box in the diagnostic message dialog. Automatically propagated by target indirection, i.e. it is initialized by copying the corresponding property from the ErrHandler specified by ehp_targobj.
ehp_ignore_noparam: Flag property indicating whether to ignore errors caused by passing too many arguments to a method or UDF. This covers VFP's Error # 1238, "No PARAMETER statement is found" and Error # 94, "Must specify additional parameters". These errors would otherwise require special-case handling for Ignore, Retry and Abort logic to work properly, so you may find it best to use this option. It's easy to perform explicit tests for too-many-argument errors via PARAMETERS( ), if such a check is really needed. Typically this would be initialized via the property sheet, and not subsequently altered.
ehp_interactive: Flag property indicating whether there should be a pause on error reporting, or it should be handled non-interactively (without pausing) in method EHM_ShowAppErr. Typically this would be initialized via the property sheet or subclassed Init logic, and not subsequently altered.
ehp_log_function: Property containing the name of an optional application-specific logging function, which should conform to the standard ErrHandler API that requires 4 arguments (like the first 4 arguments of errhshow) and returns success flag. If this property is non-empty, the specified logging function will be invoked upon every call to EHM_ShowAppErr, allowing the capture of detailed error information, tracing messages, and user replies to the diagnostic dialog in any sort of external, application-defined repository. Typically this would be initialized via the property sheet or subclassed Init logic, and not subsequently altered. Automatically propagated by target indirection, i.e. it is initialized by copying the corresponding property from the ErrHandler specified by ehp_targobj.
ehp_logfilepath: Property specifying the path of an ASCII text log file to which EHM_ShowAppErr should echo error and tracing messages if the echoing to the text log file is enabled (ehp_echologfile = .T.). Note that this ASCII text log file is entirely separate from any optional application-specific log file associated with the ehp_log_function property. This property can be set via controls in the diagnostic message dialog. Automatically propagated by target indirection, i.e. it is initialized by copying the corresponding property from the ErrHandler specified by ehp_targobj.
ehp_on_err_abort: Flag property used by the ON ERROR handler, errhoerr.prg, to determine whether to abort on abnormal errors. If this is .F. (the default), errors that trigger the ON ERROR handler will be reported, but the ErrHandler object will be given an opportunity to continue. Otherwise, if ehp_on_err_abort = .T., the ErrHandler object will self-destruct automatically (via EHM_Abort). Typically this would be initialized via the property sheet, and not subsequently altered. This property applies only when ehp_on_err_handle = .T. (Compare with the similar ehp_on_errx_abort property, which deals with errors that trigger the ErrHandler's Error event.)
ehp_on_err_handle: Flag property indicating whether this form should handle "abnormal" ON ERROR events via errhoerr( ) while the form is active. Related logic is in the Activate/Deactivate events, so this applies only to ErrHForm, not ErrHCustom class objects. This property makes it easy for a form to provide "catch-all" error handling for all of the controls contained in the form. Typically this would be initialized via the property sheet, and not subsequently altered.
ehp_on_err_prev: Property containing the previous ON ERROR handler, prior to activation of this form. Only used internally, if ehp_on_err_handle = .T.
ehp_on_errx_abort: Flag property used by the Error event handler, errherr.prg, to determine whether to abort on "exceptional" errors, i.e. those occurring in an ErrHandler method while ehp_traperrors = .F. If ehp_on_errx_abort = .F. (the default), such errors that trigger the ErrHandler's Error event will be reported, but the ErrHandler object will be given an opportunity to continue. Otherwise, if ehp_on_errx_abort = .T., the ErrHandler object will self-destruct automatically (via EHM_Abort). Typically this would be initialized via the property sheet, and not subsequently altered. (Compare with the similar ehp_on_err_abort property, which deals with errors that trigger an ON ERROR handler.)
ehp_pathtypedefault: Property containing a numeric code for the preferred default flavor of absolute or relative path representation. Used by the diagnostic message dialog for paths obtained via PUTFILE( ). See ERRH_PATHTYPE_... macros for codes in errhandl.h. This property can also be useful for establishing other path preferences in ErrHandler subclasses. Typically this would be initialized via the property sheet, and not subsequently altered, but you may also want to consider making this a user-settable option in some applications. Automatically propagated by target indirection, i.e. it is initialized by copying the corresponding property from the ErrHandler specified by ehp_targobj.
ehp_quiet: Flag property indicating whether to suppress display of error messages reported via EHM_ShowAppErr. This is useful for allowing the caller to supply its own more context-specific error information, e.g. for nested ErrHandlers. Defaults to .F., meaning display messages (not quiet). Typically this would be initialized via the property sheet or subclassed Init logic, and not subsequently altered.
ehp_showstack: Flag property indicating whether to include the full program stack in VFP error messages returned by the errhvfms( ) core UDF, which is used by EHM_VFPErrMsg methods. Defaults to .T., but you can turn this off to produce less verbose messages. Automatically propagated by target indirection, i.e. it is initialized by copying the corresponding property from the ErrHandler specified by ehp_targobj.
ehp_success: Property containing a success flag maintained by generic error-handling logic. This is the default return value for modal forms, but you may override the Unload event logic by subclassing. This flag is set to .T. by the EHM_Zero method, indicating that there is no error. In order to detect errors in your own methods, you should examine this property after executing each segment of code that has error trapping enabled, i.e. ehp_traperrors = .T. Changes to the ehp_success property should normally be made via the EHM_Zero and EHM_ShowAppErr methods, not by direct assignment, in order to assure proper support of target indirection.
ehp_targclass: Property containing the default class of optional external error handler to be created (via NEWOBJECT) when this object is initialized, to support target indirection. The external error handler should belong to one of the ErrHandler foundation classes, or one of their subclasses. This property is used by the errhtarg( ) function, which is called by Init. Typically this would be initialized via the property sheet, and not subsequently altered.
ehp_targlib: Property containing the class library path/name of the optional target external error handler, for support of target indirection. Typically this would be initialized via the property sheet, and not subsequently altered.
ehp_targname: Name of extra ErrHandler object to be maintained, for target indirection. If non-empty, the errhtarg( ) function, which is called by Init, will set the corresponding object reference, auto-initializing a member allocation or public memory variable, if necessary. Typically this would be initialized via the property sheet, and not subsequently altered.
ehp_targobj: Target ErrHandler object reference for additional externally managed error handling by target indirection. If non-null, error information is automatically copied to the target, as well as being maintained internally. This provides a way to return error info after the primary object is gone. Normally this property is set automatically via the errhtarg( ) function, which is called by the standard Init event method. Note that Init supports an optional target ErrHandler object reference argument, or you can use the ehp_targ... properties to provide other initialization options for ehp_targobj. (Used internally.)
ehp_tracelevel: Property specifying the level of diagnostic tracing in effect for ErrHandler methods and core functions. Tracing messages are generated by calls to EHM_ShowAppErr with an error code of 0. When ehp_tracelevel = 0, tracing is turned off. Verbosity generally increases as the trace level is raised. See errhandl.h for macro-defined trace level codes (ERRH_TRACE...) used by ErrHandler. Note that multiple trace levels can be selectively activated by multiplying the values of the individual trace levels, and this facility can accommodate additional subclass-specific trace levels. This property can be set via controls in the diagnostic message dialog. Automatically propagated by target indirection, i.e. it is initialized by copying the corresponding property from the ErrHandler specified by ehp_targobj.
ehp_tracequietly: Flag property to suppress normal display of EHM_ShowAppErr tracing messages via WAIT WINDOW, MESSAGEBOX( ), or the diagnostic message dialog. When ehp_tracequietly = .T., however, you can still view and/or record tracing messages by echoing to DEBUGOUT, SCREEN, File, and an external logging function. This property can be set via a check box in the diagnostic message dialog. Automatically propagated by target indirection, i.e. it is initialized by copying the corresponding property from the ErrHandler specified by ehp_targobj.
ehp_traperrors: Flag indicating that the Error event method should quietly capture VFP error information (in properties ehp_vfperr...) and set ehp_success = .F., but let method code be responsible for generating a context-specific error message. Otherwise, the Error method uses a catch-all "exceptional" error handling strategy. When ehp_traperrors = .T., method code is responsible for checking the status of ehp_success and taking appropriate action for that particular context. Typically, the appropriate action would be to report the error via EHM_ShowAppErr and fail cleanly. The normal procedure would be to leave this property set to .F., except in those sections of code where explicit error trapping is briefly turned on, e.g. where common errors are anticipated.
ehp_vfperrarray: Array result of AERROR( ), which contains VFP's extended error information. Note that ODBC errors may generate a multi-row array of error info.
ehp_vfperrmethod: Property containing the name of method in which the error occurred, as passed to the Error event or ON ERROR handler. If a method calls a UDF and an error occurs within that function, this is the name of the user-defined function, not the name of the method that called it.
ehp_vfperrmsg: Property containing the text of the current error message (character string), as returned by VFP's MESSAGE( ) function.
ehp_vfperrno: FoxPro's unique error number, as passed to the Error event or ON ERROR handler and returned by the ERROR( ) function. Zero means there was no VFP error. (However, there could still be some sort of application error, indicated by a non-zero ehp_apperrcode.)
ehp_vfperrparam: Property containing the parameter associated with certain VFP error messages, as returned by SYS(2018). Names of variables and files are common types of error message parameters.
ehp_vfperrprogdepth: Property containing the numeric value of the program level at which the error occurred, just below the Error event or ON ERROR handler that detected it.
ehp_vfperrprogpath: Property containing the result of VFP's SYS(16) function for the program level that caused the error. This includes the full program path.
ehp_vfperrprogram: Property containing the result of VFP's PROGRAM( ) function for the program level that caused the error, just below the Error event or ON ERROR handler that detected it.
ehp_vfperrsource: Property containing text of the program source line that caused the error, if available, as returned by VFP's MESSAGE(1) function.
ehp_vfperrsourcelineno: Property containing the source code line number within the method or user-defined function that caused the error, as passed to the Error event or ON ERROR handler that detected it.

Methods

The following custom methods are defined for all ErrHandler foundation classes. Also note that error handling logic exists for certain native VFP event methods, where applicable to the base class.

EHM_Abort( ): Method to force immediate, clean termination of this ErrHandler object when user explicitly chooses to Abort or after an abnormal error. Sets the value of ehp_aborted to .T. and initiates self-destruction.
EHM_Copy (toerrob_arg): Method to copy detailed error information to another ErrHandler object. Used internally by various core functions to support target indirection. The underlying logic for this method resides in the errhcopy( ) core procedure.
EHM_CopyDiags (fromerrobj_arg): Method to copy diagnostic settings from another ErrHandler object. Used internally by errhtarg( ) to propagate tracing, output, and logging options which would typically be used as global defaults. The underlying logic for this method resides in the errhdiag( ) core procedure.
EHM_ShowAppErr (ernum_arg, msg_arg, title_arg, mode_arg, ignore_arg, retry_arg, aborto_arg): Method to display an application-specific error or tracing message, possibly including generic VFP error info formatted via EHM_VFPErrMsg( ). The underlying logic for this method resides in the errhshow( ) core procedure. This is the method you should generally use to report context-specific errors in your own method code. It is highly recommended that you make use of an include file to define macros for your application's error codes and messages, for example see the errhandl.h include file used by the ErrHandler subsystem itself.
EHM_VFPErrMsg ( ): Method to return the fully expanded generic VFP error information (contained in the ehp_vfperr... properties) as a string, suitable for display. The underlying logic for this method resides in the errhvfms( ) core function. Typically you would construct an error message to pass to EHM_ShowAppErr by using an expression involving this method.
EHM_Zero ( ): Method to clear error properties, including those in the indirect target ErrHandler, if applicable. The underlying logic for this method resides in the errhzero( ) core procedure.
Activate Event: (applies to class ErrHForm only) Establishes a catch-all ON ERROR handler if ehp_on_err_handle = .T., i.e. when "abnormal" error handling is enabled. This method also supports optional diagnostic tracing (at level defined by macro ERRH_TRACE_ACTIVATION2 in errhandl.h). In order to avoid triggering a Deactivate event, a NOWAIT tracing mode is used for this special case.
Deactivate Event: (applies to class ErrHForm only) Restores the previous ON ERROR handler (saved in property ehp_on_err_prev) if ehp_on_err_handle = .T., i.e. when "abnormal" error handling is enabled. Also performs an ACTIVATE SCREEN to prevent misdirected output when using form modelessly. This method supports optional diagnostic tracing (at level defined by macro ERRH_TRACE_ACTIVATION2 in errhandl.h). In order to minimize unintended side-effects, a NOWAIT tracing mode is used for this special case.
Error Event: Invokes the ErrHandler core Error event handler, errherr.prg, and executes either a RETURN or a RETRY depending on the value returned by errherr( ). Classes or forms derived from an ErrHandler foundation class inherit this standard Error method, which generally requires no alteration.

Unlike the usual VFP programming practice of putting application-dependent error handling logic in Error event methods, the ErrHandler approach moves context-specific error handling logic into the methods where such errors are likely to occur, or uses separate generic error handling routines; the Error event method deals only with the basic problem of capturing VFP's error information and invoking a default "exceptional" error handler. This approach avoids the need to maintain logic in Error methods, where VFP imposes severe restrictions on coping with any further (nested) errors.
Init Event (targob_arg): This method calls the core errhtarg( ) function, which deals with initialization of this ErrHandler's error properties and support of target indirection. If the targob_arg argument points to an ErrHandler object, this target will be used; otherwise, other ehp_targ... properties determine how ehp_targobj is initialized. When you subclass one of the ErrHandler foundation classes, you would normally use DODEFAULT(targob_arg) to incorporate this logic as the first step of your Init method. This method also supports optional diagnostic tracing (at level defined by macro ERRH_TRACE_ACTIVATION in errhandl.h).

For forms based on the foundation ErrHForm class, Init also saves the previous ON ERROR handler (in property ehp_on_err_prev). If abnormal error handling is enabled (ehp_on_err_handle = .T.), a generic default ON ERROR handler (errhoerr.prg) is established.
Refresh Event: (applies to class ErrHForm only) contains minor logic for convenience in supporting modeless forms and a non-interactive mode of usage. Contains logic to force immediate self-release if invoked as a non-interactive modal form, i.e. when ehp_interactive = .F. This provides a simple way of turning a form-based application into an equivalent function that has no visible user interface. The Refresh logic also issues an ACTIVATE SCREEN for modeless cases, in order to prevent misdirected output into the form window.
Unload Event: (applies to class ErrHForm only) Restores the previous ON ERROR handler (saved in property ehp_on_err_prev) if ehp_on_err_handle = .T., i.e. when "abnormal" error handling is enabled. Also issues a SET MESSAGE TO in order to clear any lingering status bar prompt, and returns the modal form result, which defaults to the success flag, ehp_success. This method supports optional diagnostic tracing (at level defined by macro ERRH_TRACE_ACTIVATION in errhandl.h).

Core Functions and Procedures

The following core programs support common logic shared by methods of the ErrHandler foundation classes. These are used internally, and should not be called directly, except by their corresponding methods. The only reason that these are separate from the class definitions is to minimize redundancy, because of VFP's limitation that its base classes cannot be derived from any single ancestor class. Logically, these functions should be regarded as an integral part of the ErrHandler foundation classes.

errhcopy (fromerrobj_arg, toerrob_arg): (This program is only called directly by wrapper EHM_Copy methods.) Procedure to copy detailed error information from a source to a target, which can be any pair of objects derived from ErrHandler foundation classes. If the second argument is .NULL., this function does nothing (no-op). The standard ErrHandler properties copied are those whose names begin with "ehp_apperr" and "ehp_vfperr", plus ehp_success and ehp_aborted. This procedure recursively propagates error information all the way up the target indirection hierarchy. If the source object was aborted, i.e. ehp_aborted = .T., then the target object is also aborted, unless this abort propagation behavior has been deliberately suppressed by setting the target's ehp_abortstopshere property to .T.
errhdiag (fromerrobj_arg, toerrob_arg): (This program is only called directly by wrapper EHM_CopyDiags methods.) Procedure to copy diagnostic/tracing/output option settings from a source to a destination ErrHandler, which is done when errhtarg establishes target indirection. Only the following properties are copied: ehp_diagforce, ehp_diagmode, ehp_echodebugout, ehp_echologfile, ehp_echoscreen, ehp_log_function, ehp_logfilepath, ehp_pathtypedefault, ehp_showstack, ehp_tracelevel, and ehp_tracequietly.
errherr (errobj_arg, nError, cMethod, nLine): (This program is only called directly by ErrHandler Error Event methods.) The default handler function for all Error events in the ErrHandler foundation classes. Contains logic for capturing VFP error information (in ehp_vfperr... properties) or ignoring certain special cases of errors (see ehp_ignore_noparam). If target indirection is enabled, the error information is also copied into the object pointed to by ehp_targobj. This function sets ehp_success = .F. and quietly returns if ehp_traperrors = .T., allowing the method that encountered the error to perform its own context-specific error reporting and specialized error handling logic. Otherwise, when ehp_traperrors = .F., this function performs generic "exceptional" error handling, which includes reporting the error via EHM_ShowAppErr, and optionally invoking the EHM_Abort method if ehp_on_errx_abort = .T. If enabled, the diagnostic message dialog is used to display exceptional error messages or optional tracing (at level ERRH_TRACE_ERRHERR), giving the user the choice of Ignoring, Retrying, or Aborting, as well as various debugging options. The default final action after reporting an exceptional error is to execute a RETURN TO statement that pops the stack back to the caller of the program that encountered the error, so that there is no resumption of the offending method or UDF. (Also see similar errhoerr.prg, which deals with VFP's global ON ERROR mechanism.)
errhoerr (nError, cMethod, nLine, cMessage, cParam): (This program is only called directly by an ON ERROR command, which is generated automatically by VFP when there is no applicable Error Event method.) The default ON ERROR used by foundation class ErrHForm when ehp_on_err_handle = .T. Contains logic for capturing VFP error information (in ehp_vfperr... properties) and setting ehp_success = .F., or ignoring certain special cases of errors (see ehp_ignore_noparam). If target indirection is enabled, the error information is also copied into the object pointed to by ehp_targobj. This function performs generic "abnormal" error handling, which includes reporting the error via EHM_ShowAppErr, and optionally invoking the EHM_Abort method when ehp_on_err_abort = .T. If enabled, the diagnostic message dialog is used to display the abnormal error message, giving the user the choice of Ignoring, Retrying, or Aborting, as well as various debugging options. The default final action after reporting an abnormal error is to execute a RETURN TO statement that pops the stack back to the caller of the program that encountered the error, so that there is no resumption of the offending method or UDF. (Also see similar errherr.prg, which deals with VFP's Error Event mechanism.)
errhshow (errobj_arg, ernum_arg, msg_arg, title_arg, mode_arg, ignore_arg, retry_arg, aborto_arg): (This program is only called directly by wrapper EHM_ShowAppErr methods.) Procedure for reporting application errors or tracing messages and retaining application error information in custom error-handling properties, ehp_apperrcode, ehp_apperrfrom, and ehp_apperrmsg. The ehp_success flag is set to .F. if a non-zero ernum_arg is supplied, indicating an application error. When ernum_arg is zero, a "tracing" message is generated. If target indirection is enabled (ehp_targobj non-null), the target ErrHandler's error properties are also set.

This program supports several modes of operation, based on both its arguments and various property settings. In "quiet" modes (see ehp_quiet and ehp_tracequietly) the normal display of messages is suppressed. When messages are displayed, the mode may be either interactive or non-interactive, according to the setting of ehp_interactive. Non-interactive mode always avoids pausing for a user interaction by generating messages via WAIT WINDOW NOWAIT (truncating msg_arg as necessary to avoid exceeding VFP's 254 character limit). In interactive mode, a WAIT WINDOW is used for short messages (<= 254 chars), and VFP's MESSAGEBOX() is used for longer messages. Interactive messages can be presented either in the preceding "normal" ways, or in a "diagnostic" mode (governed by ehp_diagmode and ehp_diagforce), displaying a diagnostic message dialog. A default dialog title is automatically supplied, but this can be overridden by passing an explicit title_arg.

The mode_arg argument provides the caller with some additional flexibility to temporarily override the preceding property settings that determine the default output mode. This can be used to force either diagnostic or NOWAIT types of output. (See ERRH_SHOWMODE_... macros in the errhandl.h include file for supported mode_arg codes.) If the diagnostic message dialog is displayed, the Ignore and Retry buttons will be disabled unless they are explicitly enabled via the optional flag arguments, ignore_arg and retry_arg. The final argument, aborto_arg, specifies the relative stack depth to jump to for an explicit user Abort request. (The last 3 arguments are used internally by errherr and errhoerr.)

Errhshow( ) always assigns a value to the ehp_diagresponse property, indicating how the user exited from the diagnostic message dialog, if it was employed. An empty string value indicates that the user replied OK, or no choice was given. When called with either ignore_arg or retry_arg = .T., which is unusual, it is the caller's responsibility to check for an Ignore or Retry request. If the user exits from the diagnostic message dialog with an Abort request, however, this will be handled by errhshow.

In addition to its primary function of displaying a message (msg_arg), errhshow.prg supports secondary "echoing" output, to the main screen, a text file, and/or the VFP Debugger, controlled by properties ehp_echoscreen, ehp_echologfile, and ehp_echodebugout. There is also a simple API providing a hook to an external application-specific logging function, specified via ehp_log_function.

Because it is used internally within error handling procedures, errhshow must take care to avoid nested error handling complications. For this reason, any errors that it detects (e.g. argument usage or logging errors) are treated as warnings appended to the message it was called to display, not separate errors.
errhtarg (errobj_arg, targob_arg, targnm_arg, tclass_arg, tarlib_arg): (This program is only called directly by ErrHandler Init Event methods.) Function to clear the error properties (via EHM_Zero) and establish the target of indirection to an external ErrHandler, returning a success flag result. This program deals with the initialization of the ehp_targobj property, which is the object reference to an additional error handler to be maintained, e.g. for returning detailed error info from a modal form or a nested ErrHandler-based function.

Errhtarg( ) also invokes the EHM_CopyDiags method to copy diagnostic mode settings from targob_arg to errobj_arg. This provides a simple, flexible way to establish and propagate global defaults for tracing, output, and logging properties (as listed under the description of errhdiag). Note that the targob_arg is used as the source of default values for these diagnostic options, but it will become a destination for error information.

The last 4 arguments, which are optional, specify the information used to find or allocate a target ErrHandler object, if one is desired. The targob_arg argument simply specifies an ErrHandler object reference directly; if supplied, it is assigned to ehp_targobj, and the rest of the arguments are ignored. The remaining arguments normally come from the ehp_targname, ehp_targclass, and ehp_targlib properties, which would typically be set via the VFP Class/Form Designer's property sheet.

If no target name is supplied, ehp_targobj is set to NULL, meaning that there is no target indirection. Otherwise, the targnm_arg is assumed to be the name of a target ErrHandler object, which may or may not already exist. If the object already exists, a reference to it is retained in the ehp_targobj property. Otherwise, if no such object currently exists, errhtarg( ) attempts to create the specified object, using VFP's NEWOBJECT function or method, as appropriate. Depending on the syntax of the target name, one of the following two types of target object is automatically created:

    1. free-standing target ErrHandler referenced by PUBLIC mvar
        or
    2. member ErrHandler object allocated in another existing object
errhvfms (errobj_arg): (This program is only called directly by wrapper EHM_VFPErrMsg methods.) UDF to return the text of a fully expanded VFP error message. Properties displayed include: EHP_VFPErrNo, EHP_VFPErrMsg, EHP_VFPErrSourceLineNo, EHP_VFPErrMethod, EHP_VFPErrSource, EHP_VFPErrProgDepth, EHP_VFPErrProgram, and EHP_VFPErrProgPath. The entire program stack below the point of error is also appended to the message, unless verbosity has been suppressed by setting ehp_showstack = .F.
errhzero (errobj_arg): (This program is only called directly by wrapper EHM_Zero methods.) Procedure to clear error information (EHP_AppErr* and EHP_VFPErr* properties) and reset the EHP_Success property to .T. If target indirection is enabled (ehp_targobj non-null), the target ErrHandler's error properties are also cleared. Use this function when you want to clear the ehp_success flag, in order to assure that target indirection is supported properly, as well as clearing all error detail properties.

Target Indirection

The ErrHandler classes support an optional feature called "target indirection", making it easier to return detailed error information from functions, modal forms, and other sub-applications. Error information is automatically copied into a "target" ErrHandler object, which is external to the primary object or program that originally detected the error. This makes it possible to get to the complete error details, even though the program or form that generated the error has already terminated. The error properties propagated to the target are ehp_apperr..., ehp_vfperr..., ehp_success, and ehp_aborted.

Target indirection is also useful for employing nested ErrHandler-based functions, where the called function returns its detailed error information directly into the caller's own ErrHandler properties. By suppressing the display of error messages in a nested function (using the ehp_quiet property), the caller can substitute its own "wrapper" error code and message to provide more context-specific information. The ehp_apperrfrom property allows the caller to tell that its error properties originated via target indirection from a sub-application. On the other hand, instead of wrapping subordinate (nested) ErrHandler error messages, you also have the option of simply leaving them as-is, if they are sufficiently self explanatory.

Note that target indirection is handled recursively, by errhcopy, so that error information is automatically propagated all the way up the hierarchy. For the special case of Aborts, i.e. when ehp_aborted = .T., errhcopy recursively propagates the abort up the target indirection hierachy via ehm_abort, until it encounters a target with ehp_abortstopshere = .T. By default, when an ErrHandler invokes a subordinate ErrHandler method that is aborted, the caller is also aborted, and its calling ErrHandler is aborted, and so on. The ehp_abortstopshere property allows you to override this default abort propagation behavior, so you can localize an abort to a sub-application without having to abort the master application.

The ehp_targobj property is non-NULL when target indirection is in effect. An optional Init event method argument and several properties, ehp_targname, ehp_targclass, and ehp_targlib are available to the developer for controlling how this property is automatically initialized (when Init invokes the errhtarg( ) function).

Propagation of Diagnostic and Tracing Output Options

In addition to its primary function of returning error information from a sub-application, target indirection is also used to propagate default diagnostic options to the sub-application, via errhtarg( ). In this way, target indirection establishes a bi-directional connection that makes the called sub-application behave like an extension of the calling application: the caller supplies default diagnostic property settings (listed under errhdiag), and the callee returns error information through the same ErrHandler object.

ErrHandler Forum

Discussion