|
XFormDBF Help |
Error Handling |
XFormDBF returns a success flag (.T. = success, .F. = failure) plus additional detailed error information in a separate ErrHandler object, derived from one of SpaceTime's foundation error-handling classes. By default, the global memory variable m.xformerrh is used to hold on to this object reference, which the caller may pre-allocate. Otherwise xformdbf will automatically allocate an external ErrHandler and assign it to m.xformerrh. If m.xformerrh doesn't exist in the scope of xformdbf, XFormDBF allocates it as a PUBLIC memory variable. Alternatively, you can pass an explicit "target" ErrHandler reference as an argument to XFormDBF, bypassing the use of m.xformerrh.
The point of the external ErrHandler object is to provide a way of returning extended error information in a comprehensive, standardized way after the XFormDBF application has been run, e.g. as part of a batch processing job. When XFormDBF is run as a modal form (which includes the non-interactive cases), the form no longer exists after the command that invoked it has returned, so it won't suffice simply to store the resulting error information in the form itself. That's where the external ErrHandler comes is: it contains a copy of the detailed error information, so that the caller can decide what to do about it. See ErrHandler developer help for more about Target Indirection.
Another function of the target ErrHandler is to provide a convenient way of initializing various diagnostic, tracing, and error output options used by XFormDBF. See ErrHandler developer help for more about Propagation of Diagnostic and Tracing Output Options.
Note that if XFormDBF is allowed to make the ErrHandler allocation, the form's data session will not be released until the external ErrHandler object is released. This doesn't necessarily cause any problems, but if you wish to avoid the lingering data session, you can do so by pre-allocating an ErrHandler object and passing it as an argument or assigning its object reference to a global memory variable (PUBLIC or PRIVATE) named xformerrh. XFormDBF will then use this external ErrHandler object instead of allocating one itself, and there will be no residual data session.
Because the XFormDBF form is based on class SaverForm, which is based on class ErrhForm, it includes a number of properties that begin with "ehp_", which are used to support error handling features. Some of these properties have been initialized via XFormDBF's property sheet in order to support the preceding defaults. (If necessary, the defaults could be altered by changing these property sheet settings and rebuilding the application.)
For modeless invocations of XFormDBF, you can obtain the current error information by referring directly to the ehp_... properties of the form instance in question. Since the form persists in modeless invocations, there is no need to refer an external ErrHandler object in these cases.
Refer to the xformdbf.h include file for a complete list of XFormDBF's error codes and messages, as well as other compile-time constants that may be of interest.