Including Report Files for Distribution
When you distribute an application, you have a number of decisions to make about how you deploy the reports you have designed to provide application output. This topic describes options for inclusion of report and label definition tables (.frx and .lbx files) and the distributable Visual FoxPro Report System components.
Distributing Report and Label Files
Reports and labels can be included in your project and built into your application (.exe or .app file), or they can be delivered separately on disk.
Tip
You can reference reports and labels in your application project, for easy reference while designing the application, without building the report and label files into the compiled application file. For more information, see How to: Exclude Files from Builds.
Which strategy you decide to use usually depends on whether you want end-users to have the ability to adjust the reports and labels. If the reports and labels are on disk as separate files, your application can provide facilities for end-users to customize them, using the MODIFY REPORT and MODIFY LABEL commands.
Tip
In Visual FoxPro 9, you can offer end-users a customized and safe design experience, by leveraging custom Report Builder dialogs and such features as Report Protection and Report Designer ToolTips, and Design-time Captions. For more information, see Setting Protection for Reports, How to: Add Tooltips to Report Controls, and How to: Add Design-time Captions to Field Controls.
You can use a combination approach, building the reports and labels into your application to serve as read-only output templates, but copying them to disk for end-users' modifications. This approach has the advantage of ensuring that you can revert to a "clean" copy of the original report or label definition file when necessary.
Tip
Using a built-in template also allows you to make some last-minute adjustments to the report or label before an end-user design session. For example, you could adjust protection flags in the editable copy using an application lookup table for user permissions. You might also replace the ToolTips for report controls you use for development purposes, with developer notes, for another set containing end-user instructions. Because you can add extension fields to report and label tables, this programmatic run-time adjustment would be as simple as opening the report or label table with the USE command, followed by a command such as REPLACE ALL ORDER WITH <your extension field>. For more information, see Understanding and Extending Report Structure.
Under some circumstances, Visual FoxPro permits the commands MODIFY REPORT and MODIFY LABEL to be used with the names of read-only report and label files built into the application. When the application's end-user saves the report or label from the designer, Visual FoxPro saves the copy to disk. For this strategy to work, the report and label files must either be in the same folder as the project (.pjx) file or in a folder whose name Visual FoxPro can resolve at run time, relative to the application file (.exe or .app).
For example, suppose your project is in a folder named d:\app and the report form you wish to include is d:\app\reports\my.frx on your development computer. At run time, you install the application file (.exe) to c:\programs\myapp. If you create a reports subfolder, c:\programs\myapp\reports, you can use the command MODIFY REPORT my.frx. When the user chooses to save the report, Visual FoxPro saves the report as c:\programs\myapp\reports\my.frx by default. However, if c:\programs\myapp does not have the subfolder, an error occurs on the MODIFY REPORT command.
You can verify the availability of the subfolder at run time, and use the MD | MKDIR Command if necessary. Alternatively, use the following commands, where lcDir holds the name of a target folder you have previously verified with the user.
SELECT * FROM my.frx INTO TABLE (lcDir + "my.frx")
MODIFY REPORT(lcDir + "my.frx")
This approach puts the process completely under your control. It allows you to configure the target folder to meet the user's needs rather than the project's design-time structure.
Note
When distributing reports, whether built-in or as external files, ensure that all additional required files are available to your application at run time. For example, if your report references an image file, include the image file in your application or distribute the file as a separate file on disk. Ensure that the image file is in the same location in your project's build structure, or in the folder structure of your distributed application on disk, relative to the report file, as it was when you designed the report. Otherwise, Visual FoxPro cannot find the image file when it generates the report. If you choose to build reports into your application, other compiled modules, such as ReportOutput.app or ReportBuilder.app, may not be able to locate the files within your compiled module. You can ensure that the report system components find your files by building in their source files to your application, rather than distributing them as separate applications. The next section discusses your options for distributing these components.
Distributing Report System Components
If you provide end-users with the opportunity to modify reports and labels, you should distribute the Report Builder Application, or your customized version of the Report Builder Application, to ensure that your users have all the advantages of its Report Designer enhancements.
By default, Visual FoxPro looks for a file with the name ReportBuilder.app in the HOME() or startup location. For an executable application (.exe), this location is always the folder where Visual FoxPro's run-time support libraries are installed, such as C:\Program Files\Common Files\Microsoft Shared\VFP. For more information, see HOME( ) Function. If you include the Microsoft Visual FoxPro 9 Report Applications merge module with your application installation Setup programs, as described in the next section, the default ReportBuilder.app installs to the appropriate location on the user's disk.
Warning
Installing any other applications with the names ReportBuilder.app, ReportPreview.app, and ReportOutput.app to the default location of the run-time support libraries is not recommended, since you might install over the default applications required by other Visual FoxPro applications. If you wish to install customized versions of these applications to the default location, use different application names and designate your preferred reporting components by name, in your application, as described in this section.
You can use the _REPORTBUILDER System Variable in your application, or in the configuration file (CONFIG.FPW) for your application, to specify a different location and a different file name for your distributed Report Builder Application. For more information, see Setting Configuration Options at Startup.
When you deploy applications, you have the option to build Report Builder component files into your executable application (.exe) rather than distributing Report Builder Application as a standalone file. For more information, see How to: Specify and Distribute ReportBuilder.App.
To provide Visual FoxPro 9's enhanced output capabilities in your applications, using ReportListener and PreviewContainer objects, you should also distribute the Report Output Application (ReportOutput.app) and Report Preview Application (ReportPreview.app) or suitable replacements. The techniques for specifying the names and locations of these components are the same for all three report applications. For more information, see How to: Specify and Distribute ReportPreview.App and How to: Specify and Distribute Report Output Application Components.
Tip
You can leverage the default ReportListener-derived classes used by the Report Output Application and many of the capabilities of the Report Builder Application separately from the two applications, by using Foundation Class libraries containing identical visual classes. For more information, see ReportListener Foundation Classes, FRX Cursor Foundation Class, and FRX Device Helper Foundation Class.
Distributing additional files for reports and Visual FoxPro's Report System
Visual FoxPro supplies merge modules (.msm files) so you can build distributable Setup programs for your applications and include all the necessary support files. For more information, see Walkthrough: Creating a Visual FoxPro Application Setup Program Using InstallShield. The following table lists the modules of special significance to applications using Visual FoxPro's reporting features.
Merge module file name |
Merge module title |
Remarks |
|---|---|---|
vfp9rptapps.msm |
Visual FoxPro 9 Report Applications |
Installs ReportBuilder.app, ReportOutput.app, and ReportPreview.app to their default locations for executable applications. |
msxml4sxs32.msm msxml4sys32.msm |
MSXML 4.0 |
These module are required for all Visual FoxPro application installations, and are used extensively by the default Report Applications. |
GDIPlus.msm |
Microsoft GDI+ |
This module is required for all Visual FoxPro application installations, and is used extensively by the Report System in object-assisted reporting mode. |