| Bottom | Unframe | Help |

Locate in Contents | (framed)

Locate in Discussion | (framed) 

The main purpose of this extension is to simplify state-saving logic in Saver-based applications, by providing a more concise alternative to a frequently used construct.  Note the equivalence of this:

IF NOT oCmdr.CMDRM_AddFuncStep(funcid, seq, cmdline)
    RETURN .F.
ENDIF

to the following single command line, which uses the new abort_to_depth argument (-1):

oCmdr.CMDRM_AddFuncStep(funcid, seq, cmdline, -1)

The reason that we can't simply substitute this command:

oCmdr.CMDRM_AddFuncStep(funcid, seq, cmdline)

i.e. omitting the last argument will not do, because the point is to fail cleanly as soon as an error has been detected.  The new argument avoids clumsy in-line error checking, but it still provides the same rigorous level of clean, modular error handling.

Nadya mentioned noticing this problem (in connection with BTCrit) in her email of 5/20/01.  This also applies to any other Saver-based apps, e.g. XFormDBF.

This idea was mentioned a long time ago, but suddenly its usefulness has become clear in the context of BTCrit.  (We can use this GOTO mechanism to support an optimized mode of Saver-based state restoration logic for BTCrit's non-interactive "Run" action.)

Some preliminary logic for this new method was implemented on 2/13/01, but I didn't quite finish with testing and error handling aspects.  Also the Commander Help documentation hasn't yet been updated to show this extension.  The latest version of Commander includes this preliminary logic, since it does no harm, but this feature is not yet ready.

Also take this opportunity to allow for customized error reporting based on the pseudo-function logic itself.  Use a modified version of the factorial function example, demo07b, to test and demonstrate proper use such error reporting, e.g. for the logic that validates the required numeric argument.  This requires only a minor change in the Commander.CMDRM_DoFunc method logic.  (Instead of treating the failure of the &cmd expansion as a generic error, the non-zero value of ehp_apperrno indicates that the pseudo-function logic has already reported the error and assigned a failure return value.)

Documentation in Commander Help - Design Overview really should include sections for all native methods (e.g. Init) that have any logic, and this should be kept in synch with program changes.  Also include a section about the cmdrclon( ) utility function.

• use VFP's newobject( ) function and method where appropriate
  See errhtarg.prg and XFormDBF.Init for examples of cleaner newobject( ) usage, which avoids possible confusion in locating the proper versions of class libraries.  This change affects only the shell program, commandr.prg.
• introduce a PRIVATE mvar for reference to the Commander object itself
  Following the same naming conventions as for other such global mvars, call this m.cmdr_self.
• AddFuncStep should clear the Notes field when re-using a deleted record
  But let the Notes field be optional, since logic is otherwise not dependent upon it.

Since these are incompatible changes, review cross-references to these names in order to determine which other programs will need to be adjusted.  In order to minimize disruption of XFormDBF and BTCrit, make these temporary provisions for compatibility:

• retain old method names, AddFuncStep and DoFunc
  I.e. let the methods just pass on the call to the corresponding new method name.
• use an ASSIGN method for the QuietNoFunc property
  Since the only usage by XFormDBF or BTCrit is an assignment in the Init method, we only need to introduce an Assign method to propagate these settings to the corresponding renamed property.

Also revise the names of macros defined in commandr.h to avoid use of the same prefix as used for global memory variables.  Retain the convention that Commander's global memory variables start with "cmdr_".  Rename macros previously starting with "CMDR_" to use the prefix "CMDM_", which is not used for any other purpose (regardless of upper/lower case, which is not significant to VFP).  Temporarily retain selected old macro definitions for compatibility, until all obsolete references have been eradicated.  (Most of these macros are only used internally in Commander, but note that BTCrit.Init uses CMDR_CLASS and CMDR_CLIBQ, and BTCrit criteria classes may also contain references to CMDR_DLAS1 and CMDR_DLAS2.)

• redefine Commander as a subclass of ErrHCustom
  (See ErrHandler Help - Usage, Creating an ErrHandler-Based Application for more about the required adjustments.)  Start out with default ehp_... property settings (no target indirection, interactive error reporting).
• add/adjust error handling logic in all methods
  • Init Event
    supply standard ErrHandler Init Event method logic, plus additional error checking as appropriate.
  • Destroy Event
    Seems OK as-is, at least for this pass.  Errors here are very unlikely, and would require dealing with the complication of preserving information about any prior error.
  • AddFuncStep
  • DeleteFunc
  • DoFunc
    This is the most important event for which to provide good error handling coverage.
  • CMDRM_SeekFunc
  • CMDRM_Open
• phase out use of the obsolete errorcode property
  Substitute the generic ehp_apperrcode property in its place.  Also make this substitution in Saver programs, to maintain compatibility with these Commander changes.  The only external users of the Commander.errorcode property are Saver.StateRestore (in old Saver.vcx) and savrrest.prg (in Saver2.pjx), which should be adjusted.  (Also see cmma0004 about internal Commander naming changes that will require further Saver adjustments.)
• revised definition of the Commander.quietnofunc property
  This property affects the way that the DoFunc( ) method treats cases where the specified functionid is not found.  Previously, setting this flag to .T. suppressed an error message, but returned a failure result (.F.).  Redefine the quietnofunc property to have DoFunc( ) return success (.T.) and set ehp_apperrcode = 0 in these cases.  This simplifies the logic required in Saver's usage of Commander.DoFunc( ), but note the corresponding Saver adjustments required for compatibility.
• eliminate obsolete CMDR_E* macros in commandr.h
  Get rid of the old macros for Commander error codes and messages in the commandr.h include file, because these are superseded by new macros that follow the new Commander naming conventions.  The old CMDR_E... macros were used only internally in Commander and in Saver, which needs to be adjusted accordingly as for the errorcode change.
• define new Commander error codes and messages in commandr.h
  (The commandr.h include file should be included in the developer help pages for Commander, for convenient reference.)  New macros for Commander error codes and messages have the prefixes "CMDM_EC" and "CMDM_EM", respectively, according to the new Commander naming conventions.

Further extensions to consider are a Commander subclass having ehp_quiet = .t. as its default property setting, and an additional optional Init argument for passing an explicit target errhandler (see cmma0007).  This may be helpful in dealing with nested error handling issues, as in Saver changes for improved error handling during Init.  Wait and see how this falls out in the course of making those Saver changes.