Preliminary Notes About the Generic Reporter Application
	By M. Asherman, 11/27/99

	Intro:

The Reporter application is a generic table-driven facility for defining canned reports and "COPY TO" operations.  It supports actions to Create, Modify, or Run a canned report, with optional user-defined arguments.  To get a quick overview, start by running the following VFP command:

	? reporter()
	
This will bring up a report destination dialog corresponding to the first sample report.  To view the sample report definitions, exit from the preceding dialog and browse the table that was implicitly opened (alias reportdf) by the previous command.  See the Notes memo field for each of the sample reports.  You will find it useful to make use of VFP's browse preferences to open up a bunch of memo windows and adjust their sizing and placement, so that BROWSE LAST will restore this arrangement.

Note that the reporter() function is really just a wrapper for the Reporter class (in reporter.vcx).  Developers may wish to use the pure class-based interface in order to exercise greater control over the choice of meta-file and data session.

To clean up after testing reporter() without closing out the current VFP session, use the this command:

	_screen.removeobject('reporter')

This will release the default Reporter object and close the meta-file.  This is mainly useful during development and testing of the Reporter facility itself, to avoid "class is in use" errors. 

	Currently available documentation:

- annotated examples are in the sample meta-file, reportdf.dbf (see Notes field)
- run reporter('run', 'demotest13') for report of sample meta-file contents
- brief descriptions have been attached to all files in reporter.pjx
- there are DBC-based field comments for all meta-file fields (in reportdf.dbf)
- note that certain generic mdacomm functions are employed in the meta-file
- all programs are liberally commented

	Related outstanding issues and tasks (* indicates it can wait):

- support improved error-handling by using the generic MDA ErrHandler class
- use VFP's newobject() function and method where appropriate
	To avoid annoying hassles with older SET CLASSLIB + add/createobject() approach.
- add more global mvars for easy access to current report_id and Reporter object
- provide more conspicuous summary documentation of available action codes
	Really should have a block of comments in reporter.prg and reporter.init.
- automatically re-open the meta-file if it gets closed
	As a convenience, in case of heavy-handed cleanup logic.
- cleanups to reptdest.scx dialog - compare with newer querdest.scx in Querier
	Putfile arg1 gets truncated in Windows 95.  Probably should make this a more modular, generic dialog along same lines as querdest.scx, etc.
- additional documentation on usage, overall design, and meta-file maintenance
	There is a simple mode of usage provided for development and testing, as well as a mode of usage for inclusion of this facility into an application.  An effort has been made to allow for clean, modular integration of the Reporter facility into any kind of VFP application.
- add a convenient option governing temp setting of SAFETY ON/OFF
	This would make it easier to support a per-report option as to whether the user should be prompted before replacing an existing file.
- support optional default file extension for use in prompt for File output
	Minor, but this would be a nice touch for Report/Label Run cases.  Note that optional default extension is already supported, however, for COPY TO ... mode; this is done by treating outdestexp as a default extension for prompting when it evaluates to a result that starts with a period.
- be sure to preserve initial record position (as well as selection) in all cases
	Logic needs to be double-checked for cases where the report is run against an already open table.  The general objective is to minimize unintentional side-effects of running a report.
- try to get WIDTH <ncols> option working for Quick Report creation, if possible
	For easy auto-creation of wide tabular reports.  This used to work in FoxPro for DOS, but seems to have no effect in VFP 6.0.  Appears to be an undocumented regression in VFP, so this may be a lost cause until Microsoft fixes it.
- provide tie-ins to VFP Report/Label Wizards
	In addition to the rudimentary, non-interactive Quick Report mechanism already supported, it would be convenient to have an option to launch VFP's interactive Wizards.  This feature requires that the user has the VFP Development System, not just the VFP runtime environment.
- support multiple copies specification via separate meta-file field
	Maybe could be done via the _pcopies system variable.
- support 1st page/last page specs via separate meta-file field(s)
	Maybe could be done via the _pbpage/_pepage system variables.
- give some more examples of reports to demonstrate all supported features
	E.g. illustrate use of the DELETEDEXP meta-file field for controlling deletion hiding behavior during a report.  Also should have an example of a report against an SQL view, which is already supported via the usetable() UDF, but hasn't yet been tested.
*- support settings for any useful VFP _Printer-related system variables
	This feature is described as obsolete in VFP 6's Help, but it may provide some convenient hooks to control more handy report-related option.  Will require some experimentation.
