Crystal Report Engine Automation Server

The Crystal Report Engine Automation Server has been designed as both an object-oriented approach to adding Crystal Report Engine features to your applications, and as an ideal method for displaying reports in web pages. If you work in a development environment that supports access to COM-based automation servers, such as Visual Basic, you will quickly make full use of the Crystal Report Engine Automation Server to add powerful reporting to your applications. In addition, if you manage a web server that supports Active Server Pages, such as Microsoft’s Internet Information Server (IIS) or Personal Web Server, the Crystal Report Engine Automation Server satisfies all of your dynamic reporting needs.

Seagate Crystal Reports provides both 16-bit (CPEAUT16.DLL) and 32-bit (CPEAUT32.DLL) versions of the Crystal Report Engine Automation Server, depending on the version of Seagate Crystal Reports you installed. The Crystal Report Engine Automation Server was installed in your \WINDOWS\SYSTEM directory when you installed Seagate Crystal Reports.

The Crystal Report Engine Automation Server is an in-process automation server based on the Component Object Model (COM). This automation server provides an IDispatch interface, but is not programmable through a vtable interface. For Visual Basic programmers and in Active Server Pages, handling the IDispatch interface is almost transparent. For more information on the Component Object Model and COM interfaces, refer to Microsoft documentation.

The following topics are discussed in this section.

Adding the Automation Server to your Visual Basic Project, Page 111

Using the Automation Server in Visual Basic, Page 112

Object Name Conflicts, Page 114

Viewing the Crystal Report Engine Object Library, Page 115

Handling Preview Window Events, Page 115

Distributing the Automation Server with Visual Basic Applications, Page 117

Sample Applications, Page 117

Adding the Automation Server to your Visual Basic Project

Before you can use the Crystal Report Engine Automation Server with a Visual Basic project, it must be registered on your system, and you must add it to your project. If you selected to install Development Tools when you installed Seagate Crystal Reports, the automation server will have already been registered on your system. If you did not select Development Tools, run the Seagate Crystal Reports setup application again, select Custom installation, and make sure Development Tools are installed.

NOTE: The following procedures demonstrate the use of the Report Engine Automation Server in versions 5.0 and later of Visual Basic. For information on using automation servers in earlier versions of Visual Basic, or in other development environments, please refer to the documentation that came with your software.

Visual Basic Solutions

111

To add the automation server to a project in Visual Basic versions 5.0 or 6.0, use the following procedure:

1With your project open in Visual Basic, choose REFERENCES from the Project menu. The References dialog box appears.

NOTE: For complete information on adding ActiveX components to a project, refer to your Visual Basic documentation.

2The Available References list box shows all available component object libraries currently registered on your system. Scroll through this list box until you find the Crystal Report Engine 7.0 Object Library. This is the Crystal Report Engine Automation Server.

NOTE: If the Crystal Report Engine Object Library does not appear in the Available References list box, use the Browse button to locate and select the Crystal Report Engine Automation Server (CPEAUT16.DLL or CPEAUT32.DLL) in your \WINDOWS\SYSTEM directory.

3Toggle on the check box next to the Crystal Report Engine 7.0 Object Library reference. This makes the Crystal Report Engine Automation Server available to your project.

4Click OK in the References dialog box.

Using the Automation Server in Visual Basic

There are five primary steps to using the Crystal Report Engine Automation Server in your Visual Basic project:

1.Creating an Application Object, Page 112

2.Obtaining a Report Object, Page 113

3.Using the Report Object, Page 113

4.Releasing Objects, Page 114

5.Handling Errors, Page 114

Creating an Application Object

The Application object in the Crystal Report Engine Automation Server’s object library is the only object that can be created. Using the Application object, you can obtain a report object by opening a report file, manipulate aspects of the report object, such as select formulas and sort fields, then print or export the report.

Since the Application object is the only creatable object exposed by the Crystal Report Engine Automation Server, you must create an Application object before you can perform any other tasks using the Crystal Report Engine. Use code similar to the following to create an Application object in your Visual Basic project:

