Compiled Reports

Chapter 16 - Deploying Your Report
Mastering Crystal Reports 9
by Cate McCoy and Gord Maric
Sybex 2003

Compiled reports are reports that are compiled into an executable program that can be installed on the end user’s computer. The end user does not need a copy of Crystal Reports to view the report and will be able to view, refresh, and schedule running the report on a desktop.

Crystal Reports contains a Distribution Expert that guides you through the steps to create a setup package for the end user’s computer. The Compiled Report utility and Crystal Report Distribution Expert are part of Crystal Reports 7. In version 8 and 8.5 it is a separate add-on utility that you need to download from the Crystal Decision website.

Warning 

As of this writing, the compiled deployment utility is not available for Crystal Reports 9, and the version 8 utility does not work with Crystal 9. Crystal Decisions indicated to the Crystal Decisions User Group of North America, http://www.cdugna.org, that they will make compiled reports available for version 9. Crystal Decisions have also indicated that their preferred choice for deployment is web based using the Report Application Server or Crystal Enterprise, and as a result we don’t expect functionality to be added when the compiled report utility for Crystal Reports 9 is released. If you have version 7 or 8 of Crystal Reports, you can follow our examples. If you have version 9 this will give you an overview of the capabilities of the compiled report utility so you can decide if you would like to wait for it to be released or use one of the alternative deployment techniques discussed.

Tip 

The Crystal 8 compiled distribution tool, SCR8_distr_expert.exe, can be downloaded from http://support.crystaldecisions.com/updates. Also, keep an eye on this Internet support database for the version 9 compiled deployment tool.

The pros and cons of this type of deployment are shown below:

Pros	Cons
Easy to deploy.	Less functionality than Crystal Enterprise.
Free distribution of report.	Requires files to be installed on the end user’s computer.
Users cannot change report.	Requires a Crystal Developers license to compile reports.

The remaining chapters in Part 4, “Application Development with Crystal Reports,” reveal how you can create a customized application to deploy Crystal Reports using VB 6 or VB.NET. You can duplicate the compiled report’s functionality and add your own functionality. Creating and compiling a report using the Crystal Reports compiled report utility is a multistep process:

1. Download and install the Compiled Report utility if you’re using Crystal Reports 8 or greater.

2. Compile the report.

3. Create a setup program to install on the end user’s computer.

4. Install the Compiled Report package on the end user’s computer.

We expect the functionality of version 9.0 to be identical because Crystal Decisions has stated that they want customers to migrate to Crystal Enterprise and their web-based technology. However, they don’t want to abandon customers that still want to use this older technology. They will continue to support them.

Installing the Compiled Reports Utility

Once you download scr8_distr_expert.exe, copy it to a directory on your computer and double-click it. Scr8_distr_expert is a self-extracting zip file, and it will extract itself into three files:

• Compiles_reports.pdf: contains program documentation.

• Rdwiz.exe: contains the setup program.

• Readme.txt: contains licensing information and indicates what versions of Crystal this utility is for.

  Note 

  Crystal Licensing requires that you have the Developer Edition to use Compiled Report utility.

Double-click the rdwiz file to start the installation process. When the installation is done, start Crystal Reports and click the Report menu. Notice that Compile Report and Report Distribution Expert have been added to the bottom of the menu (see Figure 16.13).

Figure 16.13. New items added to the Report menu

Compiling a Report

Once your report is complete and you are ready to give the report to the end users, save the report and choose Reports > Compile Report. You will see the Compile Report dialog, as shown in Figure 16.14.

Figure 16.14. Compile Report dialog

In the Compiled File Name text box, specify the directory and report name for the compiled report. Crystal reports will provide a default filename the same as the report name.

Tip 

To avoid confusion, we recommend that you keep the compiled filename the same as the report name.

After this step is finished, Crystal will create three filenames in the directory you specified:

• RPT file: report file

• EXE file: program to run and view the report

• CRF file: configuration file required by the EXE file

It is important that all three files have the same name, and the name cannot be setup.exe.

To determine whether a program group will be created off the Start menu, choose one of the Create A Program Item For The Report options. If you choose Yes, an icon link to your compiled report will be placed in the program group specified. If a program group does not exist, it will be created. If the program group does exist, an icon link will be added to the program group.