*- investigate other ways to control reporting options
	Look into what can be done with the NAME <ObjectName> option, which gets an object reference to the data environment of a report.  This may not be too useful, however, since we can handle database setups without relying on the data environment.
*- simple mechanism for conditional database open/close
	Make it easier to support logic that opens and closes only if not already open by adding a property to flag whether table or view was already was open, and using this in both initexp and cleanupexp logic.
*- provide a way to record failure of cleanupexp
	Obscure refinement: supply a property in Reporter class object for recording whether the cleanupexp evaluation was successful, since a failure in this step does not show up as a failure in running the report.
*- create a form-based user interface to the report definitions meta-file
	In the present implementation, the user is expected to manipulate the meta-file directly through a VFP Browse window.  This is not too bad if you make use of VFP's Preferences mechanism (e.g. with BROWSE LAST), to save the layout with memo windows opened, sized, and positioned properly.  Of course you also need to have a good understanding of the meta-file fields and handy techniques for working with it from VFP command level.  Ideally, however, one would want a more traditional form-based interface, and something suitable for runtime users.
*- meta-file based mechanism for setup/cleanup of database setups
	The current implementation of Reporter makes use of some simple generic UDFs in the initexp and cleanupexp fields to handle this.  (See the functions usetable(), docmd(), and ifcmd(), for example.)  A more general apprach would be to support UDFs that make use of a separate (generic, of course) meta-file exclusively devoted to the problem of opening and closing databases, tables, and views, and handling all of the related options that pertain, e.g. ordering, filtering, SET SKIP, SET RELATION, etc.  Some additional aspects to consider are a reference count mechanism and the concept of nested database setups.  I've created such a facility in the past (under VFP 3.0b), but I'd want to break it out from my old framework and clean it up before reincarnating these programs.
*- table-driven report layout definition mechanism
	For creation of new reports without requiring the user's knowledge of VFP's .FRX file formats, but presumably this detailed knowledge would need to be understood by the program.  This is a big can of worms, which may be best left to simply using VFP's Report Wizards.

	General conventions:

@- maintain clean copies of selected files in shared mdacomm directory
	For Reporter, the files copied into mdacomm are reporter.app/vcx/vct/txt.
@- maintain thorough error-handling provisions
@- avoid unnecessary direct cross-app dependencies by making use of mdacomm
@- all apps should avoid potential name conflicts in case moved into mdacomm
	E.g. avoid file names like "notes.txt" in favor of "<appname>.txt".

	Change history:

990512 add a sequence number (SEQ) for convenient user-defined ordering of meta-file
990512 add user-defined field, layoutid, for hook into app-specific extensions
990512 support user-defined name for timestamp field via macro FNAM_DTMOD in mdacomm.h
990512 adjust logic to return failure result if the Run action fails or is cancelled
990512 avoid use of PUTFILE's 1st argument, since this is too restricted under under Windows
990512 add usage comments to wrapper function reporter.prg
990513 add support for a COPY TO ... flavor of reporting based on new COPYTOMODE field
990513 sample report definition for COPY TO ... mode (report_id = demotest14)
990513 rename reportdf1.FRX/FRT to reportd2.* to avoid long file name (meta-file report)
990514 massage report format for reportd2.frx (meta-file report)
990514 adjust field notes re new COPYTOMODE usage affecting outpoptexp, outdestexp, etc.
990514 avoid all needless use of long file names in sample report forms
990514 supply brief descriptions for all files in reporter.pjx
990615 avoid including "ADDITIVE" in REPT_CLIB macro
990615 renamed this file from "notes.txt" to "reporter.txt" and massaged contents
990925 make adjustments for move from M: to D:
	- adjust icon for launching VFP to start in dir on D:... and use -cd:... option
	- open .pjx and tell dialog OK to move it from M: to D:
990925 new reportdf fields queryid and xformid for linking to Querier and Xformdbf
	Reporter doesn't use these fields, but they are provided for the user's convenience, e.g. to associate a report definition with a query and transformation step.  Unfortunately VFP requires that browse preferences (useful for meta-file maintenance) be reconstructed manually after DBF structure changes.
990925 adjust lingering references to drive M: in Reporter examples
	Avoid needlessly hard-wired drive letters and absolute paths.  Requires changes to initexp for demotest03, 5, 6, 7, 8, 9, 10, 11, 12, mtd.
990926 **** UPLOADED CHANGES TO BT SERVER'S D:\REDP\APPL\REPORTER\ & ...MDACOMM\ ****