Dim app As CRPEAuto.Application

Set app = CreateObject(“Crystal.CRPE.Application”)

Visual Basic Solutions

112

Alternately, you can use the following code:

Dim app as New CRPEAuto.Application

Crystal.CRPE.Application is the Application object’s ProgID (programmatic identifier). Visual Basic uses this ID to create an instance of the Application object, which can then be used to obtain a Report object. For a complete description of the CreateObject function, refer to your Visual Basic documentation.

Obtaining a Report Object

You obtain a Report object by specifying a Seagate Crystal Reports (.RPT) file and opening it with the OpenReport method of the Application object:

Dim report As CRPEAuto.Report

Set report = app.OpenReport(“c:\reports\xtreme.rpt”)

The OpenReport method has only one parameter, the path of the report file you want to access. By setting a report object according to the return value of this method, you can proceed to manipulate, print, preview, or export the report using other objects, methods, and properties available in the Crystal Report Engine Automation Server’s object library.

Using the Report Object

Once you obtain a Report object, you can use that object to make runtime changes to the report file, then send the report to a printer, a preview window, a disk file, an e-mail address, an ODBC data source, or a group folder in Microsoft Exchange or Lotus Notes. Note that the changes you make at runtime are not permanent; they do not change the original report file, they only affect the output of the report during the current Crystal Report Engine session.

Through the report object, you obtain access to different aspects of the report file, such as selection formulas, subreports, sort fields, and format settings. For example, the following code changes the record selection formula for the report:

report.RecordSelectionFormula = “{customer.Region} = ’CA’"

Refer to the reference section of this manual for complete information on all objects, properties, and methods available in the object library and how to use them.

Once you make all desired changes and review settings for the report using the functionality available in the automation server, you can print, preview, or export the report just as you do from Seagate Crystal Reports. The automation server provides default settings for these activities, or you can specify your own settings. The simplest technique for sending the report to a printer would look like this:

report.PrintOut

Without receiving any parameters, the PrintOut method simply sends the report to the default printer with default settings. For more information about methods for the Report object, search for each method by name in Developer’s online Help.

Visual Basic Solutions

113

Releasing Objects

Visual Basic will clean up any objects that have not been released when your application terminates. However, since objects use memory and system resources that can not be accessed by other running applications, you should get into the habit of releasing any objects when you are finished with them.

To release an object, simply set it equal to Nothing:

Set report = Nothing

Set app = Nothing

Handling Errors

Error trapping for the Crystal Report Engine Automation Server can be handled just like normal error trapping in Visual Basic. When an error occurs in the automation server, the error is sent to Visual Basic which sets the properties of the Err object appropriately. To avoid runtime problems, you should trap for errors inside your Visual Basic code. A typical error trapping routine might look something like this:

On Error GoTo HandleError

’Several lines of

’Visual Basic code HandleError:

If (Err.Number <> 0) Then MsgBox (Err.Description)

End If

The advantage of handling automation server errors like this is that they can be handled at the same time other Visual Basic errors are handled, making your code more efficient and easier for other developers to understand.

Object Name Conflicts

Some object names in the Crystal Report Engine Object Library may conflict with object names in other object libraries attached to your Visual Basic projects. For instance, if your project includes the Data Access Objects (DAO) Object Library, the DAO Database object can conflict with the Report Engine Object Library’s Database object. Another common name conflict can occur between the Report Engine’s OLEObject and the RichTextLib OLEObject control. Such name conflicts can produce errors in your applications.

NOTE: RichTextLib is a component included with some versions of Visual Basic.

To avoid name conflicts, you should append all references to Crystal Report Engine Object Library object names with CRPEAuto, the name of the object library as it appears in Visual Basic. For instance, the following code can be used to create a Report object:

Dim rpt As CRPEAuto.Report

Set rpt = app.OpenReport(“c:\reports\xtreme.rpt”)

Object names in other object libraries should also be appended with an object library name. For instance, the DAO Database object could be appended with DAO:

Dim db As DAO.Database

Visual Basic Solutions

114