Tip 

If you choose not to create a program link, then you can create a shortcut using Windows.

Choose Yes under Distribute The Report After to run the Distribution Expert, which will build the necessary setup files to install the compiled report on the end user’s computer. If you choose No, you can run the Distribution Expert at a later time by choosing Report >Report Distribution Expert.

Distribution Expert

The Distribution Expert creates the Setup.exe program and installs all the required files to view and run Crystal Reports on the end user’s computer.

After you have compiled the report, the Distribution Expert will start automatically if you selected Yes in the Distribute The Report After options in the Compile Report dialog (see Figure 16.14). Otherwise, you can start the Distribution Expert by choosing Report >Report Distribution Expert.

The Distribution Expert consists of four tabs that must be completed before the distribution files are created. These tabs are detailed in the following sections.

1. Options

The Reports field contains a list of reports that will be added into this distribution (see Figure 16.15). Click the Add button to add other reports to this distribution if you are going to deploy multiple reports.

Figure 16.15. Report Distribution Expert - Options

Note 

Make sure each report is compiled before adding it to the Reports list.

Select a destination directory where the setup programs and reports will be placed.

If this is the first time you are installing a compiled report on the end user’s computer, we recommend selecting both Include Database Files(s) Used By Report and DLLs For Exporting. These options will ensure that the end user has all the necessary files to run the report.

Note 

Crystal Reports requires many support programs in order to run and view reports. Those programs are called Dynamically Linked Libraries (DLLs). They are automatically installed when you install Crystal Reports. However, because we want to view reports on a computer where Crystal Reports is not installed, we need to include them in our distribution. You will see a list of these files in the File List tab.

Warning 

Be careful about distributing third-party DLLs without first checking the license agreement with the vendor that created them. Crystal Decisions has a royalty-free license agreement.

2. File List

The File List tab provides a list of all the files that will be included in your distribution, including the export DLLs and database files mentioned above (see Figure 16.16). In this screen you have the option of adding and removing any DLLs in your distribution.

Figure 16.16. Report Distribution Expert - File List

Tip 

This list can be very intimidating because you may not know which files to touch. We recommend leaving the files alone and clicking the Next button. Refer to the section below on testing the deployment for how to deal with these files if necessary.

3. Third Party DLLs

This list is similar to the File List tab’s list above, except that it is a list of required files that are not from Crystal Decisions but from other vendors (see Figure 16.17). These files can include files such as database drivers.

Figure 16.17. Report Distribution Expert - Third Party DLLs

Tip 

Again we recommend leaving the files alone and clicking the Next button. Refer to the section below on how to test the deployment for how deal with these files if necessary.

4. Distribution

The Distribution tab is the final step in your distribution (see Figure 16.18). The Distribution Expert should display a screen saying it is ready to build the distribution program. At this point all you need to do is click the Build button, and the Distribution Expert will package up all the DLL, RPT, report EXE, and CRF files and create a Setup.exe file that you can run on the end user’s computer.

Figure 16.18. Report Distribution Expert - Distribution

Installing the Compiled Report on the End User’s Computer

At this point, the Crystal Decisions Distribution Expert has created an installation program called Setup.exe in the destination directory you specified in the Options tab above. This directory also contains all the DLLs and files that your report will require.

Warning 

Before you roll out your newly created installation program to your entire organization, we suggest testing it on one user’s computer to make sure everything works as expected.

To install the compiled report on the end user’s computer, run the Setup.exe program from the end user’s computer. If your destination directory was on a network drive and your user also has access to this destination drive, then run the installation in the distribution directory from the end user’s computer.

Tip 

If you have a CD burner, it might be easier to burn a CD with the contents of the distribution directory and run Setup.exe from the CD on the end user’s computer. This will also provide a backup disk.

The installation program is a standard Windows-type installation program. You will be asked to do the following:

• Specify the installation directory. The default directory is C:\Program Files\Seagate Software\ Distributed Reports. If this is okay, click Yes to continue; otherwise, choose an appropriate directory.

• Choose the program group that will be created off the Start menu for Windows. If the program group exists, the report will be added to it. Otherwise, the group will be created and the report added. The default program group name is Seagate Crystal Reports Distribution.

Running a Report

