Seagate Crystal Reports™ 7.0

Technical Reference

Volume I - Development Tools

Overview

Seagate Software, Inc.

840 Cambie Street

Vancouver, B.C., Canada V6B 4J2

© 1999 (manual and software) Seagate Software, Inc. All Rights Reserved.

Seagate Software, Seagate, and the Seagate logo are registered trademarks of Seagate Technology, Inc., or one of its subsidiaries. Seagate Crystal Reports, Seagate Crystal Info, Seagate Info, the Seagate Crystal Reports logo, and Smart Navigation are trademarks or registered trademarks of Seagate Software, Inc. All other product names referenced are believed to be the registered trademarks of their respective companies.

Manual written by:

ELUCIDEX

655 Stuart Road

Bellingham, WA 98226 http://www.elucidex.com

1999

C O N T E N T S

Chapter 1 - Crystal Web Report Server

Seagate Crystal Web Reports Server Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Implementing the Web Reports Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Crystal Web Reports Server Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Web Reports Server Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Web Reports Server Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Chapter 2 - Building Active Web Sites

Seagate Crystal Report Engine Automation Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Visual InterDev Design-time ActiveX Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Editing Active Server Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Sample Web Site. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Chapter 3 - Configuring the Crystal Smart Viewers

Crystal Smart Viewer Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Crystal Smart Viewer for HTML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Crystal Smart Viewer for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Crystal Smart Viewer for ActiveX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Chapter 4 - Crystal Report Engine
Introduction to the Crystal Report Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. 64
Before using the Crystal Report Engine in your application . . . . . . . . . . . . . . . . . . .	. 65
Using the Crystal Report Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. 66
Crystal Report Engine API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. 68
Exporting reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. 94
Handling Preview Window Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	. 97
Distributing Crystal Report Engine Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . .	102
Additional Sources of Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .	102

Chapter 5 - Visual Basic Solutions

Using the Crystal Report Engine API in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . 104

Crystal ActiveX Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Crystal Report Engine Automation Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Active Data Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Crystal Data Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Crystal Data Source Type Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Grid Controls and the Crystal Report Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

i

Chapter 6 - The Report Designer Component

The Seagate Crystal Report Designer Component - Introduction . . . . . . . . . . . . . . . .146 The Seagate Crystal Report Designer Component - Features . . . . . . . . . . . . . . . . . . .146 The Report Designer Component vs. Seagate Crystal Reports . . . . . . . . . . . . . . . . . .147 Installing the Report Designer Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151 Using the Seagate Crystal Report Designer Component . . . . . . . . . . . . . . . . . . . . . .151 Working with data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158 Report Designer Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169 Report Designer Object Model Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173 Report Distribution Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190

Chapter 7 - Seagate Crystal Visual Component Library

VCL Component Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194 Programming Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199 Programming Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209 TCrpeString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .212 Using Variables with Formulas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215 About Section Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221 C++ Builder 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224 Known Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .226 Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .227

Index

ii

Volume1
1	Crystal Web Report Server

What you will find in this chapter...

Note: This chapter contains information specific to the

Professional Edition of Seagate Crystal Reports.

Seagate Crystal Web Reports Server Overview, Page 2

...including an introduction to the features of the Web Reports Server with the new features in Version 7.0, Web Reports Server vs. Active Server Pages, and sample web sites.

Implementing the Web Reports Server, Page 8

...including choosing, installing and confirming installation of a Web Reports Server, virtual directories, creating a web site, and additional resources.

Crystal Web Reports Server Administration, Page 16

...including configuring the Web Reports Server, the Page and Image Servers, smart navigation, drilling down on data, and database location.

Web Reports Server Commands, Page 28

...including the Web Reports Server Command Expert, constructing, exporting and refreshing reports, changing selection formulas, and SQL and ODBC data sources including stored procedures and parameter fields.

Web Reports Server Architecture, Page 37

...including the Web Reports Server extension, the Page and Image Servers, report processing, and an overview of the Job Manager.

Crystal Web Report Server

1

Seagate Crystal Web Reports Server Overview

This topic is only supported by the Professional Edition of Seagate Crystal Reports.

