| Bottom | Unframe | Help |

Locate in Contents | (framed)

Locate in Discussion | (framed) 

• repair numerous broken links
  For example:
  • Universal Thread links need to fixed, because of changes in that system's URL conventions.
  • Usenet links via Deja need to be replaced by corresponding Google links, if available.
  • many MSDN links need to be adjusted for site reorganization by Microsoft.
  • some FoxTalk free downloads are no longer available.
• add more references to new topics and threads
  Make the references more complete and up-to-date, including additional sources.  A few potential additions were mentioned in notes about Further Plans for This Page.
• include the detailed outline within the article page
  Work out a better way of handling the outline, which serves as an aid for navigating through an increasingly long list of references.  With appropriate use of include pages and proper construction of URLs, it should be possible to incorporate the detailed outline into the article itself, as well as continuing to support the two inclusion of this outline in the ErrHandler Forum Contents page (framed and unframed versions).  Having the outline in the article would make this page more useful as a self-contained module.
• let primary outline links go straight to final target
  Make the outline more convenient (especially in framed mode) by using links that point directly to the final target, instead of being a link to a link.  If there is some further annotation for a given reference in the body of the article page, use a very compact secondary link to point to this too (but keep the primary link pointing to the ultimate target).  In framed mode, the primary link for each outline entry in the upper frame should immediately load the target into the lower frame.
• explore further refinements to article layout
  Consider how to make it easier to maintain the article in a very compact form, while at the same time allowing for occasional annotations.

• display COM-related error information
  Add logic to the errhvfms function for deciphering the relevant AERROR( ) information stored in property ehp_vfperrarray into displayable error message text.
• support use of COMRETURNERROR( )
  It may be desirable to add an option to enable the use of VFP's COMRETURNERROR( ) function in the core error handling functions (errherr and errhoerr) of a VFP Automation server.  This will require some further review and experimentation.

Here are some COM-related references on the Fox Wiki:

• ActiveX
• AutomationObjects
• ComArchitecture
• COMComponent
• COMComponentExample
• ComDiscussion
• ComErrorHandling
• ComErrors
• COMReturnError
• ConfigureDCOM
• DCOM
• OLE
• OleErrors

I would have followed this convention in the first place, but I had the mistaken impression that VFP doesn't allow specifying a return value in the RETURN TO ... command.  The VFP 6.0 Help file specifies the following syntax for the RETURN command:

RETURN [eExpression | TO MASTER | TO ProcedureName]

I tried the following syntax without success:

RETURN .F. TO foo

This gave me a syntax error, leading to my incorrect conclusion.  I have since learned (thanks to Larry Miller on the Universal Thread) that the following syntax does work:

RETURN TO foo .F.

Note that the VFP Help file information is incorrect, because it implies one can have either eExpression or TO ProcedureName, but not both.  Also the help information is misleading because it gives these options in the wrong sequence, and it happens to matter in this case.  (That the sequence matters is yet another flaw, uncharacteristic of the FoxPro language in general.)

Although the problem is somewhat obscure, I've occasionally encountered situations where the current logic doesn't work properly.  The cause of these difficulties is that the name of the procedure to RETURN TO is not always obtainable [via the PROGRAM( ) function] in a simple, consistent syntax that can be used straightforwardly, if at all.  For example, I recall having seen bugs where the error handler attempted to return to an ON ... command, which was triggered by a menu choice.  The present kludge needs to be made even kludgier to deal with every possible case.  Further review and testing will be needed to make this logic as robust as possible.

I believe that a simple VFP extension (which must come from Microsoft) would entirely eliminate these problems, and I raised this idea in a discussion with Doug Hennig on the Universal Thread.on 1/4/01 (Subject:  Error stack).  My suggestion was that the RETURN TO ... command support a simple numeric stack depth argument, instead of requiring a potentially ambiguous and awkward-to-construct procedure name argument.  Doug indicated that no such feature is included in VFP 7 or under consideration by Microsoft, to his knowledge.

