Distributing RDC Applications | Crystal Reports 10: The Complete Reference

After you create an RDC application that integrates Crystal Reports, you ll want to compile and test the application. This process is unchanged with Crystal Reports 10. Unless you re using the application only for yourself, you also need to set up a distribution mechanism to pass your application to your intended audience: the application users.

Because you are distributing Crystal Reports features and components with your VB application, some distribution issues come into play. This section of the chapter discusses both the general points you want to keep in mind when creating your distribution package and specific areas that concern certain reporting features you may want to include or exclude from your application.

Distribution Overview

The days of creating a single .EXE executable file that can be easily copied to a single floppy disk are long gone. Standard Visual Basic projects already consist of the main program executable file, run-time files, and a host of support files. Introducing Crystal Reports into the mix adds a fairly large burden to this process. Because Crystal Reports is designed in a very modular fashion, it s easy to add functionality and upgraded features to the tool. However, this modularity also complicates the distribution process because so many different files are involved in the overall Crystal Reports product.

If you prefer to integrate external .RPT files with your RDC application, rather than using the ActiveX designer within the VB IDE, you must include those .RPT files in your distribution package. A variety of support files also are required, depending on several issues such as the database connections the report uses and the export capabilities that the project entails. The best part is that this is all handled pretty much automatically if you use Visual Basic distribution tools to create your distribution package.

In addition to available third-party distribution products, such as InstallShield and Wise, Visual Basic 6 includes the Package and Deployment Wizard, and Visual Basic 5 includes the Application Setup Wizard. All of these tools are designed to gather all the necessary executable and support files required for a project, compress them into a smaller space, and add them to a setup program. When the setup program is run from floppies or a CD-ROM, run from a network share, or downloaded from a web server, all the necessary files are decompressed and installed in the proper locations.

Note	Specific instructions for using these distribution tools can be found in the documentation accompanying them ”this chapter will not teach you how to distribute VB applications. Examples in the chapter are based on the Visual Basic 6 Package and Deployment Wizard.

Distribution tools, such as the Package and Deployment Wizard, look through your VB project file and attempt to determine all the necessary files that must be distributed with the project. Depending on the different RDC libraries and modules you have chosen for your application, a different set of files needs to be included in the distribution process. Having a fundamental understanding of this process will help you tailor your project s distribution, based on its individual needs.

Most tools use dependency files to determine what files to include in your distribution package. These files consist of the same base filename as the file used to provide Crystal Reports integration, but contain a .DEP extension. For example, the dependency file for the combined design-time/run-time RDC library (CRAXDDRT.DLL) is CRAXDDRT.DEP. The dependency file is a straight ASCII text file that you can open with Notepad, containing a list of all related DLLs or other files that the base file is dependent upon. The distribution package uses the dependency file to include all necessary files (and, in most cases, several that are unnecessary) when the VB application is packaged. If you create VB projects on a regular basis, you may want to customize the appropriate .DEP files to include additional files or exclude files that your applications don t need.

If you let your distribution tool work with default options, you most probably will include necessary files for your application. Simply taking the default options has two potential disadvantages, though:

More files than you actually need may be included, which likely is a minor inconvenience, eating up a bit more disk space than you really need to use.
Necessary files may not be automatically detected , which means the application won t work correctly.

By reading on, you ll learn how to selectively remove unnecessary files that are included automatically. However, only by carefully considering your individual application, and the files that it ultimately requires, will you avoid the second problem. In all cases, the rule of thumb is to test and then test again ”always try installations on a clean machine (similar to what your end users will have in place) to ensure that all files are being installed correctly. Simply installing the package on your development PC (which already has a complete copy of Crystal Reports Developer or Advanced Developer Edition on it) won t be a sufficient test ”you won t detect any missing elements that may be required on a user machine without Crystal Reports already installed.

The RDC is unique among integration methods in that it doesn t use external .RPT files, unless you specifically choose to use them over the internal ActiveX report designer. Report definitions are actually contained in the ActiveX designer (.DSR) files that are added to the project. Because these are an integral part of your application, VB will compile the .DSR files and include them automatically in the project s executable. In addition, the other COM components that make up the RDC will be included in the project.

In particular, the CRAXDRT.DEP or CRAXDDRT.DEP dependency files will include all necessary COM components for the RDC libraries. If you are using the ActiveX Report Viewer to view your reports in a form, CRVIEWER.DEP will be used to include its necessary components. While you probably won t have to worry about including external .RPT files, make sure any required database files are included in your package. You may also want to remove some unnecessary database or export-support files to save disk space.

Tip

In some cases, the Package and Deployment Wizard won t be able to find all necessary files. Crystal Reports 10 stores many libraries in \Program Files\Common Files\Crystal Decisions\2.5\bin. You may need to manually locate files in this folder, or use the Windows Explorer Search function to find them.

Tip	Business Objects includes an online Help file that contains a complete discussion of run-time file requirements. Open the RUNTIME.CHM file from \Program Files\Crystal Decisions\Crystal Reports 10\Developer Files\Help\<language> .

Database Considerations