The Seagate Crystal Web Reports Server is the reporting solution for web sites running on Microsoft and Netscape web servers and most CGI compliant web servers running in the Microsoft Windows environment. The Web Reports Server provides the perfect interface for instantly displaying up-to-date reports in the familiar environment of the web browser. In addition, page-on-demand technology and report caching optimize the performance of the Web Reports Server for fast delivery of report data.

The following topics are discussed in this section.

What is the Web Reports Server?, Page 2

Who should use the Web Reports Server?, Page 3

Web Reports Server Features, Page 3

New Features in Version 7, Page 5

The Web Reports Server vs. Active Server Pages, Page 5

Sample Web Sites, Page 6

What is the Web Reports Server?

The Web Reports Server consists of an extension to your existing web server software along with back-end report and image processing applications. Your web server sends URL requests for reports to the Web Reports Server, which then processes the requests and delivers the information in the form of HTML pages or an advanced format viewable through a Java based or ActiveX Smart Viewer embedded in a lightweight HTML page.

Crystal Web Report Server

2

Who should use the Web Reports Server?

The Web Reports Server is for network administrators and web masters who find a need to provide access to corporate and other business reports via a web site, on a corporate intranet or on the internet. The Web Reports Server has been improved and expanded to support large workgroups needing frequent access to information based on current data. The fact that it is web based means that sales and marketing staff can get to the information they need, even on a sales call thousands of miles away.

The exact number of users who can work together on a single Web Reports Server depends on your network and server resources. More resources means more users, so consider the size and capabilities of your system before implementing a web site in your organization.

For high traffic sites web site administrators will enjoy the simplicity of setting up a powerful Web Reports Server to handle most, if not all, of their report distribution needs.

NOTE: An alternative approach is to use Seagate Crystal Reports Automation Server with Active Server Pages. However this approach does not employ page caching and is not recommended for high traffic web sites. For further information refer to The Web Reports Server vs. Active Server Pages, Page 5.

Web Reports Server Features

Version 7 of Seagates Crystal Reports has provided a Web Reports Server that includes cutting-edge technology for the most efficient handling of data and reports over the web.

Page On Demand

Page On Demand means report pages are delivered when demanded. Sometimes a user may only need one or two pages of information out of a 100 page report. Rather than tie up your network by frequently transferring massive amounts of data, the Web Reports Server delivers reports a page at a time as requested by the client. When a report page is requested for the first time the report is generated. The requested page is delivered to the client and stored in a cache. The next time the client requests the same page it is retrieved from the cache rather than being generated again (note, however, that cached reports can be updated either by the client, if allowed by the administrator, or periodically).

By handling requests on a per page basis, the Web Reports Server can quickly handle large numbers of requests, limiting the delay in delivery for any one single request. Caching report pages also allows report information to be shared among clients more efficiently as multiple requests for the same report will not require that the report be generated multiple times.

Smart Navigation

When reports are displayed inside a browser, they can include a navigation tree that speeds access to the information your users need. The navigation tree works much like the directory structure presented in Windows Explorer but provides access to specific groups and records within the report. Smart search controls allow navigation to a specific data value. Rather than waste time flipping through pages of data to locate the information that is most important, users jump right to what they need through Smart Navigation.

Crystal Web Report Server

3

Supports Secured Databases

Do your reports connect to ODBC and SQL data sources that require secure log on information? Do users need to specify user Ids and passwords before data can be generated for a report? The Web Reports Server will automatically prompt users for Ids, passwords, and data source information when necessary. Alternatively, you can use Web Reports Server commands to automatically handle security through hyperlinks or other web links to reports. Seagate Crystal Reports continues to support the security procedures you have already established on your data, even over the web.

NOTE: Commands can be passed to the Web Reports Server by way of HTML links or forms.

Supports Stored Procedures and Parameter Fields

Stored procedures often improve performance and data selection in large SQL databases. Additionally, Seagate Crystal Reports parameter fields can provide on-the-fly data selection inside your reports. Both of these powerful features are supported by the Web Reports Server.