There needn't be any redundancy in the way this information is shown in other contexts, e.g. WAIT WINDOW, output echoing, and logging to a text file.  The proposed change only affects how error info would be displayed in the diagnostic dialog.

In the present implementation, the following command is executed in the Resume button's Click method:

KEYBOARD '{CTRL+M}'

I.e. the present implementation assumes that Ctrl+M (the VFP default) is the keyboard shortcut for Resuming a suspended program.  At the very least, one should be allowed to substitute a different hot key, in order to allow for application-specific menu customizations.  (It is also possible that VFP 7.0 may provide some cleaner alternative, but this needs to be researched further.)

(Note that I tried the obvious approach of using VFP's RESUME command, as well as the less obvious alternative of SYS(1500, '_MPR_RESUM', '_MSM_PROG') to implement the Resume button, but neither of these techniques worked, presumably because they only operate from the VFP command window.)

Because the logic for supporting Suspend and Resume depends on system menu bars, it is recommended that you define your menus to include the standard VFP Suspend and Resume bar #s, _mpr_suspend and _mpr_resum, so that these form buttons can function.  Otherwise, if SKPBAR('_MSM_PROG', _MPR_RESUM) is undefined, the diagnostic message dialog's Suspend and Resume are disabled, to avoid the risk of errors.  Since the diagnostic message dialog may be called from an error handler, we settle for this conservative "dumb" mode instead of risking a nested error, which can't be handled in VFP.

If you want to support Suspend and Resume under the VFP Development System, be sure to incorporate VFP's Suspend and Resume system menu bar #s in your own menu system, or use the standard VFP menus.  Also note that the Resume button logic depends on VFP's standard Ctrl+M shortcut, because if uses a KEYBOARD hack.  (This kludge really should be made a little more flexible, but I'll deal with that rather obscure limitation later, under a separate task.)

For example, one question is what error information to return.  The current logic will generally return information about the last error that took place.  A better default might be to return info about the first of a series of errors, since this is much more likely to be the real indicator of the original problem.

Likewise, let Aborts be propagated up the stack, along the target indirection hierarchy, but introduce a new property, ehp_abortstopshere, to optionally force the Abort not to be propagated past a certain point.  Introduce a new subclass of ErrHCustom, ErrHCustNoAbort, having ehp_abortstopshere = .T., for use as a terminal ErrHandler.  ErrHCustDiag should be redefined as a subclass of ErrHCustNoAbort.

This change simplifies the use of nested ErrHandler objects, because it avoids the necessity of adding extra "wrapper" logic around calls to subordinate ErrHandler methods; the change enhances symmetry between an object's own methods and those of the nested ErrHandler.  (This has immediate application to XFormDBF, an ErrHForm-based application that uses Commander, based on ErrHCustom.)

The EHM_ShowAppErr method and its corresponding core UDF, errhshow, support an optional argument, aborto_arg, for specifying a relative RETURN TO stack depth.  This argument is intended primarily for internal use by the catch-all error handlers, errherr.prg and errhoerr.prg, and would generally be omitted otherwise.  The previous default value of aborto_arg was interpreted to mean that the an Abort should pop back to the caller of the caller of EHM_ShowAppErr, which is therefore the caller of the caller of the caller of errhshow.  In the revised specs, the default aborto_arg value (empty or zero) means to just return to the caller of EHM_ShowAppErr.  Under the new specs, aborto_arg = -1 would now designate what was previously the default.  In other words, aborto_arg is the stack depth to RETURN TO relative to the caller of EHM_ShowAppErr, if the user Aborts.

Also make a slight change in specs for errhzero (hence the EHM_Zero method as well) to include ehp_aborted among the error properties that are cleared.  There is no good justification for treating this property asymmetrically.  In any case, failure/cleanup logic must take care not to call EHM_Zero after an error has taken place.

Note that the demo screen shots really should be updated to show the program stack info that is now appended to error messages by default, but this can wait.  As it stands, these screen shots reflect what happens if ehp_showstack = .F.

• doc changes related to erma0016
  The description of errhshow really should be clearer about aborto_arg.  Also note slight revision of errhzero specs, to include ehp_aborted among properties that are reset.
• doc changes related to erma0015
  Update sample error messages to show latest format of program stack info.  Also should note significance of the fact that extended stack info is dynamically obtained by errhvfms, as opposed to other info obtained directly from ErrHandler properties.
• mention/explain the noread_arg to errhdemo.prg
• add a graphic illustrating tracing output to screen
• add a section discussing types of errors
  Including my terminology as to "exceptional" vs "abnormal" and "anticipated" vs "unanticipated" errors.  Note special cases, like too-many-argument errors.  Note limitations in RETRY for certain cases.
• mention appropriate use of ASSERTs
• supply an example of nested ErrHandler usage
  I.e. where an ErrHandler object invokes another ErrHandler object.  Show how the caller can wrap a sub-application's errors with additional information about the caller's context.

Introduce a new method, ehm_copydiags, to handle the details of copying the above properties from one ErrHandler to another.  Let errhtarg.prg invoke ehm_copydiags to handle the new propagation logic.  Also introduce a new core UDF, errhdiag.prg, which does the actual work for method ehm_copydiags.  Also create a new subclass of ErrHCustom, called ErrHCustDiag, which differs only by the setting of ehp_diagmode = .T.

The rationale is that these properties govern variable modes of message handling that would typically be global settings, and this is a convenient way to propagate the current settings.  Individual per-object properties can still be adjusted manually, if desired, but that should seldom be necessary in typical usage.

• catch-all error event handling for "exceptional" errors
  This covers all of the ErrHandler's Error events for unanticipated error cases, i.e. when ehp_traperrors = .F.  Generate a generic exceptional error message and code in these cases.  Use RETURN TO ... logic to pop the stack back to the caller of the method or UDF that encountered the error, avoiding resumption of the offending program.
• support optional tracing
  Setting ehp_tracelevel = ERRH_TRACE_ERRHERR turns on tracing for anticipated error cases, i.e. when ehp_traperrors = .T.  This can be useful for debugging.
• employ diagnostic extensions for generating messages
  Use recent extensions to EHM_ShowAppErr( ) for tracing and exceptional error reporting.  Enable Ignore and Retry commands for this context.  Use the new abort-to-depth argument for supporting the Abort command in the new diagnostic message dialog.
• optionally Abort on exceptional errors
  Depending on the setting of the new ehp_on_errx_abort property, automatically invoke the new ehm_abort method after reporting exceptional errors.  This would be a conservative option, allowing a sub-application to cleanly self-destruct without needlessly taking down the main application.
• optionally Ignore too-many-arguments errors
  Since these types of errors are a troublesome special case, support the new ehp_ignore_noparam property to optionally Ignore these.  It's arguable that VFP really shouldn't have raised an error in the first place, since a function can easily count its arguments and decide for itself whether to complain.
• avoid scattered references to core UDFs
  Observe the new convention that core UDFs should only be called by their corresponding wrapper methods.  This will assure the greatest flexibility in subclassing the ErrHandler foundation classes, and it simplifies maintenance.

• revise Commander's Init to support the new optional argument
  All that's required is to pass the new target ErrHandler argument along to dodefault( ), so that the parent ErrHCustom.Init logic can do its usual thing.  This change should be made along with the introduction of new quiet Commander subclass for nested error handling.  (As part of svma0013, Saver's initialization logic should pass a self-reference, via the new argument, when it invokes newobject( ) to instantiate a temporary Commander object.)
• perform testing to confirm behavior when newobject( ) fails
  The point is to confirm that this change allows the capture of class-specific error details when an ErrHandler's Init event fails, i.e. when there is no direct object reference available.  (It's not sufficient to just capture the VFP error info about the failure of the newobject function invocation.)  It may be easiest to do this testing in the context of Commander, which is an ErrHandler subclass.