The databases that your reports use must be considered when you are deploying your VB application to end users. Obviously, you need to ensure that each end user is able to connect to the database that the reports require. This may be a PC-style database distributed along with the application, a database shared on a common LAN drive, or a client/server database accessed through either a native Crystal Reports database driver or ODBC. You also need to include only the .DLL files specific to the database and access method being used by your reports. Although it won t necessarily hurt to include database driver DLLs for Microsoft Access in your project, even if your reports all connect to an Informix database via ODBC, you can save disk space by eliminating any unnecessary database drivers.

Direct Access Databases

If your reports use a PC-style database, such as a Microsoft Access .MDB file or a dBASE for Windows .DBF file, you ll want to make sure that the reports will be able to locate the database when the application is installed. If these files were installed on the C drive when you designed the report, but will reside on a network F drive when the end user runs the application, you need to make sure the reports can still find the file. You can either execute calls inside your VB application to change the data-source location of the reports, or use the Crystal Reports Database Set Datasource Location command in either Crystal Reports or the RDC ActiveX report designer to point to a different database before distributing the application. You may prefer using the Same As Report option from the Set Datasource Location dialog box to have the report look in the same drive and directory as the report for the database. In this scenario, you need only ensure that the database and reports reside in the same place, regardless of drive or directory, for the reports to be able to locate the database.

You may be able to save disk space by including only the necessary database drivers for your particular Direct Access database. If, for example, you are using only reports that connect directly to a Microsoft Access database, you don t need to include all the other database drivers in your distribution package. Look in the RUNTIME.CHM file to determine the core set of database drivers required for the particular method your reports use to connect to the database. If you exclude other database drivers, make sure you test your installation on a machine similar to those found in your end-user environment, to make sure all necessary drivers are being included.

ODBC Data Sources

As a general rule, ODBC is used to connect to centralized client/server databases (although some desktop databases you distribute with your application still may use ODBC as the connection method). Therefore, you probably won t have to worry about distributing the actual database with your application. However, you need to make sure that an ODBC data source is set up so that the report will be able to connect to the database from your end user s machine. Your VB application may take care of this automatically if the application itself will be accessing the same ODBC data source. Also, if your report will be using the Active Data driver to connect to a Data Access Objects (DAO) or ActiveX Data Objects (ADO) record set in the application, special provisions probably won t need to be made.

If your report is the only part of the application that will be using a particular ODBC data source, make sure that the setup application creates the correct ODBC data source. You may even need to install ODBC as part of your setup program, if there s a possibility it won t already be installed on the end user s machine.

You also save disk space if you eliminate other Crystal Reports database drivers that won t be used in your application. Look in the RUNTIME.CHM file to determine which ODBC drivers will be required for the particular ODBC data source and database your reports use. Once you exclude other database drivers, make sure you test your installation on a machine similar to those found in your end-user environment, to make sure all necessary drivers are included.

File Export Considerations

The Xtreme Orders sample application that is used in this chapter allows three output destinations to be used: the preview window, the printer, and a .PDF file attached to an e-mail message. Both exporting the report to a .PDF file and selecting e-mail as the output destination create additional file requirements when you distribute the application. Because Crystal Reports is designed with a modular framework, both the file type (PDF, Word, Excel, HTML, and so on) and output destination (disk file, MAPI e-mail, Exchange public folder, and so on) functions are provided in separate .DLL files. If you are using these export formats and methods, make sure the correct files are included in your application.

Conversely, if you are using only a few output types and destinations, or perhaps none at all, you ll save disk space by eliminating these DLLs from your distribution package. Crystal Reports output destinations are provided by U2D*.DLL files. Output formats are provided by CRXF*.DLL and U2F*.DLL files. There are a few additional requirements for certain picture types when exporting to HTML. Look at RUNTIME.CHM for specifics. You need to include only the formats that you specifically call in your application or wish to have available to your end users if they click the Export button in the preview window.

User Function Libraries

If you use formulas in your report that call external User Function Libraries (UFLs), don t forget to include the external UFL .DLL files when you distribute your application. An external .DLL file is called anytime a formula uses any functions in the Additional Functions list in the Formula Editor. If you fail to include the .DLL file with your application, the formula will fail when the report runs on the end user s machine.

By default, Crystal Reports installs several UFLs with the rest of the Crystal Reports package. These are all included in the dependency files that Crystal Reports supplies , so you generally don t have to worry about manually including the UFL files in your distribution package. However, if you ve created your own UFLs (a supplementary document appears on www.CrystalBook.com describing how to create your own UFLs with Visual Basic), you ll want to either manually add them to your distribution package or modify the .DEP files to include them in all future distributions. You ll also be able to save disk space by removing UFL files that aren t used in any of your formulas.

UFL files generally adhere to the file format U2*.DLL. RUNTIME.CHM contains a description of individual UFL .DLL files and the functions that they provide. If none of the formulas in your report use functions from the Additional Functions list, you can safely remove these UFL files from your distribution package. Again, you should test your installation on a target machine to ensure that your formulas will work properly without the extra UFL files.

Tip	Business Objects has now made available merge modules to help in distribution of RDC applications with third-party distribution tools that make use of Microsoft Installer (MSI). Download the merge modules by navigating to http://Support.BusinessObjects.com/MergeModules.