If your reports are based on stored procedures, or if they include Seagate Crystal Reports parameter fields, the Web Reports Server can automatically prompt users for parameter values when the report is generated. URL parameters in hyperlinks, or HTML forms can also specify values for parameter fields or stored procedures.

Exploits Microsoft and Netscape Web Server Extensions

If you are using a Microsoft or Netscape web server to distribute reports, the Seagate Crystal Web Reports Server can directly exploit the power of your web server through the ISAPI or NSAPI programming interfaces. The Web Reports Server supports both APIs in a single file: CRWEB.DLL. The APIs improve web application performance through direct extensions to the web server itself.

For more information on ISAPI, refer to Microsoft documentation. For more information on NSAPI, refer to Netscape documentation.

Crystal Smart Viewers

The Web Reports Server handles report generation and distribution on the server side. The client, however, actually views a report using one of the Crystal Smart Viewers. These browser based viewers provide complete access to report information without the need for installing any applications on the client machine other than a web browser.

Two of the Smart Viewers are based on the HTML 3.02 standard, delivering reports in plain HTML format or HTML with frames. These viewers can be used on any web browser that supports the HTML 3.02 standard. The Java based viewer sits inside an HTML page as a standard Java applet. Reports are displayed inside the Java viewer using the advanced Encapsulated Page File (EPF) format. EPF is a report format that retains almost all of the original report formatting options and settings while producing files that are smaller than HTML files. The result is faster access to reports. Finally, the ActiveX viewer is a standard ActiveX control that also displays reports using the EPF format. Each viewer has its advantages, and you have the option of choosing the viewer that works best for your web site. If you do not specify a viewer, the Web Reports Server will automatically use a specific viewer based on the web browser used to request the report.

For complete information on the Crystal Smart Viewers, see Crystal Smart Viewer Overview, Page 50.

Crystal Web Report Server

4

New Features in Version 7

Version 7 of Seagate Crystal Reports has also added several new features to improve Web Reports Server options, accessibility, and performance. The new Web Reports Server brings you information anytime and anywhere.

Supports Multi-threaded Job Handling

The Crystal Web Reports Server makes use of multi-threading in the 32-bit Windows environment. Each time a request is made by a client, the Web Reports Server generates a new worker thread that handles the actual request. By generating a new thread for each task, the server can exploit the inherent power of multi-tasking in the operating system, delivering reports in the most efficient manner.

New CGI Version Supports Most Current Web Servers

Previously, the Seagate Crystal Web Reports Server was available only as a web server extension that supported the ISAPI and NSAPI programming interfaces for Microsoft and Netscape servers. Now, a second version of the same application, CRWEB.EXE, supports the CGI web application standard. Since most web servers support the CGI standard, you can safely and easily distribute reports using the Web Reports Server on almost any existing web server you may have already implemented.

Improvements for Larger Sites

Many internal improvements have been made to this version of the Web Reports Server in an effort to establish efficient handling of large numbers of requests. Generated report pages can be cached on the server for easy page distribution to multiple clients. If the same report is requested on a repeat basis, the server need only generate it once, then distribute it multiple times, reducing impact on server resources. Report pages are delivered as requested, avoiding network traffic for large amounts of data. Additionally, large numbers of requests are quickly and efficiently handled through the Crystal Reports Job Manager (Job Manager Overview, Page 41). Many of these features were available in a previous version of the Web Reports Server, but Seagate Software has worked to improve the power and speed with which jobs are handled internally. The Seagate Crystal Web Reports Server provides the most powerful solution for fast report delivery over a web site.

The Web Reports Server vs. Active Server Pages

The Crystal Web Reports Server is designed as a fully functional report distribution system for your web server. When you install the Web Reports Server, it is immediately ready for use, and you can simply begin designing your site.

Seagate Crystal Reports also provides an Automation Server that can be used with Active Server Pages on a Microsoft web server. Using the Crystal Report Engine Automation Server, you can design ASP pages that also deliver reports to clients through a web site. Additionally, your ASP pages can incorporate the Crystal Smart Viewers, much like the Web Reports Server does.

Crystal Web Report Server

5