• also add a similar new (optional) Saver Init argument
  Since this new argument really has to do with nested error handling in general, we'll also need it to support nested Savers cleanly.  This minor extension can be easily included along with other details of svma0013.
• rebuild and test other apps for compatibility with these changes
  Update shared ErrHandler, Commander, and Saver files in mdacomm.  Confirm that Querier, XFormDBF and BTCrit still work properly after rebuilding.

• properties (for all ErrH foundation classes)
  • new property ehp_apperrfrom
    This property contains the appname from which the error originated.  Defaults to empty string.  (Keep EHP_AppName as a static property, used by errhshow as before.)
  • new property ehp_quiet
    for suppressing display of error messages. Defaults to .F.
• core ErrH UDFs
  • errhshow
    Capture the current this.EHP_AppName in new property ehp_apperrfrom for the benefit of target indirection.  The target object is responsible for reporting ehp_apperrfrom, if desired, but this is entirely optional.  Also suppress display of message if ehp_quiet is set.
  • errhcopy
    don't copy EHP_AppName to the target errhandler (documentation change is required for this).  Copy ehp_apperrfrom to the target ErrHandler.
  • errhzero
    clear the new ehp_apperrfrom property.

Test these changes via the ErrHandler demo application, plus direct use of the VFP command window and Debugger.  Adjust ErrHandler Help - Foundation Classes and Core Functions to reflect the above changes.  An example of nested ErrHandler usage would also be handy in ErrHandler Help - Usage, but hold off on this until we've got a real example in Saver's calls to Commander, i.e. after redefining Commander as a subclass of ErrHCustom.

