The simplest way to test out XFormDBF is to launch it from the VFP command window with the following command line:

xformdbf( )

When called in this manner, i.e. with no arguments, XFormDBF makes a number of default assumptions.  Specifically, it assumes the default action ('Prompt' with interactive modal dialog), the default configuration (functionid = 'xformdbfdf'), and the default meta-file ('xformdbf.dbf' in the current directory).

Optional Arguments

XFormDBF supports the following 6 optional arguments:

action_arg

one of the reserved action codes, 'prompt', 'promptn', 'promptnx', 'run', or 'runc'.  Recommended macro definitions for these codes are in xformdbf.h, along with brief descriptions.  The default is 'prompt' (defined as macro XFDB_ACPRM in the xformdbf.h include file), which means to use a modal dialog for interactive operation.

funcid_arg

functionid for the state (form configuration) to be restored/saved.  If empty string, use the default form configuration, i.e.bypass state restoration and saving.  If empty non-string value or omitted, use the default state function id, determined by evaluating the Saver property, svp_dfltfuncexp.

cmdrob_arg

object reference to the generic Commander controlling the meta-file for state saving and restoration.  If null or omitted, use the default Commander object determined by evaluating the property svp_dfltcmdrexp.  If an object reference is provided, it should point to a Commander.  For character string values, this argument specifies the meta-file path to be opened automatically by allocating a temporary Commander object.

infile_arg

optional input file path.  If specified and non-empty, the input file will be held to this specification, regardless of the configuration that may be restored.  If empty or omitted, the input file specification will be restored from a previous saved state.

outfil_arg

optional output file path.  If specified and non-empty, the output file will be held to this specification, regardless of the configuration that may be restored.  If empty or omitted, the output file specification will be restored from a previous saved state.

targob_arg

optional object reference to the target ErrHandler to be used.  If supplied, hold on to the given ErrHandler in ehp_targobj.  If NULL, empty, or omitted, let ehp_targ* properties determine the target ErrHandler requirements and any related initializations.

Action Codes

The following actions are supported as the first argument to XFormDBF:

Prompt

(the default) launches an interactive, modal dialog.  (A modal dialog is one that requires you to exit from the form before you can activate another window in the same process.)

PromptN

launches an interactive, Non-modal (i.e. modeless) dialog.  This action does not produce a meaningful function return value, because the form continues to exist beyond the command that launched it.  (A modeless dialog is useful because it allows you to run multiple applications or forms at the same time in the same process, switching between applications simply by clicking on their forms.)  This action also allows you to access the VFP Command Window while XFormDBF is active, if you are running under the VFP Development System.

PromptNX

interactive, Non-modal (modeless) dialog, with READ EVENTS.  The same as PromptN, but this action also causes the wrapper function to execute a READ EVENTS, so it doesn't return until the form is closed, which triggers a CLEAR EVENTS.  Consequently, the wrapper function's return value does provide a meaningful success flag result in this mode.  This is primarily intended for standalone testing purposes, in order to avoid problems due to limitations in VFP's RETURN TO ... mechanism, which can affect some abnormal error handling situations.

Run

Restores a previously saved configuration and runs the transformation, non-interactively.  In this case, the form is deliberately hidden from view, except for its progress messages in the status bar and WAIT window.  The Run action bypasses the usual state-saving logic, so the saved configuration will not be altered, even if overriding input/output file arguments were supplied.

RunC

Clones and Runs.  First this clones the associated template output file belonging to a previously saved configuration, and then it runs the transformation non-interactively.  If an explicit output file argument is supplied, this will be the output destination.  The RunC action bypasses the usual state-saving logic, so the saved configuration will not be altered, even if overriding input/output file arguments were supplied.

Return Value

XFormDBF returns a success flag result, which is set to .T. only if completely successful.  In cases of errors, a mechanism is provided for obtaining detailed error information.

Copyright © 2000 - 2002, SpaceTime Systems