From the Start menu, select > Programs > Seagate Crystal Reports Distribution and select the name of the report you would like to view. The compiled report viewer allows you to view, export, or print your report immediately or at a scheduled time in the future (see Figure 16.19).

Figure 16.19. End-user report viewer

In the Report drop-down list, select where you would like the report to be displayed. You must choose from viewing the report in a window on your computer, exporting it to a different format, or exporting it to a printer. Depending on the output destination you choose, the button in the middle of the screen will change and allow you to format your destination:

• If you choose the Print The Report To A Window option, you will be able to customize the report view (see “The Report Viewer” section below).

• If you choose the Export The Report option, choose which format you want to export the report in and the destination. These are the same export options as discussed earlier in the chapter.

• If you choose the Print The Report To A Printer option, the report will be sent to a printer of your choice.

The unlabeled drop-down list beside the Report drop-down allows you to select when you would like to run the report. The default is Right Now. Click the Print button and the report will run right away.

Notice beside the Print button the Use Saved Data and Refresh Data buttons. If your report contains saved data, you will be able to view the saved data. The report will access the database source when you refresh to get the latest information.

Scheduling the Report

By selecting Right Now in the drop-down box, you can see your options to run the report in the future. Crystal has created some standard future times, such as in one hour, at midnight, at two in the morning, etc. If none of these meets your requirements, you can choose At A Specific Time and enter the time and date when you want to run the report.

When you click the Print button, the report viewer will minimize and wait for the time indicated to run the report.

Note 

Keep in mind that the report is running on the computer where the report viewer is installed, so the computer must remain on.

Changing the Report Selection Criteria

If your report contains selection criteria, you may choose Modify Selection Formula. The report viewer will display a Record Selection dialog (see Figure 16.20), allowing you to choose how you would like to filter the report.

Figure 16.20. Changing the selection criteria

The Report Viewer

When you choose the Print The Report To A Window option, the report is displayed in a report viewer (see Figure 16.21). The report viewer is similar to the report viewer in Crystal Reports, but it does not allow you to change the report.

Figure 16.21. Report viewer

The toolbar at the top of the viewer allows you to navigate through the report, print the report, or export it to another format. You can customize the toolbar in the report viewer by clicking the Window Styles button to bring up the Window Style Options screen (see Figure 16.22). This will allow you to choose which viewer options you want to make available.

Figure 16.22. Report viewer Window Style Options screen

Testing and Troubleshooting the Installation

If you are deploying your report to many users, it is best to test your installation package on one user’s computer until it works. If the installation package works on your computer, there is no guarantee it will work on the end user’s computer. There are two main things that can go wrong:

Database connection The connection information is contained in the report. When you move the report to the end user’s computer, that computer must have the same access setup as the computer where the report was created.

If the report was created from a Microsoft Access database, the end user’s computer must be able to access the Access database, and it must be in the same path as the computer where the report was created.

If the report was created from an ODBC database source, then the ODBC DSN must be configured the same way as the computer where the report was created

If you are using OLE/DB or native drivers to connect to the database, the user must have the same drivers installed on their computer. You may be able to deploy those by including them when compiling your report package. Or you might need to install them separately using the vendor’s installation tool.

Missing DLL If the report is using a DLL, it is easy to forget to include that DLL in the deployment package. Crystal Reports will provide a message saying that it is unable to find a required DLL. Re-create the deployment package including the missing DLL, and retry the deployment. You may need to do this a few times until it works.

Sometimes if the DLL is part of database connectivity, such as Oracle’s SQL*Net, it is better to install the necessary database driver’s DLLs, called middleware, from the vendor’s CD and retry running your report.

We hate to be vague on the issue of testing and troubleshooting; however, it is very difficult to write about all the different problems that can happen. Unfortunately, it comes down to trial and error. That is why we emphasize testing the deployment on one end user’s computer before deploying to your whole organization.

Note 

The grief involved in testing and debugging on each user’s computer is one of the main drivers of Internet deployment. With Internet deployment, you only need to get the report to work on the web server, and all your users need is a web browser. However, this is not feasible for all users, so we still need to deal with installation issues.

Use of content on this site is expressly subject to the restrictions set forth in the Membership Agreement

Conello © 2000-2003     Feedback