As a further refinement, introduce a sub-section of the main Contents outline in order to give a topical breakdown of these references.  This is similar to the way we've organized task lists into an tasks outline and an accompanying tasks table, i.e. this page.  (The benefits of this organization become clearer when one uses the framed mode of browsing.)

Maintain notes about further changes and ongoing maintenance of this reference page in a section at the bottom of the article.

However, as previously noted (which Doug Hennig points out in his very helpful article, "Error Handling in Visual FoxPro"), one really needs an additional layer of error handling for cases where there is no explicit error-checking, to perform required cleanups and terminate properly in all cases.  In other words, we need a way to specify default form-level error-handling logic that allows the form to fail cleanly without taking the overly heavy-handled action of terminating the entire application.  The same idea could also be applied to other classes of error-handling objects, but the ErrHForm foundation class is a good starting point, because this is the basis for some existing applications with fairly complex and rigorous error-handling requirements.

In particular, we want to ensure that Saver-based forms like XFormDBF and BTCrit can handle unanticipated errors at least to the extent that they do the following:

• trap any unhandled error, even if not explicitly checked for
  Let this be governed by the new ehp_on_err_handle property, which causes ErrHForm to establish errhoerr( ) as a temporary ON ERROR handler while the form is active.  Supporting logic is required to save and restore the previous ON ERROR handler in Init, Activate, Deactivate, and Unload event methods.  As done in errherr, optionally suppress too-many-argument errors, based on setting of the new ehp_ignore_noparam property.
• report the error, with optional error logging
  As done in errherr, let errhoerr report its "abnormal" errors via the souped-up EHM_ShowAppErr( ) method.  This provides the same diagnostic, tracing, output, and debugging options that are supported for "exceptional" errors.
• give the user some options about how to proceed
  Support for the diagnostic message dialog automatically comes as a consequence of using EHM_ShowAppErr to report errors.  This means the user can choose from OK, Ignore, Retry, Abort, Debug, Suspend, and Resume.
