Escolar Documentos
Profissional Documentos
Cultura Documentos
0
Technical Reference
Volume I - Development Tools
Overview
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
Index
ii
Volume1
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 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.
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.
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.
NOTE: Commands can be passed to the Web Reports Server by way of HTML links or forms.
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.
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.
The default installation of the Crystal Web Reports Server also installs several web samples on your Internet
or intranet server system. These samples provide live demonstrations of reports being distributed over the
web. To access these samples:
Select "Web samples and Utilities Page" from the Seagate Crystal Reports Program group menu
or
Enter the following URL at your web browser:
http://localhost/scrsamples/
http://localhost/scrreports/
After selecting a Web Reports Server extension and viewer, you can view any of five sample reports. This site
demonstrates each of the Reports Server extensions and the Smart Viewers in a live environment. If you are
unsure about which server extension or viewer you want to use on your own site, this page allows you to try
each one and determine the best choice for your own needs.
NOTE: You may also choose to implement the Seagate Crystal Report Engine Automation Server inside Active
Server Pages to distribute reports. This technique is substantially different from the Web Reports Server,
though, and is discussed in Building Active Web Sites, Page 43.
The Web Reports Server extension for the Web Reports Server (CRWEB.DLL) implements both ISAPI and
NSAPI programming interfaces. These interfaces provide powerful direct connections to Microsoft (ISAPI)
and Netscape (NSAPI) web servers. If you are using a web server from either of these companies, you should
consider using the Web Reports Server extension first.
The web server CGI extension application (CRWEB.EXE) is designed to support the CGI standard. Since most
web servers support CGI, the Web Reports Server can be installed with most any existing web server.
Additionally, you may have security or other considerations that prevent you from choosing the web report
server extension.
Ultimately, the decision is straightforward. If you are using a Microsoft or Netscape web server, and no
internal corporate or other business policies prevent you, you should use the ISAPI/NSAPI server extension.
Otherwise, use the CGI web server application.
The Seagate Crystal Web Reports Server supports the following operating systems:
Windows NT Server 4.0 or later with:
Microsoft Internet Information Server (IIS) 2.0 or later, or
Netscape Enterprise Server 2.0 or later
Windows NT Workstation 4.0 or later with:
Microsoft Personal Web Server, or
Netscape FastTrack 2.0 or later
Windows 95/98 with Microsoft Personal Web Server
The Seagate Crystal Web Reports Server has been successfully tested with the following web server
applications:
Microsoft Internet Information Server (IIS) 2.0 or later
Microsoft Personal Web Server
Netscape Enterprise Server
Netscape FastTrack 2.0 or later
O’Reilly
Lotus Domino
Additionally, the CGI version of the Web Reports Server is compatible with many other CGI compliant web
servers not listed here.
The following instructions guide you through the steps to install the Seagate Crystal Web Reports Server. The
procedure assumes that you have already installed a web server and have confirmed that it is running
correctly. You must be logged on to the web server system under an account that has permission to
administrate the local machine. The procedure also assumes that you are installing the Web Reports Server
without any other components of Seagate Crystal Reports.
NOTE: Make sure that your web server has been stopped before beginning the install procedure.
NOTE: This is not a complete list of files installed when you install the Seagate Crystal Web Reports Server. It
is only a list of principal Web Reports Server files. Refer to Crystal Reports on line Developers Help for the
complete list.
Configuring NT Services
If you have installed the Seagate Crystal Web Reports Server on a Windows NT system, then The Seagate
Crystal Web Page Server, Page 39, and The Seagate Crystal Web Image Server, Page 39 were installed under the
System account. The following steps indicate how to correctly set up the Crystal Page Server and Crystal
Image Server as NT Services under an NT Domain Administrator account.
1 While logged on as a Windows NT Domain Administrator, open the User Manager for Domains
application. If you are not familiar with this application, refer to Microsoft Windows NT documentation.
2 Select the New User command from the User menu in the User Manager for Domains. The New User
dialog box appears.
3 Enter a new user name to be used by the Web Reports Server. For instance: CRWEBUSER.
4 Provide a password that you will remember.
5 Toggle off the User Must Change Password at Next Logon check box.
6 Toggle on the User Cannot Change Password check box.
7 Toggle on the Password Never Expires check box.
8 Click the Groups button, and make this user a member of the Administrators group.
9 Click OK to close the New User dialog box, and exit the User Manager for Domains application.
10 Open the Services Control Panel. If you are not sure how to do this, refer to Microsoft Windows NT
documentation.
11 Select Crystal Web Image Server in the Service list box, and click Startup. The Service dialog box appears.
12 Click Automatic in the Startup Type section of the dialog box.
13 Click This Account in the Log On As section of the dialog box.
Once Setup finishes installing the Web Reports Server, and you have successfully restarted your system, your
web server should be automatically restarted. Verify that it has been, and, if not, restart it manually. For more
information on starting your web server, refer to the documentation for you web server software.
After confirming that the web server has been restarted, you need to verify that the Web Reports Server has
been correctly installed.
1 Select "Web Samples and Utilities Page" from the Crystal Reports Program Group menu
or
Open a browser (such as Internet Explorer or Netscape Navigator), and enter the following URL address:
http://localhost/scrsamples
The Seagate Crystal Reports Web Samples/Utilities Page appears in your browser.
2 Click the Reports Server Samples link. The Reports Server Samples page appears.
3 Select whether the ISAPI/NSAPI Web Reports Server Extension, or the CGI Web Reports Server
Extension, and click a viewer option supported by your web browser. A page appears with a list of five
sample reports.
4 Click the link for one of the sample reports. The report should be generated and displayed inside your
browser using the viewer you selected.
If you have trouble getting the Web Reports Server running correctly on your web server, you may need to
check the configuration on the web server itself. The following sections demonstrate how to do this in
Microsoft’s Internet Information Server and Netscape’s Enterprise Server.
Netscape Servers
To determine if the Crystal Web Reports Server is configured correctly on Netscape web servers, follow these
steps:
1 Locate the MIME.TYPES file and the OBJ.CONF file. These files are normally located in the following
directories:
● Netscape
Enterprise 3.51:
<dir>\Netscape\SuiteSpot\https-<machinename>\config
● Netscape
Enterprise 3.0:
<dir>\Netscape\SuiteSpot\https-<machinename>\config
● Netscape
Enterprise 2.0 and Netscape FastTrack:
<dir>\Netscape\server\https-<machinename>\config
2 In MIME.TYPES, verify the following lines appear:
type=magnus-internal/rpt exts=rpt
type=magnus-internal/cri exts=cri
3 In OBJ.CONF, verify that the following line appears:
4 In OBJ.CONF, under the heading <Object name="default"> verify that the following lines appear:
The following virtual directories should be set up on your web server pointing to the indicated paths:
● /viewer: C:\Program Files\Seagate Software\Viewers
● /scrreports: C:\Program Files\Seagate Software\Crystal Reports\Reports
● /scrsamples: C:\Program Files\Seagate Software\Crystal Reports\Sample
Once you have installed and set up the Seagate Crystal Web Reports Server, you will, undoubtedly, want to
create a web page that uses your new online reporting features. The following steps lead you through the
process of creating a simple web page that links to two sample reports installed with Seagate Crystal Reports.
First, you must decide on a location for your new web page, then create a virtual directory for the site that
points to the new directory.
1 Create a new directory on the server where your page will be located. For this example, we will use the
directory
c:\webroot\newsite
NOTE: For information on the location of your web servers root directory, refer to your web server software
documentation. The directory shown here is intended only as an example.
2 Use your web server administration software to create a new virtual directory that points to the physical
directory you just created. For this example, we will use the virtual directory
http://localhost/newsite
3 Next, you must create a new physical directory and virtual directory for the reports your site will link to.
http://localhost/scrreports/accounting
4 Using a simple text editor, such as Notepad, or your favorite HTML editor, create the following HTML
code.
<HTML>
<HEAD>
<TITLE>Index of Reports</TITLE>
</HEAD>
<BODY>
</BODY>
</HTML>
Although the Crystal Web Reports Server is installed with the most common settings selected (by default), an
application is provided that allows changes and customization of the Web Reports Server. The Web Reports
Server Configuration application (WEBCONF.EXE) is installed, by default, in the main application directory
you specified for Seagate Crystal Reports during installation. An icon is also available in the Seagate Crystal
Reports Program Group. When run, the application displays a tabbed dialog box. By making changes in this
dialog box, you can customize the Crystal Web Reports Server according to your needs. The following sections
describe the options available on each tab of the application dialog box. This information is also available as
context sensitive Help for the application itself.
NOTE: All changes made in the Web reports Server Configuration utility are stored in the Windows Registry.
Any changes made in webconf.exe will not be effective until the web server is stopped and restarted.
Server Port
Use this text box to specify a TCP/IP port number for the Page Server to listen for requests and to return
information. For valid values for this port, refer to your web server software or TCP/IP documentation. The
default port, if available, is 2000. This port must match the port specified for Report (.rpt) files in the Server
Mappings Tab, Page 22.
Virtual Path
This setting specifies the virtual path for the ActiveX and Java versions of the Seagate Crystal Smart Viewers.
When you install the Web Reports Server, this path is set to:
http://localhost/Viewer
by default. If this path is not available, you must specify a different virtual path using your web server
administration software.
Use your web server administration software to set the virtual path to this directory, then specify that virtual
path on the Page Server Tab for the Web Reports Server Configuration application.
Advanced Settings
Click the Advanced Setting button to access the Page Server - Advanced Settings dialog box.
Use this dialog box to make changes to the advanced configuration options of the Page Server. This dialog box
exposes the following options:
Threads
The Page Server is a multi-threaded application that generates a new thread for processing every request it
receives. Threads consume system memory and resources, though, and large numbers of threads can slow
down the overall performance of a system.
By specifying the maximum number of threads that can be generated by the Page Server, you control how
much of the systems resources can be dedicated to responding to requests at any given time. If the number of
requests received by the Page Server exceeds the number of threads specified, additional requests are held
until threads are available.
When determining a maximum number of threads, you should consider the available memory on the server
system and the size of the reports that are commonly accessed. The larger the report, the more time that is
required, thus tying up threads for longer periods.
Idle Time
Idle time is a period of time during which no actions occur. If a job, for instance, is unused for a large amount
of time, it should be discarded by the Web Reports Server to allow those resources to be freed up for other jobs
and requests. There are two types of idle time that you can set a maximum time for:
Close a job
A job refers to an actual report that has been generated and cached on the server. If no users request the report
for the time specified, the report job will be closed and discarded. Thus, if someone requests the report after
the job has been closed, a new job will need to be generated, causing an initial delay.
Close a client
Every request Id stored by the Page Server includes an Id for the client that made the request. If that client does
not make any new requests or does not interact with an open report for the specified period of time, all
requests corresponding to that client will be closed. If that client makes a new request after their client Id has
been closed, they will experience a slight delay while the Page Server establishes a new request for them.
Use the Image Server Tab to control the settings for the Seagate Crystal Web Image Server. You can change the
TCP/IP port used by the Image Server or set the maximum number of threads the Image Server can generate
to handle requests.
Threads
The Image Server is a multi-threaded application that generates a new thread for processing every image
request it receives. Threads consume system memory and resources, though, and large numbers of threads
can slow down the overall performance of a system.
Use this option to specify a maximum number of threads that can be generated by the Image Server. If the
number of requests received by the Image Server exceeds the number of threads specified, additional images
are not generated until existing threads have been freed up.
The Report Exporting Tab lets you determine whether or not users can export reports from a Smart Viewer
and which formats they can export to.
NOTE: If a user exports to HTML format, the resulting report will not be available through the Web Reports
Server.
Use the Server Mappings Tab to map the TCP/IP ports used by the Page Server and Image Server to specific
file extensions (.rpt and .cri). These ports must correspond to the ports specified on the Page Server Tab, Page
17, and the Image Server Tab, Page 20.
Add button
Use the Add button to add a new file type mapping for the Web Reports Server. When you click Add, a dialog
box appears asking for the file extension of the new file type, the TCP/IP hostname of the server, and the TCP/
IP port used by the application that handles that file type.
NOTE: In most cases, you do not need to add a file type mapping unless upgrading to another Seagate
Software product.
Delete button
Use Delete to remove any of the entries in the Server Mappings list box. Simply select the item in the list, and
click Delete. You will be prompted to verify the delete before it is actually performed.
Use the Report Viewing to control what options are available to users when they view a report inside a
browser. Additionally, you can access the cache settings from this tab to control how reports are cached on the
server.
Smart Navigation
Smart Navigation, a feature of several of the Crystal Smart Viewers, presents your users with a tree control
much like the tree control in Windows Explorer. The Web Reports Server dynamically analyzes a report when
it is first requested, then populates the tree control with branches for each group in the report.
Once displayed in your browser, the Smart Navigation Group Tree works like the Group Tree in the Seagate
Crystal Reports Preview Tab. Simply expand and collapse branches in the Group Tree to find the section of
the report you are most interested in. Click a branch to quickly jump to that part of the report.
Web administrators can control access to Smart Navigation and the Group Tree by setting the Display Group
Tree check box in the Smart Viewer options list box of the Report Viewing Tab, Page 23 in the Web Reports
Server Configuration utility. The Configuration utility also allows you to control the maximum number of
groups that are read and added to the Group Tree.
If you choose to allow users to make use of the Smart Navigation Group Tree, keep in mind that generating
the Group Tree forces the Web Reports Server to make an extra pass across the report, gathering group
information and generating the Group Tree. This extra step in generating a report can tie up system resources
and cause extensive delays in returning report data to the user, depending on the size of the report and how
deep the grouping is. Consider the information your users need before deciding if Smart Navigation is right
for your web site.
Database Location
When moving report files to a web server, be aware of changes in database location. If a report is created on
one machine, then moved to the Web Reports Server machine, the relative location of the database information
used to create the report may change.
Installing the full Seagate Crystal reports package on your Web Reports Server system can often simplify
report troubleshooting. By opening a report directly in the Report Designer, you can quickly determine the
source of any problems accessing report data. For information on installation of the Web Reports Server, see
Installing the Web Reports Server, Page 9.
Running Page Server and Image server as NT services with Domain Admin privileges allows the database to
be stored across the network and still be accessible.
INIT command
Specifies how the report should be displayed in the web browser. For example:
init=java
NOTE: Not all browsers support all methods of viewing reports. For instance, both the ActiveX viewer and
Java viewer are unavailable in versions of Internet Explorer previous to 3.02. Internet Explorer also requires
that Authenticode 2.0 be installed. Netscape Navigator does not support the ActiveX viewer at all, and does
not support the Java viewer in versions prior to 3.0.
In addition to specifying a record or group selection formula when designing a report, you can also change
the selection formula using a command appended to the URL of a report called through the Crystal Web
Reports Server. As an administrator, you can create one report and design a web page that allows users to
choose selection criteria for the information they need. The Crystal Web Reports Server then dynamically
generates the requested report with only the selected records.
To specify a record selection in a request for a web report, use the parameter SF command, Page 31. For example:
http://server_name/reports/boxoffic.rpt? sf={studio.Studio}+%3d+'Universal'
This will override any selection formula already contained in BOXOFFIC.RPT. However, the new selection
formula will not be saved with the original report file. It is only valid for the currently requested job. The GF
command, Page 31 can be used to change a group selection formula in a report.
The Crystal Web Reports Server does not check the validity of any selection formulas you send to a report. If
the selection formula you create is invalid, an error will be returned to the web browser. If you are designing
a web site that passes selection formulas to reports, be sure to test the selection formulas before allowing users
to access your site.
GF=<formula>
GF= Sum({customer.Sales},{customer.Region})>10000
«Selects all groups in which the sum of all customer sales in each region is greater than 10,000.»
SF command
Specifies a selection formula.
SF=<formula>
http://server_name/reports/boxoffic.rpt?sf={studio.Studio}+%3d+”Universal”
NOTE: Reports that have the SF# or GF# commands applied will not have their pages shared. Caching will be
by user.
The Seagate Crystal Web Reports Server opens reports based on SQL servers and ODBC data sources as easily
as it opens reports based on smaller, desktop database files. If the data in a report requires access to a secure
data source such as an SQL server or ODBC data source, the Web Reports Server will automatically prompt
the user requesting the report to provide a user ID and password before it displays report data.Your existing
database security continues to work, even over the web.
NOTE: Although the Web Reports Server requires users to log on before it displays reports that access secured
databases, security conflicts can arise if several people attempt to access the same report simultaneously. To prevent
such conflicts, you should add security to your web site, preventing users from seeing and accessing secured
reports. Forcing users to log on to the intranet site is a common solution to providing complete system security.
NOTE: If the database security has no password or a blank password, users will not be prompted by the Web
Reports Server to log on. To ensure security, make sure databases have valid passwords.
To create hyperlinks in your web pages that handle user IDs and passwords automatically, use the USER#
command, Page 33, and PASSWORD# command, Page 32. These commands will let you specify more than one
user ID and password if the report connects to two or more secured databases. Keep in mind that if an incorrect
user ID or password is sent, the Crystal Web Reports Server will prompt for user name and password again
and prevent access to the report.
NOTE: The Crystal Web Reports Server applies a simple encryption algorithm to user names and passwords. If
you are using a Microsoft web server, make sure your intranet or extranet site has the Secure Sockets Layer
(SSL) encryption protocol installed and enabled to ensure complete security when accessing database
information. Due to a documented problem in the Netscape web servers, SLL is not supported by the Web
Reports Server on Netscape servers. For more information, refer to Netscape documentation.
PASSWORD# command
Specifies passwords for logging on to SQL, ODBC, or password-protected databases used by the report.
PASSWORD#=<password>
«<password> is a string.»
For example:
password0=secret
password0=secret&password1=mystery&password2=unknown
PASSWORD# is normally used in conjunction with the USER# command, Page 33. For example:
user0=SmithJ&password0=secret&user1=JohnS&password1=mystery
If the report contains subreports that require passwords for logging on to SQL or ODBC data sources, use the
following syntax in the URL:
password@subname#=<userid>
user@Crosstab0=jimmys&password$Crosstab0=jimmyz
NOTE: Make sure passwords appear in the URL in the same order in which the password-protected databases
appear in the report. Additionally if passwords are not passed using the URL address, the user will be
prompted for logon information at runtime.
USER# command
Specifies user IDs for logging on to SQL or ODBC databases used by the report.
USER#=<userids>
«<userids> is a string.»
For example:
user0=SmithJ
If the report accesses more than one password-protected database, multiple user IDs can be passed by
incrementing the USER index number. For example:
user0=SmithJ&user1=JohnS&user2=JSmith
USER# is normally used in conjunction with the PASSWORD# command, Page 32. For example:
user0=SmithJ&password0=secret&user1=JohnS&password1=mystery
If the report contains subreports that require user IDs for logging on to SQL or ODBC data sources, use the
following syntax in the URL:
user#@subreportname
For example:
user0@Crosstab=jimmys&password0Crosstab=jimmyz
Seagate Crystal Reports supports designing reports based on stored procedures in SQL databases.
Additionally, the Report Designer allows you to create parameter fields in the report itself. Both stored
procedures and parameter fields can prompt users at runtime for a value to base the report on. For instance, a
sales person may want to see sales information for their region only. When they request the report, the report
can prompt that sales person to enter a region name. The report then delivers data just for that region.
When the Web Reports Server encounters a report containing a stored procedure or parameter field, it can
automatically prompt the user requesting the report to provide a parameter value. The report is then
generated based on the user’s input. The prompting page is dynamically generated at runtime based on the
actual stored procedure or parameter field. The following image is an example of a parameter value prompt:
To prevent users from specifying their own values for parameter fields or stored procedures, use the
PROMPT# command, Page 35 when specifying the URL of a report. PROMPT# lets you specify values for one
or more parameter fields in a report. Alternately, you can design your own web based forms that accept user
input and dynamically create the URL that includes the PROMPT# parameter and value.
NOTE: Users should not surround parameter values with quotation marks. All values are sent to the report as
strings, regardless of the type of data. Parameters that expect numeric values interpret the string received
when necessary.
NOTE: Parameter fields and SQL stored procedures limit the effectiveness of report caching and job sharing.
Since each report containing stored procedures or parameter fields may generate a different set of data every
time it is requested, multiple requests for the same report may not be distributable among multiple users.
PROMPT# command
Specifies values for parameter fields in the report. parameter values are assigned to parameters in the order in
which they exist in the report.
PROMPT#=<value>
«<value> is a string.»
For example:
prompt0=CA
NOTE: Do not use quotation marks around parameter values to indicate string values. All parameter values are
passed to the report as strings. Intended numeric values are translated from strings to numbers by the report.
If the report contains more than one parameter field multiple values can be passed to parameters by
incrementing the PROMPT index value. For example:
prompt0=CA&prompt1=1000
NOTE: Make sure parameter values appear in the URL in the same order in which the parameter fields and
stored procedures appear in the report. If parameter values are not passed using the URL address, the user
requesting the report will be prompted to provide values at runtime.
NOTE: Reports that have the PROMPT# command applied will not have their pages shared. Caching will be by
user.
promptOnRefresh# command
Specifies whether report should prompt for parameter field values when refreshed.
promptOnRefresh#=<value>
«<value> is 0 or 1.»
For example:
promptOnRefresh=1
NOTE: Reports that have the promptOnRefresh command applied will not have their pages shared. Caching
will be by user.
● Excel 4.0(XLS)
● Excel 5.0(XLS)
● Excel5.0(XLS)Extended
● Word Document(DOC)
The report server will assign the CONTENT-TYPE header the appropriate MIME-TYPE, therefore the browser
can be configured to launch the appropriate application after downloading the file. To issue a request to the
report server to export a report, the query string must contain two commands. These commands are "CMD"
and "EXPORT_FMT". The CMD command must always be assigned the value "EXPORT", and the
"EXPORT_FMT" command is assigned the desired Export Format. The table below lists the supported export
formats and their corresponding EXPORT_FMT representation.
The server extension for Crystal Web Reports communicates directly with your web server. When you install
the Crystal Web Reports Server, two new file extensions are established on your system: .rpt and .cri. When
your web server receives a request for either of these file types, it directs the request toward the Web Reports
Server extension (CRWeb). The Web Reports Server extension then determines what application should be
used to process the request, the Image Server (.cri) or the Page Server (.rpt). Once a request is processed, the
server extension also handles returning the data to the web server for delivery to the client’s browser. This is
the main point of contact between the web server and the back-end report processing servers.
There are actually two versions of the Web Reports Server. One has been designed specifically for Microsoft
and Netscape web servers, while the other can run on most CGI compliant Windows based web servers.
ISAPI/NSAPI
The Web Reports Server extension implemented in CRWEB.DLL is both an ISAPI and NSAPI extension. By
utilizing the API extensions exposed by Microsoft and Netscape web servers, CRWEB.DLL produces a faster,
more robust system for report delivery to the web server.
The ISAPI extension is supported by Microsoft Internet Information Server (IIS) versions 2.0 and later.
Additionally, the Personal Web Server available for Windows NT Workstation, Windows 95, and Windows
98 also supports ISAPI extensions.
The NSAPI programming interface is available on all Netscape web servers.
When a report is rendered in HTML, graphic images, maps, graphs, charts, and OLE objects are rendered as
Crystal Image (.CRI) files and stored by the Page Server module. When the Web Reports Server encounters a
Crystal Image inside of the HTML report, it asks the Image Server to interpret it. The Image Server translates
the image into a form that can be displayed by browsers (such as JPEG format), and sends the image back to
the Web Reports Server for distribution through the web server.
NOTE: Crystal Image files are not used if the report is rendered as an Encapsulated Page File (EPF) for display
inside the Crystal Smart Viewers for ActiveX, Java, or Java Beans.
NOTE: This section refers to the Job Manger which is the component responsible for implementing report
sharing and page caching among other thing. Refer to the section titled Job Manager overview for a general
description of how page caching and report sharing are implemented.
The Page Server is the most complex piece of the Crystal Web Reports Server system. It is actually made up of
several smaller components each responsible for handling specific parts of the report processing task. It’s
primary job, though, is to receive a request for an .RPT report file from the Web Reports Server, generate the
report, and return it in a form that can be viewed by a web browser.
NOTE: The Web Reports Server limits report caching features with reports based on SQL stored procedures or
that include parameter fields. Such reports may generate a different set of data every time they are requested,
due to the dynamic values passed to the parameter field or stored procedure. Thus, multiple requests for the
same report may actually produce separate report jobs.
NOTE: EPF files do not retain formatting information set by printer drivers. Examples of such formatting
include page size and page orientation.
Report Processing
When the Page Server gets a request for a new report, it must obtain a new request Id from the Job Manager and
determine if the Job Manager needs to obtain a new job Id from the Report Engine. If a new job Id is required, the
Report Engine must actually generate a new report. The interaction between the Page Server, the Job Manager,
and the Report Engine has been designed to maximize performance in intranet and extranet environments.
The Crystal Reports Job Manager must generate new request Ids for every request the Web Reports Server
receives. If the Page Server determines that the requested report already exists in the cache, it will simply
obtain a new request Id from the Job Manager, then match that request to the job Id of the existing report. If
the report has not been cached, the Page Server must obtain a new job Id from the Job Manager, as well as a
new request Id.
If the Page Server demands a new report job Id from the Job Manager, the Job Manager will start the Report
Engine and have it generate the new report. The Report Engine creates a job Id for the new report and returns
it to the Job Manager which, in turn, returns both the job Id and the request Id to the Page Server.
Report Engine
The Report Engine is the component which actually generates reports. The Report Engine opens a requested
RPT file, locates the necessary data, and produces a complete report file. If you are an application developer,
this is the same Report Engine that you can add to your own applications (see Crystal Report Engine, Page 63
for more information). Every report produced by the Report Engine has a unique job Id to identify that report.
The Page Server uses the job Id to determine what actual report must be used for a specific client request.
Page caching and job sharing are implemented via the Job Manager (CRJM). This section provides a general
description of the Job Managers function as it concerns Job Sharing and Page Caching:
When a client requests a report, that has not been requested before, the following occurs:
● A new report Job is created. A cache is created, which will hold report pages as they are requested. A
reference to the report job is created. The reference has a unique id (Request Id) by which the client can
access the job in the future.
● There is usually a refresh interval associated with a report job.This is the time interval (specified as the
Database Refresh Time in the Configuration Manager) after which a new request for the same report
will result in accessing the database for updated information. In other words if a new client requests
the report after the refresh interval for the existing report job then new report job is created as a result.
● If a client referencing an existing report job selects refresh then a new report job is created and the client
gets a reference to the new job.
Job Sharing
If the report contains saved data and there are no SF# and GF# commands or if a report does not have saved
data and there ar no SF#,GF#,PASSWORD#,USER#,PROMPT# or promptOnRefresh# commands then the
resulting report job can be shared. What this means is that requests for the same report (which occur within
the same refresh interval) will result in references to the same report job.
There are conditions under which a shared report job will no longer be shared:
● If a client sharing an existing report job selects refresh then a new report job will be created and the
client will receive a reference to the new report job.
● If a client sharing an existing report job submits a page request that includes one of the commands listed
previously then a new report job will be created and the client will receive a reference to the new report job.
Page Caching
Associated with each report job is a cache to store requested pages. The pages are generated as requested,
passed to the client and stored in the cache. If another client, who is sharing the same report job, requests a
page which is already cached then that client will received the cached page. This can greatly reduce access time
(subject to the traffic conditions of your network at any given time).
This topic is only supported by the Professional Edition of Seagate Crystal Reports.
The Seagate Crystal Report Engine Automation Server allows you to build powerful active web sites with any
web server that supports ActiveX and Active Server Pages. This section demonstrates how to bring the full
power of the Report Engine Automation Server to your Microsoft Internet Information Server (IIS) web sites.
Although the Seagate Crystal Web Reports Server provides many features for viewing reports from a web
browser, the ability to format and select data is limited to a few simple commands. The Seagate Crystal Report
Engine Automation Server, on the other hand, gives you all the power of the Seagate Crystal Report Engine.
For adding the Report Engine Automation Server to a web site, Seagate Crystal Reports provides the Visual
InterDev Design-time ActiveX Control for use with Microsoft Visual InterDev. In this chapter, you will learn
how to use the Visual InterDev Design-time ActiveX Control to automatically set up VBScript code in your
Active Server Pages that uses the Report Engine Automation Server and the Active Data Driver.
NOTE: For additional information on the objects, methods, and properties provided by the Seagate Crystal Report
Engine Automation Serve, Please see Crystal Report Engine Object Model for the Automation Server, Volume 3,
Chapter 6.
The Visual InterDev Design-time ActiveX Control can build a report dynamically at runtime based on an
ActiveX data source such as ActiveX Data Objects. The design-time control uses the Crystal Active Data Driver
to dynamically design a generic report based on tables and fields you select from a data source connected to
your project. To use the dynamic reporting features of the design-time control, first add a data source to your
web project.
1 With a project open in Visual InterDev, choose the DATA CONNECTION command from the Project|Add
To Project menu. The Select Data Source dialog box appears.
2 To select an ODBC data source, click the Machine Data Source Tab.
3 Select a data source from the Data Source Name list, and click OK, or click NEW to create a new data source.
Once you click OK in the Select Data Source dialog box, the data source will be added to your project.
4 Save your project.
NOTE: You may be required to specify logon information when you select a data source. For complete
information on adding data sources to a web project, refer to your Visual InterDev documentation.
Now that your project contains a data source, the Visual InterDev Design-time ActiveX Control can be used
to create an Active Server Page that dynamically creates and displays a report based on this data source.
1 Choose the NEW command from the File menu. The New dialog box appears.
2 On the Files Tab of the New dialog box, select Active Server Page.
3 Enter a name for the new Active Server Page in the File name text box, and click OK. The new Active
Server Page is created and appears in the Microsoft Developer Studio.
4 Make sure the comment <!-- Insert HTML here --> is highlighted, and choose the ACTIVEX CONTROL
command from the Insert|Into HTML menu. The Insert ActiveX Control dialog box appears.
5 Click the Design-Time Tab to display the design-time ActiveX controls that are registered on your system.
6 Highlight the CrystalReport.DTC design-time control, and click OK.
7 Close the Properties dialog box if it appears. The Visual InterDev Design-time ActiveX Control appears in
the Microsoft Developer Studio window.
8 Toggle the Use existing report check box off, if it is not off already.
9 In the Data Connection drop-down list, select the database corresponding to the data source you added to
your project.
10 In the Record Source drop-down list, select a database table from the database.
11 In the Columns list box, toggle the check box on for any field you want as a column in your report.
The Crystal Smart Viewer for Java is a standard Java applet, while the Crystal Smart Viewer for ActiveX is an
ActiveX control. Both can be customized using the <PARAM> tags that appear under the <OBJECT> tag
created in your Active Server Page by the design-time control. In your Active Server Page, look for the OBJECT
tag appearing below the VBScript code. For information on how to change and set parameter for either viewer,
see Configuring the Crystal Smart Viewers, Page 49.
Although the Visual InterDev Design-time ActiveX Control provides all of the necessary VBScript code to
display your reports in a web browser, you may want to customize the output of the actual report. By using
the Report Engine Object Model, provided by the Report Engine Automation Server, you can change report
format, grouping, selection formulas, and sort fields. For additional documentation, refer to Seagate Crystal
Report Engine Automation Server, Page 44.
In your Active Server Page, look through the VBScript code created by the design-time control. Notice that all
of the VBScript code generated is server-side script, making your web site compatible with any browser
(depending on the Crystal Smart Viewer you specified).
Notice that the Report object is stored in the session object. For complete information on the session object,
refer to the Microsoft documentation for Active Server Pages.
Session Timeout
By default, the session object provided by Visual InterDev for your project has a timeout value of 20 minutes.
When designing web sites that use the Report Engine Automation Server and the Visual InterDev Design-time
ActiveX Control, you will not be able to edit reports using Seagate Crystal Reports for 20 minutes after viewing
them in a browser. Once your web site is designed and finished, this timeout period may be just fine. However,
during the development process, you may want to alter the session timeout period.
The Session object has a Timeout property that determines how long the session waits before timing out.
During development, add a line of code to your Active Server Pages to set the Timeout property to a much
shorter timeout period, such as 1 minute. The following code demonstrates this:
session.Timeout = 1
Be sure to remove the line of code before making your web site available to other users.
3 Configuring the
Crystal Smart Viewers
This topic is only supported by the Professional Edition of Seagate Crystal Reports.
Seagate Crystal Reports provides several methods for viewing reports from a web browser. Actually adding
a viewer by directly editing the web page is not normally necessary. The Crystal Web Reports Server, for
example, can detect a user’s web browser type when a report is requested, and automatically provide an
appropriate viewer. If, on the other hand, you develop web sites using Microsoft Visual InterDev and the
Crystal Design-Time ActiveX Control, you can select a viewer using the design-time control, and the
appropriate code will be added to your site automatically.
As a reference, the following table illustrates the Crystal Smart Viewer that is defaulted to by the Web Reports
Server based on the web browser being used by a client:
Although changing these defaults is not necessary, there may be times when you need to manually write web
pages that display a specific viewer despite the browser being used, or when you want to customize your web
site by editing the code created by the design-time control. This chapter explains how to understand and work
with the Crystal Smart Viewers directly in your web pages.
If you are designing web sites using one or more of the Crystal Smart Viewers, be aware that only the Java
Viewer can be directly assigned a report file through one of its parameters. This means that the Web Reports
Server, in most cases, must provide the Smart Viewer for you, and any customization must be done through
the The Web Reports Server Configuration Application, Page 16. If you develop sites using the Crystal Report
Engine Automation Server, though, or if you connect to the Web Reports Server from Active Server Pages or
Visual Basic, you have several options for configuring the Smart Viewers. For further information on using
Crystal Smart Viewers inside Active Server Pages, refer to Customizing the Crystal Smart Viewer, Page 47. For
further information on connecting to the Web Reports Server from Visual Basic, see Connecting to the Web
Reports Server, Volume 3, Chapter 1.
NOTE: This chapter is intended as a supplement to the web design solutions presented in Seagate Crystal Web
Reports Server Overview, Page 2, and Building Active Web Sites, Page 43. It is assumed that you are familiar with
the concepts in at least one of those two chapters.
Seagate Crystal Reports provides rich and powerful reporting features for data analysis and presentation.
Ideally, web presentations of reports will maintain those report features. Several of the Crystal Smart Viewers
are designed to provide this power asit exists in the original report.
Web administrators often have important reasons for choosing one web technology over another when
presenting information on a web site. When deciding on the Smart Viewer technology used on your web site,
you should consider the reporting features provided by each Smart Viewer and be aware of any limits that a
particular web technology might impose on the Crystal Smart Viewers.
The following table illustrates what major reporting features are available in each of the Crystal Smart
Viewers:
If your reports make use of a particular reporting feature, verify that feature is available in the Smart Viewer
you choose before designing your site.
When you create a report in Seagate Crystal Reports, the program analyzes the printer that is currently
selected for your system to determine font size and how to size and position objects, such as field objects and
text objects on the report. If the report is then printed to a printer other than the one selected when it was
created, problems with font size, clipped text, and pagination may arise.
With this in mind, consider what may happen when a report is created on one machine, served over the
network by a web server on a second machine, and viewed or printed from a web browser through a Crystal
Smart Viewer on a third machine. If each of these machines is connected to a different printer, report
formatting problems may be compounded.
Viewing reports is not exclusive to web sites, and you may find a need for client side applications that display
reports on screen to users. The Crystal Smart Viewer/ActiveX and the Crystal Smart Viewer/Java Bean are
fully functional components that can be added to applications written in Microsoft Visual Basic, Borland
Delphi, Symantec Visual Cafe, and many other development environments that support ActiveX controls or
Java Beans.
NOTE: The Crystal Smart Viewer/Java Bean is intended primarily for application development and is,
therefore, not discussed in this chapter. Instead, this chapter concentrates on the Smart Viewers intended for
web site development and that can be distributed by the Web Reports Server or added using the Crystal
Design-Time ActiveX control.
A common use of the Crystal Smart Viewers in application development is when designing N-tier applications
that may use the Crystal Web Report Server, Page 1, the Seagate Crystal Report Engine Automation Server, Page 44,
or the The Report Designer Component, Page 145, as a middle tier and the Smart Viewer as part of the client user
interface. For more information on using the ActiveX and Java Bean versions of the Crystal Smart Viewers in
application design, see Application Development with Crystal Smart Viewers, Volume 3, Chapter 1.
NOTE: If you drill-down on data and then click the Back button on a Netscape browser 3.x, you may
encounter JavaScript errors. To prevent these errors, click the corresponding tab for the view you want
retrieved, rather than the Back button.
Since HTML 3.2 format does not provide all of the formatting features available in the Seagate Crystal Reports
report format, translating reports to HTML introduces several limitations, as described here. As a web
administrator or designer, keep these limitations in mind when deciding how to distribute reports over your
Internet or intranet site. These limitations include constraints on object layout, the objects translated, and other
limitations.
Object Layout/Positioning
HTML 3.2 translation preserves relative positioning of objects and fields. However, absolute positioning, height,
and width is browser dependent.
Objects Translated
Object Translated/Not Translated
Field Objects Yes
Text Objects Yes
Graphic, Blob, Chart Objects Yes, as JPEG images.
OLE Objects Yes, as JPEG images.
Cross-Tab Objects Yes
Subreport Objects Yes
Other Limitations
Overlayed Report Objects
● HTML 3.2 does not support overlaying. Report objects which are partially overlayed (even a tiny
fraction) will appear alongside each other.
Drill-down
● Group drill-down is supported.
● Chart drill-down is not supported.
● Map drill-down is not supported.
NOTE: If you drill-down on data inside the Java viewer, and then click the Back button on a Netscape browser
3.x, you may encounter JavaScript errors. To prevent these errors, click the corresponding tab for the view you
want retrieved, rather than the Back button.
As a Java applet, the Crystal Smart Viewer can be added to a web page using the standard HTML tag APPLET.
The name of the public class exposed by the applet is ReportViewer. Thus, the following code displays the
Crystal Smart Viewer for Java:
<APPLET CODE=”ReportViewer.class”
CODEBASE=”http://<domain>/viewer/JavaViewer”
WIDTH=600 HEIGHT=400>
</APPLET>
When you install Seagate Crystal Reports or the Crystal Web Reports Server, the Java viewer is installed under
\Program Files\Seagate Software\Viewers\JavaViewer. Additionally, a virtual directory named /viewer is
set up on your web server, which points to the \Program Files\Seagate Software\Viewers directory.
The Crystal Smart Viewer for Java provides several optional parameters to customize the look of the viewer
and to control its functionality. Apply values to these parameters using the standard PARAM tag in your
HTML code.
Parameters
The Crystal Smart Viewer for Java provides the following parameters:
CanDrillDown
Indicates whether or not the user can drill-down on summary data, graphs, or charts in the report. Use TRUE
to allow drill-down, FALSE to prevent drill-down.
HasExportButton
Indicates whether or not an Export button appears on the Smart Viewer. The export button allows users to
export reports displayed in the Smart Viewer to Microsoft Word, Microsoft Excel, HTML 3.2, or Seagate
Crystal Reports format. Use TRUE to allow exporting, FALSE to prevent it. This setting can be overridden by
settings made in the Web Reports Server Configuration utility. See the Export Report Allowed check box, Page 21.
HasPrintButton
Indicates whether or not the viewer includes a print button allowing the viewed report to be printed. Use
TRUE to allow printing, FALSE if printing is not allowed. Printing from the Java Smart Viewer requires a web
browser or Java Virtual Machine that supports version 1.1 or later of the Java Developer’s Kit (JDK).
HasRefreshButton
Indicates whether or not a Refresh button is available in the viewer to allow the user to refresh report data.
Use TRUE to allow users to refresh report data, FALSE to prevent users from refreshing report data.
HasTextSearchControls
Indicates that the viewer includes controls to allow searching for specific values in the report. Use TRUE to
allow searching, FALSE to prevent search controls from being displayed.
ReportName
Specifies the report to be displayed inside the viewer. The path must be a URL on the same server as the HTML
document and must be placed inside quotation marks.
ShowGroupTree
Indicates whether or not the Group Tree is displayed when the viewer first appears. If the HasGroupTree
parameter is set to False, this parameter is ignored. If the Group Tree is hidden, the user can display it by
clicking the Toggle Group Tree button in the viewer. Use TRUE to display the Group Tree, FALSE to hide the
Group Tree.
Example
The following code demonstrates one means of embedding the Crystal Smart Viewer for Java in a web page.
This JavaScript code determines browser version and then installs the appropriate version of the Java Smart
Viewer.
<SCRIPT LANGUAGE="JavaScript"><!--
var _ns3 = false;
var _ns4 = false;
//--></SCRIPT>
<COMMENT><SCRIPT LANGUAGE="JavaScript1.1"><!--
var _info = navigator.userAgent;
var _ns3 = (navigator.appName.indexOf("Netscape") >= 0 &&
_info.indexOf("Mozilla/3") >= 0);
var _ns4 = (navigator.appName.indexOf("Netscape") >= 0 &&
_info.indexOf("Mozilla/4") >= 0 );
//--></SCRIPT></COMMENT>
This example will display the empprof.rpt report in the Crystal Smart Viewer for Java window. A Group Tree
will be generated to allow Smart Navigation, but it will be hidden initially. The viewer does not allow a user
to refresh the report data.
The Crystal Smart Viewer for ActiveX is certified by Microsoft AuthentiCode 2.0. This certification requires
Microsoft Internet Explorer 3.02 or later in order to open the ActiveX control. If you do not have a recent
version of Internet Explorer, refer to the Microsoft web site to upgrade or use a different Crystal Smart Viewer
when designing your web sites.
Microsoft’s Internet Explorer web browser supports the OBJECT tag in HTML. This tag can be used to add the
Crystal Smart Viewer for ActiveX to a web page. Use code similar to the following:
NOTE: For additional information on the OBJECT tag, refer to your Microsoft documentation.
When you install the Crystal Web Report Server, the Crystal Smart Viewer for ActiveX is installed under
\Program Files\Seagate Software\Viewers\ActiveXViewer. Additionally, a virtual directory named /viewer
is set up on your web server, which points to the \Program Files\Seagate Software\Viewers directory.
In order for a web browser to use an ActiveX control stored on the web server, the browser must be able to
download the control from the server and register it locally. The CODEBASE attribute of the OBJECT tag
allows you to specify the location of the original ActiveX control, relative to the current page. For example:
The first part of the CODEBASE attribute value indicates the location and file name of the ActiveX control as
a URL address relative to the current web page. The Version attribute that appears after the # symbol is
optional and allows you to specify which version of the Crystal Smart Viewer for ActiveX you want to provide
for your users. If you specify 1.0.0.0, the most recent version available on wither the server or the client will
automatically be used by the browser.
When a web browser opens this page, it first checks the CLASSID attribute to see if the control is already
registered on the client system. If not, or if the version number of the viewer is lower than the current viewer
registered on the system, the browser uses the CODEBASE attribute to find the control and download it. Once
downloaded, the control can be registered and displayed by the browser.
DisplayGroupTree
Indicates whether the Group Tree is displayed when the viewer first appears. If the Has Group Tree parameter
is set to false, this parameter is ignored. If the Group Tree is hidden, the user can display it by clicking the
Toggle Group Tree button in the viewer.
●A value of 1 (TRUE) displays the Group Tree.
●A value of 0 (FALSE) hides the Group Tree.
EnableAnimationControl
Indicates whether the viewer displays the Animation Control. The Animation Control runs while a report is
being generated and downloaded. Once the report completely arrives at the client web browser, the animation
stops.
●A value of 1 (TRUE) displays the Animation Control.
●A value of 0 (FALSE) prevents the Animation Control from being displayed.
EnableDrillDown
Indicates whether a user can drill-down on summary values in a drill-down report. In a drill-down report that
appears in the Crystal Smart Viewer for ActiveX, the mouse pointer becomes a magnifying glass over any
group or value that can be drilled down on. Double-click the group or value to display a separate Drill-Down
Tab inside the viewer.
●A value of 1 (TRUE) indicates the user can drill-down on reports.
●A value of 0 (FALSE) indicates the user is not allowed to drill-down on reports.
EnableExportButton
Indicates whether or not the Export button appears in the Smart Viewer. If the Export button appears, the user
can export the displayed report to Microsoft Word, Microsoft Excel, HTML 3.2, or Seagate Crystal Reports
format.
●A value of 1 (TRUE) displays the Export button.
●A value of 0 (FALSE) prevents the Export button from being displayed.
EnablePrintButton
Indicates whether the user can print the report to a printer. When the user clicks the Print button, the report is
sent to a printer according to the settings selected by the Standard Print dialog box. If the Has Print Button is
set to 0, then you can not print. For more information, see Printing from the Crystal Smart Viewers, Page 51.
●A value of 1 (TRUE) displays the Print button.
●A value of 0 (FALSE) prevents the Print button from being displayed.
EnableRefreshButton
Indicates whether a Refresh button is available in the viewer to allow the user to refresh report data.
●A value of 1 (TRUE) allows users to refresh report data.
●A value of 0 (FALSE) prevents users from refreshing report data.
EnableSearchControl
The Search control and button that appear in the Crystal Smart Viewer for ActiveX allow a user to easily search
for and jump to instances of a specific value or field that appear in the report. The user enters the value of
interest in the drop-down list, then clicks the Search button to find the first instance of that value. Clicking the
button again finds successive instances of the value in the report.
●A value of 1 (TRUE) displays the Search controls.
●A value of 0 (FALSE) prevents the Search controls from being displayed.
EnableZoomControl
Use the Zoom Control to switch between levels of magnification in Crystal Smart Viewer for ActiveX. With
the Zoom Control, you can magnify the report up to 400% of its original size, or reduce it down to 25% in order
to see more of the report at once.
●A value of 1 (TRUE) displays the Zoom Control.
●A value of 0 (FALSE) prevents the Zoom Control from being displayed.
NOTE: For more information regarding current runtime file requirements, see the Runtime File Requirements
online Help.
From your application, you can access the Crystal Report Engine through any of several Crystal Report Engine
development tools:
● Crystal ActiveX Controls, Page 108 (CRYSTL16.OCX or CRYSTL32.OCX)
● Crystal Report Engine Automation Server, Page 111 (CPEAUT.DLL or CPEAUT32.DLL)
● Seagate Crystal Visual Component Library, Page 193 (UCRPE.DCU or UCRPE32.DCU)
● The Crystal Report Engine Class Library, Volume 2, Chapter 2 (PEPLUS.H and PEPLUS.CPP)
● The Crystal NewEra Class Library, Volume 3, Chapter 7
● Crystal Report Engine API, Page 68 (CRPE.DLL or CRPE32.DLL)
When your application runs, it links with the Crystal Report Engine to access report writing functionality.
Reporting can be simple, producing only a single report that is sent to a printer or preview window with no
options available to the user, or it can be complex, allowing the user to change such things as record selection,
sorting, grouping, or export options.
NOTE: All references to CRPE32.DLL are for the 32-bit version. If you plan on using the 16-bit version, it is
called CRPE.DLL.
Sample Applications
Seagate Crystal Reports comes with a number of sample applications that show you how to incorporate the
capabilities of the Crystal Report Engine. Use these applications to further your understanding of the Crystal
Report Engine and how to use it in various programming environments.
Exporting Reports
The Crystal Report Engine enables you to print to a printer or a preview window with simple function calls.
In addition, you can export a file in multiple formats and to multiple destinations. For example:
● through e-mail to another person or group of people
● directly to disk
● to HTML for updating a web site
● to a Microsoft Exchange folder
● to a Lotus Notes folder
● to an ODBC data source
The report can be exported in any of several word processing, spreadsheet, database file, or data exchange
formats including HTML.
NOTE: Visual Basic programmers can use the Active Data Driver, along with the Crystal Report Engine API or
the Crystal Report Engine Automation Server to create reports dynamically at runtime. For more information,
refer to Active Data Driver, Page 118.
● The Crystal Report Engine provides a convenient add-on to your existing application development
project. With just a few lines of code, you can produce a powerful report writing and distribution tool
that would take thousands of lines of code and weeks to produce otherwise.
● The Crystal Report Engine does not require the use of a fixed user interface. The Crystal Report Engine
is designed to work with your existing development project and allows you to define the user interface
your customers and users are familiar with and expect from your application.
Step 2: Designing the user interface that drives the Crystal Report Engine
The interface you develop to allow users to print reports is limited only by your needs and your imagination.
The kind of user interface you select is unimportant to the Crystal Report Engine.
Common methods of using the Crystal Report Engine include a single menu command that produces a single
report, a dialog box allowing several options for printing reports, or a completely separate front-end
application that is called by your application. All are acceptable techniques, and each has its advantages. How
you design your user interface can depend on any or all of the following:
● The purpose of your application.
● The types of reports your application will use.
● The printing options you want to make available with those reports.
● Whether your application will offer only one report or a choice of several reports.
Consider your application and your reporting needs carefully, and design a User Interface that will use the
Crystal Report Engine most efficiently.
Uses
crpe32;
The implementation section of the Crystal Report Engine API unit contains all of the Crystal Report Engine API
functions defined as external and as part of the CRPE or CRPE32 DLL.
The Using the Crystal Report Engine, Page 66, includes Delphi declarations for all Report Engine API functions
and records. In addition, the Developer’s online Help includes Delphi sample code using many of the
functions and records defined in CRPE.PAS. Search for Report Engine Functions - Sample Code in Delphi in the
Developer’s online Help.
NOTE: Many functions and records are defined differently for 16-bit and 32-bit systems. When referring to
declarations in reference sections, make sure you are using the correct version of the function or record for
the operating system environment you are working in.
NOTE: For complete information on distributing Crystal Report Engine and other runtime DLLs with your
application, refer to the Runtime File Requirements online Help.
The process for loading a DLL and calling DLL functions is a well documented aspect of the Windows API. If
you are not familiar with working with DLLs, please refer to Windows API documentation before attempting
to use the Crystal Report Engine API. You may also want to consider one of the other methods described in
this section for adding the Crystal Report Engine to your application.
The rest of this section assumes an understanding of DLLs and how to use them in a Windows application. It
also assumes a basic understanding of the C language. The examples here are written in C, and do not cover
the LoadLibrary, GetProcAddress, or FreeLibrary calls.
Many Windows development environments support direct calls to DLL functions, Visual Basic, Visual
dBASE, and Delphi, for example. Refer to the documentation for your development environment for complete
instructions on using a DLL. Your documentation may also cover instructions on how to translate C function
calls to the language you use. Study your documentation, then review the steps described here for using the
Crystal Report Engine in an application via the Crystal REAPI.
Seagate Crystal Reports provides several source code files that declare the functions in the Crystal REAPI for
several popular development languages. These files were installed in the Seagate Crystal Reports directory
(\CRW by default) and are ready to be immediately added to your project. The following Crystal REAPI
declaration files are available:
● CRPE.H declares all Crystal Report Engine API functions for C/C++.
● GLOBAL.BAS and GLOBAL32.BAS declare all Crystal Report Engine API functions for Visual Basic.
For more information on using the Crystal Report Engine API with Visual Basic, see Using the Crystal
Report Engine API in Visual Basic, Page 104.
● CRPEDB.H declares several Crystal Report Engine functions for Visual dBASE. Because of limits in the
dBASE language, not all Crystal Report Engine functions are available to dBASE programmers. Refer
to the individual function in Developer’s online Help for information on dBASE availability.
● CRPE.PAS and CRPE32.PAS declare all Crystal Report Engine API functions for Delphi. For more
information on using the Crystal Report Engine API with Delphi, see Using the Crystal Report Engine
API in Delphi, Page 68.
NOTE: Functions can be declared on an individual basis, but unless you will only be using a few of the Crystal
Report Engine functions in your code, it is easiest to simply copy one of the previously mentioned code files
into your project directory and add it to your project.
The Crystal REAPI provides two options for processing and producing reports from within an application:
1. The Print-Only Link, Page 71
2. The Custom-Print Link, Page 74
The Print-Only Link is the fastest, easiest method for producing a report with the Crystal REAPI. A Print-Only Link,
however, provides a very limited functionality. It allows a report to be printed on a default printer or previewed in
a window on-screen. It does not allow you to customize a report in any way before printing it, though.
A Custom-Print Link, on the other hand, provides all the report processing power of Seagate Crystal Reports
itself. By coding a Custom-Print Link into your application, you can change record selection, record sorting,
group creation, group selecting, group sorting, exporting to disk files, e-mail, Exchange and Lotus Notes
folders, ODBC data sources, selecting specific printers for printing, logging on to SQL servers and ODBC data
sources, editing formulas, formatting report sections, and much more. A Custom-Print Link is, however, a
more complex process to code than a Print-Only Link.
The first time you use the Crystal REAPI in your application project, you may want to start by coding a simple
Print-Only Link to produce basic reporting functionality. As your project develops and you become more
familiar with the Crystal REAPI, you can expand the reporting functionality with a Custom-Print Link.
A Print-Only Link is performed using the PEPrintReport function. The PEPrintReport function provides basic
report printing functionality and demonstrates basic techniques for calling Crystal Report Engine functions
from your application.
PEPrintReport enables your application to print a report, to select the output device, either a default printer or
a preview window, and to specify the size and location of the preview window if the report is printed to a
window. This function does not enable you to customize the report (select the records to print, set the sort
order, etc.) at print time. You can set those parameters at report design time (using the Seagate Crystal Reports
Design Tab), but you can not change them at print time through a Print-Only Link.
If the report is sent to a preview window, you should also use the PEOpenEngine and PECloseEngine
functions with your Print-Only Link. PEOpenEngine and PECloseEngine allow you to control how long the
preview window remains open. The window will remain open until the PECloseEngine function is called or
the user clicks Close in the window. If PEOpenEngine and PECloseEngine are not used, and the report is sent
to a preview window, the window will automatically close as soon as the report finishes processing.
NOTE: You may also want to get in the habit of using PEOpenEngine and PECloseEngine in all Print-Only Links,
as they are required steps to coding a Custom-Print Link. If your code includes these functions when you design a
Print-Only Link, advancing the application to use a Custom-Print Link in the future will be much easier.
PEPrintReport Arguments
PEPrintReport is declared in CRPE.H as follows:
Parameter Description
reportFilePath The name of the report to be printed. Include the path if the report is not in
the current directory. The report name can be hard-coded and unchangeable
at runtime, or you can pass a string variable or character array as the result of
a user choice.
toDefaultPrinter If toDefaultPrinter is set to TRUE (1), the report is sent to a printer. The
toWindow argument should be set to FALSE.
toWindow If toWindow is set to TRUE (1), the report is sent to a preview window. The
toDefaultPrinter argument should be set to FALSE.
That is, the default window is a visible window with a thick frame that can be used for sizing the window. The
window includes a system menu box, and maximize and minimize buttons.
short result;
switch (message)
{
case WM_INITDIALOG:
if (!PEOpenEngine())
; // Handle error
return TRUE;
case WM_DESTROY:
PECloseEngine();
return TRUE;
A more advanced, and more powerful, method of using the Crystal Report Engine is through a Custom-Print
Link. Establishing a Custom-Print Link gives you a great deal of control over your reports at runtime. For
example, you can:
● set or modify the report sort order,
● set or modify the record selection and/or group selection formulas,
● modify existing report formulas,
● set or modify the database location,
● capture and evaluate Crystal Report Engine errors,
● export a report to a file, e-mail, Exchange or Lotus Notes folder, or ODBC data source,
● log on to SQL servers and ODBC data sources,
● format report sections,
● and much more.
NOTE: The Crystal Report Engine allows you to add a selection formula and sort fields to a report at runtime,
even if none existed in the report when it was designed. Report formulas created in the Seagate Crystal
Reports Formula Editor, however, must be added when the report is created in Seagate Crystal Reports. A
formula can be edited with the Crystal Report Engine, but can not be added to an existing report from the
Crystal Report Engine. Design your reports carefully, and keep this in mind when you create your application.
NOTE: The steps described here apply to a single print job. It is possible to have more than one print job open
at once.
Description
This step starts the Crystal Report Engine and prepares it to accept a print job. The Crystal Report Engine must
be open before a print job can be established. You should open the Crystal Report Engine before the user has
a chance to try to print a report. For example, if your application uses a dialog box as the user interface to the
Crystal Report Engine, open the Crystal Report Engine immediately after the dialog box is created at runtime.
Your dialog box can allow the user to establish a print job and make changes to the report while the Crystal
Report Engine is already open.
Every time the Crystal Report Engine is opened, it should be closed once your application is finished accessing
it (Custom-Print Link Step 6: Close the Crystal Report Engine, Page 77). For example, if you open the Crystal Report
Engine when a dialog box is created, close the Crystal Report Engine when that dialog box is destroyed.
Description
When you open a print job, the Crystal Report Engine returns a Job Handle for the print job. This handle is
important to identifying the print job in the rest of your code.
To establish a print job, PEOpenPrintJob, Volume 2, Chapter 1, requires the path and name of the report that is
to be printed. This argument can be hard-coded into the function call, as in the example above, or you can
prompt the user to choose a report for printing and pass a variable argument to the function.
To close a print job, refer to Custom-Print Link Step 5: Close the print job, Page 77. In most cases, you should open
the print job immediately before printing and close the print job as soon as the job is finished and the preview
window is closed or printing is complete.
Description
The Crystal Report Engine must know where to send the final report. The report can be printed to a printer,
displayed in a preview window, exported to a disk file, exported to another database, or exported to an e-mail
address. The example above sends the report to the preview window.
Although you can choose any of the several destinations for report output, you must establish a destination
for the report to print. You can, however, write code in your application that allows your users to decide on a
destination themselves.
NOTE: This step does not actually print the report, it only establishes a destination for the report when
printed. The report is actually printed in Step 4 using the PEStartPrintJob function.
The following functions are available to establish a print destination:
● PEOutputToWindow, Volume 2, Chapter 1
Printing a report to a window requires no other print destination code other than the function itself.
● PEOutputToPrinter, Volume 2, Chapter 1
Printing a report to a printer requires no other print destination code other than the function itself.
However, PESelectPrinter, Volume 2, Chapter 1, can be used to select a printer other than the default
printer at runtime. The PESelectPrinter function uses the Windows structure DEVMODE, Volume 2,
Chapter 1. For more information on this structure, refer to the Windows SDK.
● PEExportTo, Volume 2, Chapter 1
The PEExportTo function works with the PEExportOptions Structure (page 95) and several DLLs that
control a report’s export destination and format. The information required by PEExportTo can be set in
Description
This function actually sends the report to the output device indicated in Step 3. Once PEStartPrintJob, Volume 2,
Chapter 1, is called, the Crystal Report Engine begins generating the report. The Crystal Report Engine displays a
dialog box that indicates the status of the report being generated. If the report is sent to the preview window, the
window will appear as soon as PEStartPrintJob is called. The preview window can be closed by a call to
PECloseWindow, Volume 2, Chapter 1, by closing the Crystal Report Engine (as in Step 6), or by the user clicking
the Close button.
As a general rule, you should avoid making any formatting changes to a print job once you call
PEStartPrintJob, especially if the report is being displayed in a preview window (via PEOutputToWindow).
Formatting changes made to a report while it is still being generated and displayed in the preview window
may produce undesired results, and can cause errors in the Crystal Report Engine.
Description
Once the print job has completed, it can be closed using PEClosePrintJob, Volume 2, Chapter 1. If you wish to
make more changes to the report and print it again, you can do so before closing the job. However, once your
application is finished with a report, it should close the print job to free up memory in the user’s system.
Description
This function closes the Crystal Report Engine entirely. No other Crystal Report Engine functions relating to
print jobs may be called once the Crystal Report Engine is closed. Therefore, you should keep the Crystal
Report Engine open until it is no longer needed in your application. For example, if the Crystal Report Engine
is accessed through a dialog box in your application, you should wait to close the Crystal Report Engine until
the dialog box is exited and destroyed by Windows.
Event code
short hJob; /* print job handle */
BOOL bResult;
hJob = PEOpenPrintJob(“C:\\CRW\\ORDER.RPT”);
if (!hJob)
{
ReportError(hJob);
return;
}
if (ToWindow)
{
bResult = PEOutputToWindow(hJob,
“My Report”, CW_USEDEFAULT,
CW_USEDEFAULT, CW_USEDEFAULT,
CW_USEDEFAULT, 0, NULL);
}
else
{
bResult = PEOutputToPrinter(hJob, 1);
}
Error code
void ReportError(short printJob)
{
short errorCode;
HANDLE textHandle;
short textLength;
char *errorText;
errorCode = PEGetErrorCode(printJob);
PEGetErrorText ( printJob,
&textHandle,
&textLength);
errorText = (char*)malloc(textLength);
PEGetHandleString(textHandle,
errorText,
textLength);
MessageBox( hWnd, errorText,
“Print Job Failed”,
MB_OK | MB_ICONEXCLAMATION);
return;
}
This section declares two local variables that are important to the remainder of the code. The variable hJob will
receive the handle to the print job that results from a PEOpenPrintJob call. This handle is required by most
Crystal Report Engine functions. bResult will be given a TRUE or FALSE value as the result of several Crystal
Report Engine calls. Any time bResult receives a FALSE value, an error has occurred.
hJob = PEOpenPrintJob(“C:\\CRW\\ORDER.RPT”);
This call opens the new print job according to the path and file name of the report that is to be printed. In this
example, the report name is hard-coded in the Crystal Report Engine call. A user would have no choice as to
which report is printed. This function could also accept a character array or a pointer to a character array as
an argument, allowing you to give your users the opportunity to choose a specific report for printing.
PEOpenPrintJob returns a handle to the new print job, hJob. This handle will be used in all of the subsequent
Crystal Report Engine calls shown here.
if (!hJob)
{
ReportError(hJob);
return;
}
This if statement verifies whether a valid print job handle was received in the previous line of code. If
PEOpenPrintJob returned a value of 0, the print job is invalid and an error is reported. For more information
on processing Crystal Report Engine errors, see the Error code section that appears below.
if (ToWindow)
{
bResult = PEOutputToWindow(hJob,
“My Report”, CW_USEDEFAULT,
CW_USEDEFAULT, CW_USEDEFAULT,
CW_USEDEFAULT, 0, NULL);
}
else
{
bResult = PEOutputToPrinter(hJob, 1);
}
ToWindow acts as a Boolean variable that provides information from the user’s decision as to whether this
report will be printed to a preview window or to a printer. If ToWindow holds a TRUE value, then the user has
decided to print the report to a preview window.
if (!bResult)
{
ReportError(hJob);
PEClosePrintJob(hJob);
return;
}
Once the appropriate destination function is called, you must verify its success and report an error if bResult is
FALSE. ReportError is the error handling routine. It is an internal function designed to process any errors that
occur during a print job. The function is passed the current value of the hJob handle for use in analyzing errors.
Search for Crystal Report Engine Error Codes in Developer’s online Help for information on processing errors.
NOTE: ReportError is not a Crystal Report Engine function, but specific to the code appearing here; it is meant
only as an example of how to handle Crystal Report Engine errors.
Since a print job has been opened, you must close it after the error is reported using PEClosePrintJob. See
below for more information on this function. Finally, the if statement causes a return after the error has been
reported, thus ending the print job session.
if (!PEStartPrintJob(hJob, TRUE))
{
ReportError(hJob);
}
PEStartPrintJob actually sends the print job to the printer or a preview window. If the report is printed to a
window, PEStartPrintJob creates and opens the window according to the parameters set in the
PEOutputToWindow function. If PEStartPrintJob fails (returns FALSE), an error is reported.
PEClosePrintJob(hJob);
Once the report has printed, this print job can be closed and another one can be started if needed. If the report has
been printed to a preview window, PEClosePrintJob does not close the window. The preview window is closed
when the Close button is clicked, the PECloseWindow function is called, or the PECloseEngine function is called.
return;
Now that the print job has finished, the event procedure can return, and the application can wait for the next
user event to occur.
Error code
void ReportError(short printJob)
{
NOTE: The REAPI functions described here, PEGetErrorCode and PEGetErrorText, are specific to REAPI error
handling. For complete descriptions of these functions, see Seagate Crystal Report Engine Reference, Volume 2,
Chapter 1, or search for the functions by name in Developers online Help. The function PEGetHandleString is
used to retrieve variable length strings generated by different REAPI functions.
short errorCode;
HANDLE textHandle;
short textLength;
char *errorText;
Completely processing any Crystal Report Engine error requires at least four variables like those above. While
only errorCode will be needed to retrieve the Crystal Report Engine error number, the other three variables
will all be needed to retrieve the actual error text.
errorCode = PEGetErrorCode(printJob);
PEGetErrorCode returns a number associated with the error that has occurred. For a list of these error codes
and their meanings, search for Crystal Report Engine Error Codes in Developer’s online Help or see CRPE Error
Codes, Volume 2, Chapter 1.
PEGetErrorText ( printJob,
&textHandle,
&textLength);
errorText = (char*)malloc(textLength);
PEGetHandleString(textHandle,
errorText,
textLength);
The error text must be returned in the form of a handle to a variable length string. The handle is used, along
with the PEGetHandleString function to obtain the actual error text and store it in a character array. This is a
complicated process, and it should be examined carefully if your code is to work.
MessageBox( hWnd, errorText,
“Print Job Failed”,
MB_OK | MB_ICONEXCLAMATION);
Once the error has been obtained, you can display error information to the user. This example simply opens a
warning message box to alert the user of the problem. Using the error code and the error text, however, you
can control Crystal Report Engine error messages any way that you find appropriate for your application.
return;
}
Once error processing is finished, you can return to processing the print job. If an error has occurred during
the print job, however, then the print job should be terminated immediately after the error is processed.
Review the evaluation of the event code above for ideas on how to terminate a print job after an error.
Constant Description
PE_DR_HASRANGE Only ranges are present.
PE_DR_HASDISCRETE Only discrete values are present.
PE_DR_HASDISCRETEANDRANGE Both discrete values and ranges are present. See
guidelines below.
The functions listed below are used to add and retrieve parameter discrete values and parameter ranges. The
sequence of functions that you call in your application will depend on whether discrete values, ranges, or a
combination of both are present.
PEXXXParameterCurrentValue(s) PEXXXParameterCurrentRange(s)
PEGetNParameterCurrentValues, Volume 2, Chapter 1 PEGetNParameterCurrentRanges, Volume 2, Chapter 1
PEGetNthParameterCurrentValue, Volume 2, Chapter 1 PEGetNthParameterCurrentRange, Volume 2, Chapter 1
PEAddParameterCurrentValue, Volume 2, Chapter 1 PEAddParameterCurrentRange, Volume 2, Chapter 1
Use the following guidelines when deciding which sequence of functions to call.
PEParameterValueInfo.hasDiscreteValues = PE_DR_HASRANGE
The parameter field contains only ranges.
All values will be treated as ranges.
Use the PEXXXParameterCurrentRange(s) function calls.
PEParameterValueInfo.hasDiscreteValues = PE_DR_HASDISCRETE
The parameter field contains only discrete values.
All values will be treated as discrete values.
Use the PEXXXParameterCurrentValue(s) function calls.
PEParameterValueInfo.hasDiscreteValues = PE_DR_HASDISCRETEANDRANGE
The parameter field contains both discrete values and ranges.
All values will be treated as ranges.
Use the PEXXXParameterCurrentRange(s) function calls.
You can also call PEAddParameterCurrentValue to add a discrete value, but the discrete value will
be stored internally as a range and you will need to call PEGetNParameterCurrentRanges and then
PEGetNthParameterCurrentRange when you want to retrieve it. If you try to retrieve the discrete
The following topics relating to section codes are presented in this section.
Overview, Page 84
Encoding, Page 84
Decoding, Page 86
Section Map, Page 87
Section Codes in Visual Basic, Page 88
Overview
A report, by default, contains five areas: Report Header, Page Header, Details, Report Footer, and Page Footer.
Each of those areas can contain one or more sections. When you add groups, subtotals, or other summaries to
your report, the program adds Group Header and Group Footer areas as needed, and each of those areas can
contain one or more sections as well. Since one report can have a totally different section configuration from
the next, Seagate Crystal Reports uses calculated section codes to identify the sections in each report.
In Seagate Crystal Report Engine API functions that affect report sections, the sectionCode parameter encodes
the section type, the group number (if the section is a Group Header or Group Footer section), and the section
number (if there are multiple sections in an area) together in a single value.
The Seagate Crystal Report Engine API also includes macros for encoding section codes
(PE_SECTION_CODE, for use with functions that require a section code) and for decoding section codes
(PE_SECTION_TYPE, PE_GROUP_N, and PE_SECTION_N, for use with functions that return a section code).
The examples that follow show how the encoding and decoding macros can be used.
NOTE: You can not pass the above values directly to a function as section codes. You must use the encoding
macro to create a valid section code based on one of the above constants.
Encoding
The PE_SECTION_CODE macro allows you to define a section code to pass as a parameter in Seagate Crystal
Report Engine functions that require a section code. The syntax for the macro is:
PE_AREA_CODE(sectionType,groupN)
groupNumber
Indicates which group the section is in. If the sectionType value indicated is PE_SECT_GROUP_HEADER or
PE_SECT_GROUP_FOOTER, the groupNumber is a zero (0) based index for the group section. If the
sectionType value is not one of these group section constants, the groupNumber value should always be zero.
sectionNumber
If the report area has been split into more than one section, sectionNumber indicates which section within the
area you are using. This value is a zero (0) based index. In other words, the first section in an area is 0, the next
section is 1, etc.
NOTE: The macro PE_SECTION_CODE calculates and returns the section code number; it does not return an
error code.
The following example demonstrates how to obtain a section code using the PE_SECTION_CODE macro. The
section code obtained here is for the second section in the Group Header 1 area:
code = PE_SECTION_CODE(PE_SECT_GROUP_HEADER, 0, 1);
PESetSectionFormat(job, code, &mySectionOptions);
In this case you pass the section type (PE_SECT_GROUP_HEADER), the group number (since this is the first
group, use the zero indexed group number 0) and section number (since this is the second section in the Group
Header, use the zero indexed section number 1). The program uses the encoding macro and returns a section
code which is then passed in the PESetSectionFormat call.
NOTE: The maximum number of groups is 25 (possible values of 0 to 24). The maximum number of sections is
40 (possible values of 0 to 39).
Decoding
Some Seagate Crystal Report Engine functions return section codes. These values can be decoded using one of
three macros:
1. PE_SECTION_TYPE (sectionCode),
2. PE_GROUP_N (sectionCode), or
3. PE_SECTION_N (sectionCode).
Each macro accepts an encoded section code as a parameter.
In the following example, you determine the number of sections in the report (using PEGetNSections), obtain
the section code for each section (using PEGetSectionCode), and then decode the section code using the
PE_SECTION_TYPE, PE_GROUP_N, and PE_SECTION_N macros.
numSections = PEGetNSections(job);
for (i = 0;i < numSections;i++)
{
code = PEGetSectionCode(job, loopSectionN);
areaType = PE_SECTION_TYPE(code);
groupN = PE_GROUP_N(code);
sectionN = PE_SECTION_N(code);
Once you’ve identified the area, group, and section you want, you can then set the section format using code
similar to this:
NOTE: Earlier versions of Seagate Crystal Reports used different section code constants. Those constants have
been remapped to the new section code format so reports created with earlier versions of Seagate Crystal
Reports can run with applications created with the current version.
Report Header
1000 First Section in Report Header Area
1025 Second Section in Report Header Area
1050 Third Section in Report Header Area
1075 Fourth Section in Report Header Area
up to 1975 40th Section in Report Header Area
Page Header
2000 First Section in Page Header Area
2025 Second Section in Page Header Area
2050 Third Section in Page Header Area
2075 Fourth Section in Page Header Area
up to 2975 40th Section in Page Header Area
GH1
3000 First Section in First Group Header Area
3025 Second Section in First Group Header Area
3050 Third Section in First Group Header Area
3075 Fourth Section in First Group Header Area
GH2
3001 First Section in Second Group Header Area
3026 Second Section in Second Group Header Area
3051 Third Section in Second Group Header Area
3076 Fourth Section in Second Group Header Area
Details
4000 First Section in Details Area
4025 Second Section in Details Area
4050 Third Section in Details Area
4075 Fourth Section in Details Area
GF2
5001 First Section in Second Group Footer Area
5026 Second Section in Second Group Footer Area
5051 Third Section in Second Group Footer Area
5076 Fourth Section in Second Group Footer Area
Page Footer
7000 First Section in Page Footer Area
7025 Second Section in Page Footer Area
7050 Third Section in Page Footer Area
7075 Fourth Section in Page Footer Area
Report Footer
8000 First Section in Report Footer Area
8025 Second Section in Report Footer Area
8050 Third Section in Report Footer Area
8075 Fourth Section in Report Footer Area
End Function
End Function
End Function
End Function
Several REAPI functions provide information in the form of a variable length string value or character array.
When your program calls an REAPI function that produces a variable-length string, the Crystal Report Engine
saves the string, creates a string handle which refers to the string, and returns that handle along with a value
indicating the length of the string. To retrieve the contents of the string, you must call PEGetHandleString,
Volume 2, Chapter 1. This approach allows you to allocate a buffer of the exact size needed to hold the string
before obtaining the actual string.
If your development language can not allocate a buffer at runtime, you should declare a reasonably large
buffer. Field names and error messages will generally be less than 100 bytes, but formulas may be 1000 bytes
or longer. You can control how much data is copied to the buffer when you call PEGetHandleString.
Here is the procedure to follow when obtaining a variable length string:
1 Call-up the function which produces the string. This returns the string handle and length. The length
includes all characters in the string plus a terminating null byte.
2 If necessary, allocate the string buffer.
3 Call-up PEGetHandleString to copy the string from the handle into the buffer.
Sample Code
Use the following C code as an example of how to call a function that returns a variable length string. The code
uses the PEGetNthSortField, Volume 2, Chapter 1, function which obtains the name of a field being used to sort
the report and the direction of the sort. There are several other functions that return variable length strings, all
of which are handled in a similar fashion.
Examine this code carefully and try to incorporate it into your own application without modifying the basic
procedure. Only experienced programmers should try making changes to this technique since small mistakes
here can cause major errors in your application. If you expect to use several REAPI functions that return
variable length strings, you may want to set this code up in a separate function to avoid repetition and errors.
HANDLE nameHandle;
short nameLength;
short direction;
char *fieldName;
PEGetHandleString ( nameHandle,
fieldName,
nameLength);
/*
** fieldName now contains name
** of field and nameHandle is no
** longer valid.
*/
NOTE: If you retrieve a string handle but do not retrieve the string itself (i.e., you do not use
PEGetHandleString), you should free up the string memory by calling GlobalFree (nameHandle).
Any time you evaluate a function that returns a variable length string, you will need at least three variables:
1. a handle to the string,
2. a short integer to hold the length of the string, and
3. a character array or pointer to a character array.
The direction variable in this example will hold the sort direction and is specific to PEGetNthSQLExpression,
Volume 2, Chapter 1.
It is important to note that although the PEGetNthSortField function is defined in the Crystal Report Engine
as accepting a pointer to a handle (HANDLE*) and a pointer to a short (short*), nameHandle and nameLength
are not defined as pointer variables. Instead, they are defined simply as a HANDLE and a short integer, then
passed to PEGetNthSortField with the & operator. This technique automatically initializes the variables with
the address of the variable itself. Since the PEGetNthSortField function requires the address in memory to
place the information, this is the most convenient method to define and pass the variables.
The PEGetNthSortField function places a handle to the sort field name in the nameHandle location and the
length of the field name (all characters in the name plus a terminating null byte) in the nameLength location.
These values will be used to extract the actual field name.
Now that you know the actual length of the field name you are trying to obtain, you can allocate exactly the
right amount of memory to store that name. The malloc function does this.
PEGetHandleString, Volume 2, Chapter 1, uses the string handle to retrieve the field name and store it in
fieldName. At the same time, nameHandle is invalidated. Now, the text can be used like any other character
string.
NOTE: This code is meant as a basis for your own code. Although these elements shown here are necessary for
extracting a variable length string from certain Crystal Report Engine functions, experienced programmers
may wish to expand the code to trap errors or handle the string text differently.
Several REAPI functions require a structure or user-defined variable type to be passed as one or more
arguments. Some of these functions require that you assign values to all members of the structure before
calling the function so that the information can be used to make various settings in the Crystal Report Engine.
Other functions require only the size of the structure be assigned to the StructSize member. These functions
fill in the rest of the structure members for you, providing you with valuable information about a print job.
NOTE: The term structure is used here to mean both C structures and other user-defined types or records in
languages such as Visual Basic and Delphi. If you are unfamiliar with this type of data, refer to the
documentation for the programming language you are using.
Each structure used by REAPI is defined and explained in Developer’s online Help with a link to the function
that uses it. Functions that use structures also have hypertext links to the structure definitions.
Some of the structures, PEMouseClickEventInfo(Other Declares), Volume 2, Chapter 1, for example, are
complex, requiring other structures be passed as member values. Not all programming languages support this
feature. If you are using a programming language that does not allow the use of a structure variable as a
member variable defined inside other structures, declare the member variable as another data type, such as an
integer or a variant data type, and assign it a value of 0 (zero) at runtime. The Crystal Report Engine will
automatically provide default values or will request information from the user.
NOTE: Structure variables can not be created using Visual dBASE. Crystal Report Engine functions requiring
structures as parameters are not available to dBASE.
Your application can have much of the same control over subreports that it has over primary reports. The only
exceptions are:
● you can not open or close a print job while a subreport is open, and
● you can only work with report sections that are actually in the subreport.
For example, subreports do not have page header sections like primary reports do, so you can not do anything
with a subreport that requires a page header section.
Most Crystal Report Engine functions require a print job handle as a parameter. When you supply the handle
to a primary report, the functions act on the primary report. When you supply the handle to a subreport, the
functions act on the subreport. Getting the handle requires a number of steps.
When sending reports to a preview window using PEOutputToWindow, Volume 2, Chapter 1, you should
always avoid making any formatting changes to a print job once you call PEStartPrintJob, Volume 2, Chapter 1.
If the first page of a report has been displayed in the preview window, and you make formatting changes to
the print job, subsequent pages of the report, if requested, may appear formatted differently than the first page.
Depending on the changes made, trying to change report formatting after calling PEStartPrintJob can even
cause errors in the Crystal Report Engine.
To avoid such formatting problems, you should get in the habit of formatting the report before starting the
print job with PEStartPrintJob. Adding a routine to monitor job status using PEGetJobStatus, Volume 2, Chapter
1, can also help avoid conflicts. If you need to display the same report with different formatting options, create
two separate print jobs, format each separately, and start each separately.
Exporting reports
The following topics are discussed in this section:
PEExportTo Overview, Page 95
PEExportOptions Structure, Page 95
Considerations when using the export functions, Page 97
Using the Professional Edition of Seagate Crystal Reports, you can give your applications the ability to export
reports in a number of word processor and spreadsheet formats, and in a variety of popular data interchange
formats as well.
The program includes two export functions, PEExportTo, Volume 2, Chapter 1, and PEGetExportOptions, Volume
2, Chapter 1. PEExportTo can be used by itself or in conjunction with PEGetExportOptions.
● Use PEExportTo by itself if you want your application to export reports in a fixed format to a fixed
destination. Use this alternative, for example, if you want to preset the format and destination for a
report and have the application export the report according to your specifications in response to user
input.
● Use PEExportTo in conjunction with PEGetExportOptions to export reports in the format and
destination your user selects from the Export dialog box at Print time.
PEGetExportOptions can only be used in conjunction with PEExportTo.
The PEExportTo, Volume 2, Chapter 1 function uses a structure, PEExportOptions, Volume 2, Chapter 1, as part
of its argument list. This structure passes format and destination data to the function.
When using the PEExportTo function by itself, you hard code the format and destination data into the
structure. Then, when you issue a call to PEStartPrintJob, Volume 2, Chapter 1, the program exports the report
using the format and destination you specified in the code.
● Most of the format and destination data that you need to enter can be taken from the table in the
PEExportTo topic.
● To hard code an export file name or e-mail header information, you will have to pass a second structure
as an argument to the PEExportOptions structure. This second structure is defined in the *.h file that
corresponds with the destination DLL you have selected.
When using the PEExportTo function in conjunction with the PEGetExportOptions function, you run the
PEGetExportOptions function first to:
● retrieve the format and destination data that the user specifies in the Export dialog box, and
● pass that data to the PEExportOptions structure (again, part of the PEExportTo argument list).
Then, when you issue a call to PEEnableEventInfo, Volume 2, Chapter 1, the program exports the report using
the format and destination specified by the user.
PEExportOptions Structure
struct PEExportOptions
{
WORD StructSize;
// the size of the structure. Initialize to sizeof PEExportOptions
char formatDLLName [PE_DLL_NAME_LEN];
// Each export format is defined in a DLL. This is the name of the
// DLL for the format you select. From table in PEExportTo topic.
// Requires a null-terminated string. Does not need to include
// drive, path or extension. For example, uxfsepv is an example of
// a valid formatDLLName.
DWORD formatType;
// Some DLLs are used for more than one format. Enter the
// appropriate value from the table under PEExportTo.
void FAR *formatOptions;
// Some formats offer additional options (see table in the
// PEExportTo topic). You can set this element to 0. Then, If the
// DLLs require more information, they will prompt the user
// for it. To hard code this information, see the note immediately
NOTE: You may choose to hard code the data for formatOptions and destinationOptions. You can set the
formatOptions and destinationOptions elements to 0 as indicated. If the DLLs require more information than
this, however, they will prompt the user to include more information. To hard code this information, you must
define and fill in a structure of the appropriate kind. See the header file for the specified DLL for examples.
Once the structure is defined, set the formatOptions or destinationOptions element to the address of the
structure. Once PEExportTo returns or finishes, deallocate the formatOptions and destinationOptions
structures. You should also deallocate the PEExportOptions structure once PEExportTo returns.
#include “crpe.h”
#include “Windows.h”
switch(eventID)
{
case PE_CLOSE_PRINT_WINDOW_EVENT:
case PE_PRINT_BUTTON_CLICKED_EVENT:
case PE_EXPORT_BUTTON_CLICKED_EVENT:
case PE_FIRST_PAGE_BUTTON_CLICKED_EVENT:
case PE_PREVIOUS_PAGE_BUTTON_CLICKED_EVENT:
case PE_NEXT_PAGE_BUTTON_CLICKED_EVENT:
case PE_LAST_PAGE_BUTTON_CLICKED_EVENT:
case PE_CANCEL_BUTTON_CLICKED_EVENT:
case PE_ACTIVATE_PRINT_WINDOW_EVENT:
case PE_DEACTIVATE_PRINT_WINDOW_EVENT:
case PE_PRINT_SETUP_BUTTON_CLICKED_EVENT:
case PE_REFRESH_BUTTON_CLICKED_EVENT:
{
PEGeneralPrintWindowEventInfo * eventInfo =
(PEGeneralPrintWindowEventInfo *) param;
ASSERT(eventInfo != 0 && eventInfo->StructSize ==
PE_SIZEOF_GENERAL_PRINT_WINDOW_EVENT_INFO);
// TODO
}
break;
case PE_ZOOM_LEVEL_CHANGING_EVENT:
{
PEZoomLevelChangingEventInfo * eventInfo =
(PEZoomLevelChangingEventInfo *) param;
ASSERT(eventInfo != 0 && eventInfo->StructSize ==
PE_SIZEOF_ZOOM_LEVEL_CHANGING_EVENT_INFO);
// TODO
}
break;
// TODO
}
break;
case PE_CLOSE_BUTTON_CLICKED_EVENT:
{
PECloseButtonClickedEventInfo *eventInfo =
(PECloseButtonClickedEventInfo *)param;
ASSERT(eventInfo != 0 && eventInfo->StructSize ==
PE_SIZEOF_CLOSE_BUTTON_CLICKED_EVENT_INFO);
// TODO
}
break;
case PE_SEARCH_BUTTON_CLICKED_EVENT:
{
PESearchButtonClickedEventInfo *eventInfo =
(PESearchButtonClickedEventInfo *)param;
ASSERT(eventInfo != 0 && eventInfo->StructSize ==
PE_SIZEOF_SEARCH_BUTTON_CLICKED_EVENT_INFO);
// TODO
}
break;
case PE_SHOW_GROUP_EVENT:
{
PEShowGroupEventInfo * eventInfo =
(PEShowGroupEventInfo *)param;
ASSERT(eventInfo != 0 && eventInfo->StructSize ==
PE_SIZEOF_SHOW_GROUP_EVENT_INFO);
// TODO
}
break;
case PE_DRILL_ON_GROUP_EVENT:
{
PEDrillOnGroupEventInfo * eventInfo =
// TODO
}
break;
case PE_DRILL_ON_DETAIL_EVENT:
{
PEDrillOnDetailEventInfo * eventInfo =
(PEDrillOnDetailEventInfo *) param;
ASSERT(eventInfo != 0 && eventInfo->StructSize ==
PE_SIZEOF_DRILL_ON_DETAIL_EVENT_INFO);
// TODO
}
break;
case PE_READING_RECORDS_EVENT:
{
PEReadingRecordsEventInfo * readingRecordsInfo =
(PEReadingRecordsEventInfo *) param;
ASSERT(readingRecordsInfo != 0 &&
readingRecordsInfo->StructSize ==
PE_SIZEOF_READING_RECORDS_EVENT_INFO);
// TODO
}
break;
case PE_START_EVENT:
{
PEStartEventInfo * startEventInfo =
(PEStartEventInfo *) param;
ASSERT(startEventInfo != 0 &&
startEventInfo->StructSize ==
PE_SIZEOF_START_EVENT_INFO);
// TODO
}
break;
case PE_STOP_EVENT:
{
PEStopEventInfo * stopEventInfo =
PEWindowOptions windowOptions;
windowOptions.StructSize = PE_SIZEOF_WINDOW_OPTIONS;
PEGetWindowOptions(printJob, &windowOptions);
windowOptions.hasGroupTree = TRUE;
windowOptions.hasSearchButton = TRUE;
windowOptions.canDrillDown = TRUE;
if(!PESetWindowOptions(printJob, &windowOptions))
return FALSE;
// enable event.
// by default, events are disabled.
PEEnableEventInfo eventInfo;
eventInfo.StructSize = sizeof(PEEnableEventInfo);
eventInfo.activatePrintWindowEvent = PE_UNCHANGED;
eventInfo.closePrintWindowEvent = TRUE;
eventInfo.startStopEvent = TRUE;
eventInfo.printWindowButtonEvent = PE_UNCHANGED;
eventInfo.drillEvent = TRUE;
eventInfo.readingRecordEvent = TRUE;
PETrackCursorInfo cursorInfo;
cursorInfo.StructSize = sizeof(PETrackCursorInfo);
cursorInfo.groupAreaCursor = PE_UNCHANGED;
cursorInfo.groupAreaFieldCursor = PE_UNCHANGED;
cursorInfo.detailAreaCursor = PE_TC_CROSS_CURSOR;
cursorInfo.detailAreaFieldCursor = PE_TC_IBEAM_CURSOR;
cursorInfo.graphCursor = PE_UNCHANGED;
if(!PESetTrackCursorInfo(printJob, &cursorInfo))
return FALSE;
return TRUE;
}
Using the Crystal Report Engine API in Visual Basic, Page 104
...including comments regarding opening and closing the Crystal Report
Engine, embedded quotes in VB calls, identifying string issues, passing
dates and date ranges, hard coded nulls in User Defined Types and VB
Wrapper DLL.
Crystal ActiveX Controls, Page 108
...including comments regarding adding and using ActiveX Controls in
your project, and upgrading Crystal Custom Controls.
Crystal Report Engine Automation Server, Page 111
...including comments regarding adding, using and distributing
Automation Server in your projects, Object name conflicts, preview
window events, viewing the Object Library, and sample applications.
Active Data Driver, Page 118
...including comments regarding using Active Data Driver, Data
Definition Files, and using ActiveX Data Sources at design time.
Crystal Data Object, Page 128
...including comments regarding Crystal Data Object, the Object Model,
and the Crystal Data Source Type Library
Crystal Data Source Type Library, Page 131
...including adding and implementing the Crystal Data Source Type
Library, Crystal Data Source Projects, and passing DataSource objects to
the Active Data Driver.
Grid Controls and the Crystal Report Engine, Page 139
...including comments regarding Control Properties, bound and
formatted bound reports, and a sample application.
In a Visual Basic application, you can either open the Crystal Report Engine when you open your application
or when you open a form. As a general rule, it is always best to open the Crystal Report Engine when you open
the application and close it when you close the application. Here is why:
● When you open and close a form, the Crystal Report Engine opens every time you open the form and
closes every time you close the form. If you print a report, close the form, and later decide to print a
report again, the application has to reopen the Crystal Report Engine when you open the form, creating
a time delay while running your application.
● When you open and close the application, the Crystal Report Engine opens as you start the application,
and stays open as long as the application is open. Once the Crystal Report Engine is open, you can
print a report as often as you wish without the need to reopen the Crystal Report Engine every time
you print.
When you pass a concatenated string from Visual Basic to the Crystal Report Engine (for example, for a record
selection formula), it is important that the resulting string has the exact syntax that the Crystal Report Engine
expects. You should pay special attention to embedded quotes in concatenated strings because they are often
the source of syntax errors.
Several examples follow. The first example shows code with a common embedded quote syntax error and the
last two examples show code using the correct syntax.
Correct syntax
VBNameVariable$ = “John”
Recselct$ = “{file.LASTNAME} = “ +
(chr$(39) + VBNameVariable + chr$(39)
You may want to pass date or date range information from your Visual Basic application to the Crystal Report
Engine for use in formulas, selection formulas, etc. Here is an example showing a way to do it successfully:
1 Start by opening a print job and assigning the print job handle to a variable.
JobHandle% = PEOpenPrintJob (“C:\CRW\CUSTOMER.RPT”)
2 Create variables that hold the year, month, and day for both the start and end of the range.
StartYear$ = 1992
StartMonth$ = 01
StartDay$ = 01
EndYear$ = 1993
EndMonth$ = 12
EndDay$ = 31
● Second, build the selection formula using the StrtSelect$ and EndSelect$ variables.
4 Once your formula is built, set the record selection formula for the report.
RetCode% = PESetSelectionFormula
(JobHandle%, RecSelect$)
When passing a string to the Crystal Report Engine as part of the Custom-Print Link, you may think that you
are passing one thing when the program, in fact, is passing something entirely different. This can happen
easily, for example, when you are passing a concatenated string that you have built using variables. A small
syntax error (with embedded quotes, for example) can lead to an error message and a failed call. A simple
debugging procedure follows.
MsgBox (variablename)
When you assign a string to a user defined type in Visual Basic, it is necessary to hard-code a null immediately
after the string. For example:
Some of the features of the Crystal Report Engine API are not directly available to Visual Basic programmers,
due to restrictions in the Visual Basic language, while others present technological issues that are better
handled differently from what was originally designed in the Report Engine API. To avoid problems calling
functions in the API, you may want to consider using the Crystal ActiveX Controls, Page 108, or the Crystal
Report Engine Automation Server, Page 111. However, if you prefer to work with the API, Seagate Crystal
Reports includes the Visual Basic Wrapper DLL, CRWRAP16.DLL (16-bit) and CRWRAP32.DLL (32-bit).
The Visual Basic Wrapper DLL has been designed specifically for programming in the Visual Basic
environment and can be used to build Crystal Report Engine applications in Visual Basic 4.0 or later. The
CRWRAP.BAS module, installed by default in the \Seagate Software\Crystal Reports directory, redefines
many of the functions and structures defined in GLOBAL.BAS. When working with the Crystal Report Engine
API, add both modules to your Visual Basic project.
The functions and structures defined in the Visual Basic Wrapper DLL provide an interface for handling
export formats, parameter fields, SQL server and ODBC logon information, graphs, printing, and more. For
complete information on each of the structures and functions included, search for Visual Basic Wrapper for the
Crystal Report Engine in the Developer’s online Help. In most cases, each function or structure has a
corresponding function or structure in the original Crystal Report Engine API with a similar name. When
working in Visual Basic though, you must use the functions and structures provided by the Visual Basic
Wrapper DLL.
NOTE: The development tools may refer to an ActiveX Control by any of the following names: OLE Control,
OCX Control, Custom Control, or ActiveX Control. As long as the term used refers to a control with an .OCX
filename extension, it is synonymous with the term ActiveX Control used here.
NOTE: Seagate Crystal Reports also includes a Visual Basic Custom Control (CRYSTAL.VBX). However, the
ActiveX Control is based on more advanced technology and provides more features. You should use the
ActiveX Control for development of any new Visual Basic projects. To upgrade an existing project to use the
ActiveX Control, see Upgrading from the Crystal Custom Control, Page 110. If, for some reason, you choose to
use the VBX in your project rather than the ActiveX Control, the VBX has been fully documented in
Developers online Help.
This section demonstrates how to add the Crystal ActiveX Control to an application project being designed in
Visual Basic versions 5.0 and 6.0. If you wish to use the ActiveX Control in a different development
environment or a different version of Visual Basic, please refer to the documentation that came with your
development tools for information on adding an ActiveX or OLE Control (OCX) to your project.
The Crystal ActiveX Control was installed in the \WINDOWS\SYSTEM directory when you installed Seagate
Crystal Reports. You add the ActiveX Control to your Visual Basic project using the C OMPONENTS command
on the Visual Basic Project menu.
1 Open Visual Basic.
2 Open the project to which you want to add the ActiveX Control.
6 To add the ActiveX Control to a form, double-click the tool in the toolbox and Visual Basic installs it on
the active form.
NOTE: For instructions on how to add an ActiveX Control or OLE control to development applications other
than Visual Basic, refer to the documentation that came with the development application you are using.
Once you have the ActiveX Control object on your form, you build the connection between your application
and Seagate Crystal Reports by setting the object's properties at design time or changing properties at runtime.
The ActiveX properties let you specify:
● the name of the report you want to print in response to an application event,
● the destination for that report (window, file, or printer),
● the number of copies you want to print (if your report is going to the printer),
● print file information (if your report is going to a file),
● preview window sizing and positioning information (if your report is going to a window),
● selection formula information (if you want to limit the records in your report),
● sorting information, and
● other related properties.
Crystal ActiveX Control properties can be changed either at design time or at runtime. Note, however, some
properties are available only at runtime. These properties do not appear in the Properties list at design time.
NOTE: For a complete description of each property in the Crystal ActiveX Control, refer to the Crystal ActiveX
Control Reference, Volume 3, Chapter 5.
NOTE: ActiveX Control properties also appear in the Visual Basic Properties list box. For instructions on using
the Properties list box, refer to your Visual Basic documentation.
If you are using the Crystal Custom Control (CRYSTAL.VBX) in a Visual Basic project, you can upgrade your
project to use the more powerful Crystal ActiveX control. All previous code and settings will be retained when
you upgrade your project.
Normally, Visual Basic versions 4.0 and 5.0 automatically upgrade the control used in your project when you
simply open the project in the Visual Basic environment. If Visual Basic does not upgrade your Crystal Custom
Control correctly, open the VB.INI file in a text editor, such as Notepad, and verify the following settings exist
in the appropriate sections.
For 16-bit environments:
[VBX Conversions16]
crystal.vbx={00025600-0000-0000-C000-000000000046}
#5.0#0;c:\windows\system\crystl16.ocx
[VBX Conversions32]
crystal.vbx={00025600-0000-0000-C000-000000000046}
#5.0#0;c:\windows\system\crystl32.ocx
NOTE: The actual path indicated should correspond to the location of the Crystal ActiveX Control. The path
on your system may or may not be the same as the path shown here. In addition, each entry should appear on
a single line in your VB.INI file.
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.
NOTE: For complete information on adding ActiveX components to a project, refer to your Visual Basic
documentation.
2 The 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.
3 Toggle 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.
4 Click OK in the References dialog box.
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
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.
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.
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.
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.
NOTE: While viewing the Crystal Report Engine Object Library in the Visual Basic Object Browser, you may
notice several classes, methods, and properties that are not documented in the Seagate Crystal Reports
Technical Reference. There are several features in the Crystal Report Engine Automation Server that are not
available with Seagate Crystal Reports, and are protected by a security feature built into the Object Library.
These features will become available in future Seagate Software products. Contact Seagate Softwares Sales
department for further information.
Seagate Crystal Reports also provides the Crystal Report Engine Object Library Browser Application as a
convenient utility for accessing online information about the Crystal Report Engine Object Library. Simply
choose the Xtreme Mountain Bike option in the Sample Files when installing, or choose an automatic
installation (the files will be installed by default) to install the utility, then browse through the Object Library
using the tree control. Select a class, method, or property for more information on how to use it.
The Report and Window objects in the Crystal Report Engine Object Library include several Events. By
handling these events in your Visual Basic project, you can customize how your application responds to user
actions. For instance, if a user clicks on a button in the toolbar of the preview window, such as the Zoom button
or the Next Page button, your application can respond to that event.
NOTE: Events are only available in Visual Basic 5.0 and later. If you are using a version of Visual Basic earlier
than 5.0, you will not be able to make use of the Events exposed by the Report or Window object.
To handle Events for the Report or Window object, you must declare the instance of the object as Public and
WithEvents. For example:
Once declared, the objects will appear in the Visual Basic Object window. If you select the object, its Events
will be displayed, just as if you were working with any other Visual Basic object.
End Sub
End Sub
For complete descriptions of all available Crystal Report Engine Object Library Events, refer to the Report
Object, Volume 3, Chapter 2, and the Window Object, Volume 3, Chapter 6.
NOTE: In the previous version of Seagate Crystal Reports a report or window object variable declared
WithEvents could only be Set once. A VB error occurred if you tried to Set the variable to a different value(i.e.
access a new report or display a new Preview window). This problem no longer exists. You can now reset the
values of WithEvent object variables.
When you finish designing your application and decide to distribute it to your users, you must make sure that
the Crystal Report Engine Automation Server is distributed with it. In addition, you must make sure the
automation server gets registered on your users’ systems. The easiest way to do this is to use the Application
Setup Wizard installed with Visual Basic.
This Wizard leads you through the process of designing a setup application for your project. In addition, the Setup
Wizard detects any ActiveX components included in your project and leads you through the process of adding
code to the setup application to include the required files and register the components on a user’s machine.
For more information about files that need to be distributed with Crystal Report Engine applications, refer to
Runtime File Requirements online Help.
Sample Applications
Seagate Crystal Reports includes a complete sample application written in Visual Basic 5.0 using the Crystal
Report Engine Automation Server. The Xtreme Mountain Bike Inventory Application is a complete real-world
application that provides various reports to employees at a fictitious company. Report access is restricted
based on user logon information. The application is located in \Program Files\Seagate Software\Crystal
Reports\sample\Xtreme\Inventory and provides the option of viewing the source code for any Visual Basic
form displayed.
NOTE: You can add sample data to the data definition file so that values will appear for each field in the
Preview Tab at design time, but the values will be identical for all records, and grouping will not be available.
At runtime, your application opens the report file, just as it would any other report file. Instead of simply
formatting and printing the file at runtime, though, you change the data source pointed at by the Crystal
Active Data Driver, which is the data definition file, to a Recordset or Rowset object for an ActiveX data source
such as ADO, RDO, DAO, or the Crystal Data Sources (see Crystal Data Object, Page 128), and the Crystal Data
Source Type Library (see Crystal Data Source Type Library, Page 131).
Once the Crystal Active Data Driver obtains the Recordset from the runtime data source, the Crystal Report
Engine can generate the actual report using existing data. The entire process saves you time designing reports
and produces reports that are much more flexible and portable at runtime. For more information on data
definition files, see Creating Data Definition Files, Page 123.
Designing and generating reports using the Crystal Active Data Driver is a straightforward process, but
requires several specific steps:
1. Select the design time data source, Page 120
2. Design the Report, Page 120
3. Obtain a Recordset from the Runtime Data Source, Page 121
4. Open the Report, Page 122
5. Pass the Recordset to the Active Data Driver, Page 122
6. Print the Report, Page 123
NOTE: For information on specifying an OLE DB provider or other ActiveX data source at design time instead
of a data definition file, see Using ActiveX Data Sources at Design Time, Page 126.
NOTE: Before saving your report, be sure to turn off the Save Data with Report option under the File menu.
The sample data stored with the data definition file is unnecessary at runtime, and will only increase the size of
your report file.
NOTE: You must add the Data Access Objects component to your Visual Basic project before performing the
following steps. For instructions on using DAO with Visual Basic, refer to your Visual Basic documentation.
1. Declare variables for the Database and Recordset objects in your Visual Basic application. This can be
handled in the declarations section of a form or module. Use code similar to this:
Set db = DBEngine.Workspaces(0).OpenDatabase( _
“c:\Program Files\Seagate Software\Crystal Reports\xtreme.mdb”)
3. Obtain a Recordset object from the Orders table of the Xtreme database.
NOTE: You must add the Crystal Report Engine Automation Server component to your Visual Basic project
before performing the following steps. For complete information on using the Automation Server, see Crystal
Report Engine Automation Server, Page 111.
1. Declare variables for the Application and Report objects that you will obtain from the Crystal Report
Engine Object Library in the automation server. This can be handled in the declarations section of a form
or module.
Dim app As CRPEAuto.Application
Dim report As CRPEAuto.Report
2. Create an Application object with the Crystal Report Engine Automation Server.
Set app = CreateObject(“Crystal.CRPE.Application”)
3. Obtain a Report object by opening the report file you created earlier. This example uses the file
ORDERS.RPT.
The Item property in the DatabaseTables collection lets you specify which table in the database you are replacing.
Since the data definition file acts as a database with a single table, you should pass 1 to the Item property.
Once you have a DatabaseTable object for the Report object, you can pass the Active data source to the Report
object using the SetPrivateData method. This method requires two parameters. The first is a value indicating
that the data source you are passing to the report is an ActiveX data source. This value must be 3. The second
parameter is the data source itself. For example:
reportTable.SetPrivateData(3, rs)
report.PrintOut
Once the data source has been set in the report object, runtime reporting can proceed normally. All features of
the Crystal Report Engine are available to you. For more information, refer to the sections of this manual
appropriate to the Report Engine development tool you are using.
A data definition file is a tab-separated text file that contains information about field names, field types, and
sample field data. Field names used in the data definition file must match the field names that will appear in
the ActiveX data source that is specified at runtime. Field type information indicates the type of data in each
field (string, numeric, date, etc.) and, if it is a string field, the maximum length of the string. Finally, sample
field data is simply sample data that Seagate Crystal Reports can display in the preview window while you
design the report.
For complete information on creating data definition files, see Creating Data Definition Files, Page 123. Seagate
Crystal Reports installs a sample data definition file in the \Program Files\Seagate Software\Crystal Reports
directory on your system. This file is named ORDERS.TTX and can be used with the Orders table in the
XTREME.MDB sample database or the Xtreme sample data ODBC data source that was created when you
installed Seagate Crystal Reports.
The following is an example of how fields are defined in a data definition file:
Order ID Long 1
Customer Name String 50 Sample string value
Order Date Date Jan 5, 2000
Order Amount Currency $1.00
The Active Data Driver supports the following data types in a data definition file:
● 07/11/97 5:06:07
● 07/11/97
● 23:30:01
NOTE: To use the functions in the Active Data Driver DLL, you must declare the functions first. Refer to your
Visual Basic documentation for information on declaring DLL functions. Search for Crystal Active Data Driver
Reference in Developers online Help for information about declaring the Active Data Driver functions.
CreateReportOnRuntimeDS(daoRs, “c:\reports\orders.rpt”,
“c:\reports\orders.ttx”, True, False)
This example creates a data definition file named ORDERS.TTX, then creates a simple report file based on this
data definition file and names it ORDERS.RPT. If the last argument is set to True, Seagate Crystal Reports, if
installed on the system, will open automatically on the user’s machine, allowing them to make changes to the
report file.
Notice that the first argument is a DAO Recordset object. If you are using this function in a language such as
C or C++, you would pass a pointer to an IUnknown derived interface to the Recordset.
NOTE: For complete information on the functions provided by the Active Data Driver, search for Crystal
Active Data Driver Reference in Developers online Help.
The Active Data Driver is intended to allow reports to be based on ActiveX data sources such as ADO and
DAO. Data definition files allow you to avoid specifying an actual data source until runtime. However, you
may often need to simply specify an ADO data source at design time for the report.
The Select Data Source dialog opens when you click the Active Data button on the Data Tab of the Report
Expert. This dialog box provides four options for selecting a data source to use in your report: specify an
ODBC data source for ADO or RDO, specify an ADO connection string for OLE DB, specify a DAO recordset,
or specify a data definition file. The Data Definition option has been thoroughly discussed earlier in this
section. The remainder of this section will discuss selecting an ADO, RDO, or DAO data source.
NOTE: For simplicity, RDO Resultsets are also referred to as Recordsets in this dialog box.
5 If you want to connect to a database object, use the Object Type drop-down list box to select the type of
database object, such as a Table, then select the object itself from the Object drop-down list box.
6 If you want to obtain a Recordset using a SQL statement, write the SQL statement in the text box
provided, or click Build to use the Microsoft Query application and Query Wizard to visually design your
SQL statement.
DAO
1 Click the DAO option in the Select Data Source dialog box. This option allows you to connect to a
database file through Data Access Objects (DAO).
2 Select a database type from the Database drop-down list box. This list displays all DAO compatible
database drivers installed on your system. Seagate Crystal Reports installs many DAO drivers for you.
For this example, you can select Access as the database type.
3 Use the Browse button to open the Select Database File dialog box. Use this dialog box to locate and select
a database file. Seagate Crystal Reports includes several sample databases in the \Program Files\Seagate
Software\Crystal Reports directory by default. You can select the XTREME.MDB Access file from this
directory for this example.
This code adds four fields to the Rowset with the specified field names, and field types. The field types are
based on constant values for the Variant data type. The constant names used here are from Visual Basic. For
information on valid constant values, see the AddField method in the Crystal Data Object Reference in
Developer’s online Help.
This specifies an array named Rows that contains 12 rows (0 to 11) and 4 columns (0 to 3). Notice that the four
fields are defined with the AddField method, so the 4 columns in the Rows array are also defined. In addition,
room has been made for 12 rows or records. Finally, since each field holds a different type of data, the array is
defined as a Variant type.
NOTE: If your Rowset contains only a single field, you can use a one dimensional array instead of two
dimensional. The single dimension indicates the number of rows or records in your Rowset.
Now that you have defined an array to hold data, you can begin adding values to the array. These array values
will become the actual field values for the virtual database. Most likely, you will want to design a routine in
your application that adds runtime data generated by your application into each cell of the array. The
following code, however, demonstrates how you can explicitly add values to the array:
From here, you could continue by adding a value to the first field of the second record, Rows (1, 0). You
continue filling in data record by record and field by field. This technique, of course, requires a lot of code and
is not very practical. Most real applications would contain a looping procedure that progressively filled in
values for the array.
CDOSet.AddRows Rows
The AddRows method accepts a two-dimensional array containing the values you want added to the Rowset
and, ultimately, added to a report file that is printed or exported. A one-dimensional array is used to add a
single row with multiple fields.
Rows can be added to a CDO Rowset with multiple calls to the AddRows method. However, once you begin
adding rows of data to a Rowset, you can not add any new fields to the Rowset. Any call to AddFields after a
successful call to AddRows will fail.
Once you finish populating your virtual database in the CDO Rowset object, you can pass this object as an active
data source to the Active Data Driver using the SetPrivateData method in the Crystal Report Engine Automation
Server. For complete instructions on doing this, see Pass the Recordset to the Active Data Driver, Page 122.
Crystal Data Objects support several methods and properties that can be used to work with the Rowset object.
The object model for CDO is completely defined and described in the section Crystal Data Objects, Volume 3,
Chapter 3.
NOTE: The Crystal Data Source type library is designed for Visual Basic 5.0 or later.
If you simply need a quick means for packaging some data in a form that can easily be reported off of, you
should consider using Crystal Data Objects. Crystal Data Source, on the other hand, is designed for developers
who need more flexibility when working with custom data sources. Keep in mind, though, once you add the
Crystal Data Source interface to your class, you must implement all methods and properties exposed by the
interface.
The Crystal Data Source interface can be implemented inside almost any type of application. You might want
to create and internal data source, for instance, inside the same standard executable application that you are
implementing the Crystal Designer Component or the Automation Server. On the other hand, you could
create an ActiveX DLL that did nothing except implement Crystal Data Source. Your ActiveX DLL then could
work as a separate data source to be accessed from other applications, much like ADO, RDO, and DAO are
used.
NOTE: If you are not creating an ActiveX DLL, you may not have a class module in your project. See the next
section, Adding a class module to a project.
4 Change the value of the (Name) property for Class1 to MyDataSource.
5 Select Project1 in the Project window, and change the value of the (Name) property for Project1 to
MyDataSourcePrj.
6 Save the project. Use MyDataSource as the name of the class file and the project file.
Sub Main()
End Sub
Implements CRDataSourceLib.CRDataSource
2 Open the drop-down list of objects in the upper left of the code window. You will see a new object has
been added to the list: CRDataSource.
3 Select CRDataSource from the list of objects. A new Property Get procedure is added to the class module
for the FieldCount property of the CRDataSource object. Remember that in COM interfaces, properties
are actually implemented as Get and Let procedures. For more information, refer to your Visual Basic
documentation.
4 Open the drop-down list in the upper right of the class module code window. Notice that several
procedures appear corresponding to the properties and methods of the Crystal Data Source interface. In
fact, the properties and methods you saw in the Object Browser are the same properties and methods
listed here in the code window.
Once you have added the Crystal Data Source interface to your class module, you must implement all of the
properties and methods in the interface to successfully produce a data source that can be compiled into an
ActiveX DLL and used with the Active Data Driver. The first step to implementing all of the properties and
methods is to add procedures to your class for each of the Crystal Data Source procedures.
Adding procedures
When you selected the CRDataSource object in the object list in the previous section, you automatically added
a procedure to the class for the FieldCount property. This property procedure appears in bold in the list of
CRDataSource methods and properties to indicate that it has already been added.
1 With the CRDataSource object selected in the code window, select Bookmark [Property Get] from the drop-
down list in the upper right corner of the code window. A Property Get procedure appears in the class for
the Bookmark property of CRDataSource.
2 Repeat the process for the Property Let procedure of the Bookmark property. Keep in mind that Property
Get procedures allow values to be retrieved from properties while Property Let procedures allow values
to be assigned to properties.
Implementing procedures
Exactly how you implement each of the properties and methods in the CRDDataSource interface depends
upon the purpose and design of your application or component. To give you an idea of how to implement the
procedures, though, the following code sample simply uses an ADO Recordset object connected to the Xtreme
sample data DataSource. Obviously, this example has little value in a real application; an ADO Recordset can
itself be reported on through the Active Data Driver. However, the example does illustrate how the properties
and methods in the Crystal Data Source interface work.
Implements CRDataSourceLib.CRDataSource
Dim adoRs As ADOR.Recordset
Private Sub Class_Initialize()
Set adoRs = New ADOR.Recordset
adoRs.Open "Customer", "Xtreme sample data", _
adOpenKeyset, adLockOptimistic, adCmdTable
End Sub
Private Sub Class_Terminate()
adoRs.Close
Set adoRs = Nothing
End Sub
Public Property Let CRDataSource_Bookmark(ByVal RHS As Variant)
adoRs.Bookmark = RHS
End Property
Public Property Get CRDataSource_Bookmark() As Variant
CRDataSource_Bookmark = adoRs.Bookmark
End Property
Public Property Get CRDataSource_EOF() As Boolean
CRDataSource_EOF = adoRs.EOF
End Property
Public Property Get CRDataSource_FieldCount() As Integer
CRDataSource_FieldCount = adoRs.Fields.Count
End Property
Public Property Get CRDataSource_FieldName _
(ByVal FieldIndex As Integer) As String
CRDataSource_FieldName = adoRs.Fields(FieldIndex).Name
End Property
Report.Database.SetDataSource myDs
NOTE: This example is based on a Visual Basic application created using the Crystal Designer Component, not
the Crystal Report Engine Automation Server, Page 111. If you are using the Report Engine Automation Server to
assign the new data source to the Active Data Driver, refer to the instructions under Pass the Recordset to the
Active Data Driver, Page 122 in the section on the Active Data Driver, Page 118.
Now that you have seen the extensive power of the Crystal Data Source interface implemented inside a Visual
Basic class, you can begin to consider the extensive possibilities for its use. Many computer based operations
produce continuous streams of data in real-time. In your own work, you may encounter needs for gathering
data from process control systems, data acquisition applications, or computer-based instrumentation.
In these kinds of applications, data is usually gathered and stored for later analysis. Systems running in real-
time, however, may need real-time monitoring and reporting. With objects that implement the Crystal Data
Source interface, you can gather and move through data as it is generated, then produce up to the instant
analysis through reports.
Programmer’s building n-tier applications that operate across a network may often find themselves designing
business objects and other business rules components. By implementing the Crystal Data Source interface in
business object components, you can design reports that produce real-time information about data traveling
across the network. Even Microsoft Transaction Server components can implement a fully functional ActiveX
data source for reporting. Crystal Data Source takes your applications from runtime to real time.
This topic is only supported by the Professional Edition of Seagate Crystal Reports.
In Seagate Crystal Reports, a Crystal ActiveX Control can be bound directly to a Visual Basic Data Control.
Using the Visual Basic Data Control with the Crystal ActiveX Control offers the following benefits:
● Generating reports in Visual Basic programs is made even easier and does not require an existing .RPT
file.
●A powerful feature of Visual Basic is ad-hoc queries that are run by executing SQL statements in the
RecordSource property of the Data Control. By directly binding a Crystal Custom Control to a Data
Control, users can now create reports of dynaset data which are the results of such ad-hoc queries.
When using Seagate Crystal Reports to generate reports from database files of a particular file format (for
example, Paradox file format), you need to have the appropriate report driver (i.e., PDBPDX.DLL) to retrieve
data from the databases. Similarly, when you generate reports by binding to a Visual Basic Data Control, a
Bound Report Driver (PDBBND.DLL) is used to retrieve data from the Data Control. Make sure PDBBND.DLL
is in your \WINDOWS\SYSTEM directory or search paths, along with other database drivers.
Several properties are added to the Crystal Custom Control in order to support bound reports. These new
properties are described below.
Custom
This property allows you to create bound .RPT files at Visual Basic design time and is not available at runtime.
After a bound .RPT file is created, programmers can then use Seagate Crystal Reports to customize the report
layout or even link the bound data to other database tables.
BoundReportFooter (Boolean)
This property can be read/write both at design-time and runtime. This property is ignored if the ReportSource
property is 0 (Report files). Default is False and the bound reports generated will not have page numbers
printed. If set to True, page numbers will be printed at the bottom of a page.
Run the application, click the command button, and the Crystal ActiveX Control will retrieve data from the
Data Control and create the report. The report will appear as a simple columnar report. There are no runtime
properties to control any report formatting. However, this can be accomplished at design-time by editing the
report designed by the ActiveX control (a report template) in Seagate Crystal Reports.
The following steps describe an alternative method of creating formatted bound reports:
1 Create your Visual Basic application as in the first example above.
2 Set the ActiveX Control to print to a preview window, and run the application.
3 Click the Export button in the preview window, and export the report to a disk file in .RPT format.
4 Once the report has been exported, you can open it up in Seagate Crystal Reports.
5 Perform all formatting changes that you want and save the report.
6 Return to the Visual Basic application and stop it if it is still running.
7 On the ActiveX Control:
8 Set the ReportSource to 0 - Report File.
9 Set the ReportFileName to the .RPT file that you created.
10 Run the Visual Basic application and you will be able to see your bound report with the formatting
changes you've made.
CrystalReport1.SortFields(0) = “+{TableName.FIELDNAME}”
Sample Application
Seagate Crystal Reports includes a complete sample application written in Visual Basic 5.0 using the Crystal
Report Engine Automation Server and the Microsoft Data Bound Grid control. The Xtreme Mountain Bike
Inventory Application is a complete real-world application that provides various reports to employees at a
fictitious company. The Microsoft Data Bound Grid control is used for an order-entry page that dynamic
reports are produced from. The application is installed, by default, in the \Program Files\Seagate Software
\Crystal Reports\sample\Xtreme\Invntory directory.
ActiveX designers
ActiveX designers provide a design environment inside of the Visual Basic Integrated Development
Environment (IDE) for visual development of an application feature. An example is the Microsoft
UserConnection designer that comes with Visual Basic. The UserConnection designer allows you to visually
design ODBC database connections accessible from within your Visual Basic application. For more
information on the UserConnection designer, refer to your Visual Basic documentation.
The Seagate Crystal Report Designer Component lets you visually add reporting functionality to your
applications. The Report Designer window and the Create Report Expert provide the tools to visually design
a report and implement it within your project at design time. The Report Designer object model provides a
complete set of objects, properties, and methods to write code that manipulates your report and its data at
runtime.
The Report Designer Component supports data access through Data Access Objects (DAO), Remote Data
Objects (RDO), and ActiveX Data Objects (ADO). Through these three access methods, you can connect to
most ISAM, ODBC, and SQL data sources available to Windows applications. In addition, you can create DAO
Recordsets, RDO Resultsets, or ADO Recordsets in Visual Basic, then replace the data source used by a report
at runtime by calling the SetDataSource method of the report Designer object model’s Report object.
The Report Designer Component also provides the ability to design reports based on Data Definition files, text
files that define the fields and field types of a database without actually serving as a source of data. Using Data
Definition files, you can design a report without depending on the existence of a database at design time, then
dynamically create the data at runtime and assign it to the Report object of the Report Designer Component.
If you have installed the full Seagate Crystal Reports product, you also have the ability to use the Report
Designer Component to connect to any data source that Seagate Crystal Reports can connect to. In such a case,
the Report Designer Component implements the Seagate Crystal Reports user interface that you are already
familiar with, so you can quickly connect to any existing data.
Finally, the Report Designer Component also supports Data Environments in Visual Studio 6.0. If your project
includes a data environment, the Report Designer Component will allow you to select the data environment
as a data source at design time. Runtime reports make full use of the data exposed by a data environment by
working with the standard connection, command, or recordset objects provided, much like working directly
with an ADO object.
For complete information on data access, refer to Working with data, Page 158.
When you have multiple Report Designer Components open within the Visual Basic IDE, you cannot drag and
drop objects, such as fields, text objects, subreports, lines and boxes, and formulas between reports. To move
or copy objects between reports, use the standard Windows Cut, Copy, and Paste commands.
Conditional Formatting
Conditional formatting is created using formulas. With the Report Designer Component, you can produce
conditional formatting results using all of the power of the Visual Basic language. If you have used Seagate
Crystal Reports before, you may already be familiar with conditional formatting and the Seagate Crystal
Reports formula language. The formula language is still available within the Report Designer Component, but
you also have the option of making full use of the entire Visual Basic programming language. For more
information on using Visual Basic to produce conditional formatting, refer to Designing Reports in the Visual
Basic Integrated Development Environment.
Pictures
Images can now be dynamically displayed in a report at runtime using OLE objects. You may need to display
images of products, corporate logos, employee pictures, or any other type of image in your report, but you
may want to control which images are displayed based on variables that exist in your application only at
runtime.
By adding OLE objects to your report, then changing the image at runtime using the FormattedImage property
of the OLE object in the Report Designer object model, you can produce exciting, visually attractive reports for
your users. For complete information working with OLE images, see Changing OLE object images.
Guidelines
Guidelines are not implemented in the Report Designer Component’s design window as they are in the
Seagate Crystal Reports Design Tab. However, new alignment and sizing options have been added to
eliminate much of the need for guidelines.
Subreports
Subreports are supported by the Report Designer Component, but they must be designed from within the
main report. In Seagate Crystal Reports, you are able to create subreports from within the main report. You
are also able to import existing report files as subreports. With the Report Designer Component, however, you
are better off to create your subreports within the main report if you include Visual Basic code in your
subreport.
● Ifyou create a report in the Report Designer Component and use Visual Basic code in the report, any
report calculations or formatting that you performed using that code are dependent on that code being
in place. If you save such a report to a Crystal Report file (.rpt), you will lose all the embedded Visual
The Report Designer Component supports all of the same formula design capabilities that exist in Seagate
Crystal Reports, including the complete Seagate Crystal Reports formula language. However, the Seagate
Crystal Report Designer Component, as an ActiveX designer for use inside Visual Basic, also supports the
Visual Basic language. By exposing much of its functionality through the Report Designer object model, the
Report Designer Component allows you to create powerful functions and procedures that control not only the
look of a report, but also the results displayed in a report. With this capability, you are able to leverage your
experience with Visual Basic to do more sophisticated reporting. You’ll have:
● access to the robust functionality of Visual Basic,
●a familiar programming environment, and
● no need to learn an additional scripting language.
While you will still be able to use the Seagate Crystal Reports formula language, you won’t need to use it for
your calculations and conversions.
On a high level, the way you create calculated fields in the Report Designer using Visual Basic is to:
● create a text object,
● enter the text object where you want the calculated value to appear,
● create a variable to capture the result of the Visual Basic calculation, and
● code the calculation.
Finally, you have the text object display the value in the variable via the SetText method.
You can also use Visual Basic code when implementing the Format event procedure of a section in the report.
You can open a Format event procedure for a section by double-clicking the section in the Report Designer
window or selecting the section and clicking the View Code button in the Visual Basic Project window.
System Requirements
The Seagate Crystal Report Designer Component has the following system requirements:
Microsoft Windows 95, Windows 98, or Windows NT 4 (Server or Workstation)
Visual Basic versions 5.0 and 6.0 (Professional or Enterprise Edition)
Netscape Navigator or Microsoft Internet Explorer (Version 3.0 or higher)
x86 processor or higher
32 MB RAM (minimum)
22 MB hard drive space (minimum for a full installation)
CD-ROM drive
Installation
NOTE: The Seagate Crystal Report Designer Component is available with Microsoft Visual Basic 6.0 or as a
download from the Seagate Software web site (www.seagatesoftware.com).
Part One
Adding the Report Designer Component to a Project, Page 152
Selecting Data, Page 153
The Report Expert, Page 154
Adding the Smart Viewer, Page 155
Running the Application, Page 155
Part Two
CrystalReport1 - The Report Designer Component, Page 156
CRViewer1 - The Smart Viewer Control, Page 156
The Code, Page 157
Report Packages, Page 158
NOTE: In Visual Basic 6.0, the command Add Crystal Reports 7.0 will appear directly on the Project menu.
The first step to creating any report is selecting the source of the data that will be displayed. The Report
Designer Component supports data sources exposed through Data Access Objects (DAO), Remote Data
Objects (RDO), ActiveX Data Objects (ADO), Crystal Data Objects (CDO) through a Data Definition File, and
Visual Basic Data Environments. If you have installed the full Seagate Crystal Reports product, you can also
access any source of data supported by Seagate Crystal Reports, including SQL servers and ODBC data
sources. In the following steps, you will connect to a data source using ADO.
1 In the Report Gallery, click the Standard button to design a standard report using the Report Designer
Component. The Create Report Expert appears with the Data Tab active.
NOTE: If you close the Report Gallery dialog box without selecting a report type, the Report Designer
Component will assume that you wish to use an Empty Report. You will be prompted to add the Smart Viewer
control to your project.
2 In the Data Source section of the Data Tab, click the Project button to select a data source for your Visual Basic
project. The Select Data Source dialog box appears.
NOTE: The VB Data Environment button on the Data Tab allows you to connect to an existing Visual Basic
Data Environment. The Custom button allows you to connect to a data source other than RDO, ADO, DAO, or
a Data Definition File. This option is only available if you have performed a complete install of Seagate Crystal
Reports. For more information, refer to Working with data, Page 158.
3 Verify that the first option in the dialog box, ODBC, is selected. This option allows you to connect to an
ODBC data source through ADO or RDO.
4 In the drop-down list below the ODBC option, select Xtreme sample data. This is a sample database and
ODBC data source created when you installed Seagate Crystal Reports.
5 Click the Advanced button. The Advanced Options dialog box appears.
6 Make sure the ADO option is selected in the Advanced Options dialog box. You will connect to the Xtreme
sample data data source through ActiveX Data Objects.
7 Click OK in the Advanced Options dialog box, and notice that ADO appears in parentheses next to the
ODBC option.
8 Click Next in the Select Data Source dialog box. The Select Recordset dialog box appears. Now that you have
specified a data source and a connection type (ADO), you must specify the data within the data source that
will be used for the report.
9 From the Object drop-down list, select Customer. This is the Customer table in the Xtreme database. Note
that if you are familiar with the SQL query language, you could also use the SQL option and write a SELECT
statement. The Build button next to the SQL option opens Microsoft Query so that you can visually build a
SQL statement.
10 Click Finish to return to the Create Report Expert. Notice that ado now appears in the Tables list of the Data
Tab, indicating that you have selected an ActiveX Data Objects data source. You are now ready to design
your report.
Once you’ve selected a data source, you can continue designing your report through the Report Expert. The
Report Expert in the Report Designer Component works exactly like the Report Expert in the Report Designer
for Seagate Crystal Reports.
1 Select the Fields Tab in the Create Report Expert. The Database Fields list box lists the ADO connection
that you made, and all available fields from the table you selected.
2 Select Customer Name in the Database Fields list box, drag and drop the field into the Report Fields list box.
ado.Customer Name will appear in the list box. You have just specified that data from the Customer Name
field appear in your report.
3 Continue using the drag and drop procedure, or use the Add button on the Fields Tab, to add the Last Year’s
Sales, City, and Region fields to your report.
4 Click the Sort Tab to sort the data in your report.
5 Once again, use either the drag and drop method or the Add button to select the ado.Region field, then the
ado.City field and add them to the list of Sort Fields. The records in the report will be sorted first by Region,
then by City within each Region.
6 Select each field in the Sort Fields list box, in turn, and verify that in ascending order is specified in the Order
drop-down list.
7 Select the Total Tab in the Create Report Expert. For each Region, your report will specify a subtotal of the
Last Year’s Sales values.
8 If ado.Last Year’s Sales does not appear in the Total Fields list box, select the field from the Report Fields list
box and add it now.
9 With ado.Last Year’s Sales selected in the Total Fields list box, verify that sum is selected in the drop-down list
below.
10 Click the TopN Tab to obtain the Top N regions. Top N of Sum of ado.Last Year’s Sales should already be
selected in the tab.
11 Change the 5 in the where N is text box to 10. Your report will display the top 10 regions.
12 Click the Graph Tab to create a graph for the report. The Graph Expert appears inside the Graph Tab.
13 Click the Pie button on the Type Tab, then proceed to the Data Tab.
14 Review the settings on the Data Tab. A single graph will appear in your report that contains a separate pie
slice for each grouping of the Region field. The sizes of the pie slices will be determined by the subtotal
obtained by adding together the values in the Last Year’s Sales field.
15 Click the Style Tab of the Create Report Expert. The Expert can automatically generate an overall style or look
for your report.
16 Select Executive, Leading Break, and notice the image next to the list. This is the look that your report will have.
17 You have finished designing your first report in the Seagate Crystal Report Designer Component. Click
Finish.
After you have finished designing your report in the Create Report Expert, you have the option of
automatically adding the Smart Viewer Component to your Visual Basic project. The Smart Viewer displays
your report at runtime and allows a user to navigate through the report. When you add the Smart Viewer, a
new Form is added to your project, and the Smart Viewer is added to the form as an object.
When you click Finish in the Create Report Expert, the Crystal Report Expert dialog box appears.
1 The first option is whether or not you want a form containing the Crystal Reports Smart Viewer added to
your project. The Smart Viewer is an ActiveX control that allows you to display reports directly in a form
inside your application. Click Yes, if this option is not already selected.
2 The second option is whether or not the form containing the Smart Viewer should be the first form displayed
when your application runs, the startup form. Click Yes for this option as well.
You could design your application so that another form is displayed initially, and the Smart Viewer form
is displayed in response to some event. However, for the purposes of this demonstration, your application
will simply display the report immediately upon running.
3 Click OK in the Crystal Report Expert dialog box. If you look in the Project window for your Visual Basic
project, you will see that a new form and the Report Designer Component ActiveX designer have been
added. In addition, the Report Designer Component design window appears in the Visual Basic IDE.
4 Save your new project and the attached forms. For this tutorial, you can use the name CrystalReport1 for
your project.
Your Report Designer Component project is complete. Now, you can run the application within Visual Basic
to see the results.
1 Click the Start button on the Visual Basic toolbar, or select the Start command from the Run menu. The
Report Designer Component connects to your data source through ADO, and generates a report based on
the design you created. The report is displayed inside the Crystal Smart Viewer, which sits on a Visual
Basic form object.
2 Use the arrow buttons at the top of the Smart Viewer to page through the report.
3 If your system is connected to a printer, click the Print Report button to print a hard copy.
4 Click CA in the tree control at the left side of the Smart Viewer. The group containing California data appears
in the Smart Viewer.
5 Click the plus sign next to CA to expand the CA group in the tree control. Four cities are listed for California.
NOTE: If you are unsure of the name of a toolbar button, hold the mouse pointer over the button for a couple
of seconds, and a tool tip will appear that indicates the buttons name.
8 Click the Search Text button. Data for Vancouver is highlighted in the Smart Viewer.
9 When you are finished reviewing the report in the Smart Viewer window, close the window. Your
application stops running as well.
Part Two
NOTE: When you view the form containing the Smart Viewer control, the control may appear to completely
fill the form. However, the control is a separate object inside the form and can be resized within the form.
8 In the Properties window, select the CRViewer1 control from the list of objects. Properties appear that are
specific to the Smart Viewer control.
The Code
Now you have seen the two principal objects added to your project, the Report Designer Component and the
Smart Viewer control. The Report Designer Component provides an environment for designing powerful
reports. The Smart Viewer control allows these reports to be displayed at runtime. There is only one element
missing from the equation. You must have code that displays the Report Designer's report inside the Smart
Viewer.
1 With the form containing the Smart Viewer control active, select the Code command from the View
menu. A code page for the form appears. There are three sections to the code that appears in the form, a
General Declarations section, a Load event for the Form, and a Resize event for the Form.
2 Examine the code in the General Declarations section:
An instance of the CrystalReport1 object is declared. This object will be used in the Load event of the Form.
3 Now, examine the code for the Load event of the Form:
CRViewer1.ReportSource = Report
CRViewer1.ViewReport
The first line assigns the declared CrystalReport1 object to the ReportSource property of the Smart Viewer
control, CRViewer1. For the Smart Viewer to display a report, it must know where to find that report. In
this case, it gets the report from the Report Designer Component, CrystalReport1.
The second line of code simply tells the Smart Viewer to display the report. That is all of the code that is
required.
CRViewer1.Top = 0
CRViewer1.Left = 0
CRViewer1.Height = ScaleHeight
CRViewer1.Width = ScaleWidth
These four lines make sure that the Smart Viewer takes up the entire area of the Form, and that the Smart
Viewer is resized whenever the Form is resized, so it continues to fill the entire form. Note that this code
is optional, but such techniques are often good practice to provide a complete user interface.
Report Packages
A report package is a convenient way to group reports from different sources for viewing or printing. Relevant
information can be combined in one place, rather than having to output separate reports.
Report packages can be created at design-time in Visual Basic. The package can contain reports created by the
RDC, for example, CrystalReport1, and reports created outside the application using the designer in Seagate
Crystal Reports or Seagate Info with an .rpt extension. The latter method uses CRAXDRT: Crystal Reports
ActiveX Designer Run Time Library. The following code demonstrates how to create a report package at
design time in VB:
ActiveX Data Objects (ADO) and OLEDB are the new data connection technologies designed to provide a
common interface for working with relational databases, mail messaging, event logs, and most any form of
data storage. In addition, ADO provides a method of working with data that is easier and faster than previous
technologies such as DAO and RDO. For more information on ADO, refer to Microsoft documentation.
ADO can be used to connect to any ODBC or OLE DB compliant data source when you design your report in
the Report Designer Component. The resulting ADO Recordset is not directly available from the Report
Designer Component, but it can be replaced by alternative Recordset objects. For example, if your Visual Basic
application allows users to make choices that can affect the set of data displayed by a report, simply create a
new ADO Recordset at runtime, then pass it to the Report Designer Component using the SetDataSource
method. The only restriction is that the fields in the new Recordset match the fields originally used to design
the report. For more information on using the SetDataSource method, see Setting a new data source for the
report.
The Report Designer Component provides two options for connecting to a data source via ADO: specifying
an ODBC data source or specifying an ADO connection string.
RDO
Remote Data Objects (RDO) is designed specifically for working with remote data sources. This includes
ODBC and most common SQL database systems. In fact, RDO acts as an object-oriented wrapper around the
ODBC API. The flexibility of ODBC is available to Visual Basic programmers through the simplicity of a COM
based object model. Already a common choice for developers of client/server systems, RDO allows the
execution of stored procedures and the processing of asynchronous operations, meaning your users can
continue to work while your application processes a data query in the background.
The basic object used to manipulate data in RDO is a Resultset (specifically, the rdoResultset object). A new
Resultset can be defined in your Visual Basic application and passed to the Report Designer Component at
runtime using the SetDataSource method. The RDO data source used to initially create your report at design
time, however, is not available for direct manipulation. Instead, information about the connection to the data
source is stored inside the instance of the Report Designer Component that you add to your application. By
creating a new Resultset at runtime, though, and passing the Resultset to the Report Designer Component, you
can control the data in a report based on user requests and responses. For more information on using the
SetDataSource method, see Setting a new data source for the report, Page 176.
RDO provides a powerful connection to remote data sources through ODBC. If you are designing a client/
server application, or any application that needs to connect to a large database system such as Microsoft SQL
Server, Oracle, or Sybase Adaptive Server, RDO can provide a strong solution. However, RDO limits your
application to standard relational database systems. Other sources of data, such as e-mail and messaging
servers, system logs, and Internet/intranet server logs are unavailable to RDO. Developers designing web-
based applications using Visual InterDev would also be served better by ActiveX Data Objects (ADO).
Use the following steps as a guide for connecting to an ODBC data source through RDO:
1 On the Data Tab of the Create Report Expert, click Project. The Select Data Source dialog box appears.
2 Verify the ODBC option is selected, and click Advanced. The Advanced Options dialog box appears.
3 Select RDO as the technology to connect to your data source, and click OK.
4 Select an ODBC data source from the ODBC option drop-down list. For this example, select Xtreme sample
data.
5 Click Next in the Select Data Source dialog box. The Select Recordset dialog box appears.
6 If the data source requires logon information, enter a user name and password in the Logon section of the
dialog box.
7 In the Recordset section of the dialog box, select either Pick from a list of Database Objects or SQL.
● ThePick from a list option provides a list of object types and objects for each type. For this example,
verify that Pick from a list is selected.
● TheSQL option allows you to write a SQL query statement. The Build button next to the SQL option
opens the Microsoft Query Builder and allows you to visually design a SQL query.
8 Select Table from the Object Type drop-down list.
9 Select Customer from the Object drop-down list.
10 Click Finish in the Select Recordset dialog box. rdo appears in the list of Tables on the Data Tab of the Create
Report Expert.
DAO
Data Access Objects (DAO) is designed primarily for use with local and ISAM (Indexed Sequential Access
Method) data sources created through applications such as Microsoft Access, Microsoft FoxPro, and Borland
dBASE. Although DAO can be used to connect to ODBC data sources, RDO and ADO provide more powerful
options for such data. However, DAO is the oldest of the three technologies, giving it the advantage of being
familiar to many Visual Basic programmers. As a result, DAO is also frequently found in existing applications,
and applications created with older versions of Visual Basic.
If you are adding the Report Designer Component to a Visual Basic application that already uses DAO, or if
you are connecting to a local data source such as an Access or dBASE file, you should consider using DAO to
design your reports. Experienced Visual Basic programmers familiar with the DAO object model may also
want to stick with a known technology. However, if you are working with ODBC or other remote data sources,
RDO and ADO may be a better solution.
Once you design your report in the Report Designer Component, information about the connection to your
DAO data source is stored with the report, and can not be accessed directly. However, you can change the data
displayed by a report by changing the data source at runtime using the SetDataSource method. A DAO
Recordset object may be passed to the report through this method. Keep in mind, though, the Recordset must
have fields identical to those in the original data source used at design time.
For more information on using the SetDataSource method, see Setting a new data source for the report.
Data Environments
Data Environments (introduced with VB 6) allow for interactive creation of ADO Objects at design time, and
easy access to data at run time. Through the Data Environment Designer you create Data Environment objects
to connect with Data sources (Connection Objects), and access data from those sources (via Command Objects)
at design time and run time.
The following steps illustrate how to create and connect to Data Environment objects for Microsoft Access type
data sources (.mdb files). This algorithm can be used as a general guide for any data source for which an OLE
DB provider exists. Consult the Microsoft documentation for more detailed information on the Data
Environment Designer.
Add the Seagate Crystal Report Designer Component and the Data
Environment Designer to your project
1 Select Components from the project menu.
2 In the Components dialog box, click on the Designers tab.
3 Click on the Crystal Reports 7 checkbox and the Data Environment checkbox.
Order ID long 1
Customer ID long 1
Employee ID long 1
As you can see, the Data Definition File is a simple ASCII text file with fields listed on separate lines. Each field
in the text file represents a field that must exist in the true ADO, RDO, or DAO data source that replaces the
Data Definition file at runtime. At design time, you create your report based on the Data Definition file. The
three columns of the file provide the name of the fields, the data type for the fields, and a sample value. String
fields, as you can see, also require a value for the length of the string. The values in the sample value column
are optional and will only be used if you neglect to replace the Data Definition file with a true data source.
At runtime, you change the data source pointed at by the report using the SetDataSource method. The new
data source can be a Recordset or Resultset object produced using DAO, RDO, ADO, or through the Visual
Basic Data Control. Once the Report Designer Component obtains the Recordset or Resultset object from the
runtime data source, it can produce and display the final report using actual data. The process saves you the
time of creating a complete data source prior to designing the report and your application.
Report.Database.SetDataSource rs
For more complete information, see Setting a new data source for the report.
Report Templates
If a Crystal Report file already exists that closely resembles the report you want to create, and it connects to
the same or similar data and displays the data in a desirable fashion, you can use the existing report file as a
report template. When you select the existing report, a copy of the report is created and set up as the basis of
your new report in the Report Designer Component. The original report file is never changed.
To use a report template:
1 Begin by adding the Report Designer Component to your Visual Basic project (see Adding the Report
Designer Component to a Project).
2 When the Report Gallery appears, click Import Report. The Open dialog box appears.
3 Use the Open dialog box to locate and select an existing Crystal Report file. These files have .rpt extensions.
4 Click Open. The Crystal Report Expert dialog box appears.
5 Indicate whether or not you want a form containing the Crystal Smart Viewer added to your report, and, if
so, whether or not this form should be the start-up form for your application.
6 Click OK. An instance of the Report Designer Component appears in your project. The designer contains a
new report design based on the report file you selected.
The data source accessed by the new report is identical to the data source used by the original report file. The
following procedure describes how to change the location of the data source. Keep in mind, though, the
structure of the new data source must match the original data source. For instance, relational databases must
have identical tables and fields.
1 In the Field View of the Report Designer Component window, click the plus sign next to Database Fields.
A list of all data connections will appear. If the report connects directly to a database, you will see a list of
database tables. If the report uses a connection technology, such as ADO, you will see ado in the list.
2 Right-click one of the data connections in the list and select SET LOCATION from the shortcut menu. The Set
Location dialog box appears.
3 In the Databases list, select the database table or other data connection that you want to change the location
of, and click Set Location. A dialog box appropriate to the connection type appears. The remaining steps
assume the data connection is an ADO connection.
4 With the Choose SQL Table dialog box open (the dialog box that appears when setting the location of an
ADO data source), click Log On Server. The Log On Server dialog box appears.
Local and remote data sources not accessed through an object model (such as ADO or DAO) are available to
the Report Designer Component if you have installed the full Seagate Crystal Reports product. The Report
Designer Component can use the same database drivers that are available through Crystal Reports. This
includes ODBC data sources, SQL server database systems, NT event logs, and Web server logs for Microsoft
and Netscape web servers.
When connecting to an ODBC, SQL, or PC data source, the Report Designer Component provides an interface
much like the Seagate Crystal Reports interface. If you click the Custom button on the Data Tab of the Create
Report Expert, the Log On Server dialog box appears, providing access to ODBC data sources and SQL server
database systems. If you then click the Database File button, the Choose Database File dialog box appears. Use
this dialog to open xBase, Paradox, Btrieve, or Microsoft Access databases.
PC Databases
This tutorial demonstrates how to connect to a Btrieve, xBase, Paradox, or Access database. Assuming you
have clicked Custom on the Data Tab of the Create Report Expert:
1 From the Log On Server dialog box, click Database File. The Choose Database File dialog box appears.
2 Use the Choose Database File dialog box to locate and select the database file you want to use in your report,
then click Add.
3 Continue selecting database files and clicking Add for every database you wish to use in your report.
4 Click Done when finished selecting databases. You will return to the Create Report Expert, and the Linking
Tab will be activated.
5 Use the Linking Tab to specify links between database tables.
6 Continue designing your report.
The Seagate Crystal Report Designer Component includes several COM objects that work with the Visual
Basic design and runtime environments. The following sections describe this interaction. For complete
descriptions of all of the components in the Report Designer architecture, see Component Descriptions, Page 172.
Design Time
At design time, the Report Designer Component provides a user interface that closely integrates with the
Visual Basic IDE. Through the user interface, you design and manipulate reports and report data. This
interface includes events that can be directly programmed from within Visual Basic.
The Report Designer Component uses the Active Data Driver(see Active Data Driver, Page 118) for connecting
to ISAM, ODBC, and SQL databases through Data Access Objects (DAO), Remote Data Objects (RDO),
ActiveX Data Objects (ADO), and Data Environments (Visual Basic 6.0 only). You can design the data set from
within Visual Basic, then apply it to the report contained by the Report Designer Component.
When working in Visual Basic, you will often need to use the Seagate Crystal Report Smart Viewer for ActiveX
as a user interface to display reports. The Smart Viewer is an ActiveX control that you can drop right on to a
standard Visual Basic Form. The Smart Viewer is, ultimately, where your report is displayed at runtime.
Runtime
The user interface provided by the Report Designer Component at design time does not appear in your
application at runtime, or when it is compiled into an executable file. Instead, the Report Designer Component
is accessed directly by your Visual Basic code. The Report Designer object model provides a complete object
hierarchy for direct manipulation in Visual Basic.
The Active Data Driver is also available at runtime, through the Report object of the Report Designer
Component object model, and can be assigned a new set of data based on user interaction with your
application. You design a Recordset or Resultset object in Visual Basic using the DAO, RDO, or ADO object
model, and pass it to the report.
Finally, the Smart Viewer takes center stage at runtime, connecting to the Report Designer Component and
displaying the embedded report. With careful design and placement on the Form, the Smart Viewer appears
simply as a window inside your application.
Component Descriptions
Component Description
Crystal Report Designer This is a COM (Component Object Model) component that provides the
UI Component user interface at design time for the user to interact with and create or
modify the report.
Crystal Report Designer This is an underlying COM component that provides services for the user
Design Time Component interface component.
Crystal Report Designer This is the component that encapsulates all of the report objects and is
Run Time Component responsible for doing all of the data processing and report layout.
Active Data Driver This is a data access driver that provides access to various types of object
data sources including DAO, RDO, and ADO.
Crystal Reports Smart This component is an Active X control which can be drawn on a form and
Viewer for ActiveX manipulated at design time. It provides a rich object model which can be
used to modify user interaction with the report at runtime. This
component is required only if a developer wants to provide on-screen
display of reports at runtime.
Dual - Interface
The object model for the Report Designer Component is exposed as a dual-interface. This means the
component can be accessed and utilized easily in all kinds of development environments including Visual
Basic, Visual InterDev, Visual C++, and Delphi. Although the component may not work as an ActiveX
designer in all environments, the object model can be used as an automation server or ActiveX DLL in any
development environment that supports ActiveX.
The Seagate Crystal Report Designer Object Model has been optimized for easy access to reports created using
the Report Designer Component and the objects within those reports. Rather than forcing you to navigate
through a complex hierarchy of collections and objects to get at a single report element, the Report Designer
Object Model presents a flatter hierarchy that requires only obtaining, at most, a couple layers of objects to get
at any report element. This hierarchy begins with the Report object.
Many existing ActiveX object models require declaring and creating a high level object, such as an Application
object, before you can work directly with the data. The Report Designer Component, however, allows direct
access to the Report object, giving you control over your reports with a small amount of Visual Basic code.
Assuming you have added the Report Designer Component to a Visual Basic application, and the (Name)
property of that component is set to CrystalReport1, the following code demonstrates how to obtain a Report
object representing that component:
Dim cr As CRAXDRT.Report
Set cr = New CrystalReport1
The first line declares cr as Report object from the CRAXDRT object library, the Report Designer Component’s
object library. The second line of code defines cr as a new instance of the report in the CrystalReport1
component in your application.
Obtaining a Report object allows you to manipulate the report at runtime. Of course, once you make changes
to the report, you will frequently want to display it through the Smart Viewer. The Smart Viewer is an ActiveX
control that actually sits inside a Visual Basic form. Assuming you have added the Smart Viewer to a form
named frmViewer, and the Smart Viewer control is named CRViewer1, the following code displays the report.
frmViewer.CRViewer1.ReportSource = cr
frmViewer.CRViewer1.ViewReport
frmViewer.CRViewer1.Visible = True
This code can be added to the Load event of the frmViewer form. When the form loads, the report is displayed.
After looking over the previous sections on obtaining a Report object and displaying the report in the Smart
Viewer, you will quickly see how little code is required to perform the basic operations of displaying a report
on screen. The Report Designer object model is designed to simplify your code and reduce project
development time.
CRViewer1.ReportSource = Report
CRViewer1.ViewReport
End Sub
Notice that this code is handled in the Load event of a Form. This would normally be the form that contains
the Smart Viewer ActiveX control. Handling this process during the load event of the Smart Viewer form is
the quickest and easiest means of assigning new data to the report.
In the first line of code, a new Report variable is defined as an instance of the Report Designer Component that
has been added to the Visual Basic project. Immediately after that, a new ADO Recordset object is defined. The
Recordset object is then assigned a set of data (a recordset) using a SQL query statement. In this example, the
statement is hard-coded into the application. However, you could easily design an application that
dynamically generates a query statement based on a user’s input or selections.
Next, the SetDataSource method of the Report Designer Component’s Database object is used to specify that
the new ADO Recordset should be used to generate the report. SetDataSource accepts a single argument: the
Recordset object itself. This argument could also be a DAO Recordset or an RDO Resultset, or any other
ActiveX data source, as described in Active Data Driver, Page 118. The only restriction on the data source
assigned using SetDataSource is that it contain fields that match the fields used to originally create the report.
For instance, if the report was created using three string fields named SSN, LastName, and FirstName, the new
data source must also consist of three string fields named SSN, LastName, and FirstName.
The last two lines of code in this example assign the report object containing the new data source to the Smart
Viewer ActiveX control that appears in the Form, and displays the report. When the Form is loaded by your
Visual Basic application, the report will be displayed with the new data from the ADO Recordset.
When using the SetDataSource method, be aware that the method will fail if your Recordset or Resultset object
goes out of scope. For example, consider the following code:
In this example, although the rpt object is global (for the Form), the rs object exists only for the life of the
SetData procedure. Even though it is assigned to the rpt object before SetData finishes, the object, and the data,
that rs represents goes out of scope and is invalid for the Load event. Thus, the code will fail.
This problem can be solved using the ReadRecords method. ReadRecords forces the report to read the records
into the report so that they are internal to the Report object itself rather than remaining as a separate Recordset
object referenced by the report. Normally, this process would not happen until the report is displayed in the
viewer using the ViewReport method.
● Address2
● City
● Region
● Country
● Postal Code
● Phone
● Fax
When you create a new recordset, if you only add the three fields that appear in your report, values for one or
more fields may be missing. You must, instead, include the three fields in your report in the order that they
appear in the Data Definition file, along with any fields that may appear between them. Thus, to correctly
display Customer ID, Customer Name, and Last Year’s Sales in your report, you must design the new
recordset using all of the following fields:
● Customer ID
● Customer Name
● Contact First Name
● Contact Last Name
● Contact Title
● Contact Position
● Account Manager
● Last Year’s Sales
In fact, you may want to get in the habit of designing your runtime recordsets so that they include all fields
from the original Data Definition file. This can save time later if you make changes to the report.
Calculating Results
If you are using the Format event to calculate values, do not perform any calculations which require the values
to be carried across sections. For example, if you want to display a value in a Text object for the first record in
the Details section, add a value to the first value, and display the results for the next record, the result may be
incorrect. (This process is known as a running total.)
It is possible for the Format event to be fired multiple times for a section, each time the report is displayed.
Whether or not this happens depends on the contents of the section, groupings in the report, and various other
common report features. For this reason, a calculation performed in the Format event, may be performed
several times before final display, resulting in invalid results if the calculation is dependent on a value created
in another record or section.
In general, the Format event should be used primarily for formatting the report. Calculations can be
performed, as long as they do not depend on assigning a value to an outside variable or receiving a value from
an outside variable. For example, you could evaluate the value of a field in the section, then display a flag
based on its value. If Sales values drop below a minimum quota, for instance, they could be displayed in red
with a warning message next to them.
All report objects, such as Fields and Text objects, are contained within Sections. Often, these can be obtained
directly by referring to the name property of an object in your code. However, there may be times when you
need to obtain an object through the report section it is in. For example, you may need to iterate through all
objects in a section. At other times, you may have a need to make changes to the section itself.
Every report contains a collection of its sections, stored in the Sections property of the report object. Individual
sections can be accessed through this collection. For example, the code below sets the height of the first section
of the report (the Report Header) to half an inch (720 twips) and suppresses the second section of the report
(the Page Header) so that it will not appear.
Report.Sections.Item(1).Height = 720
Report.Sections.Item(2).Suppress = True
For information on how to obtain and work with other objects within a Section object, such as fields and text
objects, refer to Working with the ReportObjects collection.
The ReportObjects collection of a report Section object contains all report objects in that section. Report objects
may be Text objects, Fields, Subreport objects, or Crosstabs. To be able to work with a particular report object,
you must first obtain the object, then you must determine what type of object it is.
Usually, report objects can be addressed directly in your code based on their Name property. However, if you
intend to work with several objects in a section, you may need to refer to them through a Section object in the
report. The following code locates the last object in the last section of the report and assigns a value to a String
variable based on the type of object it is.
lastSectWithObject = Report.Sections.Count
Set sect = Report.Sections.Item(lastSectWithObject)
lastSectWithObject = lastSectWithObject - 1
Set sect = Report.Sections.Item(lastSectWithObject)
Loop
Case crBlobFieldObject
objKind = “BLOB field object”
Case crBoxObject
objKind = “Box object”
Case crCrossTabObject
objKind = “CrossTab object”
Case crFieldObject
objKind = “Field object”
Case crGraphObject
objKind = “Graph object”
Case crLineObject
objKind = “Line object”
Case crOleObject
Case crSubreportObject
objKind = “Subreport object”
Case crTextObject
objKind = “Text object”
Case Else
objKind = “Unknown object”
End Select
All relational databases have two standard features: records and fields. Records contain the actual data, while
fields define what type of data the records contain. Records are controlled through Recordset and Resultset
objects exposed by ADO, RDO, and DAO. Through such interfaces, you can also manipulate the fields in the
data source. However, to manipulate the fields that appear in your report, you must obtain a FieldObject from
the Report Designer object model.
A FieldObject is a feature of your report, and is, therefore, obtained through the ReportObjects collection. You
can query a specific report object to find out if it is a field, then work directly with the field, and even query it
for its value. The sample code below locates the first database field that appears in a report then obtains
information about that field.
Dim Report As New CrystalReport1
Dim rptObject As ReportObject
Dim fldObject As FieldObject
Dim dbFieldDef As DatabaseFieldDefinition
Dim message As String
‘ Locate the first field in the report
For Each sect In Report.Sections
For Each rptObject In sect.ReportObjects
‘ Is it a field?
If rptObject.Kind = crFieldObject Then
Set fldObject = rptObject
‘ Is it a database field?
If fldObject.Field.Kind = crDatabaseField
Exit For
End If
End If
A SubreportObject object is, essentially, another Report Object (see Report Object, Volume 3, Chapter 2), inside
the original report. Once you have obtained a SubreportObject, you can work with any aspect of it just as if it
were a standard Report object.
NOTE: You can not print, export, or display in the Smart Viewer a subreport outside of its primary report. The
SubreportObject can be manipulated in any way that Report objects are, but they can only be printed,
exported, or displayed as part of the primary report.
A SubreportObject is obtained through the ReportObjects collection. The following example shows how to
iterate through the sections of a report and change the background color of each subreport to magenta.
Dim Report As New CrystalReport1
Dim subReport As SubreportObject
For Each sect In Report.Sections
For Each rptObject In sect.ReportObjects
If rptObject.Kind = crSubreportObject Then
Set subReport = rptObject
subReport.BackColor = RGB(255, 0, 255)
Set subReport = Nothing
End If
Next
Next
NOTE: Currently, the Seagate Crystal Report Designer Component does not support subreports inside of
subreports. The report iterations can not go more than one subreport deep. However, you can have multiple
subreports inside the main report.
For more information on working with the ReportObjects collection, see Working with the ReportObjects
collection, Page 183.
Exporting a report
Often, once a report is created, you may need to get the data into a different format. For instance, if you want
to display the report on an Internet or intranet site, you need to export the report to HTML format. In such
cases, exporting is an alternative to displaying the report in the Smart Viewer control.
A common scenario might be to add a button control to a Form in your Visual Basic application, then have the
Click event of that control send the report to the required format. The following code demonstrates this
technique:
Private Sub Command1_Click
Dim Report As New CrystalReport1
Report.Export True
End Sub
The Export method is designed to automatically prompt the user with dialog boxes for information about the
destination and format to use when exporting the report. The Seagate Crystal Report Designer Component
allows users to export to any of the export formats and destinations provided by Seagate Crystal reports. For
more information on export formats, refer to the Seagate Crystal Reports User’s Guide.
NOTE: The sample call to CreateObject above uses a version independent Prog Id for the Report Designer
Component. The correct Prog Id for this version of the Report Designer Component is CrystalRuntime.Application.7,
but the version independent Prog Id should use the most recent version of the component installed on your system.
Report events
Although the Format event for the Section object is the only event directly supported by the Report Designer
Component, the Report object can produce the standard Visual Basic Initialize and Terminate events. The
Initialize event is fired when your Report object is first referenced at runtime. For example, your application
may contain a global variable that represents the Report object of the Report Designer that you added to your
application at design time:
In this case, declaring and setting the Report variable fires the Initialize event. The Terminate event will be
fired when this variable is set to Nothing:
As you can see, the Initialize event and the Terminate event are fired only once for each Report instance. With
that in mind, many changes can be made to your report within the event procedure code for each of these
events:
End Sub
End Sub
Use the Initialize event to make broad changes that affect the entire report. For instance, you could assign a
new data source using the SetDataSource method. The Terminate event is designed to allow convenient clean-
up of any variables or objects that you created during the Initialize event. If, for instance, you created a new
ADO Recordset object in the Initialize event, you can use the Terminate event to set this Recordset object equal
to Nothing, freeing up system memory and resources.
If your reports connect to secure Microsoft Access sessions, you must provide session information at runtime
using the SetSessionInfo method of the DatabaseTable object. This method accepts a user Id and password that
are passed to the Access session to provide a connection to the database.
Session information must be added to your code using the SetSessionInfo method, even if you specified
session information at design time. Session information specified at design time is not stored with the Report
Designer Component.
Assuming all tables in your report are from the same secured Access database, the following code will set the
Access session information:
Next
Programmatic ID
The report Designer Component exposes two objects that can be created at runtime using the Visual Basic
CreateObject function: Application and Report. The CreateObject function expects a single argument, the Prog
Id (Programmatic Id) of the component object. The Application and Report objects expose the following Prog
Ids:
CrystalRuntime.Application.7
CrystalRuntime.Report.7
If you wish, you can use a version independent Prog Id when referring to the Report Designer Component.
For example:
CrystalRuntime.Application
This Prog Id will use the most recent version of the Report Designer Component registered on your system.
However, if you have more than one version of the Report Designer Component installed, and you want to be
sure of using a specific version, include the version number in your CreateObject call.
When you create a report using the Report Designer Component in Visual Basic, it is bound inside the final
executable application. When you distribute the application, you do not need to worry about distributing
separate report files. Your end users, however, will not be able to modify the reports from within standalone
versions of Seagate Crystal Reports.
During development, Report Designer reports are saved in .DSR files. These are standard ActiveX designer
files that are added to your project whenever you add an ActiveX designer. For example, the default report
created by the Create Report Expert is CrystalReport1.dsr. This file contains both the Report Designer
Component and the report you design. It is part of your Visual Basic project and appears in the Project window
under the Designers folder.
You can also save reports as external Crystal Reports files (.RPT). Your Visual Basic application still uses the
report bound inside of the .DSR file, but the report becomes available for edits if you have a standalone version
of Seagate Crystal Reports 6.0 or later. Additionally, you may choose to use the OpenReport method of the
Application object to create a new Report object at runtime using the external report file. For information on
using this method, see the section on using the Application object.
To save a Report Designer Component report as an external file:
1 Create your report using the standard tools and features of the Report Designer Component. See the
tutorial Using the Seagate Crystal Report Designer Component Index for complete instructions on
creating a report.
2 With the Report Designer window active inside Visual Basic, click the Save to Crystal Reports File button in
the Report Designer’s toolbar. This button appears to the far right of the toolbar, and you may need to expand
the Report Designer window before you see it. When you click this button, a Save As dialog box appears.
3 Use the dialog box to select a location and file name for the report.
4 Click Save, and return to your Visual Basic project.
When working with the Report Designer Component, keep in mind that data is not stored with the report. The
report maintains a connection to the data through the ActiveX data source connection used (e.g DAO or ADO).
When the application is distributed, you must make sure that your users will still be able to access the data. If
this is not possible, you may want to consider using external report files.
External report files created and/or edited in a standalone version of Seagate Crystal Reports can have data
stored with the report file. This increases the size of the report file, but eliminates a dependency on a
connection to the original data source.
By using the Report Designer Component as an automation server, and obtaining a Report object through the
Application object’s OpenReport method, you can provide reports to your users without providing a data
connection at runtime. Remember, though, you will have to distribute the report files with your application.
Installation
The following topics are covered in this section.
Delphi 2, Page 194
Delphi 3 & 4, Page 195
C++ Builder 3, Page 198
Delphi 2
NOTE: It is also necessary to add the Crystal VCL install path to Delphi's Library Path string (Tools |
Environment Options | Library) in order for the Component files to be found by Delphi.
Problems
If another UCRPE32.DCU or CRYSTAL.DPL (CRYSTAL.BPL for Delphi 4) is found in the search path, the
package might not install. Since the installation of the package comes after the files have been copied to the
hard-drive, they should all be available in the directory chosen during install, and it is not necessary to run the
install again. All that needs to be done in this case is to first remove any older copies of the component that
Delphi found, and then add the package using one of the three ways described below.
1. The package included (DPL/BPL) can be directly installed.
2. The component (DCU) can be installed into a new package.
3. The component (DCU) can be installed into another package (Not recommended).
C++ Builder 3
Programming Overview
The following topics are discussed in this section.
Introduction to the Object Inspector, Page 200
Changing Properties in the Object Inspector, Page 200
Changing Properties at Runtime, Page 200
Delphi Programmers introduction to the SCR Print Engine, Page 201
Dealing with SubClass Objects, Page 203
Consistent Code, Page 204
Using the Retrieve method, Page 205
Working with subreports, Page 206
Other Guidelines, Page 208
Once you add the TCrpe component to a form in your project, build the connection between your Delphi
application and the Crystal Report Engine by setting the Component's properties via the Object Inspector.
Using the Object Inspector, you specify:
● the name of the report you want to print in response to an application event,
● the destination for that report (window, file, or printer),
● the number of copies you want to print (if your report is going to the printer),
● print file information (if your report is going to a file),
● preview window sizing and positioning information (if your report is going to a window),
● selection formula information (if you want to limit the records in your report),
● sorting information, and
● other related properties.
TCrpe component properties can be changed either at design time or at runtime. Note, however, some
properties are available only at runtime. These properties will not appear on the Properties list in the Object
Inspector. For a complete description of each property in the Crystal VCL Component, refer to Seagate Crystal
Reports Technical Reference: Volume 4 - VCL Reference, which is available as a PDF file.
To change the value for a property, click the property and then do the following:
● If a text box appears next to the property name, type in a value for the property.
● Ifa drop down list box appears next to the property name, click the arrow to open the drop down list
and select a value from that list.
● Ifa text box with an ellipsis (...) button appears next to the property name, click the button to reveal a
dialog box where you can define your setting for the property.
You can set most of the properties for the TCrpe component at runtime by adding simple entries to your
procedure code. Runtime property settings replace settings you make via the Object Inspector at design time.
The Execute property is used to actually process the report at runtime. This property can only be set at
runtime, and it is the only means by which a report can actually be generated by the TCrpe component.
For information on how to set component properties at runtime, refer to your Delphi documentation.
Developer’s online Help contains code examples for each of the TCrpe component properties. Search for the
property you are interested to view these examples.
Programmers who are new to the Seagate Crystal Reports Print Engine will want to spend a few moments
reading the next few paragraphs. After installing the Component, you should see the Seagate Crystal Reports
component icon on the Data Access tab of the VCL palette. Start a new project, and add the Component to the
form.
After adding the Component to the form, there are only two basic calls that need to be made in order to run a
report. First add a Button to your new form. Double click the button to start an OnClick event in the code for
the form. Inside the OnClick event, type the following two lines:
Crpe1.ReportName := 'c:\MyReport.rpt';
Crpe1.Execute;
Change 'c:\MyReport.rpt' to point to a valid Crystal Report file that exists on your computer. Now compile
the new Project and run it. When it appears, click on the button. If all goes well, you should see a Crystal
Report appear in the runtime Preview Window.
You will want to remember a basic rule at this point: always set the ReportName property first. The reason for
this is that when the value of ReportName changes, most of the other properties are cleared. This is more fully
explained later in this chapter in the Programming Tips section.
The next property you may want to experiment with is the Output property. By default this is set toWindow, but
you can also set it toPrinter, or toExport. This can be done in code or with the Object Inspector. If you are using
it in code, be sure to write it before the Execute command, or it will be ignored until the next Execute is called:
Crpe1.ReportName := 'c:\MyReport.rpt';
Crpe1.Output := toPrinter;
Crpe1.Execute;
The following list shows which properties control the options that are available for each Output type:
Since the architecture of the VCL has changed substantially from previous releases, here is a brief
programming introduction to acquaint you with the changes. As mentioned in the Introduction, the main
change in the architecture is the implementation of numerous subclasses.
An example: the Tables object
For example, the Tables subclass now encapsulates all the functionality of what was called Datafiles and
DatafilesLocation in the previous releases. This subclass consists of 10 properties and 8 methods. Of the 10
properties, the most essential are these three:
Number
Name
Path
Crpe1.Datafiles[0] := 'c:\MyNewPath\MyNewTable.dbf';
The subscript "[0]" represented the table number, 'c:\MyNewPath\' represented the Path, and
'MyNewTable.dbf' represented the table name. With the new VCL, the Tables object would be used instead of
the Datafiles stringlist. So the same statement would be coded like this:
Crpe1.Tables.Add(0);
Crpe1.Tables.Path := 'c:\MyNewPath\';
Crpe1.Tables.Name := 'MyNewTable.dbf';
The Add method instructs the Tables object to add an item with table number zero. Instead of this, you could
use the Retrieve method, which retrieves all the table information from the report (this is the same as what was
formerly called RetrieveDatafiles):
Crpe1.Tables.Retrieve;
After Retrieve has been called, you need to instruct the Tables object to navigate to the item whose properties
you want to change. This is necessary because the Tables object only looks at one table at a time. Think of it as
something similar to scrolling through the records of a database. There are a number of properties that can be
used to navigate through the object: Item, ItemIndex, and Number.
Crpe1.Tables.Number := 2;
This will cause the Tables object to look internally for a table with the number 2. If it finds it, the object will
now point it's properties to that table and will remain pointing there until it is changed. That is one way of
navigating through the tables.
The ItemIndex property can also be used to navigate through the Tables object:
Crpe1.Tables.ItemIndex := 2;
Although in this case, ItemIndex represents the position of the table in the internal Tables list, not necessarily
the table number (although if Retrieve is used, these should be the same).
By far the easiest and most natural way of navigating through the Tables object is the default array property,
Item. Since this is a default property, it does not need to be specified when making the call, so Tables[2] is the
same as Tables.Item[2]. And since the Item property returns a reference to the Tables object, it is possible to
add other properties to the end of the subscript:
Crpe1.Tables[2].Path := 'c:\MyNewPath\';
Crpe1.Tables[3].Name := 'MyNewTable.dbf';
While initially this might seem like a lot more work, it actually is much more powerful, especially when
dealing with items that have a dozen properties, such as the SectionFormat object. With SectionFormat, the old
method involved passing a large string of about a dozen items separated by semicolons. Even if you only
wanted to set one property, you still had to pass the whole string. With the new object format, you only need
to set the property that you want to change.
Consistent Code
One of the reasons for making the properties into objects is that the coding syntax is more consistent. For
example, there are a number of methods associated with the Tables object:
Crpe1.Tables.Retrieve;
Crpe1.Tables.Count;
Crpe1.Tables.Clear;
Crpe1.RetrieveDatafiles;
Crpe1.GetNDatafiles;
Crpe1.Datafiles.Clear;
And since each object in the new Component uses the same naming convention for the same methods, they
are very easy to remember.
It is important to remember that in the older versions of the Component, most of the properties were derived
from modified stringlists and the declaration Crpe1.Datafiles[0] would add a string to the list of subscript 0.
The new Component's subclass objects do not work the same way. Instead, there are two methods now used
to add an item to the list.
The first, and preferred way, is to use the Retrieve method. This retrieves the table information from the report,
and stores it in the Tables object, so that all the necessary table items are already present. You just need to set
the object to the desired table and then change the desired properties. This would be coded as:
(* Retrieves tables from report *)
Crpe1.Tables.Retrieve;
(* Modifies path of first table *)
Crpe1.Tables[0].Path := 'c:\MyNewPath\';
(* Modifies name of first table *)
Crpe1.Tables[0].Name := 'MyNewTable.dbf';
For changing the path of more than one table at a time, a simple loop can be constructed. Since the tables property
is now an object, it was easy to add methods and properties to it that made it behave like a stringlist. So the Count
method and ItemIndex properties were added, as well as the default array property, Item. The Item property
allows you to treat the Tables object as if it were a stringlist (Tables[0] is equivalent to Tables.Item[0]):
(* Retrieves tables from report *)
Crpe1.Tables.Retrieve;
for cnt := 0 to (Crpe1.Tables.Count - 1) do
begin
(* Modifies path of table *)
Crpe1.Tables[cnt].Path := 'c:\MyNewPath\';
end;
Crpe1.ReportName := 'c:\MyCrystalReport.rpt';
Crpe1.Subreports.Retrieve;
Crpe1.Printer.Retrieve;
Crpe1.PrintOptions.Retrieve;
Crpe1.SummaryInfo.Retrieve;
begin
Crpe1.Subreports[cnt];
Crpe1.LogOnInfo.Retrieve;
Crpe1.Connect.Retrieve;
(* Do not do SQL Retrieve here because it slows down loading while trying to
Logon to the Server. Use the SQL.Retrieve method after filling in the Password
property of the Connect or LogOnInfo objects *)
Crpe1.SQL.Params.Retrieve;
Crpe1.Tables.Retrieve;
Crpe1.Selection.Retrieve;
Crpe1.GroupSelection.Retrieve;
Crpe1.Formulas.Retrieve;
Crpe1.ParamFields.Retrieve;
Crpe1.GraphType.Retrieve;
Crpe1.GraphText.Retrieve;
Crpe1.GraphData.Retrieve;
Crpe1.GraphOptions.Retrieve;
Crpe1.SectionFormat.Retrieve;
Crpe1.SectionFormatFormulas.Retrieve;
Crpe1.AreaFormat.Retrieve;
Crpe1.AreaFormatFormulas.Retrieve;
Crpe1.SectionFont.Retrieve;
Crpe1.SectionMinHeight.Retrieve;
Crpe1.RetrieveDetailCopies;
end;
Please remember that the Retrieve method clears out the subclass object first before retrieving values from the
report, so be sure to use it at the beginning of the code that deals with that particular object. This is the correct
way:
Crpe1.Tables.Retrieve;
Crpe1.Tables[4].Name := 'MyNewTable.dbf';
And this is the wrong way:
Crpe1.Tables[4].Name := 'MyNewTable.dbf';
Crpe1.Tables.Retrieve;
Other Guidelines
Zero-based numbering is used throughout the Seagate Crystal Component, to make it compatible with the
Seagate Crystal Reports Print Engine. So, the first table is Table[0], the first Formula is Formulas[0], etc. The
only exception to the rule is the Group numbering, which starts with 1, just as it is in the Crystal Reports
Designer. So the various Section objects use GH1 as the first group, not GH0. Likewise, the GroupCondition
property takes 1 as the first Group for the Number property.
For numeric properties, -1 has been used as a default value. Normally, empty strings in properties that are of
string type will not be sent to the Print Engine. If you want to send an empty string, use the CrEmptyStr constant,
which will tell the Crystal component that you want to intentionally pass an empty string to the report.
Beware of saving Reports from the Seagate Crystal Report Designer with the Saved Data toggle on (this option
is located on the Report Options dialog box from the File menu), unless you want them that way. When they
are run from Delphi, if you don't set the DiscardSavedData property to True, the report will run from the
Saved Data (which is the default mode), and will not show the changes that have been made to the database.
After a report has been run via the VCL once, and the Print Job has not been closed (either via the CloseJob
method or changing the ReportName property), the report that is currently in memory now has Saved Data.
If you run it again, it will run with the Saved Data from the first run. This means that some of the changes you
pass in the second time, may not have any effect. The solution is to set the DiscardSavedData property to True.
Verify Database
Under the Database menu in Seagate Crystal Report Designer, there are two menu items: Verify Database and
Verify on Every Print. Since the database structure and index information are stored in a report file when it is
saved, the report may have problems running if the database structure changes.
One solution is to load the report into the Designer, and choose Verify Database, then resave the report. This
works fine during development, but if the database structure will be changing during runtime operation, there
is no equivalent for these Verify commands in the runtime engine. Therefore, Verify on Every Print should be
turned on in these instances. With this option on, the report will reread the database structure every time the
report runs. The amount of time taken to do this extra step is usually minimal. If the database structure will
not change after deployment, there is no reason to turn this feature on.
When changing Grouping fields at runtime via the GroupCondition or GroupOptions object, remember that
any inserted summary fields, or formulas containing summary fields in the report may cause errors, since they
contain the grouping field name as the second element of their parameters. For example, take the following
Summary field:
This formula sums the amount of company sales per State. This summary field assumes that (*
company.STATE *) is one of the grouping fields. If the grouping field is changed from (* company.STATE *)
to (* company.COUNTRY *), this formula field will generate an error.
The way to avoid this problem is to insert the grouping field into a formula field when designing the report. Then
when you create the group, base it on the formula field. Any summary fields inserted will also look at the formula
field as the grouping field, regardless of what it contains. Then to change the group field at runtime, simply pass
a new (* table.field *) value to the formula field. All the summaries will automatically change.
Since the VCL's Execute method uses the Send methods from the VCL's sub-class objects, there is usually no
need to call these methods in code. However, there are at least two cases where this can be advantageous:
1. For changing the order in which items get sent to the Print Engine. For example, the Execute method of
the VCL sends the Formulas first, and then the Grouping information. If GroupOptions.Send is called
just before Execute, this has the effect of sending in the Grouping information before the Formulas.
2. For testing the VCL and/or the Print Engine. Properties can be set and then passed from the VCL to the
Print Engine by calling the Send method. Then the values can be retrieved using the Retrieve method and
examined to make sure they are getting passed correctly.
The Crystal Reports Print Engine (CRPE32.DLL) assigns a specific Job Number to each open Print Job. This Job
Number is used internally in the VCL component, and is used when making calls to the CRPE so that it knows
which Print Job the call is going to. Because this number is exposed in the JobNumber property of the VCL, it
can be used to make direct calls to the CRPE, bypassing the VCL layer. While this is not normally
recommended, since making changes to the Print Job without the VCL knowing about the changes can lead to
problems, there are also times when this can be a powerful feature.
For example, the Execute method of the VCL has Events available within it, such as OnExecuteEnd,
OnPrintEnded, etc. These events have protection which prevents the programmer from calling another
Execute within the event (which would lead to an infinite loop). However, by the use of direct Print Engine
calls, this limitation can be worked around. The call to run a Report in the Print Engine is
function PEStartPrintJob(
JobNum : Word;
WaitUntilDone : Bool): Bool; stdcall;
The second parameter "WaitUntilDone" should always be True, and the first Parameter is the Print Job
number, which is available in the VCL via Crpe1.JobNumber. Therefore, making this call within the
OnExecuteEnd event (just as an example, not because it is meaningful!), causes the Report to be run
immediately.
For a complete list of the available Print Engine calls, consult the DEVELOPR.HLP that came with Crystal
Reports, or take a look at the CRDELPHI.PAS (if you have Crystal Reports 7), or CRPE32.PAS, which are also
in the Crystal Reports install directory, or some of the VCL source code files.
TCrpeString
The following topics are discussed in this section.
Introduction, Page 213
TCrpeString VCL Properties, Page 214
Using the TCrpeString, Page 214
TCrpeString = class(TStringList)
TCrpeString is the same as Delphi's TStringList, except the Put method defaults to Add if the subscript is one
number larger than the number of strings in the StringList. With a normal StringList, the following code would
cause an error:
var
slTemp : TStringList;
begin
slTemp := TStringList.Create;
slTemp[0] := 'The first line';
end;
The reason for the error is the code attempts to access the first string in the stringlist, but the first string does
not exist yet. The proper way to do this would be:
var
slTemp : TStringList;
begin
slTemp := TStringList.Create;
slTemp.Add('The first line');
end;
However, with the TCrpeString type, the first example would work as well as the second one. Therefore, this
is perfectly legal with the TCrpeString type:
var
slTemp : TCrpeString;
begin
slTemp := TCrpeString.Create;
slTemp[0] := 'The first line';
end;
This type was primarily created for the previous versions of the Crystal Reports VCL, where string lists were
used for almost every property that required multiple values or multiple lines, and where the subscript often
represented the order of items in the report. It was decided to retain this type and continue using it in the new
VCL, even though its added functionality is not quite as necessary as it used to be. The following properties
all use the TCrpeString type:
You can use any method that is legal for a TStringList to pass values to the TCrpeString as well as the subscript
method described above. The following describes how this works:
var
crList : TCrpeString;
begin
crList := TCrpeString.Create;
crList[0] := 'Subscript adds a new line if it doesn't currently exist, or
replaces the value in the line specified if the line currently
exists';
crList.Assign('Assign replaces anything in the List with this new value');
crList.Text := 'Text treats the stringlist as one block of text';
crList.SetText('SetText adds PChar strings to the List');
crList.Add('Add adds one new line to the List');
crList.Free;
end;
Introduction
Delphi variables can be used with Crystal Reports Formulas and the Crystal Component's Formulas object if
they are declared as string or converted to string (regardless of the actual data type) before being passed to the
Report. The value of the variable passed to the Report must be in the same format and look exactly as if entered
directly into the Crystal Reports Formula Editor:
● Stringdata types must be surrounded by double quotes: "This is a String". Single quotes are also valid
within Crystal Reports but because Delphi uses single quotes, all string data types passed to Crystal
should use double quotes to avoid conflicts.
● Numbers do not need quotes: 1234
● Dates must be put in the Crystal Reports Date function format: Date(YYYY,MM,DD)
The VCL Formulas object can only be used to change formulas that already exist in Crystal Reports, not to
create new formulas. The Formulas object can contain numerous Formula items, which can either be created
by using the Retrieve method:
Crpe1.Formulas.Retrieve;
or the manual Add method:
Crpe1.Formulas.Add('FormulaOne');
NOTE: Although Crystal Reports automatically prefixes the @ symbol to each Formula Name when a Formula
is created, the @ must not be included when using the Name or Add methods of the Formulas object in Delphi.
Once the Formulas object has items in it, the next step is to navigate to the desired item. This can be done in 3
different ways:
1. Use the default Item array property (subscript):
Crpe1.Formulas[0];
2. Use the Name lookup property:
Crpe1.Formulas.Name := 'FormulaOne';
3. Use the ItemIndex property:
Crpe1.Formulas.ItemIndex := 0;
NOTE: It is also acceptable, and perhaps easier to read, if the subscript specifying the Formulas item is also
used in the expression, although since the VCL objects have an internal Index, it is not strictly necessary:
{Clear the Formula first}
Crpe1.Formulas[0].Formula.Clear;
Crpe1.Formulas[0].Formula[0] := '"Formula String"';
If the subscript value is not known, it can be obtained right after setting the Formula Name:
{Clear the Formula first}
Crpe1.Formulas.Name := 'FormulaOne';
i := Crpe1.Formulas.ItemIndex;
Crpe1.Formulas[i].Formula.Clear;Crpe1.Formulas[i].Formula[0] := '"Formula
String"';
2. The Text property:
Crpe1.Formulas.Formula.Text := '23';
Crpe1.Formulas.Formula.Assign('Date(1998,01,01)');
Examples
Passing a variable from Delphi that results in a String data type in Crystal
Reports
As both Delphi and Crystal Reports require string values to be surrounded by quotes, a variable that results
in a string data type in Crystal Reports requires two sets of quotes: one set for Delphi and one set for Crystal
Reports. The first two examples show how to pass the variable when the value of the variable is hard-coded.
The third example shows how to pass the variable when the value of the variable is entered via an EditBox at
runtime.
var
sTmp: string; {Declare sTmp as a string variable}
begin
{Assign the contents of an EditBox to the sTmp variable}
sTmp := Edit1.Text;
Crpe1.Formulas.Name := 'StringFormula';
{Concatenate Formula with: open quote, variable name, close quote}
Crpe1.Formulas.Formula.Text := '"' + sTmp + '"';
{Display the value passed to the Report}
ShowMessage(Crpe1.Formulas.Formula.Text);
{The Message Box will display: EditBox value with surrounding double quotes}
{The Report will print: EditBox value without surrounding double quotes}
var
sNum: string; {Declare sNum as a string variable}
begin
{Assign a value to the variable. Note the use of one set of quotes}
sNum := '1234';
Crpe1.Formulas.Name := 'NumberFormula';
{Pass the variable value to the Formula text}
Crpe1.Formulas.Formula.Text := sNum;
{Display the value passed to the Report}
ShowMessage(Crpe1.Formulas.Formula.Text);
{The Message Box will display: 1234}
{The Report will print: 1234}
Example 2: The value is hard-coded and the variable declared as type Integer:
var
nTmp: integer; {Declare nTmp as an integer variable}
sNum: string; {Declare sNum as string variable}
begin
{Assign a value to the integer variable.}
nTmp := 1234;
{Assign the value of nTmp to the sNum string variable}
Str(sNum, nTmp;
Crpe1.Formulas.Name := 'NumberFormula';
{Pass the variable value to the Formula text}
Crpe1.Formulas.Formula.Text := sNum;
{Display the value passed to the Report}
ShowMessage(Crpe1.Formulas.Formula.Text);
{The Message Box will display: 1234}
{The Report will print: 1234}
var
sDate: string; {Declare sDate as a string variable}
begin
{Assign a value to the variable. Note that the year is 4 digits, the month and
day are 2 digits. The year, month and day are in the order Crystal Reports
expects and are delimited by commas, and the entire string is surrounded by
quotes.}
sDate := '1995,01,31';
Crpe1.Formulas.Name := 'DateFormula';
{Concatenate Formula with: the word Date, opening parenthesis, the variable
name, closing parenthesis}
Crpe1.Formulas.Formula.Text := 'Date(' + sDate + ')';
{Display the value passed to the Report}
ShowMessage(Crpe1.Formulas.Formula.Text);
{The Message Box will display: Date(1995,01,31)}
{The Report will print: 95/1/31}
{The Date format will be Windows default unless formatted otherwise in the
Report}
Example 2: The date is hard-coded and assigned to three variables as numeric strings. Formatting is done in
the Formula statement:
var
{Declare sYear, sMonth, sDay as string variables}
sYear, sMonth, sDay: string;
begin
{Assign a value to sYear; Note that the year is 4 digits}
sYear := '1995';
{Assign a value to sMonth; Note that the month is 2 digits}
sMonth := '01';
{Assign a value to sDay; Note that the day is 2 digits}
sDay := '31';
Crpe1.Formulas.Name := 'DateFormula';
{Concatenate the Formula with: the word Date, opening parenthesis, the sYear
variable, a comma, the sMonth variable, a comma, the sDay variable,
a comma, and a closing parenthesis}
var
{Declare sYear, sMonth, sDay, and sWholeDate as string variables}
sYear, sMonth, sDay, sWholeDate: string;
begin
{Assign the Year Entry EditBox value to sYear}
sYear := Edit1.Text;
{Assign the Month Entry EditBox value to sMonth}
sMonth := Edit2.Text;
{Assign the Day Entry EditBox value to sDay}
sDay := Edit3.Text;
{Concatenate Formula with: the word Date, an opening parenthesis, the sYear
variable, a comma, the sMonth variable, a comma, the sDay variable, a
comma, and a closing parenthesis, and assign the value to the sWholeDate
variable}
sWholeDate := 'Date(' + sYear + ',' + sMonth + ',' + sDay + ')';
Crpe1.Formulas.Name := 'DateFormula';
{Pass the variable value to the Formula text}
Crpe1.Formulas.Formula.Text := sWholeDate;
{Display the value passed to the Report}
ShowMessage(Crpe1.Formulas.Formula.Text);
{The Message Box will display: Date(YYYY,MM,DD) where YYYYMMDD represents
whatever was entered in the Year Entry, Month Entry, and Day Entry Edit
Boxes at runtime}
{The Report will print: YYYY/MM/DD}
{The Date format will be Windows default unless formatted otherwise in the
Report}
Introduction
Section names in the Crystal Reports VCL are now the same as the shortened section names used in the Crystal
Report Designer. The following prefixes are used for the different possible sections:
RH = Report Header
PH = Page Header
GH = Group Header
D = Details
GF = Group Footer
PF = Page Footer
RF = Report Footer
Group Headers and Footers also have a number associated with the prefix, which specifies to which Group
they belong, starting with the number 1 for the first Group:
If a Section has been divided into multiple Sub-Sections, these are specified by alphabetic letters going from a
to z and then aa to zz, and so on.
If the Retrieve method is used for the properties such as SectionFormat and AreaFormat, the Section property
will automatically be calculated and filled by the VCL Component. If the manual Add/Delete methods are
used, the Section will have to be assigned manually.
The Crystal Reports Print Engine uses the following numbering division:
● 1000 for each main section
● 25 for each sub-section
●0 to 24 for each Group
For example:
1000 is used for the report Header
2000 for the Page Header
3000 for the Group Header, etc.
Groups can be from 0 to 24, so:
Group Header 1 is 3000
Group Header 3 is 3002, etc.
Sub-sections are divided by 25, so:
Group Header 1a is 3000
Group Header 2b is 3026, etc.
This means a possible 40 divisions of 25 for each Section, since 40 * 25 = 1000. Therefore the print engine cannot
access more than 40 sub-sections at runtime. Since the VCL Component uses the runtime print engine, it also
has this limitation. While this is not usually a problem with most reports, the limit is reached if a report
contains more than 40 Detail sections, for example. In such cases, the VCL Component will only retrieve the
first 40 sections.
Using the information spelled out above, a simple example of the sections of a report, with their corresponding
section code numbers is illustrated below:
Area / Sections Area / Section Numbers
Report Header 1000
Report Header a 1000
Report Header b 1025
Page Header 2000
Page Header a 2000
Page Header b 2025
StrToSectionCode
The StrToSectionCode function is used internally by the Seagate Crystal Reports Component, but it is also a
public method and can be used by programmers. It's purpose is to take a Section name from one of the
component's Section properties and turn it back into a Print Engine Section code. This function is also used by
those objects that have a SectionAsCode property.
Introduction
The Inprise (formerly Borland) C++ Builder 3 version of Seagate Crystal Reports 32-bit Delphi VCL
Component has the same features as the Delphi version. In fact, it was recompiled from the Delphi source
code. This component is released "as-is". It has slight modifications to the source (nothing that affects the
properties or methods, just some compiler directives, etc.) made by a third party, to make it compile and run
in the BCB3 environment. Currently, only limited support is offered for any problems arising from the use of
this component. The Help file included is from the Delphi VCL Component, using Delphi code examples.
Some notes regarding the BCB syntax are included below.
Note that it is always possible to use direct Print Engine calls to the CRPE32.DLL using the CRPE.H and other
header files included with Crystal Reports as an alternative.
The installation of the C++ Builder Component was discussed earlier in this chapter in the installation section,
C++ Builder 3, Page 198.
Code Syntax
The general guidelines for translating the Delphi code examples (in the Help file) to BCB are as follows:
1. Use the equals sign (=) instead of the colon-equals sign (:=) for assignment, and use the arrow pointer (->)
instead of Delphi's dot (.) to specify class members.
//Delphi
Crpe1.DetailCopies := 3;
//C++Builder
Crpe1->DetailCopies = 3;
2. Use double quotes ("test") instead of single quotes ('test') for strings, and use double slashes for directories
(\\) instead of single slashes (\).
//Delphi
Crpe1.ReportName := 'C:\Report1.rpt';
//C++Builder
Crpe1->ReportName = "C:\\Report1.rpt";
//Delphi
Crpe1.SectionFormat.Retrieve;
//C++Builder
Crpe1->SectionFormat->Retrieve();
4. For default array properties, use the name of the array property instead of just the array brackets:
//Delphi
Crpe1.SectionFormat[1].BackgroundColor := clRed;
//C++Builder
Crpe1->SectionFormat->Item[1]->BackgroundColor = clRed;
Here are a few more brief examples that show the proper syntax for using the VCL Component. Refer to the
Help file for a reference as to what the actual Component properties do.
Crpe1->ReportName = "d:\\7Company.rpt";
Crpe1->Connect->Retrieve();
Crpe1->Connect->Password = "password";
if (Crpe1->Connect->Test())
ShowMessage("Test Succeeded");
else
ShowMessage("Test Failed");
//Retrieve and set Parameter Fields
Crpe1->ParamFields->Retrieve();
//According to which parameter field you want, you can set the
//ItemIndex (first parameter starts at 0) and have the ability
//to directly change the Value in this field
Crpe1->ParamFields->ItemIndex = 0;
Crpe1->ParamFields->Value = "CA";
Crpe1->SectionFormat->Section = "D";
Crpe1->SectionFormat->BackgroundColor = clRed;
Crpe1->SectionFormat->Item[1]->BackgroundColor = clGreen;
Crpe1->Execute();
Known Problems
The following topics are discussed in this section.
Retrieving ParamFields from a Subreport, Page 226
DialogParent and Temporary Forms, Page 226
There is a known problem with the CRPE32.DLL of Crystal 7 when attempting to retrieve ParamFields when
a Subreport is the current Report (that is, Subreports[n], where n is a number greater than zero). This does not
prevent access to Subreport ParamFields, since retrieving Subreports from the main Report (Subreports[0])
will retrieve the Subreport Parameters as well. The only time this will be a problem is if a Subreport is being
run as a separate Report (Crpe1.Subreports.SubExecute := True), and the Subreports class is pointing to a
Subreport when the ParamFields.Retrieve method is called. If you need to do this, do not use the
ParamFields.Retrieve method, simply build your ParamFields items manually with the Add method.
If the DialogParent property is set to a temporary Form, the Report is run, and then the temporary Form is
destroyed, attempting to run the Report a second time will cause an Access Violation in CRPE32.DLL. This is
because the CRPE stores the address of the DialogParent as long as the PrintJob is open. There seems to be no
way, at this time, to set the CRPE's Dialog Parent memory location back to nil. There are a number of ways
around this:
1 Set the DialogParent property of the VCL to a valid Form before running the Report a second time.
2 Close the Print Job (Crpe1.CloseJob) and open it again to run it the second time.
Index-1
connecting with the VCL Report, and Report Designer installation
Component ....................... 210 Component ....................... 154 C++ Builder 3 VCL
ODBC .................................... 31 export functions Component ........................ 198
secured .................................. 31 considerations for Crystal Web Report
SQL ........................................ 31 using .................................... 97 Server ..................................... 9
DatabaseTable object ............... 186 exporting Delphi 2 VCL
Delphi reports ................................... 94 Component ........................ 194
installation, Delphi 2 VCL Delphi 3 VCL
Component ....................... 194 F Component ........................ 195
installation, Delphi 3 VCL FieldObject object .................... 184 Delphi 4 VCL
Component ....................... 195 Files Component ........................ 195
installation, Delphi 4 VCL Data Definition .................. 119 Report Designer
Component ....................... 195 Data Definition, and Report Component ........................ 151
Design-time ActiveX Control ..... 44 Designer Component ...... 164 VCL Component ................. 194
developers Data Definition,
session timeout in Automation creating .............................. 123 J
Server ................................... 48 DLL, see DLL Java
what you should know ........ 65 formatted bound reports Crystal Smart Viewer ........... 55
development creating ............................... 142
Report Engine API ................ 68 Formulas L
directories Delphi, examples with Libraries
Crystal Web Report variables ............................ 216 Crystal Data Source
Server ................................... 14 Delphi, using variables ..... 215 Type .................................... 131
distributing Report Engine
Crystal Report Engine
applications .......................... 102 G Object ................................ 115
DLL GF command ............................... 31 limitations of HTML reports ....... 53
VB Wrapper ........................ 107 Grid Controls ............................. 139 links
drilling down on data ................. 27
group selection formulas coding custom-print ............. 75
Drivers
GF command ....................... 31 establishing custom-print .... 74
Active Data ......................... 125 establishing print-only ......... 71
database (ADO, DAO, and
RDO) .................................. 118
H logging on
handling preview window Password# command .......... 32
using Active Data ............... 119
errors ....................................... 97 USER# command ................. 33
E Help
M
Context-sensitive, Delphi 3
editing VCL Component .............. 197 methods
Active Server Pages ............. 47
Context-sensitive, Delphi 4 Retrieve, and VCL
errors, preview window
VCL Component .............. 197 Component ........................ 205
handling ................................ 97
HTML Send, and VCL
establishing Crystal Smart Viewer ........... 53 Component ......................... 211
custom-print links ................ 74 HTML reports StrToSectionCode, and VCL
print-only links ..................... 71
limitations of ......................... 53 Component ........................ 223
Events
Microsoft
Format, and Report Designer
Component ....................... 179
I Access, and Report Designer
Image Server Component ........................ 189
Preview window events in
Crystal Web Report AuthentiCode ........................ 58
Automation Server ........... 115
Server ................................... 39
Report, and Report Designer
Component ....................... 188 Images O
existing reports Report Designer Component Object Inspector
selecting ................................ 45 and OLE object ................ 182 VCL Component ................. 200
Expert using with Report Designer Objects
Crystal Web Server Component ....................... 149 Application and Report
Command ............................ 29 INIT command ............................ 30 Designer Component ....... 187
Application, see Application
Object ................................ 112
Index-2
CrossTabObject, and Report Crystal Smart Viewer for VCL Component, Object
Designer Component ...... 186 ActiveX ................................ 59 Inspector ............................ 200
Crystal Data ........................ 128 GF command ....................... 31 Prompt# command .............. 35, 36
Crystal Data Object ranges .................................... 83 properties
Model ................................. 131 values .................................... 83 JobNumber, and VCL
Database, and Report Designer Password# command ................. 32 Component ........................ 212
Component ....................... 186 passwords ReportName, and VCL
DatabaseTables, and Report Password# command .......... 32 Component ........................ 209
Designer Component ...... 186 Pictures
FieldObject, and Report see Images R
Designer Component ...... 184 preview window errors RDO data sources ..................... 118
Object Inspector, VCL handling ................................ 97 REAPI ............................................. 68
Component ....................... 200 printing structures ............................... 92
passing CRDataSource object from the Crystal Smart variable length strings .......... 89
to Active Data Driver ...... 137 Viewers ................................ 51 refreshing
releasing in VB ................... 114 print-only link web report data .................... 37
Report, see Report Object establishing ........................... 71 Report Designer Component ... 145
ReportObjects collection, and example code for ................. 73 adding RDC to a
Report Designer problems roject .................................. 152
Component ....................... 183 Delphi VCL adding Smart Viewer ......... 155
Rowset, see Rowset Object Component ....................... 226 and ActiveX ......................... 146
SubClass, and VCL Delphi, DialogParent and and ADO ............................. 158
Component ....................... 203 Temporary Forms ............. 226 and Application object ...... 187
SubreportObject, and Report Delphi, retrieving ParamFields and CrossTabObject
Designer Component ...... 185 from Subreport ................. 226 object ................................. 186
Text, and Report Designer procedures and CRViewer1 .................. 156
Component ....................... 180 SQL stored, see SQL and CrystalReport1 ............ 156
OCX Programmatic ID and DAO ............................. 158
adding to project ................ 108 and Report Designer and Data Definition
changing properties ........... 110 Component ....................... 189 Files .................................... 158
using ..................................... 109 programming and data sources ...... 158, 176
ODBC databases ......................... 31 Delphi, introduction to the and Database object .......... 186
OLE control Print Engine ...................... 201 and DatabaseTable
adding to project ................ 108 Report Designer Component object ................................. 186
changing properties ........... 110 Object Model ................... 173 and FieldObject Object .... 184
changing properties Report Engine API ................ 68 and Microsoft Access
at runtime .......................... 110 subreports and VCL sessions .............................. 189
using ..................................... 109 Component ....................... 206 and ODBC ........................... 158
opening VCL Component and Crystal and OLEDB ......................... 158
Crystal Report Engine ........ 104 Reports Designer .............. 202 and PC data sources .......... 158
overview VCL Component and Sub-Class and Programmatic ID ........ 189
Crystal Smart Viewer ........... 50 Objects .............................. 203 and RDO ............................. 158
Crystal Web Report Server ... 2 VCL Component tips ......... 209 and Report Events .............. 188
VCL Component, and Retrieve and Report Packages ......... 158
P method .............................. 205 and Report Templates ........ 158
Page Server VCL Component, changing and ReportObjects
Crystal Web Report properties at runtime ....... 200 collection ........................... 183
Server ................................... 39 VCL Component, changing and Seagate Crystal
pages properties with Object Reports ............................... 147
editing Active Server ........... 47 Inspector ............................ 200 and secure data sources .... 179
parameter fields VCL Component, Consistent and Smart Viewer
Prompt# command ...... 35, 36 Code .................................. 204 Control ............................... 156
parameters VCL Component, Delphi and SQL data sources ........ 158
Crystal Smart View overview ............................ 199 and SubreportObject
for Java ................................. 55 VCL Component, object ................................. 185
guidelines .......................... 208
Index-3
and Text Objects ................ 180 using in VB ......................... 113 customizing ........................... 47
and the Format Event ......... 179 Report Packages HTML ..................................... 53
and VB Data and Report Designer Java ......................................... 55
Environment ...................... 158 Component ....................... 158 printing from ......................... 51
and Visual Basic ................. 150 ReportObjects collection ......... 183 see also Crystal Smart Viewer
Architecture ........................ 170 reports SQL
Conditional Formatting ..... 148 creating formatted connection to databases with
Copy and Paste ................... 148 bound ................................ 142 VCL Component ............... 210
data access .......................... 148 distributing with Report databases, and Web Reports
Display code ....................... 157 Designer Component ...... 190 Server ................................... 31
distributing reports ............. 190 establishing custom-print stored procedures, and Web
distribution of the link ....................................... 74 Reports Server ..................... 34
Application ........................ 151 exporting ............................... 94 stored procedures, SQL
existing report as report exporting in Report Designer see SQL
template ............................. 167 Component ....................... 187 structures
exporting reports ................ 187 limitations of HTML ............ 53 Report Engine API ................ 92
features ................................ 146 selecting existing ................. 45 SubClass Objects
guidelines ............................ 149 using existing as template in and VCL
Images .................................. 149 Report Designer Component ........................ 203
images, OLE object ............ 182 Component ......................... 167 SubreportObject, and Report
installation ........................... 151 Rowset Object Designer Component .......... 185
introduction ........................ 146 adding fields ....................... 130 subreports
Object Model and the VCL Component .. 206
programming .................... 173 S using with Report Designer
passing fields ...................... 177 sample web site ........................... 48 Component ........................ 149
Pictures, see Images section codes working with ......................... 93
Preview Window ............... 149 and Report Designer system requirements
Report Expert ...................... 154 Component ....................... 182 Crystal Web Report Server .... 9
running the application ..... 155 and VCL Component ........ 221 Report Designer
section codes ...................... 182 decoding ............................... 86 Component ......................... 151
selecting data for working with ........................ 84
a report .............................. 153 Section Map ................................. 87 T
subreports ............................ 149 section names TCrpeString
system requirements .......... 151 and VCL Component ........ 221 and VCL Component ......... 212
using the RDC .................... 151 see also section codes Technical Support
Report Engine VCL Component, contacting ............................ 227
API .......................................... 68 StrToSectionCode Text Objects
before using in your method ................................ 223 and Report Designer
application .......................... 65 secured databases ....................... 31 Component ........................ 180
distributing applications ... 102 selecting
introduction .......................... 64 existing reports to use ......... 45 U
using ....................................... 66 selection formulas user IDs
Report Engine API changing in web reports ..... 30 USER# command ................. 33
overview ................................ 68 SF command ......................... 31 USER# command ......................... 33
structures ............................... 92 Server using
using in Visual Basic ......... 104 Image, Crystal Report Engine API in
variable length strings ......... 89 see Crystal Web Report Server Visual Basic ....................... 104
Report Engine Automation Page, existing reports ..................... 45
Server ....................................... 44 see Crystal Web Report Server the Crystal Report Engine .... 66
Report Events Server, Automation ..................... 44 the Crystal Report
and the Report Designer Session Timeout .......................... 48 Engine API ............................. 70
Component ....................... 188 SF command ................................ 31
Report Expert, Report Designer
Component ........................... 154
Smart Navigation ........................ 26 V
Smart Viewer variable length strings ................. 89
Report Object ActiveX .................................. 57
obtaining in VB .................. 113
Index-4
VCL Component using Automation Server .. 112
and C++ Builder 3 ............. 224 using the Crystal Report Engine
and saved data ................... 210 API in ................................. 104
and section names ............. 221 Wrapper DLL ...................... 107
and subreports .................... 206 Visual Basic applications
changing database tables and when to open Crystal Report
formulas ............................. 211 Engine ................................ 104
changing group and summary Visual InterDev Design-time
fields ................................... 211 ActiveX Control ..................... 44
connecting to
databases ........................... 210 W
Delphi programming web reports
overview ........................... 199 changing selection
installation ........................... 194 formulas in .......................... 30
JobNumber property .......... 212 refreshing data ...................... 37
know problems ................... 226 web site
overview .............................. 194 sample of .............................. 48
programming guidlines ..... 208 working
programming tips ............... 209
with section codes ............... 84
properties, changing
at runtime ............................ 200
properties, changing with
Object Inspector ............... 200
ReportName property ........ 209
Retrieve method ................. 205
Send method ....................... 211
StrToSectionCode
method ............................... 223
TCrpeString ......................... 212
using variables .................... 215
Visual Basic
ActiveX Control, upgrading
from Crystal Custom
Control ............................... 110
ActiveX Controls ................ 108
adding ActiveX Control to
project ................................ 108
adding Automation Server
to project ........................... 111
changing properties for
ActiveX Control ................ 110
changing properties for ActiveX
Control at runtime ............ 110
dates and date ranges ........ 105
embedded quotes
in VB calls ......................... 104
hard coded nulls in VB user
defined types ..................... 107
releasing objects ................. 114
sample Automation Server
application ........................ 117
section codes and ................ 88
solutions .............................. 103
string issues in
VB links .............................. 106
using ActiveX Control ....... 109
Index-5