• let the form to fail cleanly without undue hassle
  Support an option to Abort automatically by invoking the new EHM_Abort method on abnormal errors if the new ehp_on_err_abort flag is turned on.  As done in errherr, let errhoerr use RETURN TO ... logic to pop the stack back to the caller of the method or UDF that encountered the error, avoiding resumption of the offending program.

If there were no such form-level ON ERROR handler, VFP's default handler would be triggered.  But for Saver-based forms, we would generally want to suppress automatic state-saving before terminating the form abnormally, and this should be the responsibility of the form itself, not the application that called it.  Instead of choking on a low-level VFP error, the less disruptive standard error return mechanism should be used, so that the failure is localized and the caller (e.g. the JobControl application) can continue with its normal processing.  Prior to this change, the user of a Saver-based application needed to manually Abandon the form in such cases, or else risk losing the current configuration.

• new ErrHDiagDialog class for diagnostic message dialog
  (Used a class instead of a form to allow for future subclassing.)  This resizable dialog includes a scrollable read-only message editbox, controls for various user-settable diagnostic, tracing, and output properties, plus command buttons for OK, Ignore, Retry, Abort, Debug, Suspend, and Resume.  (Note that this dialog is called only by the errhshow( ) core procedure.)
• revise arguments to EHM_ShowAppErr and errhshow
  Change the specs for this method and core procedure to support either "tracing" or error reporting modes.  Tracing occurs when the error code argument is zero.  Also support optional arguments to supply a title, force into a specific output mode (mode_arg), enable the Ignore and Retry commands, and specify an Abort-to-depth.
• beef up argument validation, in case of basic usage errors
  Let errors in arguments to EHM_ShowAppErr( ) and errhshow( ) be handled by appending a warning message to the primary message this procedure was called upon to display.  This avoids nested error complications, while maintaining robustness.
• connect the diagnostic message dialog to errhshow
  Depending on settings of properties ehp_diagmode, ehp_diagforce, and the optional mode_arg, invoke the diagnostic message dialog instead of using either a WAIT WINDOW or MESSAGEBOX( ) command to display the message.  Always set the ehp_diagresponse property to indicate whether the user exited via OK, Ignore, Retry, or Abort.
• add logic to handle user Aborts within errhshow.prg
  If the diagnostic message dialog was exited via a deliberate Abort request, perform a call to the new EHM_Abort method, so that callers of EHM_ShowAppErr never need to explicitly check for Abort.  The RETURN TO ... mechanism pops directly beyond the caller's stack level, so the caller of EHM_ShowAppErr should never see its return.  This requires introducing a new optional argument, aborto_arg, for specifying the relative stack depth to jump to for Aborts.
• optional output echoing to SCREEN, Debugger, and/or File
  Introduce new properties, ehp_echoscreen, ehp_echodebugout, ehp_echologfile, and ehp_logfilepath, used by errhshow to generate secondary outputs for tracing and error messages.  These properties should also be user-settable via controls in the diagnostic message dialog.  When messages are echoed to an ASCII text file, they are preceded by a date/time stamp.  Note that this basic error logging mechanism (also mentioned previously) is a separate feature from the provision for an API to an external application-dependent logging function.
• support user-settable tracing options
  Include a spinner in the diagnostic message dialog to display and set the new ehp_tracelevel property, which can be used to selectively activate any combination of diagnostic tracing levels.  Also provide a checkbox for setting the new ehp_tracequietly flag, telling errhshow to suppress the primary display of tracing messages (but still echo them to secondary outputs).
• add tracing to methods of foundation classes and demo form
  Test out diagnostic tracing facilities by adding tracing logic to selected methods and core UDFs.  Also use this tracing to assist in debugging these changes and ErrHandler features in general.  (See ERRH_TRACE... macros in errhandl.h for trace levels currently in use.)
• adjust all ErrHandler help pages to reflect these changes

The external logging function should conform to the following API, which is essentially the same as the interface to errhshow( ), up to the first 4 arguments:

success = logfunc(errobj_arg, ernum_arg, msg_arg, title_arg)