Crystal Reports™ 5.

0
Developer’s Reference

Seagate Software Information Management Group, Inc.

1095 West Pender St., 4th Floor
Vancouver, B.C., Canada V6E 2M6
Copyright ©1991-1996 (manual and software) by Seagate
Software, Inc., All Rights Reserved.
Crystal Reports for Windows is a trademark of Seagate Software,
Inc. or one of its subsidiaries. Borland and Delphi are trademarks
of Borland International. Microsoft, MS, Visual C++, and Visual
Basic are trademarks of Microsoft Corporation. Windows, when
used in this manual, refers to the Microsoft Windows operating
system. Portions of this program Copyright 1982-1995 Btrieve
Technologies, Inc. All Rights Reserved. All other product names
referenced are believed to be the registered trademarks of their
respective companies.

Manual written by
Gary Carter, John Morse, Lisa Barry, and Kirsten Sutton
(INSTRUCTIONS, ETC.),1992-1996.
C O N T E N T S
Chapter 1 - Application Development with Crystal Reports
Introduction To The Crystal Report Engine .............................................................2
Before using the Report Engine in your application ................................................3
Using The Crystal Report Engine ............................................................................4
The Crystal Custom Control ...................................................................................5
The Crystal ActiveX Control (OCX) ........................................................................8
The Crystal Visual Component Library for Delphi ................................................11
The Report Engine Class Library ...........................................................................13
The Report Engine API .........................................................................................15
Distributing Report Engine Applications ...............................................................35
Working with subreports ......................................................................................36
Exporting Reports Using the Report Engine API ....................................................37
Special Considerations for Visual Basic users .......................................................40
Additional Sources of Information ........................................................................44
Section Codes ......................................................................................................46

Chapter 2 - ActiveX/VBX Reference

Crystal ActiveX Control Properties Index ..............................................................47
PROPERTIES ........................................................................................................55
METHODS .........................................................................................................130

Chapter 3 - Visual Component Library Reference

TCrpe Component .............................................................................................134
TCrpePrinterSetup Class .....................................................................................134
PROPERTIES ......................................................................................................135
METHODS .........................................................................................................200
EVENTS .............................................................................................................206
TUTORIALS .......................................................................................................207

Chapter 4 - Report Engine Class Library Reference

Class Library Support Structures .........................................................................210
Report Engine Classes ........................................................................................236

Chapter 5 - Crystal NewEra Class Library Reference

Crystal NewEra Class Library Overview .............................................................322
CLASS CRPELogOnInfo ......................................................................................322
CLASS CRPEJobInfo ...........................................................................................324

i
CLASS CRPETableType ...................................................................................... 325
CLASS CRPESessionInfo ..................................................................................... 326
CLASS CRPETableLocation ................................................................................ 327
CLASS CRPEPrintOptions ................................................................................... 327
CLASS CRPEExportOptions ................................................................................ 329
CLASS CRPESectionOptions .............................................................................. 333
CLASS CRPEGraphDataInfo ............................................................................... 336
CLASS CRPEGraphTextInfo ................................................................................ 338
CLASS CRPEngine .............................................................................................. 342
CLASS CRPEJob ................................................................................................. 343

Chapter 6 - Crystal Report Engine Reference

Working with section codes ............................................................................... 428
FUNCTIONS ..................................................................................................... 431
STRUCTURES .................................................................................................... 619

Chapter 7 - Creating User Defined Functions

Designing UFL Functions ................................................................................... 718
Programming the UFL ........................................................................................ 721
Helper Modules ................................................................................................. 721
Setting Up a UFL Project .................................................................................... 722
Function Definition ............................................................................................ 723
Function Definition Table .................................................................................. 725
Function Templates Table .................................................................................. 726
Function Examples Table ................................................................................... 727
Error Table ......................................................................................................... 728
InitForJob Function ............................................................................................ 729
TermForJob Function ......................................................................................... 729
UFL Function Implementation ........................................................................... 730
Returning User Defined Errors ........................................................................... 730
Obtaining parameter values from the parameter block ....................................... 731
Picture Function - a sample UFL function .......................................................... 732
Module Definition (.def) File .............................................................................. 735
UFJOB Modules ................................................................................................. 737
Multiple UFL job considerations ........................................................................ 739
Known problems with earlier versions of UFJob.C ............................................. 740

Index

ii
1 Application Development with
Crystal Reports

What you will find in this chapter...

Introduction To The Crystal Report Engine 2
Before using the Report Engine in your application 3
Using The Crystal Report Engine 4
The Crystal Custom Control 5
The Crystal ActiveX Control (OCX) 8
The Crystal Visual Component Library for Delphi 11
The Report Engine Class Library 13
The Report Engine API 15
Distributing Report Engine Applications 35
Additional Sources of Information 44

Chapter 1, Application Development with Crystal Reports 1

Introduction To The Crystal Report Engine

Besides acting as a powerful stand-alone report creating application,

Crystal Reports provides a report writing module that you can add to
your own applications. As a developer using C, C++, Visual Basic,
ObjectVision, Turbo Pascal, Visual dBASE, Delphi, or any programming
language that can access a DLL, you can add sophisticated report
generating and printing capabilities to your applications without the
time-consuming task of writing your own code.
The Crystal Report Engine is a Dynamic Link Library (DLL) that allows
your applications to access the same powerful report printing features
that are available in Crystal Reports. As a licensed user of Crystal
Reports, you receive royalty-free rights to ship the Report Engine DLL
(CRPE.DLL or CRPE32.DLL) and all of its support files with any
application you create.
NOTE: For more information regarding current runtime file
requirements, please see the Runtime File Requirements Help file.
From your application, you access the Report Engine through any of
several Report Engine development tools:
● the Crystal Custom Control, CRYSTAL.VBX,
● the Crystal ActiveX Control, CRYSTAL.OCX or CRYSTL32.OCX,
● the Crystal Visual Component Library for Delphi, UCRPE.DCU or
UCRPE32.DCU,
● the Report Engine Class Library, PEPLUS.H and PEPLUS.CPP, or
● the Report Engine API, CRPE.DLL or CRPE32.DLL.
When your application runs, it links with the 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 CRPE.DLL are for the 16-bit version. If you plan
on using the 32-bit version, it is called CRPE32.DLL.

Special SQL AND ODBC

Features Of The The Crystal Report Engine is fully compatible with most popular SQL DBMS
applications, including Sybase SQL Server, Oracle, Gupta SQLBase, and
Report Engine Microsoft SQL Server. The Report Engine includes options for logging on and
off of SQL servers and other ODBC data sources and also includes the ability
to edit the SQL statement passed through to an SQL or ODBC database.

2 Crystal Reports Developer’s Reference

 EXPORTING
The Report Engine enables you to print to a printer or a Preview window
with simple function calls. In addition, you can export a file:
● through e-mail to another person on your network,
● directly to disk,
● to a Microsoft Exchange folder,
● to a Lotus Notes folder, or
● 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.

Before using the Report Engine in your application

Before you add the Crystal Report Engine to your application, you should
be familiar with some key features of the Report Engine. Review the
following points, and make sure you understand each before attempting
to make calls to the Report Engine from your application.
● The Report Engine outputs existing reports. You can not create report
files using the functionality of the Report Engine. Reports must be
created using the Crystal Reports application described in the Crystal
Reports User’s Guide. Make sure you understand the report creation
process before trying to print reports with the Report Engine.
● The Report Engine provides a convenient add-on to your existing
application development project. With just a few lines of code, you
produce a powerful report writing and distribution tool that would
take thousands of lines of code and weeks to produce otherwise.
● The Report Engine does not require the use of a fixed user interface.
The 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.

Chapter 1, Application Development with Crystal Reports 3

Using The Crystal Report Engine

Any development project that incorporates the Crystal Report Engine

requires three steps:
1. Create the reports your users will access.
2. Design the user interface that will drive the Report Engine.
3. Add the Report Engine to your application.

Creating Creating reports to include with your applications is identical to creating

reports for your own use; there are no restrictions. Using the procedures
reports outlined in the Crystal Reports User’s Guide and online Help, create as
many kinds of reports as you want to make available to your users. You
can make the reports as simple or as sophisticated as your needs dictate.

Creating the 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
interface for is unimportant to the Report Engine.
printing the Common methods of using the Report Engine include a single menu
reports 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 Report Engine most efficiently.

Adding the As described earlier in this chapter, there are five different Report Engine
development tools that can be used to add the Crystal Report Engine to
Report Engine your application:
to your ● the Crystal Custom Control,
application ● the Crystal ActiveX Control,
● the Crystal Visual Component Library for Delphi,

4 Crystal Reports Developer’s Reference

 ● the Report Engine Class Library, and
● the Report Engine API.
Be aware that you can not use two or more of these tools in the same
application. For example, you can not create a Visual Basic application
that contains the Crystal Custom Control and also makes calls to the
functions in the Report Engine API. You must choose one tool to
implement the Report Engine in your project and stick with that tool.
When choosing a Report Engine tool, consider the following:
● What is your development environment?
● What is your programming ability?
● Do you need to implement the entire Report Engine or just a few
features of it?
For example, the Crystal Visual Component Library for Delphi only
works in the Borland Delphi programming environment. Therefore, if
you are programming in Visual Basic, the Crystal VCL is not an option.
The Report Engine Class Library, on the other hand, is based on the
Microsoft Foundation Class Library for C++. To use the Report Engine
Class Library, you must be using a C++ development tool, and you must
be using the MFC library.
If you are an experienced programmer, you might consider the Report
Engine API or the Report Engine Class Library. Novice programmers, on
the other hand, may want to take advantage of the easy-to-use features of
the Crystal Custom Control, the ActiveX Control, or the Visual
Component Library.
The rest of this chapter examines the steps needed with each tool to add
the Report Engine to your application. Remember, you can only use one
tool at a time in an application. Review each section and decide which
Report Engine tool is best for your development project.

The Crystal Custom Control

The Crystal Custom Control is a VBX file first supported by Visual Basic
3.0. Although this type of add-on control has been replaced by the more
powerful ActiveX control, many development applications, including
Visual Basic 4.0, continue to support VBX controls.
NOTE: The Crystal Custom Control is only available for 16-bit
development environments.

Chapter 1, Application Development with Crystal Reports 5

Adding the This section demonstrates how to add the Crystal Custom Control to an
application project being designed in Visual Basic 4.0. If you wish to use
Custom Control the Custom Control in a different development environment, please refer
to your project to the documentation that came with your development tools for
information on adding a VBX control to your project.
The Crystal Custom Control is installed in the \WINDOWS\SYSTEM
directory when you install Crystal Reports. You add the Crystal Custom
Control to your Visual Basic project using the CUSTOM CONTROLS
command on the Visual Basic Tools menu.
1. Open Visual Basic.
2. Open the project that you want to add the Custom Control to.
3. Choose the CUSTOM CONTROLS command from the Tools menu.
The Custom Controls dialog box appears.
4. If Crystal Custom Control appears in the Available Controls list,
click the check box next to it, click OK, and skip to Step 8.
5. If Crystal Custom Control does not appear in the Available Controls
list, click Browse. The Add Custom Control dialog box appears.
NOTE: Do not confuse Crystal Custom Control with Crystal Report
Control. Crystal Custom Control is the Crystal VBX. Crystal Report
Control is the Crystal ActiveX control.
6. Use the controls in the Add Custom Control dialog box to locate and
select the CRYSTAL.VBX file. This file is installed in your
\WINDOWS\SYSTEM directory by default. Once you locate and
select the file, click Open.
7. Crystal Custom Control will now appear in the Available Controls
list box. Click the check box next to the name of the control, and click
OK.
8. Visual Basic adds the Crystal Custom Control to your toolbox. The
tool looks like this:

9. When you want to add the Custom Control to a form, double-click

the tool and the program installs it on the active form.
NOTE: CRYSTAL.VBX can be added to AUTOLOAD.MAK to
automatically load the Custom Control to your project. Refer to Visual
Basic documentation for information on adding controls to
AUTOLOAD.MAK.

6 Crystal Reports Developer’s Reference

 NOTE: For instructions on how to add CRYSTAL.VBX to development
applications other than Visual Basic, refer to the documentation that
came with the development application you are using.

Using the This section illustrates the basic features of the Crystal Custom Control
and how to use the Custom Control in a Visual Basic 4.0 project to add
Custom Control Report Engine functionality.
Once you have the Crystal Custom Control object on your form, you
build the connection between your application and Crystal Reports by
setting the object's properties via the Properties list. Using the properties
list, 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),
● print 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), and
● sorting information.
Crystal Custom 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 on the Properties list in Visual
Basic.
NOTE: For a complete description of each property in the Crystal Custom
Control, refer to the Crystal Reports Developer’s online Help.

CHANGING PROPERTIES ON THE PROPERTIES LIST

To change the value for a property, highlight the property and then do the
following:
● If the settings box displays an inactive (grayed-out) arrow, enter your
new value in the settings box.
● If the settings box displays an active (black) arrow, click the arrow to
reveal your alternatives and select a value from the drop down list
that appears. Alternately you can double-click the property itself to
cycle through the list of values. Move on to the next property when
the value you want is displayed.

Chapter 1, Application Development with Crystal Reports 7

 ● If an ellipsis (...) appears at the right of the settings box, click the ellipsis
to reveal a dialog box you can use to define your setting. Alternately
you can double-click the property itself to call up the dialog box. Define
your setting in the dialog box and click OK when finished.

CHANGING PROPERTIES AT RUNTIME

You can set most of the Custom Control properties at runtime by adding
simple entries to your procedure code. Runtime property settings replace
settings you make via the Properties list at design time.
The Action 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 Custom Control.
For information on how to set Visual Basic control properties at runtime,
refer to your Visual Basic documentation. The Crystal Reports
Developer’s online Help contains code examples for each of the Crystal
Custom Control properties. Search for the property you are interested in
for examples.

The Crystal ActiveX Control (OCX)

ActiveX is Microsoft’s new Internet technology designed to bring more

powerful applications to desktops and networks. ActiveX moves beyond
applications that produce static documents to a Windows environment
that provides active controls, documents, and client applications that can
operate and interact not only with each other, but also with network
intranets and the global Internet.
ActiveX controls, formerly known as OLE controls, provide plug-in
capabilities that let you add application components, and even entire
applications, to your own development projects without writing a line of
code. Crystal Reports supports the ActiveX concept with the Crystal
ActiveX Control. Use the ActiveX Control to easily add all of the report
processing power of Crystal Reports to your own Visual Basic 4.0, Visual
C++, Borland C++, Delphi, and other applications.
NOTE: Your 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.

8 Crystal Reports Developer’s Reference

Adding the This section demonstrates how to add the Crystal ActiveX Control to an
application project being designed in Visual Basic 4.0. If you wish to use
ActiveX the ActiveX Control in a different development environment, please refer
Control to to the documentation that came with your development tools for
your project information on adding an ActiveX or OLE control (OCX) to your project.
The Crystal ActiveX Control is installed in the \WINDOWS\SYSTEM
directory when you install Crystal Reports. You add the ActiveX Control
to your Visual Basic project using the CUSTOM CONTROLS command on
the Visual Basic Tools menu.
1. Open Visual Basic.
2. Open the project to which you want to add the ActiveX Control.
3. Choose the CUSTOM CONTROLS command from the Tools menu.
The Custom Controls dialog box appears.
4. If Crystal Report Control appears in the Available Controls list, click
the check box next to it, click OK, and skip to Step 8.
5. If Crystal Report Control does not appear in the Available
Controls list, click Browse. The Add Custom Control dialog box
appears.
NOTE: Crystal Report Control is the name of the Crystal ActiveX Control
when it is added to a development project. The term ActiveX Control
refers to a type of control, while Crystal Report Control is the name of the
ActiveX Control provided by Crystal Reports.
6. Use the controls in the Add Custom Control dialog box to locate and
select the CRYSTL16.OCX (16-bit) or CRYSTL32.OCX (32-bit) file.
This file is installed in your \WINDOWS\SYSTEM directory by
default. Once you locate and select the file, click Open.
7. Crystal Report Control will now appear in the Available Controls
list box. Click the check box next to the name of the control, and
click OK.
8. Visual Basic adds the Crystal ActiveX Control to your toolbox. The
tool looks like this:

9. When you want to add the ActiveX Control to a form, double-click

the tool and the program installs it on the active form.
NOTE: The ActiveX Control can be added to AUTOLOAD.MAK to
automatically load the Control to your project. Refer to Visual Basic
documentation for information on adding controls to AUTOLOAD.MAK.

Chapter 1, Application Development with Crystal Reports 9

 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.

Using the Once you have the ActiveX Control object on your form, you build the
connection between your application and Crystal Reports by setting the
ActiveX object's properties at design time or changing properties at runtime. The
Control 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),
● print 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 at design time.
NOTE: For a complete description of each property in the Crystal ActiveX
Control, refer to the Crystal Reports Developer’s online Help.

CHANGING PROPERTIES FOR THE ACTIVEX CONTROL

1. Click the ActiveX control on your form to select it.
2. Right-click and choose the PROPERTIES command from the shortcut
menu that appears. The Crystal Report Control Properties dialog box
appears.
3. Use the tabs and controls in this dialog box to change the ActiveX
Control properties at design time.
NOTE: ActiveX Control properties also appear in the Visual Basic
Properties box. Properties can be changed here much like they are
changed for the Crystal Custom Control.

10 Crystal Reports Developer’s Reference

 CHANGING PROPERTIES AT RUNTIME
You can set most of the ActiveX Control properties at runtime by adding
simple entries to your procedure code. Runtime property settings replace
settings you make via the Properties list at design time.
Use the Action property or the PrintReport method to actually process
the report at runtime. The Action property and the PrintReport method
can only be used at runtime, and are the only means by which a report can
actually be generated by the ActiveX Control.
For information on how to set ActiveX Control properties at runtime,
refer to the Crystal Reports Developer’s online Help. Online Help also
provides examples of how to set each property at runtime.

The Crystal Visual Component Library for Delphi

The Crystal Visual Component Library (VCL) has been designed

specially for the Borland Delphi development environment. The VCL can
be easily added to any Delphi project and compiled into your final
executable application. Like the Custom Control (VBX) and ActiveX
Control (OCX), the VCL provides all of the report processing power
available in Crystal Reports for your own Delphi projects.
NOTE: Delphi 2.0 can also use ActiveX Controls. Refer to your Delphi 2.0
documentation on how to use an OLE Control (OCX) in a Delphi project.

Adding the VCL The following instructions demonstrate how to add the Crystal VCL to a
Delphi 2.0 project using the INSTALL command on the Component menu.
to your project If you are using Delphi 1.x, use the INSTALL COMPONENTS command on
the Options menu and refer to your Delphi 1.0 documentation for
complete instructions.
1. With your project open in Delphi, choose the INSTALL command
from the Component menu. The Install Components dialog box
appears.
2. Click Add to add a new component to your project. The Add Module
dialog box appears.
3. Click Browse. The Add Module dialog box changes to allow you to
browse through your directories and files to find a component
module.
4. Select Unit file (*.DCU) from the Files of type drop down list box. The
Crystal VCL is a Delphi Unit file.

Chapter 1, Application Development with Crystal Reports 11

 5. Use the controls in the Add Module dialog box to locate and select
the Crystal VCL. This file is installed in the Crystal Reports VCL
directory (\CRW\VCL by default). The file is named UCRPE.DCU
(16-bit) or UCRPE32.DCU (32-bit).
6. Once you select the VCL file, click Open. The Add Module dialog
box closes.
7. In the Install Components dialog box, the name of the Crystal VCL
(UCRPE or UCRPE32) will appear in the Installed units list box.
Select this VCL, and the TCrpe class will appear in the Component
classes list box. Click OK to close the Install Components dialog box
when finished. Delphi will recompile the component library, adding
in the Crystal VCL.
8. Click the Data Access Tab on the Component Palette. The Crystal
VCL appears as the last component on the Data Access Tab. When
you hold the cursor over the component, a Tool Tip appears
indicating the name of the component as Crpe.
9. Double-click the Crpe component to add it to the active form in your
project.

Using the Once you add the Crpe component to a form in your project, you build
the connection between your Delphi application and the Crystal Report
Crystal VCL 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),
● print 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.
Crpe component 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 on the Properties list in the Object
Inspector.

12 Crystal Reports Developer’s Reference

 NOTE: For a complete description of each property in the Crystal VCL,
refer to the Crystal Reports Developer’s online Help.

CHANGING PROPERTIES IN THE OBJECT INSPECTOR

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.
● If a drop down list box appears next to the property name, click the
arrow to reveal your alternatives and select a value from the list.
● If a text box with an ellipsis (...) button appears next to the property
name, click the button to reveal a dialog box you can use to define
your setting for the property.

CHANGING PROPERTIES AT RUNTIME

You can set most of the properties for the Crpe 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 Crpe component.
For information on how to set component properties at runtime, refer to
your Delphi documentation. The Crystal Reports Developer’s online
Help contains code examples for each of the Crpe component properties.
Search for the property you are interested in for examples.

The Report Engine Class Library

The Report Engine Class (REC) Library provides object oriented

programming of the Crystal Report Engine in C++. The REC Library is
based on the Microsoft Foundation Class (MFC) Library. The two Report
Engine Class definitions in the REC Library are derived from the MFC
CObject class.
MFC is a widely available, and highly powerful class library originally
designed for use with Microsoft’s C++ development environment (now
known as Visual C++). However, MFC is a complete class library
designed for programming Windows applications and can be used with
most C++ development tools including Borland C++ Development Suite
and Symantec C++.

Chapter 1, Application Development with Crystal Reports 13

 The REC Library is comprised of two primary classes and several
supporting structures. These classes are wrapped around the Crystal
Report Engine API, providing an object oriented approach to
programming the Crystal Report Engine.
NOTE: The REC Library can be used with any available version of the
MFC Library.
The REC Library was installed in the same directory as Crystal Reports
(\CRW by default). You need to add two files to your C++ project to use
the REC Library:

PEPLUS.H
This C++ header file contains the Report Engine class definitions along
with several structure definitions used by the Report Engine classes. You
must #include this file in any code module that will be using the Report
Engine classes.

PEPLUS.CPP
This C++ source code file contains implementations of all of the class
methods for the REC Library classes. This file must be added to your C++
project file in order to use the REC Library. This code is compiled directly
into your Visual C++ project and calls the functions available in the
Crystal Report Engine.

The Report Engine API

As mentioned above, the REC Library classes are wrapped around the
Crystal Report Engine API, and the methods in these classes make direct
calls to the functions in the Report Engine API. For this reason, your
project must include the CRPE32M.LIB Report Engine library. Make sure
CRPE32M.LIB has been added to the list of libraries included with your
C++ project.

The Report Engine Class Library classes

The REC Library consists of two primary classes. The CRPEngine class
controls the entire Report Engine. It is designed so that there should only
be one CRPEngine object in the entire application. The CRPEngine object
contains methods that are common to all print jobs (e.g. SQL connections,
version information, etc.). More importantly, it is responsible for creating
and managing all CRPEJob objects.
The CRPEJob class controls print jobs. A print job is a request for a report
to be processed and printed, previewed, or exported. You do not
construct a CRPEJob object directly; instead, you request a job instance
from the CRPEngine class and receive a pointer to a CRPEJob object. It is
the CRPEJob object that allows you access to the attributes of a print job.

14 Crystal Reports Developer’s Reference

 Both classes are derived from the MFC CObject class and provide all of
the functionality of that class, including runtime class information and
object diagnostic output.
NOTE: For complete descriptions of each of the REC classes, their
respective members, and all supporting structures, refer to the Crystal
Reports Developer’s online Help.

The Report Engine API

The Report Engine API (REAPI) is the most direct method of adding the
Crystal Report Engine to your application project. The Report Engine
itself is a Windows Dynamic Link Library (DLL), and, therefore, exports
its functionality in the form of DLL functions. These functions make up
the Report Engine API.
The Report Engine DLL, CRPE.DLL (16-bit) or CRPE32.DLL (32-bit), is
installed in your \WINDOWS\SYSTEM directory when you install
Crystal Reports. This assures that the DLL is available to any application
on your system that uses the Report Engine.
NOTE: For complete information on distributing Report Engine and other
runtime DLLs with your application, refer to the Crystal Reports Runtime
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 Report Engine API. You may also want to consider
one of the other methods described in this chapter for adding the 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 Report Engine in an application via the REAPI.

Chapter 1, Application Development with Crystal Reports 15

Declarations Crystal Reports provides several source code files that declare the
functions in the REAPI for several popular development languages.
for the Report These files can be found in the Crystal Reports directory (\CRW by
Engine API default) and are ready to be immediately added to your project. The
following REAPI declaration files are available:
● CRPE.H declares all Report Engine functions for C/C++.
● GLOBAL.BAS and GLOBAL32.BAS declare all Report Engine
functions for Visual Basic.
● CRPEDB.H declares several Report Engine functions for Visual
dBASE. Because of limits in the dBASE language, not all Report
Engine functions are available to dBASE programmers. Refer to the
individual function in Crystal Reports Developer’s online Help for
information on dBASE availability.
● CRPE.PAS and CRPE32.PAS declare all Report Engine functions for
Delphi.
NOTE: You can declare functions yourself on an individual basis, but
unless you will only be using a few of the 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.

Using the The REAPI provides two options for processing and producing reports
from within an application:
Report Engine
● a Print-Only link, and
API
● a Custom-Print link.
The Print-Only link is the fastest, easiest method for producing a report
with the 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 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, or 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.

16 Crystal Reports Developer’s Reference

 The first time you use the 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 REAPI, you can expand the reporting functionality with
a Custom-Print link.

Establishing A A Print-Only link is performed using the PEPrintReport function. The

PEPrintReport function provides basic report printing functionality and
Print-Only demonstrates basic techniques for calling Report Engine functions from
Link 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 Crystal Reports
Design Tab), but you can not change them at print time through a Print-
Only link.
NOTE: 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 a Print-Only link, as they are required steps to coding a
Custom-Print link. The rest of this section demonstrates these functions
with a Print-Only link.

PEPrintReport Arguments
PEPrintReport is declared in CRPE.H as follows:
short FAR PASCAL PEPrintReport (
char FAR *reportFilePath,
BOOL toDefaultPrinter,
BOOL toWindow, char FAR *title,
int left, int top,
int width, int height,
DWORD style, HWND parentWindow);

Chapter 1, Application Development with Crystal Reports 17

 The following table describes each argument:

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 toPrinter 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 toPrinter
argument should be set to FALSE.
title The title that you want to appear in the window
title bar. This argument can receive a string
variable or a character array at runtime.
left The position, in screen coordinates, at which
you want the left edge of the Preview window
to appear if the report is being printed to a
window.
top The position, in screen coordinates, at which
you want the top edge of the Preview window
to appear if the report is being printed to a
window.
width The width, in screen coordinates, of your
Preview window, in pixels, if the report is being
printed to a window.
height The height, in screen coordinates, of your
Preview window, in pixels, if the report is being
printed to a window.
style The style setting (as defined in WINDOWS.H).
Style settings can be combined using the bitwise
OR operator. These are standard Windows
styles. Refer to Windows API documentation
for complete information on window styles.
Use 0 for default style settings.
parentWindow Specifies the window handle for the parent
window to be used for this Preview window.

18 Crystal Reports Developer’s Reference

 NOTE: If toDefaultPrinter = True, and if you have specified a printer in
the report using the P RINTER SETUP command, PEPrintReport prints to
the specified printer. Otherwise it prints to the Windows default printer.
If you wish to override both the printer specified in the report and the
Windows default printer, you will need to establish a Custom-Print link
and specify the printer using the PESelectPrinter function.
NOTE: If toPrinter = True, you may enter null values for all of the
remaining parameters except reportFilePath because they apply to
printing to a Preview window only. The title parameter requires a null
string, i.e., “”, while the rest of the parameters will accept 0 (zero).
NOTE: If parentWindow is null, Crystal Reports creates a top level
window. The top left corner specified is relative to the origin of the
screen.
● If parentWindow is the handle of an MDI frame window, Crystal
Reports creates a Preview window that is an MDI child window
with the top left corner relative to the origin of the frame window's
client area.
● If parentWindow is the handle of some other window, Crystal
Reports creates a Preview window that is a child of that window
with the top left corner specified relative to the origin of the parent
window's client area.
NOTE: You can use the Windows constant CW_USEDEFAULT as the
value of left, top, width, and height to put in the default settings.
NOTE: If the Preview window is a top-level window and the window style
is defined as 0 (i.e., the final two parameters in the PEPrintReport call are
0,0) or, if the Preview window is an MDI child window and the window
style is defined as 0, Crystal Reports uses the following default style:
(WS_VISIBLE | WS_THICKFRAME | WS_SYSMENU |
WS_MAXIMIZEBOX | WS_MINIMIZEBOX)
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 a maximize and minimize box.

Example code for a Print-Only link

The first step in actually accessing the Report Engine is to load it into
memory. This can be done just before PEPrintReport is called, when a
dialog box that allows printing opens, or even when your application first
starts.
Once the Report Engine is open, PEPrintReport can be called as a result
of some user action, such as clicking a button on screen, or some internal
application procedure.

Chapter 1, Application Development with Crystal Reports 19

 Finally, close the Report Engine by calling PECloseEngine when you are
all finished with it. If you have several print jobs, do not close the Report
Engine until all print jobs are finished. Opening and closing the Report
Engine uses processor time and should only be performed when
necessary.
The following C code demonstrates a possible message handler for an
application that provides Print-Only link functionality through a button
in a dialog box. Use this code as an example of how to perform a Print-
Only link.
short result;
switch (message)
}
case WM_INITDIALOG:
if (!PEOpenEngine())
; // Handle error
return TRUE;
case WM_DESTROY:
PECloseEngine();
return TRUE;
case WM_COMMAND:
switch (wParam)
{
case IDC_PRINTBUTTON:
result = PEPrintReport (
"boxoffic.rpt",
FALSE, TRUE,
"My Report",
CW_USEDEFAULT,
CW_USEDEFAULT,
CW_USEDEFAULT,
CW_USEDEFAULT,
CW_USEDEFAULT,
hwndParent);
if (result != 0)
return FALSE;
return TRUE;
}
break;
}

20 Crystal Reports Developer’s Reference

Establishing A A more advanced, and more powerful, method of using the Crystal
Report Engine is through a Custom-Print link. Establishing a Custom-
Custom-Print Print link gives you a great deal of control over your reports at runtime.
Link 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 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 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 Crystal Reports Formula
Editor, however, must be added when the report is created in Crystal
Reports. A formula can be edited with the Report Engine, but can not be
added to an existing report from the Report Engine. Design your reports
carefully, and keep this in mind when you create your application.

Coding a custom-print link

There are six required steps to coding a Custom-Print link in your
application. Each uses a different REAPI function. The steps are:
1. Open the Report Engine (PEOpenEngine).
2. Open a print job (PEOpenPrintJob).
3. Set the output destination (PEOutputToPrinter,
PEOutputToWindow, or PEExportTo).
4. Start the print job (PEStartPrintJob).
5. Close the print job (PEClosePrintJob).
6. Close the Report Engine (PECloseEngine).
In addition to these six steps, you can add several optional tasks any time
after Step 2, opening the print job, and before Step 4, starting the print job.
These optional tasks include changing selection formulas, editing report
formulas, selecting export options, and sorting report fields.

Chapter 1, Application Development with Crystal Reports 21

 Some REAPI functions can be called at special times to retrieve
information about the print job or Report Engine. For example,
PEGetVersion retrieves the current version of the Report Engine being
used and can be called at any time, even without the Report Engine being
open. Another example, PEGetJobStatus, can be called after Step 4 to
obtain information about the current status of a job being printed. For
more information on all REAPI functions, refer to the Crystal Reports
Developer’s online Help.
NOTE: The steps described here apply to a single print job. It is possible
to have more than one print job open at once.

1. Open the Report Engine

Example
PEOpenEngine();

Description
This step starts the Crystal Report Engine and prepares it to accept a print
job. The Report Engine must be open before a print job can be established.
You should open the 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 Report Engine, open the 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
Report Engine is already open.
Every time the Report Engine is opened, it should be closed once your
application is finished accessing it (see Close the Report Engine). For
example, if you open the Report Engine when a dialog box is created,
close the Report Engine when that dialog box is destroyed.

2. Open a print job

Example
job = PEOpenPrintJob("BOXOFFIC.RPT");

Description
When you open a print job, the 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.

22 Crystal Reports Developer’s Reference

 To establish a print job, PEOpenPrintJob 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 Close the print job below. 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.

3. Set the output destination

Example
PEOutputToWindow (job, ReportTitle,
CW_USEDEFAULT, CW_USEDEFAULT,
CW_USEDEFAULT, CW_USEDEFAULT, 0, NULL);

Description
The 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
Printing a report to a window requires no other print destination code
other than the function itself.
● PEOutputToPrinter
Printing a report to a printer requires no other print destination code
other than the function itself. However, PESelectPrinter can be used to
select a printer other than the default printer at runtime. The
PESelectPrinter function uses the Windows structure DEVMODE. For
more information on this structure, refer to the Windows SDK.

Chapter 1, Application Development with Crystal Reports 23

 ● PEExportTo
The PEExportTo function works with the PEExportOptions structure
and several DLLs that control a report’s export destination and
format. The information required by PEExportTo can be set in your
code at design time or it can work with options in your application to
allow a user to specify export destination and format. If you would
like to allow your users to set the destination and format of a report
file, but you do not wish to program the interface to do this, use the
PEGetExportOptions function to have the Report Engine provide
dialog boxes that query the user for export information at runtime.

4. Start the print job

Example
PEStartPrintJob(job, TRUE);

Description
This function actually sends the report to the output device indicated in
Step 3. Once PEStartPrintJob is called, the Report Engine begins
generating the report. The 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,
by closing the Report Engine (as in Step 6), or by the user clicking the
Close button. No changes can be made to a print job until it finishes
printing.

5. Close the print job

Example
PEClosePrintJob(job);

Description
Once the print job has completed, it can be closed using PEClosePrintJob.
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.

24 Crystal Reports Developer’s Reference

 6. Close the Report Engine
Example
PECloseEngine();

Description
This function closes the Report Engine entirely. No other Report Engine
functions relating to print jobs may be called once the Report Engine is
closed. Therefore, you should keep the Report Engine open until it is no
longer needed in your application. For example, if the Report Engine is
accessed through a dialog box in your application, you should wait to
close the Report Engine until the dialog box is exited and destroyed.

A sample Custom-Print link

The sample code below has been designed to demonstrate four of the six
basic steps in establishing a custom-print link using the C programming
language. This example is based on the following scenario:
● Using Crystal Reports, you have created a report called ORDER.RPT
and saved it to the C:\CRW directory. This report is a listing of
customer orders, and it is the only report your application will need to
print.
● In your application, you have created a PRINT REPORT MENU
command that opens a Print Report modal dialog box. The dialog box
allows the user to select whether the report is printed to the printer or
printed to a Preview window. If the report is to be printed to the
Preview window, a Boolean variable called ToWindow, declared and
initialized in another section of code not seen here, is given the value
of TRUE. If the report is to just be sent straight to the printer,
ToWindow is given the value FALSE.
● In the Print Report dialog box, there is also a Print button that
initializes the event procedure to generate and print the report. The
Event code section below demonstrates how the custom-print link can
be coded in the Print button event procedure of your application.
● PEOpenEngine is called when the dialog box is created, and
PECloseEngine is called when the dialog box is destroyed. For this
reason, these two steps are not included in the custom-print link that
appears below.

Chapter 1, Application Development with Crystal Reports 25

 The section titled Event code demonstrates the basic custom-print event
procedure. This code includes If statements that check to see if an error
has occurred during the call to the Report Engine. When an error occurs,
you can easily handle the error in a separate routine or function. The
event code below calls the function ReportError whenever an error
occurs. ReportError is not a Report Engine function but is meant simply
as an example of how to handle Report Engine errors. The code for
ReportError appears in the section Error code.

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);
}
if (!bResult)
{
ReportError(hJob);
PEClosePrintJob(hJob);
return;
}
if (!PEStartPrintJob(hJob, TRUE))
{
ReportError(hJob);
}
PEClosePrintJob(hJob);
return;

26 Crystal Reports Developer’s Reference

 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;
}

Code Evaluation
Event code
The following is an evaluation of the sample event code that appears
above.
short hJob; // print job handle
BOOL bResult;
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 Report Engine functions. bResult will be given a TRUE or FALSE
value as the result of several Report Engine calls. Any time bResult
receives a FALSE value, an error has occurred.

Chapter 1, Application Development with Crystal Reports 27

 hJob = PEOpenPrintJob("C:\\CRW\\ORDER.RPT");
This Report Engine call opens the new print job according to the path and
filename of the report that is to be printed. In this example, the report
name is hard-coded in the 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 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 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.
The if else code determines an output destination for the report based on the
user’s earlier decision. The PEOutputToWindow function prepares the Report
Engine to create a Preview window while PEOutputToPrinter directs the
Report Engine to print the report to the default printer. (The printer used by the
Report Engine can be changed with the PESelectPrinter function.) The variable
bResult receives a FALSE value if an error occurs in either function call.

28 Crystal Reports Developer’s Reference

 if (!bResult)
{
ReportError(hJob);
PEClosePrintJob(hJob);
return;
}
Once the appropriate destination function is called, we must verify its
success and report an error if bResult is FALSE. ReportError is our 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. See the Error code section
below for information on processing errors.
NOTE: ReportError is not a Report Engine function, but specific to the code
appearing here; it is meant only as an example handling Report Engine errors.
Since a print job has been opened, we 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.

Chapter 1, Application Development with Crystal Reports 29

 Error code
void ReportError(short printJob)
{
Report Engine error processing can be most efficiently handled by a
separate internal function that is called during a print job. The Event code
evaluated above calls the ReportError function. The code for that function
appears here as an example of how to access and evaluate Report Engine
errors. The error number returned by PEGetErrorCode can be used to
control how your application reacts to different types of Report Engine
errors.
NOTE: The REAPI functions described here, PEGetErrorCode and
PEGetErrorText, are specific to REAPI error handling. For complete
descriptions of these functions, refer to the Crystal Reports Developer’s
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 Report Engine error requires at least four
variables like those above. While only errorCode will be needed to
retrieve the 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
Report Engine Error Codes in the Crystal Reports Developer’s online
Help.
PEGetErrorText ( printJob,
&textHandle,
&textLength );
errorText = (char*)malloc(textLength);
PEGetHandleString(textHandle,
errorText,
textLength);

30 Crystal Reports Developer’s Reference

 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, we 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 Report Engine error messages any way that you find appropriate
for your application.
return;
}
Once error processing is finished, we 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.

Report Engine Several REAPI functions provide information in the form of a variable
length string value or character array. When your program calls an
API Variable REAPI function that produces a variable-length string, the Report Engine
Length Strings 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.
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 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.

Chapter 1, Application Development with Crystal Reports 31

 3. Call PEGetHandleString to copy the string from the handle into the
buffer.
NOTE: PEGetHandleString frees the memory occupied by the string
handle, so you can only call this function once for a given handle.
NOTE: For experienced Windows programmers: text and name handles
are Global Memory Handles for memory segments on the global heap. If
you prefer, you can access these segments using the Windows
GlobalLock, GlobalUnlock, and GlobalFree functions. Contents of name
and text handles are null terminated ASCII strings. You must free the text
handle with GlobalFree when you are done with it. (PEGetHandleString
does this for you, if you use it.)

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
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, but all 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;
PEGetNthSortField ( printJob, sortFieldN,
&nameHandle, &nameLength,
&direction );
/*allocate fieldName buffer*/
fieldName = (char*)malloc(nameLength);
PEGetHandleString ( nameHandle,
fieldName,
nameLength );
/*
** fieldName now contains name
** of field and nameHandle is no

32 Crystal Reports Developer’s Reference

 ** 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).

Code Evaluation
HANDLE nameHandle;
short nameLength;
short direction;
char *fieldName;
Any time you evaluate a function that returns a variable length string,
you will need at least three variables: a handle to the string, a short
integer to hold the length of the string, and a character array or pointer to
a character array. The direction variable in this example will hold the sort
direction and is specific to the PEGetNthSortField function.
It is important to note that although the PEGetNthSortField function is
defined in the Report Engine as accepting a pointer to a handle
(HANDLE*) and a pointer to a short (short*), we do not define
nameHandle and nameLength 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.
PEGetNthSortField ( printJob, sortFieldN,
&nameHandle, &nameLength,
&direction );
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.
/*allocate fieldName buffer*/
fieldName = (char*)malloc(nameLength);
Now that we know the actual length of the field name we are trying to
obtain, we can allocate exactly the right amount of memory to store that
name. The malloc function does this for us.
NOTE: malloc is defined in the C runtime library stdlib.h.

Chapter 1, Application Development with Crystal Reports 33

 PEGetHandleString ( nameHandle,
fieldName,
nameLength );
PEGetHandleString 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 Report Engine functions, experienced programmers may
wish to expand the code to trap errors or handle the string text
differently.
The following is a list of all of the REAPI functions that return variable
length strings:
● PEGetNthSortField
● PEGetNthGroupSortField
● PEGetFormula
● PEGetSelectionFormula
● PEGetGroupSelectionFormula
● PEGetNthParam
● PEGetSQLQuery
● PEGetErrorText

Sample Code There are many topics in the Crystal Reports Developer’s online Help
that provide sample code for using the Report Engine API in C, Visual
Basic, Visual dBASE, and Delphi.
● All topics for individual REAPI functions contain sample calls for
Visual Basic, C, Delphi, and Visual dBASE. (Search for the function by
name in the Crystal Reports Developer’s online Help.)
Other topics that contain useful example code are:
● Establishing a print-only link using PEPrintReport contains sample print-
only link calls for C.
● Coding a custom-print link contains C code which can be modified for a
custom-print link Report Engine call.
● Functions that return variable length strings contains a block of C code
that you can modify and use for calling a function that returns a
variable length string.

34 Crystal Reports Developer’s Reference

Report Engine Several REAPI functions require a structure or user-defined variable type
to be passed as one or more arguments. Some of these functions require
API Structures 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 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 the Crystal
Reports 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, PEExportOptions 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 Report Engine will
automatically provide default values or will request information from the
user.
NOTE: Structure variables cannot be created using Visual dBASE. Report
Engine functions requiring structures as parameters are not available to
dBASE.

Distributing Report Engine Applications

Crystal Reports comes with a free runtime license for any application that
uses the Crystal Report Engine through any of the methods described in
this chapter. When distributing a Report Engine application, you must
also distribute several runtime files required by the Report Engine. These
files are listed in the Runtime File Requirements Help. Be sure to carefully
examine this Help file and distribute the appropriate runtime files with
your application. All runtime files are included under the runtime license
agreement unless otherwise stated.

Chapter 1, Application Development with Crystal Reports 35

Working with subreports

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 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.

Opening the You must first open the primary report using the PEOpenPrintJob
function. When you do this, the program returns a handle to the primary
primary report report.

Retrieving an You must then identify the subreport you want to open. You can do that
using the PEGetNSubreportsInSection and PEGetNthSubreportInSection
interim functions. When you run the PEGetNthSubreportInSection function, the
subreport Report Engine returns an interim, double word handle to the subreport
handle you specify.

Retrieving the Once you have the handle, you need to retrieve the name of the
subreport. You do this using the PEGetSubreportInfo function. When you
subreport name run this function, you pass the double word handle as the
subreportHandle argument. The program retrieves the subreport name
as the name member of the PESubreportInfo structure.

Opening the Now that you have the name of the subreport (the name you assigned the
subreport when you created it in Crystal Reports), you need to open the
subreport and subreport. You do this using the PEOpenSubreport function. When you
retrieving the use this function, you pass the name (or pointer to the name, depending
job handle on your development tool) as the subreportName argument. The
program then opens the specified subreport and returns a job handle.

Running other Once you have the job handle, you can run any of the other Report Engine
functions with the subreport, passing the subreport job handle as the
Report Engine printJob argument.
functions.

36 Crystal Reports Developer’s Reference

Exporting Reports Using the Report Engine API

This topic is only supported by the Professional Edition of Crystal

Reports.
Using the Professional Edition of 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 and
PEGetExportOptions. 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 if you
want your application 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.

A PEExportTo The PEExportTo function uses a structure, PEExportOptions, as part of its

argument list. This structure passes format and destination data to the
overview function.
When you are using the PEExportTo function by itself, you hard code the
format and destination data into the structure. Then, when you issue a
PEStartPrintJob call, 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.
● If you want 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 you are using the PEExportTo function in conjunction with the
PEGetExportOptions function, you run the PEGetExportOptions
function first:

Chapter 1, Application Development with Crystal Reports 37

 ● to retrieve the format and destination data that the user specifies in the
Export dialog box, and
● to pass that data to the PEExportOptions structure (again, part of the
PEExportTo argument list).
Then, when you issue a PEStartPrintJob call, the program exports the
report using the format and destination specified by the user.

PEExportOptio struct PEExportOptions

ns Structure {
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 DLL's 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 DLL's require
// more information, they will prompt the user
// for it. To hard code this information, see
// the note immediately following this
// structure.
char destinationDLLName [PE_DLL_NAME_LEN];
// Each export destination is defined in a DLL.
// This is the name of the DLL for the
// destination you select. From table in
// PEExportTo topic. Requires a null-terminated
// string. Does not need to include drive, path
// or extension. For example, uxddisk is an
// example of a valid destination DLLName.
DWORD destinationType;
// At the present time, each DLL implements
// only one destination. We must specify a type
// here, nonetheless, because the DLL may

38 Crystal Reports Developer’s Reference

 // implement more than one destination someday. See
// the table under PEExportTo for values to enter
// here.
void FAR*destinationOptions;
// Some destinations offer additional options
//(see table in the PEExportTo topic). You can
// set this element to 0. Then, If the DLL's
// require more information, they will prompt
// the user for it. To hard code this
// information, see the note immediately
// following this structure.
WORD nFormatOptionsBytes;
// Set by 'PEGetExportOptions', ignored by
// 'PEExportTo'. Both functions use the same
// structure. PEGetExportOptions uses this
// information in communicating with the
// application. The application needs to know
// how many options bytes are being returned
// because it may need to copy the options.
// PEExportTo expects a filled in structure and
// does not need the byte info because it is
// not going to copy the options. It uses only
// a subset of the structure that does not
// include byte info.
WORD nDestinationOptionsBytes;
// Set by 'PEGetExportOptions',
// ignored by 'PEExportTo'. See comments for
// nFormatOptionsBytes above.
};
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 DLL's 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.

Chapter 1, Application Development with Crystal Reports 39

Considerations The export functions are complex function calls. To avoid errors when
exporting report files from your application, keep the following things in
when using the mind:
export ● In order to use PEExportTo and PEGetExportOptions, you must be
functions using the version of the Print Engine (CRPE.DLL) that came with the
Professional Edition of Crystal Reports. If you have an earlier version
of CRPE.DLL installed on your machine and its earlier in the path, the
program may find it first and not find the export functions. This can
happen particularly if you are upgrading to the Professional Edition
of Crystal Reports from the version of Crystal Reports that was
shipped with Visual Basic Professional Edition. Visual Basic included
an earlier version of CRPE.DLL. Search your disk and delete or
rename earlier versions of CRPE.DLL, or make appropriate
adjustments to your path statement.
● Make sure all format DLL's and destination DLL's are located in the
same directory as CRPE.DLL. Once Windows finds CRPE.DLL, it will
expect all of the DLL files to be in the same directory. Format DLL's
are all UXF*.DLL files and Destination DLL's are all UXD*.DLL files.
As a general rule, it is best to keep all of these files in the \CRW
directory or the directory into which you installed Crystal Reports.
Also, make certain that the PATH statement in your AUTOEXEC.BAT
file includes \CRW.
● The UXF*.H and UXD*.H header files are only necessary when
compiling your application. These files should be copied to the same
directory as your application's source files.

Special Considerations for Visual Basic users

Where to open/ 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
close the general rule, it is always best to open the Report Engine when you open
Report Engine the application and close it when you close the application rather than
using Visual opening and closing on a form. Here is why:

Basic API calls ● When you open and close on a form, the 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 Report Engine when you open
the form, creating a time delay while running your application.
● When you open and close on the application, the Report Engine opens
once, when you start the application, and it stays open as long as the

40 Crystal Reports Developer’s Reference

 application is open. Once the Report Engine is open, you can print a
report as often as you wish without the need to reopen the Report
Engine every time you print.

Embedded When you pass a concatenated string from Visual Basic to the Report
Engine (for example, for a record selection formula), it is important that
quotes in Visual the resulting string has the exact syntax that the Report Engine expects.
Basic calls to You should pay special attention to embedded quotes in concatenated
the Report strings because they are often the source of syntax errors.

Engine Some examples follow. The first shows code with a common embedded
quote syntax error and the last two show code using the correct syntax.

Wrong syntax
VBNameVariable$ = "John"
Recselct$ = "{file.Lastname} = " + VBNameVariable$
This code results in the string:
{file.Lastname} = John
Since John is a literal string, the Formula Checker expects to see it
enclosed in quotes. Without the quotes, the syntax is incorrect.

Correct syntax
VBNameVariable$ = "John"
Recselct$ = "{file.Lastname} = " +
(chr$(39) + VBNameVariable + chr$(39)
This code results in the string:
{file.Lastname} = 'John'
which is the correct syntax for use in a Crystal Reports record selection
formula. This is the syntax you would use if you were entering a selection
formula directly into Crystal Reports.

Also correct syntax

VBNameVariable$ = "John"
Recselct$ = "{file.Lastname} = "
(+ "'" + VBNameVariable + "'"
This code also results in the string:
{file.Lastname} = 'John'
which, again, is the correct syntax.

Chapter 1, Application Development with Crystal Reports 41

Passing dates/ You may want to pass date or date range information from your Visual
Basic application to the Crystal Report Engine for use in formulas,
date ranges in selection formulas, etc. Here is an example showing a way to do it
Visual Basic successfully:
using the 1. Start by opening a print job and assigning the print job handle to a
Report Engine variable:

API calls JobHandle% = PEOpenPrintJob (“C:\CRW\CUSTOMER.RPT”)

2. Create variables that hold the year, month, and day for both the start
of the range and the end of the range.
StartYear$ = 1992
StartMonth$ = 01
StartDay$ = 01
EndYear$ = 1993
EndMonth$ = 12
EndDay$ = 31
3. Now build a string to pass to the record selection formula. This is
done in two steps:
● First, build the starting and ending dates for the date range.
 Assign the starting date string to the variable StrtSelect$.
 Assign the ending date string to the variable EndSelect$.
StrtSelect$ = "{filea.STARTDATE} < Date
((" + StartYear$ + ", " + StartMonth$ + ", "
(+ StartDay$ +")"
EndSelect$ = "{filea.ENDDATE} < Date
((" + EndYear$ + ", " + EndMonth$ +
(", " + EndDay$ +")"
● Second, build the selection formula using the StartSelect$ and
EndSelect$ variables:
Recselect$ = StrSelect$ + " AND " + EndSelect$
4. Once your formula is built, set the record selection formula for the
report:
RetCode% = PESetSelectionFormula
((JobHandle%, RecSelect$)
5. Finally, print the report.
RetCode% = PEStartPrintJob (JobHandle, 1)
RetCode% = PEClosePrintJob (JobHandle, 1)
6. Modify this code to fit your needs.

42 Crystal Reports Developer’s Reference

"Print file When you use the PEOutputToFile call, the Crystal Report Engine will
not print to a file that already exists. If the file name you have specified as
exists" error outputFilePath is already in use by another file, you will get a "Print file
message when exists" error message. To avoid this, you either have to assign a different
printing to file file name as outputFilePath or delete any file that has the same name as the
outputFilePath prior to issuing the call. You can easily delete existing files
in VB by placing code like this prior to your PEOutputToFile call:
NOTE: This call uses the “exists” function that is listed below:
If exists(FileName) Then
Msg = FileName + " already exits.
(OK to overwrite?"
(choice = MsgBox(Msg, 36)
If choice = 6 Then ' The user said yes
Kill FileName
' What follows is code for the exists function
' This function returns True if a given file
' exists, False otherwise
Function exists (f As String) As Integer
Dim n As Integer
On Error GoTo handler
n = FreeFile
' Try to open file for input.
' If successful, file exists
Open f For Input As #n
Close #n
exists = True
Exit Function
handler:
' If we get here the file does not exist
exists = False
Exit Function
End Function

Identifying When you are passing a string to the Report Engine as part of your
custom print link, you may think that you are passing one thing when the
string issues in program, in fact, is passing something entirely different. This can happen
Visual Basic easily, for example, when you are passing a concatenated string that you
links to the 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
Report Engine debugging procedure follows:

Chapter 1, Application Development with Crystal Reports 43

 To identify a string issue (bug)
To identify a string bug, have the program display what it is passing in a
message box. To do so, put a line of code similar to the following
immediately after the call in question:
MsgBox(variablename)
Look at the string that is displayed and make certain that it is exactly what
Crystal Reports expects for a string.
● If the syntax is incorrect, look for errors in the concatenated string you
have built.
● If the syntax is correct, look for other problems that could have caused
the call to fail.
● If you are not sure if the syntax is correct, write down the string from
the message box, enter it in the Crystal Reports Formula Editor, and
click the Check button. If there is an error in the string, the Formula
Checker will identify it for you.

Hard-coded When you assign a string to a structure in Visual Basic, it is necessary to

hard-code a null immediately after the string. For example:
nulls in Visual
myStruct.stringField = "Hello" + CHR$(0)
Basic structures

Retrieving Although Crystal Custom Control (VBX) and Crystal ActiveX Control
(OCX) properties allow you to control many report writing features in
report data your application, you can not retrieve information about a report using
with Visual these properties. For instance, the SelectionFormula property allows you
Basic to add a record selection formula to a report at runtime, or change the
record selection formula that exists in the report. However, if the report
already contains a selection formula, you can not use the
SelectionFormula property to view that formula at runtime. This applies
to all Custom Control and ActiveX control properties. If you need to view
existing report information at runtime, you must use the Report Engine
API to access the Crystal Report Engine.

Additional Sources of Information

In addition to the information provided in this chapter, you will find a

wide-variety of developer topics in Crystal Reports Developer’s online
Help. Many of these topics contain sample code in C, Visual dBASE,
Delphi, and Visual Basic that you can copy directly into your application.
For a list of all developer topics, see Developer’s online Help.

44 Crystal Reports Developer’s Reference

2 ActiveX/VBX Reference

What you will find in this chapter:

Section Codes 46
Crystal ActiveX Control Properties Index 47
PROPERTIES 55
Crystal ActiveX Control Methods Index 129
METHODS 130

Chapter 2, ActiveX/VBX Reference 45

Section Codes

When a section code is required, use the following syntax to supply

the values the program needs in order to generate the code:
section type.group.section number

Section type
Section Section type
Report Header Section REPORTHDR
Page Header Section PAGEHDR
Group Header Section GROUPHDR
Detail Section DETAIL
Group Footer Section GROUPFTR
Report Footer Section REPORTFTR
Page Footer Section PAGEFTR
If the report contains one or more groups and you are specifying a
group section, use an integer to specify the group of interest (the first
group is Group 0, the second is Group 1, and so forth.)
NOTE: If you are specifying the section code for anything other than
a group section, use 0 for this parameter.

Section If an area contains more than one section, use an integer to specify
the section of interest (the first section in an area is Section 0, the
second is Section 1, and so forth.)

Example section Specifying the only (or the first) section in a non-group
codes area
REPORTHDR.0.0
«The first Report Header section.»

Specifying one of several sections in a non-group area

If a report has multiple Detail sections and you want to specify the
fourth Detail section, you can specify that section as
DETAIL.0.3
«The fourth Detail section»

46 Crystal Reports Developer’s Reference

 Specifying the only (or the first) section in a group area.
GROUPHDR.0.0
«The first section in the first group footer area.»

Specifying one of several sections in a group area

GROUPFTR.2.1
«The second section in the third group footer area.»

Crystal ActiveX Control Properties Index

Action
Triggers the printing of the report.

Connect
Logs on to a SQL server or a non-SQL database that is password-
protected (such as a Paradox database).

CopiesToPrinter
Specifies the number of copies to be printed if you are printing to a
printer.

DataFiles
Specifies the location of the database files or tables used in the report.

Destination
Specifies the destination to which your report is to be printed
(Window, Printer, or File).

DetailCopies
Specifies the number of copies of each record in the Details section
that the program is to print.

DialogParentHandle
For a Print window that is an MDI child, specifies the handle for the
parent window.

DiscardSavedData
If data is saved with the specified report, setting this property to 1
(True) discards the data.

Chapter 2, ActiveX/VBX Reference 47

 EMailCCList
Specifies the "CC" list to which you want your e-mail message sent.

EMailMessage
Specifies the message line in your e-mail message.

EMailSubject
Specifies the subject line in your e-mail message.

EMailToList
Specifies the "To" list to which you want your e-mail message directed.

EMailVIMBCCList
Specifies the "Blind CC" list to which you want your e-mail message
copied.

ExchangeFolder
Specifies the Exchange path to export a file, when you want to export
to Microsoft Exchange.

ExchangePassword
Specifies the Exchange password when you want to export to
Microsoft Exchange.

ExchangeProfile
Specifies the Exchange Profile when you want to export to Microsoft
Exchange.

Formulas
Specifies a new string for an existing formula.

GraphData
Sets the data used for a specified graph.

GraphOptions
Sets a number of options for the specified graph.

GraphText
Sets the various text components for the specified graph.

GraphType
Sets the kind of graph used in the selected section in the specified
report.

48 Crystal Reports Developer’s Reference

 GroupCondition
Specifies what kind of change in the Group Condition Field will
trigger the creation of a group.

GroupSelectionFormula
Specifies the groups to be used when printing the report.

GroupSortFields
Specifies the group field(s) that are to be used to sort your data when
the report is printed.

Index
See Visual Basic documentation.

LastErrorNumber
Returns the error code for the last runtime error.

LastErrorString
Returns the error string for the last runtime error.

Left
See Visual Basic documentation.

MarginBottom
Sets the bottom margin for the specified report.

MarginLeft
Sets the left margin for the specified report.

MarginRight
Sets the right margin for the specified report.

MarginTop
Sets the top margin for the specified report.

Name
See Visual Basic documentation.

ParameterFields
Sets parameter field values.

Chapter 2, ActiveX/VBX Reference 49

 Password
Enters the password needed to use database tables on a restricted
Access .mdb file.

PrintDay
Sets the day component of the print date (if different from the actual
date the report is printed).

PrinterCollation
If you specify more than one copy to be printed (using the
PrinterCopies property. PrinterCollation specifies whether or not the
copies will be collated.

PrinterCopies
Sets the number of report copies to be printed.

PrinterDriver
Sets the name of the printer driver that is to print the report.

PrinterName
Sets the name of the printer that is to print the report.

PrinterPort
Sets the name of the printer port that is to print the report.

PrinterStartPage
Sets the first page to be printed.

PrinterStopPage
Sets the last page to be printed.

PrintFileCharSepQuote
Sets the quote character used to enclose alphanumeric field data
when printing to a file using Character Separated format.

PrintFileCharSepSeparator
Sets the character(s) you want to use to separate the fields when
printing to a file using the Character Separated Value format.

PrintFileLinesPerPage
Indicates the number of lines to be printed before the page break.

50 Crystal Reports Developer’s Reference

 PrintFileName
Specifies the name of the file to which the report is to be printed.

PrintFileODBCPassword
Used whenever you want to export in ODBC format, specifies the
Password that you need to connect to the data source.

PrintFileODBCSource
Used whenever you export in ODBC format. Specifies the name of
the data source that you want to export to.

PrintFileODBCTable
Used whenever you want to export in ODBC format, specifies the
name of the table you want to export to in the data source.

PrintFileODBCUser
Used whenever you export in ODBC format, this specifies the User
ID that you need to connect to the data source.

PrintFileType
Specifies the type of the file to which the report is to be printed.

PrintFileUseRptDateFmt
When printing to a file, indicates whether or not the program should
save dates in the same date format (MDY, DMY, etc.) that is used in
the report or instead optimize the dates for the file format you have
selected.

PrintFileUseRptNumberFmt
When printing to a file, indicates whether or not the program should
print numbers in the same format (decimal places, negatives, etc.)
that you have used in the report or instead optimize the numbers for
the file format you have selected.

PrintMonth
Sets the month component of the print date (if different from the
actual date the report is printed).

PrintYear
Sets the year component of the print date (if different from the actual
date the report is printed).

Chapter 2, ActiveX/VBX Reference 51

 ProgressDialog
Turns the progress dialog boxes on or off.

RecordsPrinted
Determines the number of records actually printed.

RecordsRead
Determines the number of records actually read.

RecordsSelected
Determines the number of records selected.

ReportDisplayPage
Indicates which page of a multi-page report is currently being
displayed in the Print window.

ReportFileName
Specifies the report to be printed.

ReportLatestPage
Determines the last page printed in the specified report.

ReportSource
Specifies the report source as a report file, a data control, or a True
Grid data control.

ReportStartPage
Determines the first page printed in the specified report.

SectionFont
Specifies the font for a section.

SectionFormat
Specifies the format for a section.

SectionLineHeight
Specifies the line height for a section.

SectionMinHeight
Sets the minimum section height for the specified report section.

SelectionFormula
Specifies the records to be used when printing the report.

52 Crystal Reports Developer’s Reference

 SessionHandle
Sets the session handle for a user once the UserName and Password
properties have opened an Access .mdb file for use by the report.

SortFields
Specifies the field(s) that are to be used to sort your data when the
report is printed.

SQLQuery
Sets the SQL query string used by the specified report.

Status
Determines the print status for the specified report.

StoredProcParam
Sets the stored procedure parameters when using a report based on
SQL stored procedures.

Top
See Visual Basic documentation.

UserName
Enters the name given to a user for logging on to a protected Access
.MDB file to obtain data files needed by the report.

WindowBorderStyle
Specifies the type of border for the print window.

WindowControlBox
Specifies whether or not the print window is to have a control
(system menu) box in the upper left hand corner when the report is
printed to a window.

WindowControls
Specifies whether or not the print controls are to appear in the Print
window when printing a report to a window.

WindowHeight
Sets the height of the print window when the report is printed to a
window.

Chapter 2, ActiveX/VBX Reference 53

 WindowLeft
Sets the distance, in pixels, that the print window is to appear from
the left edge of the parent window. If the print window is a top level
window, the distance is measured from the left edge of the screen.

WindowMaxButton
Specifies whether or not the print window is to have a maximize
button when the report is printed to a window.

WindowMinButton
Specifies whether or not the print window is to have a minimize
button when the report is printed to a window.

WindowParentHandle
Specifies the handle of the parent window if the print window is to
be the child of another window.

WindowState
Sets the state of the Print window, normal, minimized, or
maximized, when the report is printed to a Print window.

WindowTitle
Specifies the title you want to appear in the print window title bar
when the report is printed to a window.

WindowTop
Sets the distance, in pixels, that the print window is to appear from
the top edge of the parent window. If the print window is a top level
window, the distance is measured from the top edge of the screen.

WindowWidth
Specifies the width of the print window in pixels.

54 Crystal Reports Developer’s Reference

PROPERTIES
Action Property

Description Triggers the printing of the report.

Usage [form.]Report.Action = 1
For example:
CrystalReport1.Action = 1
«Prints the specified report.»

Remarks Set the Action property to 1 in your procedure code

(CrystalReport1.Action = 1) to print the report in response to a user
event.

Data Type Integer

Availability Runtime

Related Report PEStartPrintJob (see Page 613)

Engine Functions

Connect Property

Description Logs on to a SQL server or a password-protected database.

Usage [form.]Report.Connect[=
Name;UserID;Password;DatabaseQualifier$]
For example:
CrystalReport1.Connect = "DSN = Accounting;UID
= 734;PWD = bigboard;DSQ = Administration"

Chapter 2, ActiveX/VBX Reference 55

 «Connects to the "Administration" database on the "Accounting"
server using the user ID #734 and the password "bigboard".»
CrystalReport1.Connect = “dsn=; uid=;
pwd=bigboard; dsq=“
«Connects to a password-protected Paradox database. All that is
being passed is the password “bigboard”»

Remarks Enter the parameters necessary to log on to the SQL server that you
need to be activated for your report.
Parameters should be in the following format:
DSN = name;UID = userID;PWD = password;DSQ =
database qualifier
 Name is the server name,
 userID is the name you have been assigned for logging on to
the SQL server,
 password is the password you have been assigned for
logging on to the SQL server, and
 database qualifier is the database name if your server uses
the database concept.
NOTE: Before you can use this property for an ODBC/SQL database,
you must install the ODBC/SQL driver for whatever SQL database
you are planning to use, and put the Database/BIN location in your
path.
NOTE: This parameter is required only when it is applicable to the
ODBC/SQL driver you are using.

Data Type String

Availability Design Time; Runtime

Related Report PESetNthTableLogOnInfo (see Page 591)

Engine Functions

56 Crystal Reports Developer’s Reference

CopiesToPrinter Property

Description Specifies the number of copies to be printed if you are printing to a

printer, if the value you assign to the Destination property is 1 -
Printer (see Destination Property, Page 59).

Usage [form.]Report.CopiesToPrinter[= NumCopies%]

For example:
CrystalReport1.CopiesToPrinter = 3
«Prints three copies of the specified report.»

Remarks The number you enter must not be a zero or a negative value.

Data Type Integer

Availability Design Time; Runtime

Related Report PEOutputToPrinter (see Page 541)

Engine Functions

DataFiles Property

Description Specifies the location of the database files or tables used in the report.

Usage [form.]Report.DataFiles(ArrayIndex)[=
Location$]
● Enter the file name and path of each database file or table in your
report for which you want to change the location.
● Use a separate line of code for each file for which you want to
change the location.

Chapter 2, ActiveX/VBX Reference 57

 ● The order of files in the array must conform to the order of files in
the report. (You can use Database|Set Location to determine the
order of files in the report.)
● The first file in the report is array index (0), the second file is (1),
etc.
For example, to change the location of the first and third files in a
report (first.dbf and third.dbf) to the c:\new directory, use the
following syntax:
CrystalReport1.DataFiles(0) =
"c:\new\first.dbf"
CrystalReport1.DataFiles(2) =
"c:\new\third.dbf"

Remarks ● DataFiles is an array property that is available at runtime only.

● Use this property if you want to run the report with files in
different locations than specified in the report.
● If you use this property, you do not have to change the locations
of all files in the report. Just make certain that the array index for
each file you do change matches the position of that file in the
report.
● This property is cleared once the print job is printed. If you print a
second time, the program reverts to the locations as originally
specified in the report.

Data Type Array of strings

Availability Runtime

Related Report PESetNthTableLocation (see Page 589)

Engine Functions

58 Crystal Reports Developer’s Reference

Destination Property

Description Specifies the destination to which your report is to be printed

(Window, Printer, File or Mail).

Usage [form.]Report.Destination[= Destination%]

For example:
CrystalReport1.Destination = 0
«Sends the specified report to print to a window.»

Remarks Select one of the following print destinations:

● 0 = Window (sends the report to a print window)
● 1 = Printer (sends the report to a printer)
● 2 = File (prints the report to a disk file for printing at a later time
or for importing into other applications. If you select this
property, you will also have to set the PrintFileName (see Page
93) and PrintFileType (see Page 96) properties.)
● 3 = E-mail via MAPI (sends the report to another person on your
network via MAPI E-mail (Microsoft Mail). The report is attached
to the e-mail letter in the format specified by the PrintFileType
property.)
● 4 = E-mail via VIM (sends the report to another person on your
network via VIM E-mail (cc:Mail). The report is attached to the e-
mail letter in the format specified by the PrintFileType property.)
● 5 = To Notes (sends the report to a Lotus Notes destination)
● 6 = To Exchange Folder (sends the report to a Microsoft Exchange
folder).

Data Type Integer (Enumerated)

Availability Design Time; Runtime

Related Report PEOutputToPrinter (see Page 541)

Engine Functions PEOutputToWindow (see Page 543)
PEExportTo (see Page 451)

Chapter 2, ActiveX/VBX Reference 59

DetailCopies Property

Description Specifies the number of copies of each record in the Details section
that the program is to print.

Usage [form.]Report.DetailCopies[= NumCopies%]

For example:
CrystalReport1.DetailCopies = 3
«Specifies that three (3) copies of each record in the details section
are to be printed.»

Remarks If DetailCopies is set to a value less than or equal to zero, the value is
ignored and 1 copy of the Detail section of the report is printed.

Data Type Integer

Availability Design Time; Runtime

Related Report PESetNDetailCopies (see Page 580)

Engine Functions

DialogParentHandle Property

Description Specifies the handle of the parent window. The program uses this
handle to determine the window within which it centers any dialog
boxes it displays (progress dialog boxes, parameter field prompt
dialog boxes, and so forth).

Usage [form.]Report.DialogParentHandle = [HWND]

For example:
CrystalReport1.DialogParentHandle = ParentHwnd
«Specifies the handle of the parent for all dialogs the custom control
will display.»

60 Crystal Reports Developer’s Reference

Remarks Does not affect the placement of the Print Window. Print Window
placement is determined by the WindowLeft, WindowTop,
WindowHeight, and WindowWidth properties.

Data Type Long Integer

Availability Runtime only

Related Report PESetDialogParentWindow (see Page 556)

Engine Functions

DiscardSavedData Property

Description If data is saved with the specified report, setting this property to 1
(True) discards the data.

Usage [form.]Report.DiscardSavedData[= TrueFalse%]

For example:
CrystalReport1.DiscardSavedData = 1
«Discards the data saved with the specified report.»

Remarks For TrueFalse% use one of the following values: False = 0, True = 1.

Data Type Integer

Availability Design Time; Runtime

Related Report PEDiscardSavedData (see Page 446)

Engine Functions

Chapter 2, ActiveX/VBX Reference 61

EMailCCList Property

Description Specifies the "CC" list to which you want your e-mail message sent.

Usage [form.]Report.EMailCCList [= CCList$]

For example:
CrystalReport1.EMailCCList = "John Brown; Jane
Doe"
«Sends a CC of the e-mail message to both John Brown and Jane
Doe.»

Remarks ● Applies to both VIM and MAPI.

● Multiple names must be separated by a semicolon.

Data Type String

Availability Design Time; Runtime

Related Report PEExportTo (see Page 451)

Engine Functions

EMailMessage Property

Description Specifies the string you want to appear as the body of your e-mail
message.

Usage [form.]Report.EMailMessage[=Message$]
For example:
CrystalReport1.EMailMessage = "The meeting is
at 4:00"
«Sets "The meeting is at 4:00" as the body of the e-mail message.»

62 Crystal Reports Developer’s Reference

Remarks Applies to both MAPI and VIM.

Data Type String

Availability Design Time; Runtime

Related Report PEExportTo (see Page 451)

Engine Functions

EMailSubject Property

Description Specifies the subject line in your e-mail message.

Usage [form.]Report.EMailSubject[= Subject$]

For example:
CrystalReport1.EMailSubject = "Staff meeting"
«Sets "Staff meeting" as the subject line in an e-mail message.»

Remarks Applies to both MAPI and VIM.

Data Type String

Availability Design Time; Runtime

Related Report PEExportTo (see Page 451)

Engine Functions

Chapter 2, ActiveX/VBX Reference 63

EMailToList Property

Description Specifies the "To" list to which you want your e-mail message
directed.

Usage [form.]Report.EMailToList [=ToList$]

For example:
CrystalReport1.EMailToList = "Jane Doe"
«Makes "Jane Doe" the only name in the "To" list.»

Remarks ● Applies to both MAPI and VIM.

● Multiple names must be separated by a semicolon.

Data Type String

Availability Design Time; Runtime

Related Report PEExportTo (see Page 451)

Engine Functions

EMailVIMBCCList Property

Description Specifies the "Blind CC" list to which you want your e-mail message
copied.

Usage [form.]Report.EMailVIMBCCList [=BCCList$]

For example:
CrystalReport1.EMailVIMBCCList = "John
Jacobs;Jane Doe"
«Makes "John Jacobs" and "Jane Doe" the names for the BCC list.»

64 Crystal Reports Developer’s Reference

Remarks ● Applies to VIM only, not MAPI.
● Multiple names must be separated by a semicolon.
● This property is not available in the 32 bit ActiveX control.

Data Type String

Availability Design Time; Runtime

Related Report PEExportTo (see Page 451)

Engine Functions

ExchangeFolder Property

Description Specifies the Exchange path to export a file, when you want to export
to Microsoft Exchange.

Usage CrystalReport1.ExchangeFolder =
“c:\Microsoft\Exchange\NewRpt.rpt”
«Send the report to file ‘NewRpt’ in subdirectory
\Microsoft\Exchange.»

Remarks This property is new for version 5.0.

Data Type String

Availability Runtime

Related Report PEExportTo (see Page 451)

Engine Functions

Chapter 2, ActiveX/VBX Reference 65

ExchangeProfile Property

Description Specifies the Exchange Profile when you want to export to Microsoft
Exchange.

Usage CrystalReport1.ExchangeProfile = “James Adrews”

«Specifies ‘James Andrews’ as the Exchange Profile.»

Remarks This property is new for version 5.0. Usually your profile is your
name.

Data Type String

Availability Runtime

Related Report PEExportTo (see Page 451)

Engine Functions

ExchangePassword Property

Description Specifies the Exchange password when you want to export to

Microsoft Exchange.

Usage CrystalReport1.ExchangePassword = “pickle”

«The Exchange password is ‘pickle’.»

Remarks This property is new for version 5.0.

Data Type String

Availability Runtime

66 Crystal Reports Developer’s Reference

Related Report PEExportTo (see Page 451)
Engine Functions

Formulas Property

Description Specifies a new string for an existing formula.

Usage [form.]Report.Formulas(ArrayIndex)[=
"FormulaName= FormulaText"]
Enter the formula name and the string that you want to replace the
existing string for each formula that you want to change in your
report.
For example, to change a formula @COMMISSION to
{file.SALES}*.1, and a second formula @TOTAL to {file.SALES} +
{file.COMMISSION}, enter the following:
CrystalReport1.Formulas(0) = "COMMISSION=
{file.SALES} * .1"
CrystalReport1.Formulas(1) = "TOTAL=
{file.SALES} + {file.COMMISSION}"

Remarks ● Formulas is an array property that is available at runtime only.

● Use a separate line of code for each formula you want to change.
● Change only those formulas that you want to change.
● The first formula you change must be assigned array index (0),
the second must be assigned array index (1), etc.
● The new formula string must conform to Crystal Reports syntax
requirements.
● This property is cleared once the print job is printed. If you print a
second time, the program reverts to the formulas as originally
specified in the report.
NOTE: Spaces are significant in formula names. For this reason, the
equal sign must follow the formula name with no intervening spaces.
NOTE: The @ sign is not used when designating a formula name in
this property.

Chapter 2, ActiveX/VBX Reference 67

 NOTE: You cannot use this property to create new formulas. You can
only use it to change existing formulas.

Data Type Array of strings

Availability Runtime

Related Report PESetFormula (see Page 563)

Engine Functions

GraphData Property

Description Sets the data used for a specified graph.

Usage [form.]Report.GraphData(ArrayIndex%)
[= sectionCode; graphNum; row; col;
field ;direction$]
For example:
CrystalReport1.GraphData(0)= "GH1; 1; GROUP1;
GROUP2; 0; COLANDROW"
«The value in Group 1 is used for the rows of the graph, the value
in Group 2 is used for the columns of the graph, the first
summarized field added to the report is used to set the value of
the risers of the graph, and values in both columns and rows are
used to create the graph.»

Remarks 1. With GraphData, you can specify changes to one or more graphs
at runtime. Those changes then take place sequentially when
you make the "Action=1" call.
The array index value for GraphData simply specifies the
sequence number for the change. Thus:
CrystalReport1.GraphData(0) = "GH1; 3; Group1;
Group2; 666; COLANDROW"

68 Crystal Reports Developer’s Reference

 when making changes to one graph only, but
CrystalReport1.GraphData(0) = "HEADER; 3;
Group1; Group2; 666; COLANDROW"
CrystalReport1.GraphData(1) = "GH1; 3; Group1;
Group2; 666; COLANDROW"
when making changes to more than one graph.
2. Use the following table as a guide in supplying the required
values for this property:

Parameter Description Expected value

sectionCode Specifies the section in Please refer to the
which you want to modify section code table,
a graph. Page 46.
graphNum The number of the graph Graphs in a section
within the section you are numbered,
want to modify. starting with zero,
left to right first,
then top to bottom.
row The Group number in the GROUP1,
report used to create rows GROUP2,
in the graph. GROUP3, . . .,
GROUP9
col The Group number in the GROUP1,
report used to create GROUP2,
columns in the graph. GROUP3, . . .,
GROUP9
field The summarization field The first summary
containing values to be field added to a
used as the value of each report is
riser in the graph. numbered 0, the
second is
numbered 1, etc.
direction Whether the values in the ROWS, COLS,
rows, the columns, or ROWANDCOL, or
both are used to create the COLANDROW
graph.

Data Type Array of strings

Availability Runtime

Chapter 2, ActiveX/VBX Reference 69

Related Report PESetGraphData (see Page 564)
Engine Functions

GraphOptions Property

Description Sets a number of options for the specified graph.

Usage [form.]Report.GraphOptions(ArrayIndex%) [=
sectionCode; graphNum; fontFace; barDirection;
labelRisers; gridLines; legend; max; min$]
For example:
CrystalReport1.GraphOptions(0) =
"FOOTER;0;Arial;H;T;F;X;max;min"
«Sets the font to Arial, sets horizontal bars, shows a data value on
every riser (labelRisers = T), and toggles the grid lines off in the
first Graph in the Page Footer section.»

Remarks 1. With GraphOptions, you can specify changes to one or more

graphs at runtime. Those changes then take place sequentially
when you make the "Action=1" call. The array index value for
GraphOptions simply specifies the sequence number for the
change. Thus:
CrystalReport1.GraphOptions(0) = "GH1; 1;
Arial; (H; T; F; legend; max; min"
when making changes to one graph only, but
CrystalReport1.GraphOptions(0) = "TITLE; 1
Arial; H; T; F; X; 100; 0"
CrystalReport1.GraphOptions(1) = "TITLE; 1
Arial; H; T; F; X; 100; 0"
when making changes to more than one graph.
2. Use the following chart as a guide in entering the required
property values:

70 Crystal Reports Developer’s Reference

 Parameter Description Values expected
sectionCode Specifies the section in Please refer to the
which you want to modify section code table,
a graph. Page 46.
graphNum Specifies which graph in Graphs in a section
the section you want to are numbered,
modify. starting with zero,
left to right first,
then top to bottom.
fontFace Specifies the font face you Actual name of
want to use for the entire font (e.g., Arial).
graph.
barDirection In a bar graph, specifies H = horizontal, V
the direction in which you = vertical, X = as is
want the graph bars to
appear.
labelRisers Specifies whether or not T= true, F = False,
you want to show the data X = as is
value on every riser
gridLines Specifies whether or not T= true, F = False,
you want to show grid X = as is
lines.
legend Specifies whether or not T= true, F = False,
you want to show a X = as is
legend.
max Specifies the maximum Enter a number.
value you want included
in your graph.
min Specifies the minimum Enter a number.
value you want included
in your graph.

Data Type Array of strings

Availability Runtime

Related Report PESetGraphOptions (see Page 566)

Engine Functions

Chapter 2, ActiveX/VBX Reference 71

GraphText Property

Description Sets the various text components for the specified graph.

Usage [form.]Report.GraphText(ArrayIndex%)[=
sectionCode; graphNum;title; subTitle;
footnote;series;group;x;y;z$]
For example:
CrystalReport1.GraphText(0) = "HEADER;
0;;;;;;new x label; new y label;new z label"
«Resets the x, y, and z labels for the first graph in the Page Header
section.»

Remarks 1. Select your section code from the section code table (see Page
46.)
2. With GraphText, you can specify changes to one or more graphs
at runtime. Those changes then take place sequentially when
you make the "Action=1" call. The array index value for
GraphText simply specifies the sequence number for the change.
Thus:
CrystalReport1.GraphText(0) = " GH1; 1; title
string; subtitle string; footnote string;
series string; group string; x string;y string;
z string"
when making changes to one graph only, but
CrystalReport1.GraphText(0) = "TITLE; 1; title
string; subtitle string; footnote string;
series string; group string; x string;y string;
z string"
CrystalReport1.GraphText(1) = "TITLE; 1; title
string; subtitle string; footnote string;
series string; group string; x string;y string;
z string"
when making changes to more than one graph.
3. title, subTitle, footnote, series, group, x, y, and z are the strings you
want to label the appropriate parts of the graph.

72 Crystal Reports Developer’s Reference

Data Type Array of strings

Availability Runtime

Related Report PESetGraphText (see Page 568)

Engine Functions

GraphType Property

Description Sets the kind of graph used in the selected section in the specified
report.

Usage [form.]Report.GraphType(ArrayIndex%) [=
sectionCode; graphNum; graphType$]
For example:
CrystalReport1.GraphType(0)= "GH1; 0; PIE"
«Specifies a Pie graph as the first graph (graphNum =0) in the
Group Header 1 section.»

Remarks 1. With GraphType, you can specify changes to one or more

graphs at runtime. Those changes then take place sequentially
when you make the "Action=1" call.
The array index value for GraphType specifies the sequence
number for the change. Thus:
CrystalReport1.GraphType(0) = "GH1; 0; PIE"
when making changes to one graph only, but
CrystalReport1.GraphType(0) = "HEADER; 0; PIE"
CrystalReport1.GraphType(1) = "GH1; 0; PIE"
when making changes to more than one graph.
2. Select sectionCode from the section code table, see Page 46.
3. Graph numbers are 0 origin; the first graph in a section is
number 0, the second is number 1, etc.

Chapter 2, ActiveX/VBX Reference 73

 4. Multiple graphs in a section are numbered left to right first, then
top to bottom.
5. Select from the following graph types for the GraphType value
for this property:

For this type of graph Use this code for graphType

Side-by-side SIDEBYSIDE
3-D side-by-side 3DSIDE
Stacked bar STACKEDBAR
3-D stacked bar 3DSTACKED
Percent bar PERCENTBAR
3-D percent bar 3DPERCENT
Line LINE
Area AREA
3-D bars 3DBARS
Pie PIE
Multiple pie MULTIPLEPIE
Weighted pie WEIGHTEDPIE

Data Type Arrays of strings

Availability Runtime

Related Report PESetGraphType (see Page 569)

Engine Functions

GroupCondition Property

Description Specifies what kind of change in the Group Condition Field will
trigger the creation of a group.

Usage [form.]Report.GroupCondition(SequentialIndex%)
[= group; field; condition; sortDirection$]

74 Crystal Reports Developer’s Reference

 For example:
CrystalReport1.GroupCondition(0) =
"GROUP1;{order details.ORDER ID};ANYCHANGE;A"
«Specifies that any change in the ordernum field in Group1 will
trigger a new grouping.»

Remarks Refer to the following tables for parameter values for this property:

Parameter Description Values expected

group The group in which The outermost
you want to set the group on the report
group condition. is GROUP1, the
next group is
GROUP2, etc.
field The name of the Enter the name in
field that triggers a the following
grouping format:
whenever its value {table.FIELDNAM
changes. E}
condition Enter the condition See the tables
that triggers the below.
grouping.
sortDirection The direction in A = Ascending, D =
which groups are Descending
to be sorted.

Date Field Conditions

Condition Condition Code
Daily DAILY
Weekly WEEKLY
Bi-weekly BIWEEKLY
Semi-monthly SEMIMONTHLY
Monthly MONTHLY
Quarterly QUARTERLY
Semi-annually SEMIANNUALLY
Annually ANNUALLY

Chapter 2, ActiveX/VBX Reference 75

 Boolean Field Conditions
Condition Condition Code
To Yes TOYES
To No TONO
Every Yes EVERYYES
Every No EVERYNO
Next Is Yes NEXTISYES
Next Is No NEXTISNO

Condition for all other data types

Any Change ANYCHANGE

Data Type Array of strings

Availability Runtime only

Related Report PESetGroupCondition (see Page 571)

Engine Functions

GroupSortFields Property

Description Specifies the group field(s) that are to be used to sort your data when
the report is printed.

Usage [form.]Report.GroupSortFields(ArrayIndex)
[= "+|-GroupField"]
Enter the group field(s) on which you want your report to be sorted.
For example, assume that you have broken your data into state
groups and had Crystal Reports count the number of customers in
each group. In order to print the group with the highest count first,
then the group with the next highest count, etc. (descending order),
enter a string similar to the following:

76 Crystal Reports Developer’s Reference

 CrystalReport1.GroupSortFields(0) = "-Count
({customer.CUSTOMER ID},{customer.REGION})"

Remarks ● GroupSortFields is an array property available at runtime only.

● Use a separate line of code to specify each group sort field.
● Enter group sort fields in the order that you want them to sort
your report. For example, if you want your report to be sorted
first on group sort field A and then on group sort field B, specify
group sort field A in your first line of code and group sort field B
in your second line of code.
● The first group sort field you specify must be assigned array
index 0, the second group sort field must be assigned array index
1, etc.
● The index values you assign must be continuous; no gaps are
allowed (0,1,2 = OK, 0,1,3 = wrong)
● Array index values must be subscripted in the code immediately
after the property name (i.e., CrystalReport1.GroupSortFields(0)
=).
● If you have specified sort fields for your report at Design Time,
any sort fields you enter here will replace the sort fields in your
report.
● If you do not use this property, the program will use the sorting
instructions that you specified in the report.
● If you want to clear the group sort fields in your report, use an
empty string (CrystalReport1.GroupSortFields(0) = "").
● This property is cleared once the print job is printed. If you print a
second time, the program reverts to the group sort fields as
originally specified in the report.
NOTE: The group sort field entry must follow the sort direction sign
(+ or -) with no intervening space.
NOTE: To find the correct syntax for any group in your report using
Crystal Reports for Visual Basic:
● choose the Formula Field command from the Insert menu,
● enter any formula name in the Insert Formula dialog box when
it appears,
● click the scroll button on the Fields list in the Formula Editor
when it appears, and
● double-click the group field of interest.

Chapter 2, ActiveX/VBX Reference 77

 Crystal Reports enters the group field name in the Formula Text box.
Use the name and syntax from that text box when constructing your
group sort field string.

Data Type Array of strings

Availability Runtime

Related Report PESetNthGroupSortField (see Page 582)

Engine Functions

GroupSelectionFormula Property

Description Specifies the groups to be used when printing the report.

Usage [form.]Report.GroupSelectionFormula
[= "GroupSelectionFormula"]
Enter the group selection formula just as you would enter it in the
Formula Editor. For example, to limit your report to those groups
with a subtotal on the order details.ORDER AMOUNT field less than
$10,000 (with subtotals triggered by changes in the
customer.CUSTOMER ID field), you would enter the following as a
group selection formula:
Sum ({order details.ORDER AMOUNT},
{customer.CUSTOMER ID}) < $10000

Remarks If your group selection formula includes internal quotes, change all
of the internal double quotes to single quotes and then surround the
entire selection formula in double quotes.
NOTE: If you have created a group selection formula in your report
at Design Time, any group selection formula you enter here will be
appended to that group selection formula, connected by an "and".
Thus, your records will be selected based on a combination of the
two formulas.

Data Type String

78 Crystal Reports Developer’s Reference

Availability Design Time; Runtime

Related Report PESetGroupSelectionFormula (see Page 575)

Engine Functions

LastErrorNumber Property

Description Returns the error code for the last runtime error.

Usage [form.]Report.LastErrorNumber
For example:
'If error occurs, go to Error Handler
ErrorHandler:
MsgBox
CrystalReport1.LastErrorNumber
«If an error occurs, this code calls up a message box that displays
the error number.»

Remarks LastErrorNumber is a runtime-only property.

NOTE: LastErrorNumber must come after the Action call in order to
display relevant values. After you have printed your report, you can
refer to this property to get an error number (if any). If there was no
error in printing, LastErrorNumber = 0.

Data Type Integer

Availability Runtime

Related Report PEGetErrorCode (see Page 452)

Engine Functions

Chapter 2, ActiveX/VBX Reference 79

LastErrorString Property

Description Returns the error string for the last runtime error.

Usage [form.]Report.LastErrorString
For example:
'If error occurs, go to Error Handler
ErrorHandler:
MsgBox
CrystalReport1.LastErrorString
«If an error occurs, this code calls up a message box that displays
the error string.»

Remarks LastErrorString is a runtime-only property.

NOTE: LastErrorString must come after the Action call in order to
display relevant values. After you have printed your report, you can
refer to this property to get an error string (if any). If there was no
error in printing, LastErrorNumber = 0.

Data Type String

Availability Runtime

Related Report PEGetErrorCode (see Page 452)

Engine Functions PEGetErrorText (see Page 453)

MarginBottom Property

Description Sets the bottom margin for the specified report.

Usage [form.]Report.MarginBottom[=MarginSetting%]

80 Crystal Reports Developer’s Reference

 For example:
CrystalReport1.MarginBottom = 720
«Sets a 1/2 inch bottom margin for the report (1 inch = 1440
twips).»

Remarks MarginSetting% is the margin you want, in twips. A twip is 1/20th

of a point. There are 72 points and thus 1440 twips in an inch.

Data Type Integer

Availability Design Time; Runtime

Related Report PESetMargins (see Page 576)

Engine Functions

MarginLeft Property

Description Sets the left margin for the specified report.

Usage [form.]Report.MarginLeft[=MarginSetting%]
For example:
CrystalReport1.MarginLeft = 1440
«Sets a 1 inch left margin for the report (1 inch = 1440 twips).»

Remarks MarginSetting% is the margin you want, in twips.

Data Type Integer

Availability Design Time; Runtime

Related Report PESetMargins (see Page 576)

Engine Functions

Chapter 2, ActiveX/VBX Reference 81

MarginRight Property

Description Sets the right margin for the specified report.

Usage [form.]Report.MarginRight[=MarginSetting%]
For example:
CrystalReport1.MarginRight=1440
«Sets a 1 inch right margin for the report (1 inch = 1440 twips).»

Remarks MarginSetting% is the margin you want, in twips.

Data Type Integer

Availability Design Time; Runtime

Related Report PESetMargins (see Page 576)

Engine Functions

MarginTop Property

Description Sets the top margin for the specified report.

Usage [form.]Report.MarginTop[=MarginSetting%]
For example:
CrystalReport1.MarginTop = 720
«Sets a 1/2 inch top margin for the report (1 inch = 1440 twips).»

Remarks MarginSetting% is the margin you want, in twips.

Data Type Integer

82 Crystal Reports Developer’s Reference

Availability Design Time; Runtime

Related Report PESetMargins (see Page 576)

Engine Functions

ParameterFields Property

Description Changes the default value of the specified parameter field. When the
prompting dialog box appears for the parameter field, the value you
specify with this property is the value you’re prompted with.

Usage [form.]Report.PParameterFields(ArrayIndex)[ =
"ParameterName;NewValue"]

Remarks ● This property does not eliminate the prompt by specifying a

current value for the parameter field. You will still be prompted
but the default value in the prompt will be the value you specify.
● Use a separate line of code for each parameter field for which you
want to change the value.
● The order of values in the array must conform to the order of
parameter fields in the report.
● The first parameter field in the report is array index (0), the
second is (1), etc.
For example, to change the value of the first and third parameter
fields in a report (parameter1 and parameter3) to “red” and “blue”
respectively use the following syntax:
CrystalReport1.ParameterFields(0) =
"parameter1;red"
CrystalReport1.ParameterFields(2) =
"parameter2;blue"

Data Type Array of strings

Availability Runtime only

Chapter 2, ActiveX/VBX Reference 83

Related Report PESetNthParameterField (see Page 586)
Engine Functions

ParameterFields Property

Description Changes the default value of the specified parameter field. When the
prompting dialog box appears for the parameter field, the value you
specify with this property is the value you’re prompted with.

Usage [form.]Report.PParameterFields(ArrayIndex)[ =
"ParameterName;NewValue"]

Remarks ● This property does not eliminate the prompt by specifying a

current value for the parameter field. You will still be prompted
but the default value in the prompt will be the value you specify.
● Use a separate line of code for each parameter field for which you
want to change the value.
● The order of values in the array must conform to the order of
parameter fields in the report.
● The first parameter field in the report is array index (0), the
second is (1), etc.
For example, to change the value of the first and third parameter
fields in a report (parameter1 and parameter3) to “red” and “blue”
respectively use the following syntax:
CrystalReport1.ParameterFields(0) =
"parameter1;red"
CrystalReport1.ParameterFields(2) =
"parameter2;blue"

Data Type Array of strings

Availability Runtime only

Related Report PESetNthParameterField (see Page 586)

Engine Functions

84 Crystal Reports Developer’s Reference

Password Property

Description Enters the password needed to use database tables on a restricted

Access .MDB file.

Usage [form.]Report.Password[= Password$]

For example:
CrystalReport1.Password = "dogsncats"
«Enters the password dogsncats.»

Remarks Enter the password you have been assigned.

Data Type String

Availability Runtime

Related Report PESetNthTableSessionInfo (see Page 593)

Engine Functions

PrinterCollation Property

Description If you specify more than one copy to be printed (using the
PrinterCopies property), PrinterCollation specifies whether or not
the copies will be collated.

Usage [form.]Report.PrinterCollation[=CollationCode%]
For example:
CrystalReport1.PrinterCollation = 1
«Collates the copies of the specified report.»

Chapter 2, ActiveX/VBX Reference 85

Remarks Select your CollationCode% value from the following table:

Status Code
Uncollated 0
Collated 1
Default Collation 2

Data Type Integer (Enumerated)

Availability Design Time; Runtime

Related Report PESetPrintOptions (see Page 597)

Engine Functions

PrinterCopies Property

Description Sets the number of report copies to be printed.

Usage [form.]Report.PrinterCopies[=NumCopies%]
For example:
CrystalReport1.PrinterCopies = 3
«Specifies that the program is to print three (3) copies of the
report.»

Remarks The number used for PrinterCopies must not be zero or a negative
value.

Data Type Integer

Availability Design Time; Runtime

86 Crystal Reports Developer’s Reference

Related Report PESetPrintOptions (see Page 597)
Engine Functions

PrinterDriver Property

Description Sets the name of the printer driver that is to print the report.

Usage [form.]Report.PrinterDriver [= DriverName$]

For example:
CrystalReport1.PrinterDriver = "Epson24.drv"
«Sets the printer driver to be the Epson 24 pin driver.»

Remarks The PrinterDriver, PrinterName (see Page 87), and PrinterPort (see
Page 88) properties work together to define the printer that the
report is to be sent to. All three properties must be set in order to
define a new printer. If all three properties are not set, the printer
defined in the report will be used. This may be the user’s default
printer if none has been specified in the report.

Data Type String

Availability Design Time; Runtime

Related Report PESelectPrinter (see Page 554)

Engine Functions

PrinterName Property

Description Sets the name of the printer that is to print the report.

Usage [form.]Report.PrinterName[= PrinterName$]

For example:
CrystalReport1.PrinterName = "Epson LQ-850"
«Specifies the Epson LQ-850 printer.»

Chapter 2, ActiveX/VBX Reference 87

Remarks The PrinterDriver (see Page 87), PrinterName, and PrinterPort (see
Page 88) properties work together to define the printer that the
report is to be sent to. All three properties must be set in order to
define a new printer. If all three properties are not set, the printer
defined in the report will be used. This may be the user’s default
printer if none has been specified in the report.

Data Type String

Availability Design Time; Runtime

Related Report PESelectPrinter (see Page 554)

Engine Functions

PrinterPort Property

Description Sets the port for the specified printer.

Usage [form.]Report.PrinterPort[= PortName$]

For example:
CrystalReport1.PrinterPort= "LPT1"
«Sets the printer port to LPT1.»

Remarks The PrinterDriver (see Page 87), PrinterName (see Page 87), and
PrinterPort properties work together to define the printer that the
report is to be sent to. All three properties must be set in order to
define a new printer. If all three properties are not set, the printer
defined in the report will be used. This may be the user’s default
printer if none has been specified in the report.

Data Type String

Availability Design Time; Runtime

88 Crystal Reports Developer’s Reference

Related Report PESelectPrinter (see Page 554)
Engine Functions

PrinterStartPage Property

Description Sets the first page to be printed.

Usage [form.]Report.PrinterStartPage[= StartPage%]

For example:
CrystalReport1.PrinterStartPage = 7
«Specifies that printing is to begin with Page 7 of the report.»

Remarks If a value less than or equal to 0 is used for PrinterStartPage, the

value is ignored and printing starts with Page 1.

Data Type Integer

Availability Design Time; Runtime

Related Report PESetPrintOptions (see Page 597)

Engine Functions

PrinterStopPage Property

Description Sets the last page to be printed.

Usage [form.]Report.PrinterStopPage[=StopPage%]
For example:
CrystalReport1.PrinterStopPage = 12
«Specifies that the printing is to end with Page 12 of the report.»

Chapter 2, ActiveX/VBX Reference 89

Remarks Use a value of 0 for PrinterStopPage to indicate that printing is to
continue through to the last page.

Data Type Integer

Availability Design Time; Runtime

Related Report PESetPrintOptions (see Page 597)

Engine Functions

PrintDay Property

Description Sets the day component of the print date (if different from the actual
date the report is printed).

Usage [form.]Report.PrintDay[=Day%]
For example:
CrystalReport1.PrintDay = 23
«Sets 23 as the print day.»

Remarks ● Enter a value from 1 to 31.

● The PrintYear (see Page 101), PrintMonth (see Page 101), and
PrintDay properties function together. You must change the
value of all three to change the print date. If you do not change all
three, the print date saved with the report is used. This may be
the current date if a specific date is not saved with the report.

Data Type Integer

Availability Design Time; Runtime

Related Report PESetPrintDate (see Page 595)

Engine Functions

90 Crystal Reports Developer’s Reference

PrintFileCharSepQuote Property

Description Sets the quote character used to enclose alphanumeric field data
when printing to a file using character-separated format.

Usage [form.]Report.PrintFileCharSepQuote[=Quote$]
For example:
CrystalReport1.PrintFileCharSepQuote = "‘"
«Uses the quotation character (‘) to surround values saved in
character-separated format.»

Remarks 1. Applies only when PrintFileType is 5 - Character-separated

values (see PrintFileType Property, Page 96).
2. Applies only when Destination is 2 - File, 3 - E-mail to MAPI, or
4 - E-mail to VIM (see Destination Property, Page 59).
3. If you assign a string to PrintFileCharSepQuote that is longer
than one character, the VBX uses only the first character of that
string. For example, if you assign "quote" to the property, the
VBX will only recognize "q".

Data Type String

Availability Design Time; Runtime

Related Report PEExportTo (see Page 451)

Engine Functions

PrintFileCharSepSeparator Property

Description Sets the character(s) you want to use to separate the fields when
printing to a file using the Character Separated Value format.

Chapter 2, ActiveX/VBX Reference 91

Usage [form.]Report.PrintFileCharSepSeparator
[=Separator$]
For example:
CrystalReport1.PrintFileCharSepSeparator= "@"
«Specifies that the "@" character is to be used for separating field
values.»

Remarks 1. Applies only when PrintFileType is 5 - Character-separated

values (see PrintFileType Property, Page 96).
2. Applies only when Destination is 2 - File, 3 - E-mail to MAPI, or
4 - E-mail to VIM (see Destination Property, Page 59).

Data Type String

Availability Design Time; Runtime

Related Report PEExportTo (see Page 451)

Engine Functions

PrintFileLinesPerPage Property

Description Indicates the number of lines to be printed before the page break. The
default is 60 lines.

Usage CrystalReport1.PrintFileLinesPerPage = 50
«Fifty lines will be printed before a page break.»

Remarks This property is new to version 5.0.

Data Type Integer

Availability Runtime

92 Crystal Reports Developer’s Reference

PrintFileName Property

Description Specifies the name of the file to which the report is to be printed.

Usage [form.]Report.PrintFileName[= FileName$]

For example:
CrystalReport1.PrintFileName =
"c:\crw\cust_rpt.txt"
«Prints the report to a file named "cust_rpt.txt" in the C:\CRW
directory.»

Remarks ● You can double-click this property or click the ellipsis (...) in the
Properties box to call up the Choose Print Filename dialog box. In
that dialog box, select the name of the file and the path to which
you want the program to print the report.
● Select a value for this property only if you are printing to a file, if
the value you assigned to the Destination property is 2 - File (see
Destination Property, Page 59).
NOTE: If you want to specify the PrintFileName at runtime, make
certain that you enclose it in quotes in your code.

Data Type String

Availability Design Time; Runtime

Related Report PEExportTo (see Page 451)

Engine Functions

PrintFileODBCPassword

Description Used whenever you want to export in ODBC format, specifies the
Password that you need to connect to the data source.

Usage [form.]Report.PrintFileODBCPassword[=
Password$]

Chapter 2, ActiveX/VBX Reference 93

 For example:
CrystalReport1.PrintFileODBCPassword =
"merry%%5"
«’merry%%5’ is the name of the password to connect to the data
source.»

Remarks This property is new to version 5.0.

This is only required if the ODBC datasource that you are exporting
to requires a password.

Data Type String

Availability Design Time; Runtime

PrintFileODBCSource

Description Used whenever you export in ODBC format. Specifies the name of
the data source that you want to export to.

Usage [form.]Report.PrintFileODBCSource[=
DataSource$]
For example:
CrystalReport1.PrintFileODBCSource = "pickle"
«’pickle’ is the name of the data source that you want to export
to.»

Remarks This property is new for version 5.0.

Data Type String

Availability Design Time; Runtime

94 Crystal Reports Developer’s Reference

PrintFileODBCTable

Description Used whenever you want to export in ODBC format, specifies the
name of the table you want to export to in the data source.

Usage [form.]Report.PrintFileODBCTable[= TableName$]

For example:
CrystalReport1.PrintFileODBCTable = "Employees"
«’Employees’ is the name of the table in the data source to export
to.»

Remarks This property is new to version 5.0.

Data Type String

Availability Design Time; Runtime

PrintFileODBCUser

Description Used whenever you export in ODBC format, this specifies the User
ID that you need to connect to the data source

Usage [form.]Report.PrintFileODBCUser[= UserID$]

For example:
CrystalReport1.PrintFileODBCUser = "LisaB"
«’LisaB’ is the User ID needed to connect to the data source.»

Remarks This property is new to version 5.0.

Data Type String

Chapter 2, ActiveX/VBX Reference 95

Availability Design Time; Runtime

PrintFileType Property

Description Specifies the type of print file used when printing a report to a file.

Usage [form.]Report.PrintFileType[= FileType%]

For example:
CrystalReport1.PrintFileType = 1
«Prints the report to a file in a tab separated format.»

Remarks Select one of the following print file types if you are printing to a file,
if the value you assigned to the Destination property is 2 - File (see
Destination Property, Page 59).

0 - Record
Record style (columns of values). Does not use commas or
separators. Outputs every record with a fixed field width.

1 - Tab separated
Tab separated values. Presents data in tabular form. Encloses
alphanumeric field data in quotes and separates fields with tabs.

2 - Text
Text style. Saves the data in ASCII text format with all values
separated by spaces. This style looks most like the printed page.

3 - DIF
Saves the data in DIF (data interchange format) format. This
format is often used for the transfer of data between different
spreadsheet programs.

4 - CSV
Comma separated values. Encloses alphanumeric field data in
quotes and separates fields with commas.

5 - Character Separated
Saves the data as character separated values in ASCII text format.

96 Crystal Reports Developer’s Reference

 All values are separated by a character or characters specified by
the PrintFileCharSepSeparator property (see Page 91).

6 - Tab separated Text

Saves the data in ASCII text format with all values separated by
tabs.

7 - Crystal Reports RPT

Standard Crystal Reports RPT format is used. Most often used for
sending the report to another user via e-mail.

8 - Excel 2.1 XLS

Exports the report as a Microsoft Excel 2.1 Worksheet.

9 - Excel 3.0 XLS

Exports the report as a Microsoft Excel 3.0 Worksheet.

10 - Excel 4.0 XLS

Exports the report as a Microsoft Excel 4.0 Worksheet.

11 - Lotus 1-2-3 WK1

Exports the report as a Lotus 1-2-3 WK1 format worksheet.

12 - Lotus 1-2-3 WK3

Exports the report as a Lotus 1-2-3 WK3 format worksheet.

13 - Lotus 1-2-3 WKS

Exports the report as a Lotus 1-2-3 WKS format worksheet.

14 - Quattro Pro 5.0 WB1 (16 bit only)

Exports the report as a Quattro Pro 5.0 WB1 format file.

15 - RTF
Saves the data in Rich Text Format.

16 - Word for DOS (16 bit only)

Uses the Microsoft Word for DOS format to save the data in the
report.

17 - Word for Windows

Uses the Microsoft Word for Windows format to save the data in
the report.

Chapter 2, ActiveX/VBX Reference 97

 18 - WordPerfect (16 bit only)
Uses WordPerfect format to save the data in the report.

19 - Excel 5
Uses Excel 5 format to save the data in the report.

20 - HTML 3
Uses HTML 3 format to save the data in the report.

21 - HTML Internet Explorer

Uses the Internet Explorer version of HTML to save the data in
the report.

22 - HTML Netscape
Uses the Netscape version of HTML to save the data in the report.

23 - HTML Netscape
Saves the data in ASCII text format, broken into pages.

Data Type Integer (Enumerated)

Availability Design Time; Runtime

Related Report PEExportTo (see Page 451)

Engine Functions

PrintFileUseRptDateFmt Property

Description When printing to a file, indicates whether or not the program should
save dates in the same date format (MDY, DMY, etc.) that is used in
the report or instead, optimize the dates for the file format you have
selected.

Usage [form.]Report.PrintFileUseRptDateFmt[=
TrueFalse%]
For example:
CrystalReport1.PrintFileUseRptDateFmt = 1

98 Crystal Reports Developer’s Reference

 «Specifies that the program should print dates in the same format
as used in the report.»

Remarks 1. Applies only when PrintFileType is 0 - Record, 1 - Tab-

separated, 3 - Data Interchange Format (DIF), 4 - CSV, or 5 -
Character-Separated.
2. Applies only when Destination is 2 - File, 3 - E-mail to MAPI, or
4 - E-mail to VIM (see Destination Property, Page 59).
3. For TrueFalse%, use one of the following values: False = 0, True
= 1.

Data Type Integer

Availability Design Time; Runtime

Related Report PEExportTo (see Page 451)

Engine Functions

PrintFileUseRptNumberFmt Property

Description When printing to a file, indicates whether or not the program should
print numbers in the same format (decimal places, negatives, etc.)
that you have used in the report or instead, optimize the numbers for
the file format you have selected.

Usage [form.]Report.PrintFileUseRptNumberFmt
[=TrueFalse%]
For example:
CrystalReport1.PrintFileUseRptNumberFmt = 1
«Specifies that the program should print numbers in the same
format as used in the report.»

Remarks 1. Applies only when PrintFileType is 0 - Record, 1 - Tab-

separated, 3 - Data Interchange Format (DIF), 4 - CSV, or 5 -
Character-Separated

Chapter 2, ActiveX/VBX Reference 99

 2. Applies only when Destination is 2 - File, 3 - E-mail to MAPI, or
4 - E-mail to VIM (see Destination Property, Page 59).
3. For TrueFalse%, use one of the following values: False = 0, True = 1.

Data Type Integer

Availability Design Time; Runtime

Related Report PEExportTo (see Page 451)

Engine Functions

PrintReport Method

Description PrintReport triggers the printing of the report.

Usage [form.]Report.PrintReport
For example:
Result% = CrystalReport1.PrintReport
«Prints the specified report.»

Remarks ● PrintReport returns a result code, 0 if the call is successful, an

error code in the 20XXX range if it fails.
● You can also print a report using the Action property. If
something goes wrong, however, you get a runtime error that
will terminate your application. For this reason, you will need to
set up an error handler.

Availability Runtime

Related Report PEStartPrintJob (see Page 613)

Engine Functions

100 Crystal Reports Developer’s Reference

PrintMonth Property

Description Sets the month component of the print date (if different from the
actual date the report is printed).

Usage [form.]Report.PrintMonth[= Month%]

For example:
CrystalReport1.PrintMonth= 7
«Sets July as the print month.»

Remarks ● Enter a value from 1-12 where January = 1, and December = 12.
● The PrintYear (see Page 101), PrintMonth, and PrintDay (see Page
90) properties function together. You must change the value of all
three to change the print date. If you do not change all three, the
print date saved with the report is used. This may be the current
date if a specific date is not saved with the report.

Data Type Integer

Availability Design Time; Runtime

Related Report PESetPrintDate (see Page 595)

Engine Functions

PrintYear Property

Description Sets the year component of the print date (if different from the actual
date the report is printed).

Usage [form.]Report.PrintYear[=Year%]
For example:
CrystalReport1.PrintYear = 1994
«Sets the year component of the print date to 1994.»

Chapter 2, ActiveX/VBX Reference 101

Remarks ● Enter the print year as a four-digit number.
● The PrintYear, PrintMonth (see Page 101), and PrintDay (see Page
90) properties function together. You must change the value of all
three to change the print date. If you do not change all three, the
print date saved with the report is used. This may be the current
date if a specific date is not saved with the report.

Data Type Integer

Availability Design Time; Runtime

Related Report PESetPrintDate (see Page 595)

Engine Functions

ProgressDialog Property

Description Enables/disables the display of the Progress dialog box. The

Progress dialog box displays the progress of the report when it is
running (records read, records selected, and so forth).

Usage [form.]Report.ProgressDialog[= {True|False}]

For example:
CrystalReport1.ProgressDialog = False
«Turns off the Progress dialog box that usually appears during
exporting or printing.»

Remarks Use this property to indicate whether or not a progress dialog box
should be displayed while the report is printed or exported. This
property is set to True by default.

Data Type Boolean

Availability Design Time; Runtime

102 Crystal Reports Developer’s Reference

Related Report PEEnableProgressDialog (see Page 447)
Engine Functions

RecordsPrinted Property

Description Determines the number of records actually printed.

Usage [form.]Report.RecordsPrinted
For example:
Printed& = CrystalReport1.RecordsPrinted
«Fetches the number of records printed and stores it in the Printed
variable.»

Remarks If the report being printed contains one or more group selection
formulas, the value returned by RecordsPrinted (see Page 103)
maybe significantly less than the value returned by RecordsSelected.
Otherwise, this value should equal RecordsSelected (see Page 104).

Data Type Long

Availability Runtime

Related Report PEGetJobStatus (see Page 471)

Engine Functions

RecordsRead Property

Description Determines the number of records actually processed.

Usage [form.]Report.RecordsRead
For example:
Read% = CrystalReport1.RecordsRead

Chapter 2, ActiveX/VBX Reference 103

 «Fetches the number of records read and saves it in the Read
variable.»

Remarks If the Crystal Report Engine generates a SQL query to obtain data
from a SQL database when the report is printed, RecordsRead will
only return the number of records received by the Report Engine
from the query. This value may be significantly smaller than the
number of records actually in the SQL database table.

Data Type Long

Availability Runtime

Related Report PEGetJobStatus (see Page 471)

Engine Functions

RecordsSelected Property

Description Determines the number of records selected for inclusion in the report
out of the total number of records read.

Usage [form.]Report.RecordsSelected
For example:
Selected& = CrystalReport1.RecordsSelected
«Fetches the number of records selected and saves it in the
Selected variable.»

Remarks RecordsSelected will return a value anywhere between zero and the
value returned by RecordsRead (see Page 103). The value returned
by RecordsSelected depends on the queries and selection formulas
set up in the report.

Data Type Long

Availability Runtime

104 Crystal Reports Developer’s Reference

Related Report PEGetJobStatus (see Page 471)
Engine Functions

ReportDisplayPage Property

Description Indicates which page of a multi-page report is currently being

displayed in the print window.

Usage [form.]Report.ReportDisplayPage
For example:
Result% = CrystalReport1.ReportDisplayPage
«Fetches the number of the displayed page and stores it in the
Result variable.»

Data Type Integer

Availability Runtime

Related Report PEGetJobStatus (see Page 471)

Engine Functions

ReportFileName Property

Description Specifies the report to be printed.

Usage [form.]Report.ReportFileName[= ReportName$]

For example:
CrystalReport1.ReportFileName =
"c:\crw\company.rpt"
«Prints the report named "company.rpt" that is located in the
C:\CRW directory.»

Chapter 2, ActiveX/VBX Reference 105

Remarks You can double-click this property or click the ellipsis (...) in the
Properties box to call up the Choose Report File dialog box. In that
dialog box, select the name and path of the report you want the
program to print in response to a CRW Custom Control event.
NOTE: If you want to specify the ReportFileName at runtime, make
certain that you enclose it in quotes in your code.

Data Type String

Availability Design Time; Runtime

Related Report PEOpenPrintJob (see Page 537)

Engine Functions

ReportLatestPage Property

Description Determines the last page printed in the specified report.

NOTE: ReportLatestPage will only contain the last page number after
calling CrystalReport1.PageCount

Usage [form.]Report.ReportLatestPage
For example:
Latest% = CrystalReport1.ReportLatestPage
«Fetches the number of the last page printed and stores it in the
Latest variable.»

Data Type Integer

Availability Runtime

Related Report PEGetJobStatus (see Page 471)

Engine Functions

106 Crystal Reports Developer’s Reference

ReportSource Property

Description Specifies the source of the report as a report file, a Visual Basic data
control, or a True Grid data control.

Usage CrystalReport1.ReportSource = 3
«Specifies the report source as the Visual Basic data control.»

Data Type Integer

Availability Design Time and Runtime

ReportStartPage Property

Description Determines the first page printed in the specified report.

Usage [form.]Report.ReportStartPage
For example:
StartPage% = CrystalReport1.ReportStartPage
«Fetches the number of the first page printed and stores it in the
StartPage variable.»

Data Type Integer

Availability Runtime

Related Report PEGetJobStatus (see Page 471)

Engine Functions

Chapter 2, ActiveX/VBX Reference 107

SectionFont Property

Description Sets the font for one or more sections in the specified report.

Usage [form.]Report.SectionFont(SequentialIndex%)[=
sectionCode; fontName; size; italic;
bold;underline;strikethru$]
For example:
CrystalReport1.SectionFont(0)="Footer;Arial;12;
N;N;N;Y"
«Sets the font for the footer section to 12 point, Arial,
strikethrough.»

Remarks With SectionFont, you can specify changes to one or more sections at
runtime. Those changes then take place sequentially when you make
the "Action=1" call.
The array index value for SectionFont simply specifies the sequence
number for the change. Thus:
CrystalReport1.SectionFont(0)=
"DETAIL;Arial;12;N;N;N;Y"
when making changes to the DETAIL section only, but
CrystalReport1.SectionFont(0) =
"HEADER;Arial;12;N;N;N;Y"
CrystalReport1.SectionFont(1) =
"DETAIL;Arial;12;N;N;N;Y"
when making changes to more than one section.
Use the following table as a guide in supplying the required
values for this property:

Parameter Data type Value expected

fontName string The actual font
name, e.g. Arial or
Helvetica.
size number The size of the font
in points (e.g., 12 or
16).

108 Crystal Reports Developer’s Reference

 Parameter Data type Value expected
italic character T = true, F = False,
X = as is*
bold character T = true, F = False,
X = as is*
underline character T = true, F = False,
X = as is*
strikethru character T = true, F = False,
X = as is*
*X (as is) uses the value saved with the report.

Data Type Array of strings

Availability Runtime

Related Report PESetFont (see Page 557)

Engine Functions

SectionFormat Property

Description Sets the format for one or more sections in the specified report.

Usage [form.]Report.SectionFormat(SectionArrayIndex%)
[= sectionCode; visible; newPageBefore;
newPageAfter; keepTogether;
SuppressBlankSection; resetPageNAfter;
printAtBottomOfPage; underlaySection;
backgroundColor]
For example:
CrystalReport1.SectionFormat(0)=
"GH2;F;X;X;X;X;X;X;X;255.0.0"
«Hides the Group Header 2 section (visible = F) and changes the
background color to red while maintaining default settings for all
other switches.»

Chapter 2, ActiveX/VBX Reference 109

Remarks With SectionFormat, you can specify changes to one or more sections
at runtime. Those changes then take place sequentially when you
make the "Action=1" call. The sequential index value for
SectionFormat simply specifies the sequence number for the change.
Thus:
CrystalReport1.SectionFormat(0)=
"DETAIL;T;F;F;X;X;X;X;X;255.0.0"
when making changes to the DETAIL section only, but
CrystalReport1.SectionFormat(0) =
"HEADER;T;F;F;X;X;X;X;X;255.0.0"
CrystalReport1.SectionFormat(1) =
"DETAIL;T;F;F;X;X;X;X;X;255.0.0"
when making changes to more than one section.
Use the following table as a reference when entering parameter
values for this property:

Parameter Expected value

Visible T = true, F = False, X = as is*
newPageBefore T = true, F = False, X = as is*
newPageAfter T = true, F = False, X = as is*
keepTogether T = true, F = False, X = as is*
suppressBlank T = true, F = False, X = as is*
resetPageNAfter T = true, F = False, X = as is*
printAtPageBottom T = true, F = False, X = as is*
underlaySection T = true, F = False, X = as is*
backgroundColor Supply a RGB (Red,Green,Blue) value
in the following format
<R>.<G>.<B> where R, G, and B are each integers
with a range from 0 to 255. For
example
189.210.100 If you do not want to change the
color, do not place anything in this
parameter.

* X (as is) uses the settings saved with the report.

Data Type Arrays of strings

Availability Runtime

110 Crystal Reports Developer’s Reference

Related Report PESetSectionFormat (see Page 600)
Engine Functions

SectionLineHeight Property

Description Specifies the line height in twips. A twip is 1/1440 inch; there are 20
twips in a point.

Usage [form.]Report.SectionLineHeight(SequentialIndex
%)[=sectionCode; line; height; ascent$]
For example:
CrystalReport1.SectionLineHeight(0) = "GH0; 1;
500; 300"
«Sets the line height for the second line in the group header zero
section to a height of 500 twips with an ascent of 300 twips.»

Remarks 1. With SectionLineHeight, you can specify changes to one or more

sections at runtime. Those changes then take place sequentially
when you make the "Action=1" call. The sequential index value
for SectionLineHeight simply specifies the sequence number for
the change. Thus:
CrystalReport1.SectionLineHeight(0)=
"DETAIL;1;500;300"
when making changes to the DETAIL section only, but
CrystalReport1.SectionLineHeight(0) =
"HEADER;1;500;300"
CrystalReport1.SectionLineHeight(1) =
"DETAIL;1;500;300"
when making changes to more than one section.
2. Use the following table as a guide in supplying the required
values for this property:

Chapter 2, ActiveX/VBX Reference 111

 Parameter Explanation
sectionCode Specifies the section code for the report
section(s) for which you want to set a
new line height. See Section Codes, Page
46.
lineN Specifies the line(s) for which you want
to set the line height. Line numbers in a
section are 0 origin: the first line
number is 0, the second is 1, etc.
height Specifies the line height in twips. A
twip is 1/1440 inch; there are 20 twips
in a point.
ascent Specifies the ascent in twips. Ascent is
the distance from the top of the allotted
line space (line height) to the baseline of
the font. The ascent parameter is used to
specify the position of the baseline if
you specify an oversized or undersized
line height. If you set ascent to 0, the
program puts the baseline at the top of
the space; if you set ascent to the same
value as height, the program sets the
baseline at the bottom of the space. For
any other baseline, specify the ascent in
twips.

Data Type Arrays of strings

Availability Runtime

SectionMinHeight Property

Description Sets the minimum section height for the specified report section.

Usage [form.]Report.SectionMinHeight
(SequentialIndex%)[=sectionCode;minHeight$]

112 Crystal Reports Developer’s Reference

 For example:
CrystalReport1.SectionMinHeight(0) = "ALL; 500"
«Sets the minimum height for all sections to 500 twips.»

Remarks With SectionMinHeight, you can specify changes to one or more

sections at runtime. Those changes then take place sequentially
when you make the "Action=1" call.
The array index value for SectionMinHeight simply specifies the
sequence number for the change. Thus:
CrystalReport1.SectionMinHeight(0)=
"DETAIL;500"
when making changes to the DETAIL section only, but
CrystalReport1.SectionMinHeight(0) =
"HEADER;500"
CrystalReport1.SectionMinHeight(1) =
"DETAIL;500"
when making changes to more than one section.
NOTE: Subreports cannot be modified at runtime through the
Custom Controls but they can be using direct calls to the Report
Engine API. If you want to modify subreports at runtime, you will not
be able to use the Custom Controls with your application; you will
have to create a Custom Print Link using the Report Engine API.

Data Type Array of strings

Availability Runtime

Related Report PESetMinimumSectionHeight (see Page 579)

Engine Functions

SelectionFormula Property

Description Specifies the records to be used when printing the report.

Chapter 2, ActiveX/VBX Reference 113

Usage [form.]Report.SelectionFormula[=
SelectionFormula$]
For example:
CrystalReport1.SelectionFormula = "{file.QTY}
> 5"
«Include only those records that have a quantity bigger than 5 in
the {file.Qty} field.»

Remarks ● Enter the selection formula just as you would enter it in the
Formula Editor in Crystal Reports.
● Make certain that you enclose your selection formula in double
quotes.
● If your selection formula includes internal quotes, for example:
{file.STATE} = "CA"
change all of the internal double quotes to single quotes and then
surround the entire selection formula in double quotes as
follows:
"{file.STATE} = 'CA'"
● If you have created a selection formula in your report at Design
Time, any selection formula you enter here will be appended to
that selection formula. Thus, your records will be selected based
on a combination of the two selection formulas.

Data Type String

Availability Design Time; Runtime

Related Report PESetSelectionFormula (see Page 604)

Engine Functions

SessionHandle Property

Description Sets the session handle for a user once the UserName and Password
properties have opened an Access .mdb file for use by the report.

114 Crystal Reports Developer’s Reference

Usage [form.]Report.SessionHandle[= Handle%]

Remarks If you have already opened a Jet session in your Visual Basic
application, you can set this property to be the current session
handle. Otherwise, you will have to use the Password and
UserName properties to establish the Jet session.
For example:
CrystalReport1.SessionHandle = Current-
SessionHandle
«Sets the session handle to the session handle returned elsewhere
in the application and stored in the variable
CurrentSessionHandle.»

Data Type Integer

Availability Runtime

Related Report PESetNthTableSessionInfo (see Page 593)

Engine Functions

SortFields Property

Description Specifies the field(s) that are to be used to sort your data when the
report is printed.

Usage [form.]Report.SortFields(ArrayIndex)[= "{+|-}

SortField"]
Enter the fields on which you want the data in your report to be
sorted.
For example:
To sort an order database alphabetically by customer, and then by
order date, you can enter code similar to the following:

Chapter 2, ActiveX/VBX Reference 115

 CrystalReport1.SortFields(0) =
"+{orders.CUSTOMER}"
CrystalReport1.SortFields(1) =
"+{orders.ORDERDATE}"

Remarks ● SortFields is an array property available only at runtime.

● Use a separate line of code to specify each sort field.
● Enter sort fields in the order that you want them to sort your
report. For example, if you want your report to be sorted first on
field A and then on field B, specify sort field A in your first line of
code and sort field B in your second line of code.
● The sort field you specify must be assigned array index 0, the
second sort field must be assigned array index 1, etc.
● The index values you assign must be continuous; no gaps are
allowed (0,1,2 = OK, 0,1,3 = wrong)
● Array index values must be subscripted in the code immediately
after the property name (i.e., CrystalReport1.SortFields(0) =).
● If you have specified sort fields for your report at Design Time,
any sort fields you enter here will replace the sort fields in your
report.
● If you do not use this property, the program will use the sorting
instructions that you specified in the report.
● If you want to clear the sort fields in your report, use an empty
string (CrystalReport1.SortFields(0) = "").
● Enclose field names in braces.
● Sort fields can be database fields or formula fields. If you sort on a
formula field, use the @ sign before the formula name (i.e.,
@FORMULANAME).

Data Type Array of strings

Availability Runtime

Related Report PESetNthSortField (see Page 587)

Engine Functions

116 Crystal Reports Developer’s Reference

SQLQuery Property

Description Sets the SQL query string used by the specified report.

Usage [form.]Report.SQLQuery[=SQLQuery$]
For example:
CrystalReport1.SQLQuery = "SELECT
authors.au_id, authors.au_lname,
authors.au_fname FROM pubs2.dbo.authors
authors WHERE authors.au_lname > ‘Madison’"
«Queries the SQL database to return only the records where the
authors last name falls after Madison alphabetically.»

Remarks ● You may only change the WHERE, FROM and ORDER BY
sections of an SQL query. Although the property requires that
you enter the entire SQL query, the SELECT section must not be
different from the original query in the report.
● To change the ORDER BY clause, you must place a carriage
return and linefeed characters after the WHERE clause and before
the ORDER BY clause in this way:
Report1.SQLQuery="SELECT...FROM...WHERE..." +
CHR$(13) + CHR$(10) + "ORDER BY..."
● This property is active only if you are using an SQL or ODBC data
source in your report.

Data Type String

Availability Design Time; Runtime

Related Report PEGetSQLQuery (see Page 520)

Engine Functions PESetSQLQuery (see Page 606)

Chapter 2, ActiveX/VBX Reference 117

Status Property

Description Determines the print status for the specified report.

Usage [form.]Report.Status
For example:
Status% = CrystalReport1.Status
«Fetches the print status and saves it to the Status variable.»

Remarks The Status property will return one of the following values:
● 0 - The report has not been printed or has not finished printing.
● 3 - The report has finished printing.
● 5 - The report has been cancelled by the user.

Data Type Integer

Availability Runtime

Related Report PEGetJobStatus (see Page 471)

Engine Functions

StoredProcParam Property

Description Sets the stored procedure parameters when using a report based on
SQL stored procedures.

Usage [form.]Report.StoredProcParam(Parameter Array

Index%)[= newParameter$]
For example:
CrystalReport1.StoredProcParam(0)="06/14/1989"
«Sets the first stored procedure parameter to the date June 14,
1989.»

118 Crystal Reports Developer’s Reference

Remarks StoredProcParam sets the value of the specified parameter in an SQL
database table that is based on a stored procedure. Pass the value you
wish to set the parameter to as a string. If the parameter expects a
different data type, you still must pass the value as a string. For
example, to pass the integer value 396, use the string "396". The
Crystal Report Engine will handle converting the value into integer
format.

Data Type Arrays of strings

Availability Runtime

Related Report PESetNthParam (see Page 584)

Engine Functions

UserName Property

Description Enters the name given to a user for logging on to a protected Access
.MDB file to obtain data files needed by the report.

Usage [form.]Report.UserName[= Name$]

For example:
CrystalReport1.UserName = "MIS"
«Enters the user name "MIS".»

Remarks ● Enter the name you have been assigned.

● The name must be enclosed in quotes if the variable is being
assigned at runtime.

Data Type String

Availability Runtime

Chapter 2, ActiveX/VBX Reference 119

Related Report PESetNthTableSessionInfo (see Page 593)
Engine Functions

WindowBorderStyle Property

Description Specifies the type of border for the print window.

Usage [form.]Report.WindowBorderStyle[= BorderStyle%]

For example:
CrystalReport1.WindowBorderStyle = 2
«Sets a sizable border style (Style #2) for the print window.»

Remarks Select one of the following border styles for the print window:
● 0 = None (creates a window with no border).
● 1 = Fixed Single (creates a window of a fixed size with a single
line border).
● 2 = Sizeable (creates a window that can be resized by the user).
● 3 = Fixed Double (creates a window of fixed size with a double
line border).
Select a value here only if you are printing to a window, if
Destination = 0 (see Destination Property, Page 59).

Data Type Integer (Enumerated)

Availability Design Time; Runtime

Related Report PEOutputToWindow (see Page 543)

Engine Functions

120 Crystal Reports Developer’s Reference

WindowControlBox Property

Description Specifies whether or not the print window is to have a control

(system menu) box in the upper left hand corner when the report is
printed to a window.

Usage [form.]Report.WindowControlBox[= {True|False}]

For example:
CrystalReport1.WindowControlBox = True
«Specifies that a control box (system menu) is to appear in the
print window.»

Remarks ● Select True if you want the window to contain a control box.
Select False if you do not.
● Select a value here only if you are printing to a window, if
Destination = 0 (see Destination Property, Page 59).

Data Type Integer

Availability Design Time; Runtime

Related Report PEOutputToWindow (see Page 543)

Engine Functions

WindowControls Property

Description Specifies whether or not the print controls are to appear in the print
window when printing a report to a window.

Usage [form.]Report.WindowControls[={True|False}]
For example:
CrystalReport1.WindowControls = True
«Specifies that print controls are to appear in the print window.»

Chapter 2, ActiveX/VBX Reference 121

Remarks ● Select True id you want the print controls to appear in the print
window.
● Select a value here only if you are printing to a window, if
Destination=0 (see Destination Property, Page 59).

Data Type Integer

Availability Design Time; Runtime

Related Report PEShowPrintControls (see Page 612)

Engine Functions

WindowHeight Property

Description Sets the height of the print window when the report is printed to a
window.

Usage [form.]Report.WindowHeight[= Height%]

For example;
CrystalReport1.WindowHeight = 300
● «Sets the height of the print window to 300 pixels.»

Remarks ● If you are not satisfied with the default settings, enter the external
height you want for your print window in pixels. (A standard
VGA monitor is 640 x 480 pixels.)
● Select a value here only if you are printing to a window, if
Destination = 0 (see Destination Property, Page 59).

Data Type Integer

Availability Design Time; Runtime

122 Crystal Reports Developer’s Reference

Related Report PEOutputToWindow (see Page 543)
Engine Functions

WindowLeft Property

Description Sets the distance, in, that the print window is to appear from the left
edge of the parent window. If the print window is a top level
window, then the distance is measured from the left edge of the
screen. (A standard VGA monitor is 640 x 480 pixels.)

Usage [form.]Report.WindowLeft[= Distance%]

For example:
CrystalReport1.WindowLeft = 100
«Sets the left edge of the print window 100 pixels from the left
edge of the screen.»

Remarks ● If you are not satisfied with the default settings, enter the number
of pixels you want between the left edge of the screen and the left
edge of your window.
● Select a value here only if you are printing to a window, if
Destination = 0 (see Destination Property, Page 59).

Data Type Integer

Availability Design Time; Runtime

Related Report PEOutputToWindow (see Page 543)

Engine Functions

WindowMaxButton Property

Description Specifies whether or not the print window is to have a maximize

button when the report is printed to a window.

Chapter 2, ActiveX/VBX Reference 123

Usage [form.]Report.WindowMaxButton[= {True|False}]
For example:
CrystalReport1.WindowMaxButton = False
«Specifies that no Maximize button is to appear in the print
window.»

Remarks ● Select True if you want the window to contain a maximize button.
Select False if you do not.
● Select a value here only if you are printing to a window, if
Destination = 0 (see Destination Property, Page 59).

Data Type Integer

Availability Design Time; Runtime

Related Report PEOutputToWindow (see Page 543)

Engine Functions

WindowMinButton Property

Description Specifies whether or not the print window is to have a minimize

button when the report is printed to a window.

Usage [form.]Report.WindowMinButton[= {True|False}]

For example:
CrystalReport1.WindowMinButton = True
«Specifies that a Minimize button is to appear in the print
window.»

Remarks ● Select True if you want the window to contain a minimize button.
Select False if you do not.
● Select a value here only if you are printing to a window, if
Destination = 0 (see Destination Property, Page 59).

124 Crystal Reports Developer’s Reference

Data Type Integer

Availability Design Time; Runtime

Related Report PEOutputToWindow (see Page 543)

Engine Functions

WindowParentHandle Property

Description Specifies the handle of the parent window if the print window is to
be the child of another window.

Usage [form.]Report.WindowParentHandle[=
ParentHandle%]
For example:
CrystalReport1.WindowParentHandle = Form1.hWnd
«Sets the WindowParentHandle to the handle of Form1. This
specifies that the print window is to be a child of Form1.»

Remarks This is a runtime-only property.

Data Type Integer

Availability Runtime

Related Report PEOutputToWindow (see Page 543)

Engine Functions

Chapter 2, ActiveX/VBX Reference 125

WindowState Property

Description Sets the state of the print window, normal, minimized, or

maximized, when the report is printed.

Usage [form.]Report.WindowState[= State%]

For example:
CrystalReport1.WindowState= 2
«When the report is printed to a Print window, the Print window
appears maximized when opened.»

Remarks Use the following values to set the WindowState property:

● 0 = Normal
The print window appears neither minimized nor maximized. It
appears in a default size and position previously defined by your
application or by Windows.
● 1 = Minimized
The print window appears minimized as an icon close to the
lower left hand corner of the screen. The icon can be restored to
display the window in a normal state.
● 2 = Maximized
The print window is maximized when opened to fill the entire
screen.

Data Type Integer

Availability Design Time; Runtime

Related Report PEOutputToWindow (see Page 543)

Engine Functions

126 Crystal Reports Developer’s Reference

WindowTitle Property

Description Specifies the title you want to appear in the print window title bar
when the report is printed to a window.

Usage [form.]Report.WindowTitle[= Title$]

For example:
CrystalReport1.WindowTitle = "Quarterly
Earnings"
«Sets the title of the print window (the string that appears on the
title bar) to "Quarterly Earnings".»

Remarks ● Make sure that the title is enclosed in quotes.

● Select a value here only if you are printing to a window, if
Destination = 0 (see Destination Property, Page 59).

Data Type String

Availability Design Time; Runtime

Related Report PEOutputToWindow (see Page 543)

Engine Functions

WindowTop Property

Description Sets the distance, in pixels, that the print window is to appear from
the top edge of the parent window. If the print window is a top level
window, then the distance is measured from the top edge of the
screen.

Usage [form.]Report.WindowTop[= Distance%]

Chapter 2, ActiveX/VBX Reference 127

 For example:
CrystalReport1.WindowTop = 100
«Sets the top edge of the print window 100 pixels from the top of
the screen.»

Remarks ● If you are not satisfied with the default setting, enter the number
of pixels you want between the top of the screen and the top of
your window.
● Select a value here only if you are printing to a window, if
Destination = 0 (see Destination Property, Page 59).

Data Type Integer

Availability Design Time; Runtime

Related Report PEOutputToWindow (see Page 543)

Engine Functions

WindowWidth Property

Description Specifies the width of the print window in pixels.

Usage [form.]Report.WindowWidth[= Width%]

For example:
CrystalReport1.WindowWidth = 480
«Specifies a print window 480 pixels wide.»

Remarks ● If you are not satisfied with the default setting, enter the external
width of your window, in pixels.
● Select a value here only if you are printing to a window, if
Destination = 0 (see Destination Property, Page 59).

Data Type Integer

128 Crystal Reports Developer’s Reference

Availability Design Time; Runtime

Related Report PEOutputToWindow (see Page 543)

Engine Functions

Crystal ActiveX Control Methods Index

PageCount
Returns the number of pages in the report.
PageFirst
Displays the first page of the report in the print window.
PageLast
Displays the last page of the report in the print window.
PageNext
Displays the next page of the report in the print window.
PagePrevious
Displays the previous page of the report in the print window.
PageShow
Displays a specific page of the report in the print window.
PageZoom
Sets the magnification factor for the report in the print window to a
value from 25% to 400% of the actual size.
PrinterSelect
Displays the Printer Selection common dialog box which enables the
user to specify a different printer.
PrintReport
Triggers the printing of the report.

Chapter 2, ActiveX/VBX Reference 129

METHODS
PageCount Method

Returns the number of pages in the report.

Usage [form.]Report.PageCount
For example:
NumberofPages = CrystalReport1.PageCount

Remarks PageCount must be called after the Action property to get a valid
page count.

PageFirst Method

Displays the first page of the report in the print window.

Usage [form.]Report.PageFirst
For example:
CrystalReport1.PageFirst

Remarks This method is only valid when the report is printed to a Preview
window.
This method must be called after the Action property.

PageLast Method

Displays the last page of the report in the print window.

Usage [form.]Report.PageLast
For example:
CrystalReport1.PageLast

130 Crystal Reports Developer’s Reference

Remarks This method is only valid when the report is printed to a Preview
window.
This method must be called after the Action property.

PageNext Method

Displays the next page of the report in the print window.

Usage [form.]Report.PageNext
For example:
CrystalReport1.PageNext

Remarks This method is only valid when the report is printed to a Preview
window.
This method must be called after the Action property.

PagePrevious Method

Displays the previous page of the report in the print window.

Usage [form.]Report.PagePrevious
For example:
CrystalReport1.PagePrevious

Remarks This method is only valid when the report is printed to a Preview
window.
This method must be called after the Action property.

PageShow Method

Displays a specific page of the report in the print window.

Usage [form.]Report.PageShow [(PageToShow%)]

For example:

Chapter 2, ActiveX/VBX Reference 131

 CrystalReport1.PageShow (3)
«Shows the third page of the report.»

Remarks This method is only valid when the report is printed to a Preview
window.
This method must be called after the Action property.

PageZoom Method (Active X)

Description Sets the magnification factor for the report in the print window to a
value from 25% to 400% of the actual size.

Usage [form.]Report.PageZoom [(PercentZoomLevel%)]

For example:
CrystalReport1.PageZoom (150)
«Sets the magnification/zoom level to 150% for the current.»

Remarks This method is only valid when the report is printed to a Preview
window.
This method must be called after the Action property.

PrinterSelect Method

Description Displays the Printer Selection common dialog box which enables the
user to specify a different printer.

Usage [form.]Report.PrinterSelect
For example:
CrystalReport1.PrinterSelect

Remarks This method allows you to pick the printer used for printing the
report; this is only valid when reports are printed to a printer.

132 Crystal Reports Developer’s Reference

3 Visual Component Library
Reference

What you will find in this chapter...

TCrpe Component 134
TCrpePrinterSetup Class 134
PROPERTIES 135
METHODS 200
EVENTS 206
TUTORIALS 207

Chapter 3, Visual Component Library Reference 133

TCrpe Component
UCrpe Unit The UCrpe unit contains the declaration for the TCrpe component
and its associated objects.
When you add a component declared in this unit to a form, the unit
is automatically added to the “uses” clause of that form’s unit.
The following items are declared in the UCrpe unit:

TCrpePrinterSetup Class
Unit

UCrpe

Description

Design time; Runtime

By default this is set to False.
This object is used to control whether or not the TCrpe object is to
request printer setup information at Runtime. There is no need to set
PrinterName. PrinterDriver or PrinterPort when this property is
Enabled.

TCrpePrinterSetup There are two Properties supported by the TCrpePrinterSetup object:

Enabled (Page 144) and ReportPrinterSetup (Page 179).
Properties

134 Crystal Reports Developer’s Reference

PROPERTIES
Action Property

Description Triggers the printing of the report.

Usage [form.]Report.Action:=1;
For example:
Crpe1.Action := 1;
«Prints the specified report.»

Remarks Set the Action property to 1 in your procedure code (Crpe1.Action :=

1) to print the report in response to a user event.

Data Type Byte

Availability Runtime

Connect Property

Description Logs on to a SQL server.

Usage [form.]Report.Connect[:=
Name;UserID;Password;DatabaseQualifier];
For example:
Crpe1.Connect := ‘DSN=Accounting; UID=734;
PWD=bigboard; DSQ=Administration’;
«Connects to the "Administration" database on the "Accounting"
server using the user ID #734 and the password "bigboard".»

Chapter 3, Visual Component Library Reference 135

Remarks Enter the parameters necessary to log on to the SQL server that you
need to be activated for your report.
Parameters should be in the following format:
DSN = name;UID = userID;PWD = password;DSQ =
database qualifier
 Name is the server name,
 user ID is the name you have been assigned for logging
on to the SQL server,
 password is the password you have been assigned for
logging on to the SQL server, and
 database qualifier is the database name if your server
uses the database concept.
NOTE: Before you can use this property, you must install the ODBC
or native SQL driver for whatever SQL database you are planning to
use, and put the Database\BIN location in your path.
NOTE: This parameter is required only when it is applicable to the
ODBC or native SQL driver you are using.

Data Type String

Availability Design time; Runtime

CopiesToPrinter Property

Description Specifies the number of copies to be printed if you are printing to a

printer, if the value you assign to the Destination Property=toPrinter
(see Destination Propertey, Page 138).

Usage [form.]Report.CopiesToPrinter[:=NumCopies];
For example:
Crpe1.CopiesToPrinter := 3;
«Prints three copies of the specified report.»

Remarks The number you enter must not be a zero or a negative value.

136 Crystal Reports Developer’s Reference

Data Type Integer

Availability Design time; Runtime

DataFiles Property

Description Specifies the location of the database files or tables used in the report.

Usage [form.]Report.DataFiles(ArrayIndex)[:=Location];
● Enter the file name and path of each database file or table in your
report for which you want to change the location.
● Use a separate line of code for each file for which you want to
change the location.
● The order of files in the array must conform to the order of files in
the report. (You can use Database|Set Location to determine the
order of files in the report.)
● The first file in the report is array index [0], the second file is [1],
etc.
For example, to change the location of the first and third files in a
report (first.dbf and third.dbf) to the c:\new directory, use the
following syntax:
Crpe1.DataFiles[0] := ‘c:\new\first.dbf’;
Crpe1.DataFiles[2] := ‘c:\new\third.dbf’;

Remarks ● DataFiles is an array property that is available at runtime only.

● Use this property if you want to run the report with files in
different locations than specified in the report.
● When using this property, you do not have to change the
locations of all files in the report. Just make certain that the array
index for each file you do change matches the position of that file
in the report.
● This property is cleared once the print job is finished. If you print
a second time, the program reverts to the locations as originally
specified in the report.
NOTE: The DataFilesLocation property overrides any changes you
make using this property.

Chapter 3, Visual Component Library Reference 137

Data Type Array of strings

Availability Runtime

Related Topics
Resetting Array Properties 207
Access Notes Sparse Array Properties 208

DataFilesLocation Property

Description This property is used to set the directory location of the data files at
Runtime.
Use this property when the location of the data files is different than
the report and that all the tables are in the same location.

Usage [form.]Report.DataFilesLocation[:=Location];
For example:
CRPE1.DataFilesLocation:=‘C:\Account’;
«Sets the database location for the whole report.»

Remarks Using this property overrides any changes you make using the
DataFiles[x] property.
This property requires that the table name be the same as
development.

Data Type String

Availability Runtime

Destination Property

Description Specifies the destination to which your report is to be printed

(Window, Printer, File or Email).

138 Crystal Reports Developer’s Reference

Usage [form.]Report.Destination[:=TDestination];
For example:
Crpe1.Destination := toWindow;
«Sends the specified report to a print window.»

Remarks Select one of the following print destinations:

● toWindow
Sends the report to a print window.
● toPrinter
Sends the report to a printer.
● toFile
Prints the report to a disk file for printing at a later time or for
importing into other applications. If you select this property, you
will also have to set the PrintFileName (see Page 170) and
PrintFileType (see Page 170) properties.
● toEMailViaMAPI
Sends the report to another person on your network via MAPI
Email (Microsoft Mail). The report is attached to the Email letter
in the format specified by the PrintFileType (see Page 170)
property.
● toEMailViaVIM
Sends the report to another person on your network via VIM
Email (cc:Mail). The report is attached to the Email letter in the
format specified by the PrintFileType (see Page 170) property.

Data Type TDestination = (toWindow, toPrinter, toFile, toEmailViaMapi,

toEmailViaVIM);

Availability Design time; Runtime

DetailCopies Property

Description Specifies the number of copies of each record in the Details section
that the program is to print.

Usage [form.]Report.DetailCopies[= NumCopies]

Chapter 3, Visual Component Library Reference 139

 For example:
Crpe1.DetailCopies := 3;
«Specifies that three (3) copies of each record in the details section
are to be printed.»

Remarks If DetailCopies is set to a value less than or equal to zero, the value is
ignored and 1 copy of the Detail section of the report is printed.

Data Type Integer

Availability Design Time; Runtime

DialogParentHandle Property

Description Specifies the handle of the parent window. The program uses this
handle to determine the window within which it centers any dialog
boxes it displays (progress dialog boxes, parameter field prompt
dialog boxes, and so forth).

Usage [form.]Report.DialogParentHandle = [HWND]

For example:
Crpe1.DialogParentHandle := ParentHwnd;
«Specifies the handle of the parent for al dialogs the custom
control will display.»

Remarks Does not affect the placement of the Print Window. Print Window
placement is determined by the WindowLeft, WindowTop,
WindowHeight, and WindowWidth properties.

Data Type hWnd

Availability Runtime only

140 Crystal Reports Developer’s Reference

DiscardSavedData Property

Description If data is saved with the specified report, setting this property to True
discards the data.

Usage [form.]Report.DiscardSavedData[:={True|False}];
For example:
Crpe1.DiscardSavedData := True;
«Discards the data saved with the specified report.»

Data Type Boolean

Availability Design time; Runtime

EMailCCList Property

Description Specifies the "CC" list to which you want your e-mail message sent.

Usage [form.]Report.EMailCCList[:=CCList];
For example:
Crpe1.EMailCCList := ‘John Brown; Jane Doe’;
«Sends a CC of the e-mail message to both John Brown and Jane
Doe.»

Remarks ● Applies to both VIM and MAPI.

● Multiple names must be separated by a semicolon.

Data Type String

Availability Design time; Runtime

Chapter 3, Visual Component Library Reference 141

EMailMessage Property

Description Specifies the string you want to appear as the body of your e-mail
message.

Usage [form.]Report.EMailMessage[:=Message];
For example:
Crpe1.EMailMessage := ‘The meeting is at 4:00’;
«Sets "The meeting is at 4:00" as the body of the e-mail message.»

Remarks Applies to both MAPI and VIM.

Data Type String

Availability Design time; Runtime

EMailSubject Property

Description Specifies the subject line in your e-mail message.

Usage [form.]Report.EMailSubject[:=Subject];
For example:
Crpe1.EMailSubject := ‘Staff meeting’;
«Sets "Staff meeting" as the subject line in an e-mail message.»

Remarks Applies to both MAPI and VIM.

Data Type String

Availability Design time; Runtime

142 Crystal Reports Developer’s Reference

EMailToList Property

Description Specifies the "To" list to which you want your e-mail message
directed.

Usage [form.]Report.EMailToList[:=ToList];
For example:
Crpe1.EMailToList := ‘Jane Doe’;
«Makes "Jane Doe" the only name in the "To" list.»

Remarks ● Applies to both MAPI and VIM.

● Multiple names must be separated by a semicolon.

Data Type String

Availability Design time; Runtime

EMailVIMBCCList Property

Description Specifies the "Blind CC" list to which you want your e-mail message
copied.

Usage [form.]Report.EMailVIMBCCList[:=BCCList];
For example:
Crpe1.EMailVIMBCCList := ‘John Jacobs;Jane
Doe’;
«Makes "John Jacobs" and "Jane Doe" the names for the BCC list.»

Remarks ● Applies to VIM only (cc:Mail), not MAPI.

● Multiple names must be separated by a semicolon.

Chapter 3, Visual Component Library Reference 143

Data Type String

Availability Design time; Runtime

UserPrinterSetup.Enabled Property

Description This property is used to enable or disable the UserPrinterSetup

Object.

Usage [form.]Report.UserPrinterSetup.Enabled[:={True|
False}];
For example:
Crpe1.UserPrinterSetup.Enabled:=True;
«Allows the printer settings to be prompted for by the printer
dialog box.»

Remarks Will prompt using a printer dialog when the execute command is
issued.

Data Type Boolean

Availability Design time; Runtime

Execute Property

Description Triggers the printing of a report.

Usage [form.]Report.Execute;
For example:
Crpe1.Execute;

144 Crystal Reports Developer’s Reference

Remarks ● Triggers other events before starting the report.
● Execute should be used in place of the Action Property (see Action
Property, Page 135).

Data Type Boolean

Availability Runtime

Formulas Property

Description Specifies a new string for an existing formula.

Usage [form.]Report.Formulas(ArrayIndex)
[:="FormulaName=FormulaText"];
Enter the formula name and the string that you want to replace the
existing string for each formula that you want to change in your
report.
For example, to change a formula @COMMISSION to
{file.SALES}*.1, and a second formula @TOTAL to {file.SALES} +
{file.COMMISSION}, enter the following:
Crpe1.Formulas[0] := ‘COMMISSION={file.SALES}
* .1’;
Crpe1.Formulas[1] := ‘TOTAL={file.SALES} +
{file.COMMISSION}’;

Remarks ● Formulas is an array property that is available at runtime only.

● Use a separate line of code for each formula you want to change.
● Change only those formulas that you want to change.
● The first formula you change must be assigned array index [0],
the second must be assigned array index [1], etc.
● The new formula string must conform to Crystal Reports syntax
requirements.
● This property is cleared once the print job is printed. If you print a
second time, the program reverts to the formulas as originally
specified in the report.

Chapter 3, Visual Component Library Reference 145

 NOTE: Spaces are significant in formula names. For this reason, the
equal sign must follow the formula name with no intervening spaces.
NOTE: The @ sign is not used when designating a formula name in
this property. You cannot use this property to create new formulas.
You can only use it to change existing formulas.

Data Type Array of strings

Availability Runtime

Related Topics
Resetting Array Properties 207

GraphOptions Property

Description Sets a number of options for the specified graph.

Usage [form.]Report.GraphOptions[ArrayIndex]
[:=‘sectionCode; graphNum; fontFace;
barDirection; labelRisers; gridLines; legend;
max; min’];
For example:
Crpe1.GraphOptions[0] :=
‘Title;0;Arial;V;T;F;F;10;5’;
«Sets the font to Arial, sets vertical bars, shows a data value on
every riser (labelRisers = T), and toggles the grid lines off in the
first Graph in the Title section, turns Legend off with a maximum
of 10 and a minimum of 5 on the Y axis.»

Remarks 1. With GraphOptions, you can specify changes to one or more

graphs at runtime. Those changes then take place sequentially
when you make the "Action:=1" call (see Action Property, Page
135). The array index value for GraphOptions simply specifies
the sequence number for the change. Thus:
Crpe1.GraphOptions[0] := ‘Title; 0; Arial; H;
T; F; legend; max; min’;

146 Crystal Reports Developer’s Reference

 when making changes to one graph only, but
Crpe1.GraphOptions[0] := ‘Title; 0; Arial; H;
T; F; legend; max; min’;
Crpe1.GraphOptions[1] := ‘Title; 1; Arial; H;
T; F; legend; max; min’;
when making changes to more than one graph.
2. Use the following chart as a guide in entering the required
property values:

Parameter Description Values expected

sectionCode Specifies the Please refer to the
section in which section code table
you want to (see Page 46).
modify a graph.
graphNum Specifies which Graphs in a section
graph in the section are numbered,
you want to starting with zero,
modify. left to right first,
then top to bottom.
fontFace Specifies the font Actual name of
face you want to font (e.g., Arial).
use for the entire
graph.
barDirection In a bar graph, H = horizontal, V
specifies the = vertical, X = as is
direction in which
you want the graph
bars to appear.
labelRisers Specifies whether T= true, F = False,
or not you want to X = as is
show the data
value on every
riser.
gridLines Specifies whether T= true, F = False,
or not you want to X = as is
show grid lines.
legend Specifies whether T= true, F = False,
or not you want to X = as is
show a legend.

Chapter 3, Visual Component Library Reference 147

 Parameter Description Values expected
max Specifies the Enter a number.
maximum value
you want included
in your graph.
min Specifies the Enter a number.
minimum value
you want included
in your graph.

Data Type Array of strings

Availability Runtime

Related Topics
Resetting Array Properties 207

GraphText Property

Description Sets the various text components for the specified graph.

Usage [form.]Report.GraphText(ArrayIndex)
[:=sectionCode; graphNum; title; subTitle;
footnote; series; group; x; y; z];
For example:
Crpe1.GraphText[0] := ‘HEADER; 0;;;;;;new x
label; new y label;new z label’;
«Resets the x, y, and z labels for the first graph in the Page Header
section.»

Remarks 1. Select your section code from the section code table (see Page
46).
2. With GraphText, you can specify changes to one or more graphs
at runtime. Those changes then take place sequentially when
you make the "Action := 1" call (see Action Property, Page 135).

148 Crystal Reports Developer’s Reference

 The array index value for GraphText simply specifies the
sequence number for the change. Thus:
Crpe1.GraphText[0] := ‘DETAIL; 1; title string;
subtitle string;footnote string; series string;
group string; x string; y string; z string’;
when making changes to one graph only, but
Crpe1.GraphText[0] := ‘DETAIL 1; title string;
subtitle string; footnote string; series
string; group string; x string; y string; z
string’;
Crpe1.GraphText[1] := ‘HEADER 1; title string;
subtitle string; footnote string; series
string; group string; x string;y string; z
string’;
when making changes to more than one graph.
3. title, subTitle, footnote, series, group, x, y, and z are the strings you
want to label the appropriate parts of the graph.

Data Type Array of strings

Availability Runtime

Related Topics
Resetting Array Properties 207

GraphType Property

Description Sets the kind of graph used in the selected section in the specified
report.

Usage [form.]Report.GraphType(ArrayIndex)
[:=sectionCode; graphNum; graphType];
For example:
Crpe1.GraphType[0] := ‘GH1; 0; PIE’;
«Specifies a Pie graph as the first graph (graphNum :=0) in the
Group Header 1 section.»

Chapter 3, Visual Component Library Reference 149

Remarks 1. With GraphType, you can specify changes to one or more
graphs at runtime. Those changes then take place sequentially
when you make the "Action := 1" call (see Action Property, Page
135). The array index value for GraphType specifies the
sequence number for the change. Thus:
Crpe1.GraphType[0] := ‘DETAIL; 0; PIE’;
when making changes to one graph only, but
Crpe1.GraphType[0] := ‘HEADER; 0; PIE’;
Crpe1.GraphType[1] := ‘DETAIL; 0; PIE’;
when making changes to more than one graph.
2. Select sectionCode from the section code table (see Page 46).
3. Graph numbers are 0 origin; the first graph in a section is
number 0, the second is number 1, etc.
4. Multiple graphs in a section are numbered left to right first, then
top to bottom.
5. Select from the following graph types for the GraphType value
for this property:

For this type of graph Use this code for graphType

Side-by-side SIDEBYSIDE
3-D side-by-side 3DSIDE
Stacked bar STACKEDBAR
3-D stacked bar 3DSTACKED
Percent bar PERCENTBAR
3-D percent bar 3DPERCENT
Line LINE
Area AREA
3-D bars 3DBARS
Pie PIE
Multiple pie MULTIPLEPIE
Weighted pie WEIGHTEDPIE

Data Type Arrays of strings

Availability Runtime

150 Crystal Reports Developer’s Reference

 Related Topics
Resetting Array Properties 207

GroupCondition Property

Description Specifies what kind of change in the Group Condition Field will
trigger the creation of a group.

Usage [form.]Report.GroupCondition(SequentialIndex)
[:= group;field;condition;sortDirection];
For example:
Crpe1.GroupCondition[0] :=
‘GROUP1;{header.ORDERNUM};ANYCHANGE;A’;
«Specifies that any change in the ordernum field in Group1 will
trigger a new grouping.»

Remarks Refer to the following tables for parameter values for this property:

Parameter Description Values expected

group The group in which The outermost
you want to set the group on the report
group condition. is GROUP1, the next
group is GROUP2,
etc.
field The name of the field Enter the name in the
that triggers a following format:
grouping whenever its {file.FIELDNAME}.
value changes. condition. Enter the
condition that
triggers the
grouping.
sortDirection The direction in which A = Ascending,
groups are to be sorted. D = Descending

Date Field Conditions

Condition Condition Code
Daily DAILY
Weekly WEEKLY

Chapter 3, Visual Component Library Reference 151

 Bi-weekly BIWEEKLY
Semi-monthly SEMIMONTHLY
Monthly MONTHLY
Quarterly QUARTERLY
Semi-annually SEMIANNUALLY
Annually ANNUALLY

Boolean Field Conditions

Condition Condition Code
To Yes TOYES
To No TONO
Every Yes EVERYYES
Every No EVERYNO
Next Is Yes NEXTISYES
Next Is No NEXTISNO

Condition for all other data types

Any Change ANYCHANGE

Data Type Array of strings

Availability Runtime only

Related Topics
Resetting Array Properties 207

GroupSelectionFormula Property

Description Specifies the groups to be used when printing the report.

Usage [form.]Report.GroupSelectionFormula(Sequential
Index) [:= GroupSelectionFormula];
Enter the group selection formula just as you would enter it in the
Formula Editor.

152 Crystal Reports Developer’s Reference

 For example:
Crpe1.GroupSelectionFormula[0] := 'Count
({header.AMOUNT}, {header.CUSTNAME}) > 20';
In this code the values in the Amount field are grouped each time the
value in the CustName field changes and the values are counted.
Then this property setting limits the report to only those groups for
which the group count is greater than 20.

Remarks If your group selection formula includes internal quotes, change all
of the internal double quotes to single quotes and then surround the
entire selection formula in double quotes.
NOTE: If you have created a group selection formula in your report
at design time, any group selection formula you enter here will be
appended to that group selection formula, connected by an "and".
Thus, your records will be selected based on a combination of the
two formulas.

Data Type TCrpeString

Availability Design time; Runtime

Related Topics
Resetting TCrpe String Properties 208

GroupSortFields Property

Description Specifies the group field(s) that are to be used to sort your data when
the report is printed.

Usage [form.]Report.GroupSortFields(ArrayIndex)
[:="{+|-}GroupField"];
Enter the group field(s) on which you want your report to be sorted.
For example, assume that you have broken your data into state
groups and had Crystal Reports count the number of customers in
each group. In order to print the group with the highest count first,
then the group with the next highest count, etc. (descending order),
enter a string similar to the following:

Chapter 3, Visual Component Library Reference 153

 Crpe1.GroupSortFields[0] := ‘-Count
({customer.CUSTOMER ID},{customer.REGION})’;

Remarks ● GroupSortFields is an array property available at runtime only.

● Use a separate line of code to specify each group sort field.
● Enter group sort fields in the order that you want them to sort
your report. For example, if you want your report to be sorted
first on group sort field A and then on group sort field B, specify
group sort field A in your first line of code and group sort field B
in your second line of code.
● The first group sort field you specify must be assigned array
index 0, the second group sort field must be assigned array index
1, etc.
● The index values you assign must be continuous; no gaps are
allowed (0,1,2 = OK, 0,1,3 = wrong)
● Array index values must be subscripted in the code immediately
after the property name (i.e., Crpe1.GroupSortFields[0] ).
● If you have specified sort fields for your report at design time,
any sort fields you enter here will replace the sort fields in your
report.
● If you do not use this property, the program will use the sorting
instructions that you specified in the report.
● If you want to clear the group sort fields in your report, use an
empty string (Crpe1.GroupSortFields[0] := ‘’;). Use this only if
you are certain that GroupSortFields has already been set. If
you’re unsure use the Crpe1.Clear property or this code:
If Crpe1.GroupSortFields[0] <> ‘’ then
Crpe1.GroupSortFields[0] := ‘’;
NOTE: The group sort field entry must follow the sort direction sign
(+ or -) with no intervening space.
NOTE: To find the correct syntax for any group in your report using
Crystal Reports for Delphi:
● select Insert|Formula field,
● enter any formula name in the Insert Formula dialog box when
it appears,
● click the scroll button on the Fields list in the Formula Editor
when it appears, and
● double-click the group field of interest.

154 Crystal Reports Developer’s Reference

 Crystal Reports enters the group field name in the Formula Text box.
Use the name and syntax from that text box when constructing your
group sort field string.

Data Type Array of strings

Availability Runtime

Related Topics
Resetting Array Properties 207

LastErrorNumber Property

Description Returns the error code for the last runtime error.

Usage [form.]Report.LastErrorNumber;
For example:
ShowMessage (IntToStr(Crpe1.LastErrorNumber));
«If an error occurs, this code stores the error code as a number.»

Remarks LastErrorNumber is a runtime-only property.

NOTE: LastErrorNumber must come after the Action call (see Action
Property, Page 135) in order to display relevant values. After you
have printed your report, you can refer to this property to get an
error number (if any). If there was no error in printing,
LastErrorNumber = 0.

Data Type Integer

Availability Runtime

LastErrorString Property

Description Returns the error string for the last runtime error.

Chapter 3, Visual Component Library Reference 155

Usage [form.]Report.LastErrorString;
For example:
ShowMessage (Crpe1.LastErrorString);
«If an error occurs, this code calls up a message box that displays
the error string.»

Remarks LastErrorString is a runtime-only property.

NOTE: LastErrorString must come after the Action call (see Action
Property, Page 135) in order to display relevant values. After you
have printed your report, you can refer to this property to get an
error string (if any). If there was no error in printing
LastErrorNumber = 0 (see LastErrorNumber Property, Page 155).

Data Type String

Availability Runtime

MarginBottom Property

Description Sets the bottom margin for the specified report.

Usage [form.]Report.MarginBottom[:=MarginSetting];
For example:
Crpe1.MarginBottom := 720;
«Sets a 1/2 inch bottom margin for the report (1 inch = 1440
twips).»

Remarks MarginSetting is the margin you want, in twips.

Data Type Word

Availability Design time; Runtime

156 Crystal Reports Developer’s Reference

MarginLeft Property

Description Sets the left margin for the specified report.

Usage [form.]Report.MarginLeft[:=MarginSetting];
For example:
Crpe1.MarginLeft := 1440;
«Sets a 1 inch left margin for the report (1 inch = 1440 twips).»

Remarks MarginSetting is the margin you want, in twips.

Data Type Word

Availability Design time; Runtime

MarginRight Property

Description Sets the right margin for the specified report.

Usage [form.]Report.MarginRight[:=MarginSetting];
For example:
Crpe1.MarginRight := 1440;
«Sets a 1 inch right margin for the report (1 inch = 1440 twips).»

Remarks MarginSetting is the margin you want, in twips.

Data Type Word

Availability Design time; Runtime

Chapter 3, Visual Component Library Reference 157

MarginTop Property

Description Sets the top margin for the specified report.

Usage [form.]Report.MarginTop[:=MarginSetting];
For example:
Crpe1.MarginTop := 720;
«Sets a 1/2 inch top margin for the report (1 inch = 1440 twips).»

Remarks MarginSetting is the margin you want, in twips.

Data Type Word

Availability Design time; Runtime

MDIChild Property

Description This property is used to make the print window a child of the current
form.

Usage [form.]Report.MDIChild[:={True|False}]
For example:
Crpe1.MDIChild := True;

Remarks Make sure that the forms FormStyle property is set to fsMDIForm
when you set MDIChild to True.

Data Type Boolean

Availability Design time; Runtime

158 Crystal Reports Developer’s Reference

Password Property

Description Enters the password needed to use database tables on a restricted

Access .mdb file.

Usage [form.]Report.Password[:=Password];
For example:
Crpe1.Password := ‘dogsncats’;
«Enters the password dogsncats.»

Remarks Enter the password you have been assigned.

Data Type String

Availability Runtime

PrinterCollation Property

Description If you specify more than one copy to be printed (using the
PrinterCopies property, see Page 160), PrinterCollation specifies
whether or not the copies will be collated.

Usage [form.]Report.PrinterCollation[:=TCollation];
For example:
Crpe1.PrinterCollation := Collated;
«Collates the copies of the specified report.»

Data Type TCollation = (Uncollated, Collated, DefaultCollation);

Availability Design time; Runtime

Chapter 3, Visual Component Library Reference 159

PrinterCopies Property

Description Sets the number of report copies to be printed.

Usage [form.]Report.PrinterCopies[:=NumCopies];
For example:
Crpe1.PrinterCopies := 3;
«Specifies that the program is to print three (3) copies of the
report.»

Remarks The number you use for PrinterCopies must not be zero or a negative
value.

Data Type Word

Availability Design time; Runtime

PrinterDriver Property

Description Sets the name of the printer driver that is to print the report.

Usage [form.]Report.PrinterDriver [:=DriverName];

For example:
Procedure TForm1.Button1.Click(Sender:
TObject);
var
lpPrinter, lpDriver, lpPort : pChar;
hMode : Thandle;
begin
lpPrinter := StrAlloc(255);
try
lpDriver := StrAlloc(255);
try

160 Crystal Reports Developer’s Reference

 lpPort := StrAlloc(255);
try
Cancel := not
PrintDialog1.Execute;
Printer.GetPrinter(lpPrinter,
lpDriver, lpPort, hMode);
Crpe1.PrinterName :=
StrPas(lpPrinter);
Crpe1.PrinterDriver :=
StrPas(lpDriver);
Crpe1.PrinterPort := StrPas(lpPort);
Crpe1.PrinterMode := hMode;
finally
StrDispose(lpPort);
end;
finally
StrDispose(lpDriver);
end;
finally
StrDispose(lpPrinter);
end;
end;

Remarks PrinterDriver, PrinterMode, PrinterName, and PrinterPort all work

together to define the printer that the report is to be sent to. All four
properties must be set in order to define a new printer. If all four
properties are not set, the printer defined in the report will be used.
This may be the users default printer if none has been specified in the
report.

Data Type String

Availability Design time; Runtime

PrinterMode Property

Description Allows you to set the MS Device Mode for a report (orientation,
paper size, etc.)

Chapter 3, Visual Component Library Reference 161

Usage [form.]Report.PrinterMode[:= Thandle];
For example:
Procedure TForm1.Button1.Click(Sender:
TObject);
var
lpPrinter, lpDriver, lpPort : pChar;
hMode : Thandle;
begin
lpPrinter := StrAlloc(255);
try
lpDriver := StrAlloc(255);
try
lpPort := StrAlloc(255);
try
Cancel := not
PrintDialog1.Execute;
Printer.GetPrinter(lpPrinter,
lpDriver, lpPort,
hMode);
Crpe1.PrinterName :=
StrPas(lpPrinter);
Crpe1.PrinterDriver :=
StrPas(lpDriver);
Crpe1.PrinterPort := StrPas(lpPort);
Crpe1.PrinterMode := hMode;
finally
StrDispose(lpPort);
end;
finally
StrDispose(lpDriver);
end;
finally
StrDispose(lpPrinter);
end;
end;

Remarks PrinterDriver, PrinterMode, PrinterName, and PrinterPort all work

together to define the printer that the report is to be sent to. All four
properties must be set in order to define a new printer. If all four
properties are not set, the printer defined in the report will be used.
This may be the users default printer if none has been specified in the
report.

162 Crystal Reports Developer’s Reference

Data Type THandle

Availability Design time; Runtime

PrinterName Property

Description Sets the name of the printer that is to print the report.

Usage [form.]Report.PrinterName[:=PrinterName];
For example:
Procedure TForm1.Button1.Click(Sender:
TObject);
var
lpPrinter, lpDriver, lpPort : pChar;
hMode : Thandle;
begin
lpPrinter := StrAlloc(255);
try
lpDriver := StrAlloc(255);
try
lpPort := StrAlloc(255);
try
Cancel := not
PrintDialog1.Execute;
Printer.GetPrinter(lpPrinter,
lpDriver, lpPort,
hMode);
Crpe1.PrinterName :=
StrPas(lpPrinter);
Crpe1.PrinterDriver :=
StrPas(lpDriver);
Crpe1.PrinterPort := StrPas(lpPort);
Crpe1.PrinterMode := hMode;
finally
StrDispose(lpPort);
end;
finally
StrDispose(lpDriver);
end;

Chapter 3, Visual Component Library Reference 163

 finally
StrDispose(lpPrinter);
end;
end;

Remarks PrinterDriver, PrinterMode, PrinterName, and PrinterPort all work

together to define the printer that the report is to be sent to. All four
properties must be set in order to define a new printer. If all four
properties are not set, the printer defined in the report will be used.
This may be the users default printer if none has been specified in the
report.

Data Type String

Availability Design time; Runtime

PrinterPort Property

Description Sets the port for the specified printer.

Usage [form.]Report.PrinterPort[:=PortName];
For example:
Procedure TForm1.Button1.Click(Sender:
TObject);
var
lpPrinter, lpDriver, lpPort : pChar;
hMode : Thandle;
begin
lpPrinter := StrAlloc(255);
try
lpDriver := StrAlloc(255);
try
lpPort := StrAlloc(255);
try
Cancel := not
PrintDialog1.Execute;
Printer.GetPrinter(lpPrinter,
lpDriver, lpPort,

164 Crystal Reports Developer’s Reference

 hMode);
Crpe1.PrinterName :=
StrPas(lpPrinter);
Crpe1.PrinterDriver :=
StrPas(lpDriver);
Crpe1.PrinterPort := StrPas(lpPort);
Crpe1.PrinterMode := hMode;
finally
StrDispose(lpPort);
end;
finally
StrDispose(lpDriver);
end;
finally
StrDispose(lpPrinter);
end;
end;

Remarks PrinterDriver, PrinterMode, PrinterName, and PrinterPort all work

together to define the printer that the report is to be sent to. All four
properties must be set in order to define a new printer. If all four
properties are not set, the printer defined in the report will be used.
This may be the users default printer if none has been specified in the
report.

Data Type String

Availability Design time; Runtime

PrinterStartPage Property

Description Sets the first page to be printed.

Usage [form.]Report.PrinterStartPage[:=StartPage];
For example:
Crpe1.PrinterStartPage := 7;
«Specifies that printing is to begin with Page 7 of the report.»

Chapter 3, Visual Component Library Reference 165

Remarks If a value less than or equal to 0 is used for PrinterStartPage, the
value is ignored and printing starts with Page 1.

Data Type Word

Availability Design time; Runtime

PrinterStopPage Property

Description Sets the last page to be printed.

Usage [form.]Report.PrinterStopPage[:=StopPage];
For example:
Crpe1.PrinterStopPage := 12;
«Specifies that the printing is to end with Page 12 of the report.»

Remarks Use a value of -1 for PrinterStopPage to indicate that printing is to

continue through to the last page.

Data Type Word

Availability Design time; Runtime

PrintControls Property

Description Method to show/hide the standard Crystal button bar.

Usage [form.]Report.PrintControls[:={True|False}];
For example:
Crpe1.PrintControls:=True;

166 Crystal Reports Developer’s Reference

Remarks Only works after the Execute or Action properties (see Action
Property, Page 135).
To do this before running Execute or Action, use WindowControls
property (see WindowControls Property, Page 193).

Data Type Boolean

Availability Runtime

PrintDay Property

Description Sets the day component of the print date (if different from the actual
date the report is printed).

Usage [form.]Report.PrintDay[:=Day];
For example:
Crpe1.PrintDay := 23;
«Sets 23 as the print day.»

Remarks ● Enter a value from 1 to 31.

● The PrintYear (see Page 175), PrintMonth (see Page 174), and
PrintDay properties function together. You must change the
value of all three to change the print date. If you do not change all
three, the print date saved with the report is used. This may be
the current date if a specific date is not saved with the report.

Data Type Word

Availability Design time; Runtime

Chapter 3, Visual Component Library Reference 167

PrintEnded Property

Description Specifies whether or not the printing process is completed.

Boolean result returns True when Engine is done running report.

Usage [form.]Report.PrintEnded;
For example:
Crpe1.Destination := toPrinter;
Crpe1.Execute
While Not Crpe1.PrintEnded Do
Application.ProcessMessages;
Close;
«Runs report to printer. Will not allow the program to close the
current form until the print is finished.»

Remarks When destination is to Window, this property will not return true
until you have gone to the last page of the report.

Data Type Boolean

Availability Runtime

PrintFileCharSepQuote Property

Description Sets the quote character used to enclose alphanumeric field data
when printing to a file using character-separated export format.

Usage [form.]Report.PrintFileCharSepQuote[:=Quote];
For example:
Crpe1.PrintFileCharSepQuote := ‘”’;
«Uses the quotation character (“) to surround values saved in
character-separated export format.»

168 Crystal Reports Developer’s Reference

Remarks 1. Applies only when PrintFileType (see Page 170) is
CharacterSeparated values.
2. Applies only when Destination is toFile, toEMailviaMAPI, or
toEMailviaVIM (see Destination Property, Page 138).
3. If you assign a string to PrintFileCharSepQuote that is longer
than one character, the VCL uses only the first character of that
string. For example, if you assign ‘quote’ to the property, the
VCL will only recognize ‘q’.

Data Type String

Availability Design time; Runtime

PrintFileCharSepSeparator Property

Description Sets the character(s) you want to use to separate the fields when
printing to a file using the Character Separated Value format.

Usage [form.]Report.PrintFileCharSepSeparator[:=
Separator];
For example:
Crpe1.PrintFileCharSepSeparator := ‘@’;
«Specifies that the "@" character is to be used for separating field
values.»

Remarks 1. Applies only when PrintFileType (see Page 170) is

CharacterSeparated values.
2. Applies only when Destination is toFile, toEMailViaMAPI, or
toEMailViaVIM (see Destination Property, Page 138).

Data Type String

Availability Design time; Runtime

Chapter 3, Visual Component Library Reference 169

PrintFileName Property

Description Specifies the name of the file to which the report is to be printed.

Usage [form.]Report.PrintFileName[:=FileName];
For example:
Crpe1.PrintFileName := ‘c:\crw\cust_rpt.txt’;
«Prints the report to a file named "cust_rpt.txt" in the C:\CRW
directory.»

Remarks ● You can double-click this property or click the ellipsis (...) in the
Settings box to call up the Choose Print Filename dialog box. In
that dialog box, select the name of the file and the path to which
you want the program to print the report.
● Select a value for this property only if you are printing to a file, if
the value you assigned to the Destination property is toFile (see
Destination Property, Page 138).
NOTE: If you want to specify the PrintFileName at runtime, make
certain that you enclose it in quotes in your code.

Data Type String

TPrintFile = string[TCRPE_PRINTFILE_LEN]

Availability Design time; Runtime

PrintFileType Property

Description Specifies the type of print file used when printing a report to a file.

Usage [form.]Report.PrintFileType[:=FileType];
For example:
Crpe1.PrintFileType := TabSeparated;
«Prints the report to a file in a tab separated format.»

170 Crystal Reports Developer’s Reference

Remarks Select one of the following print file types if you are printing to a file,
if the value you assigned to the Destination property is toFile (see
Destination Property, Page 138).

Records
Record style (columns of values). Does not use commas or
separators. Outputs every record with a fixed field width.

TabSeparated
Tab separated values. Presents data in tabular form. Encloses
alphanumeric field data in quotes and separates fields with tabs.

Ascii
Text style. Saves the data in ASCII text format with all values
separated by spaces. This style looks most like the printed page.

DIF
Saves the data in DIF (data interchange format) format. This format
is often used for the transfer of data between different spreadsheet
programs.

CSV
Comma separated values. Encloses alphanumeric field data in
quotes and separates fields with commas.

CharacterSeparated
Saves the data as character separated values in ASCII text format. All
values are separated by a character or characters specified by the
PrintFileCharSepSeparator property (see Page 91).

TabSeparatedText
Saves the data in ASCII text format with all values separated by tabs.

CrystalReportsRPT
Standard Crystal Reports RPT format is used. Most often used for
sending the report to another user via e-mail.

Excel2
Exports the report as a Microsoft Excel 2.1 Worksheet.

Excel3
Exports the report as a Microsoft Excel 3.0 Worksheet.

Chapter 3, Visual Component Library Reference 171

 Excel4
Exports the report as a Microsoft Excel 4.0 Worksheet.

LotusWK1
Exports the report as a Lotus 1-2-3 WK1 format worksheet.

LotusWK3
Exports the report as a Lotus 1-2-3 WK3 format worksheet.

LotusWKS
Exports the report as a Lotus 1-2-3 WKS format worksheet.

QuattroPro5
Exports the report as a Quattro Pro 5.0 WB1 format file.

RTF
Saves the data in Rich Text Format.

WordForDOS
Uses the Microsoft Word for DOS format to save the data in the
report.

WordForWindows
Uses the Microsoft Word for Windows format to save the data in the
report.

WordPerfect
Uses WordPerfect format to save the data in the report.

Data Type Integer (Enumerated)

TPrintFileType = (Records, TabSeparated, Ascii, DIF, CSV,
CharacterSeparated, TabSeparatedText, CrystalReportRPT,
Excel2, Excel3, Excel4, LotusWK1, LotusWK3, LotusWKS, RTF,
WordForDOS, WordForWindows, WordPerfect, QuattroPro5);

Availability Design time; Runtime

172 Crystal Reports Developer’s Reference

PrintFileUseRptDateFmt Property

Description When printing to a file, indicates whether or not the program should
save dates in the same date format (MDY, DMY, etc.) that is used in
the report or instead, optimize the dates for the file format you have
selected.

Usage [form.]Report.PrintFileUseRptDateFmt
[:={True|False}];
For example:
Crpe1.PrintFileUseRptDateFmt := True;
«Specifies that the program should print dates in the same format
as used in the report.»

Remarks 1. Applies only when PrintFileType is Records, TabSeparated, DIF,

CSV, CharacterSeparated.
2. Applies only when Destination is toFile, toEMailViaMAPI, or
toEMailViaVIM (see Destination Property, Page 138).

Data Type Boolean

Availability Design time; Runtime

PrintFileUseRptNumberFmt Property

Description When printing to a file, indicates whether or not the program should
print numbers in the same format (decimal places, negatives, etc.)
that you have used in the report or instead, optimize the numbers for
the file format you have selected.

Usage [form.]Report.PrintFileUseRptNumberFmt[:={True|
False}];

Chapter 3, Visual Component Library Reference 173

 For example:
Crpe1.PrintFileUseRptNumberFmt := True;
«Specifies that the program should print numbers in the same
format as used in the report.»

Remarks 1. Applies only when PrintFileType (see Page 170) is Records,

TabSeparated, DIF, CSV, or CharacterSeparated.
2. Applies only when Destination is toFile, toEMailViaMAPI, or
toEMailViaVIM (see Destination Property, Page 138).

Data Type Boolean

Availability Design time; Runtime

PrintMonth Property

Description Sets the month component of the print date (if different from the
actual date the report is printed).

Usage [form.]Report.PrintMonth[:=Month];
For example:
Crpe1.PrintMonth := 7;
«Sets July as the print month.»

Remarks ● Enter a value from 1-12 where January = 1, December = 12.

● The PrintYear (see Page 175), PrintMonth and PrintDay (see Page
167) properties function together. You must change the value of
all three to change the print date. If you do not change all three,
the print date saved with the report is used. This may be the
current date if a specific date is not saved with the report.

Data Type Word

Availability Design time; Runtime

174 Crystal Reports Developer’s Reference

PrintYear Property

Description Sets the year component of the print date (if different from the actual
date the report is printed).

Usage [form.]Report.PrintYear[:=Year];
For example:
Crpe1.PrintYear := 1994;
«Sets the year component of the print date to 1994.»

Remarks ● Enter the print year as a four-digit number.

● The PrintYear, PrintMonth (see Page 174) and PrintDay (see Page
167) properties function together. You must change the value of
all three to change the print date. If you do not change all three,
the print date saved with the report is used. This may be the
current date if a specific date is not saved with the report.

Data Type Word

Availability Design time; Runtime

ProgressDialog Property

Description Enables/disables the display of the Progress dialog box. The

Progress dialog box displays the progress of the report when it is
running (records read, records selected, and so forth).

Usage [form.]Report.ProgressDialog[:= {True|False}]

For example:
Crpe1.ProgressDialog := False;
«Turns off the Progress dialog box that usually appears during
exporting or printing.»

Chapter 3, Visual Component Library Reference 175

Remarks Use this property to indicate whether or not a progress dialog box
should be displayed while the report is printed or exported. This
property is set to True by default.

Data Type Boolean

Availability Design Time; Runtime

RecordsPrinted Property

Description Determines the number of records actually printed.

Usage [form.]Report.RecordsPrinted;
For example:
Printed := Crpe1.RecordsPrinted;
«Fetches the number of records printed and stores it in the Printed
variable.»

Remarks If the report being printed contains one or more group selection
formulas, the value returned by RecordsPrinted maybe significantly
less than the value returned by the RecordsSelected property (see
Page 177). Otherwise, this value should equal RecordsSelected.

Data Type LongInt

Availability Runtime

RecordsRead Property

Description Specifies the number of records actually processed by the print job
process.

Usage [form.]Report.RecordsRead;

176 Crystal Reports Developer’s Reference

 For example:
ReadSoFar := Crpe1.RecordsRead;
«Fetches the number of records read so far and stores it in the
ReadSoFar variable.»

Data Type Long

Availability Runtime

RecordsSelected Property

Description Determines the number of records selected for inclusion in the report
out of the total number of records read.

Usage [form.]Report.RecordsSelected;
For example:
Selected := Crpe1.RecordsSelected;
«Fetches the number of records selected and saves it in the
Selected variable.»

Remarks RecordsSelected will return a value anywhere between zero and the
value returned by the RecordsRead property. The value returned by
RecordsSelected depends on the queries and selection formulas set
up in the report.

Data Type LongInt

Availability Runtime

ReportDisplayPage Property

Description Indicates which page of a multi-page report is currently being

displayed in the Print window.

Usage [form.]Report.ReportDisplayPage;

Chapter 3, Visual Component Library Reference 177

 For example:
Result := Crpe1.DisplayPage;
«Fetches the number of the displayed page and stores it in the
Result variable.»

Data Type Word

Availability Runtime

ReportLatestPage Property

Description Determines the last page printed in the specified report.

Usage [form.]Report.ReportLatestPage;
For example:
Latest := Crpe1.ReportLatestPage;
«Fetches the number of the last page printed and stores it in the Latest
variable.»

Data Type Word

Availability Runtime

ReportName Property

Description Specifies the report to be printed.

Usage [form.]Report.ReportName[:=ReportName];
For example:
Crpe1.ReportName := ‘c:\crw\company.rpt’;
«Prints the report named "company.rpt" that is located in the
C:\CRW directory.»

178 Crystal Reports Developer’s Reference

Remarks You can double-click this property or click the ellipsis (...) in the
Object Inspector to call up the Choose Report File dialog box. In that
dialog box, select the name and path of the report you want the
program to print in response to an event.
NOTE: If you want to specify the ReportName at runtime, make
certain that you enclose it in quotes in your code.

Data Type String

Availability Design time; Runtime

ReportPrinterSetup Property

Description This property is used to set to enable or disable various settings

made in the Crystal Reports. Printer Setup command (File menu)

Usage [form.]Report.UserPrinterSetup.Enabled
[:= {True|False}];
[form.]Report.UserPrinterSetup.ReportPrinterSetup
[:=[TReportPrinterSetup]];
For example:
Crpe1.UserPrinterSetup.Enabled := True;
Crpe1.UserPrinterSetup.ReportPrinterSetup :=
[rsOrientation];
«Preserves the orientation saved in the report.»

Remarks UserPrinterSetup property must be enabled before you can use

ReportPrinterSetup.

Data Type TReportPrinterSetup: TReportPrinterSetups = set of [rsOrientation,

rsPaperSize, rsPaperSource];

Availability Design time; Runtime

Chapter 3, Visual Component Library Reference 179

ReportStartPage Property

Description Determines the first page printed in the specified report.

Usage [form.]Report.ReportStartPage;
For example:
StartPage := Crpe1.ReportStartPage;
«Fetches the number of the first page printed and stores it in the
StartPage variable.»

Data Type Word

Availability Runtime

ReportTitle Property

Description Sets a report title that supplements the DOS report name at design
time or runtime.

Usage [form.]Report.ReportTitle[:=Title];
For example:
Crpe1.ReportTitle := ‘Monthly Sales Report’;
«Sets the report title to be Monthly Sales Report.»

Remarks The value of the ReportTitle is not displayed in any part of the report,
but is provided for your own use.

Data Type String

Availability Design time; Runtime

180 Crystal Reports Developer’s Reference

SectionFont Property

Description Sets the font for one or more sections in the specified report.

Usage [form.]Report.SectionFont(SequentialIndex)
[:=sectionCode; fontName; size; italic; bold;
underline; strikethru];
For example:
Crpe1.SectionFont[0] :=
‘Footer;Arial;12;N;N;N;Y’;
«Sets the font for the footer section to 12 point, Arial, strikethrough.»

Remarks With SectionFont, you can specify changes to one or more sections at
runtime. Those changes then take place sequentially when you make
the "Action := 1" call (see Action Property, Page 135). The array index
value for SectionFont simply specifies the sequence number for the
change. Thus:
Crpe1.SectionFont[0] :=
‘DETAIL;Arial;12;N;N;N;Y’;
when making changes to the DETAIL section only, but
Crpe1.SectionFont[0] :=
‘HEADER;Arial;12;N;N;N;Y’;
Crpe1.SectionFont[1] :=
‘DETAIL;Arial;12;N;N;N;Y’;
when making changes to more than one section.
Use the following table as a guide in supplying the required values
for this property:

Parameter Data type Value expected

sectionCode string Please refer to the
section code table
(see Page 46).
fontName string The actual font
name, e.g. Arial or
Helvetica.
size number The size of the font
in points (e.g., 12 or
16).

Chapter 3, Visual Component Library Reference 181

 Parameter Data type Value expected
italic character T = true, F = False,
X = as is*
bold character T = true, F = False,
X = as is*
underline character T = true, F = False,
X = as is*
strikethru character T = true, F = False,
X = as is*
*X
(as is) uses the value saved with the report.

Data Type Array of strings

Availability Runtime

Related Topics
Resetting Array Properties 207

SectionFormat Property

Description Sets the format for one or more sections in the specified report.

Usage [form.]Report.SectionFormat(SectionArrayIndex)[
:=sectionCode; visible; newPageBefore;
newPageAfter; keepTogether; suppressBlank;
resetPageNAfter; printAtPageBottom;
backgroundColor; underlay];
For example:
Crpe1.SectionFormat[0]:=‘GH2;F;X;X;X;X;X;255.0.
0;X’;
«Hides the Group Header 2 section (visible = F) and changes the
background color to red while maintaining default settings for all
other switches.»

182 Crystal Reports Developer’s Reference

Remarks With SectionFormat, you can specify changes to one or more sections
at runtime. Those changes then take place sequentially when you
make the "Action := 1" call (see Action Property, Page 135). The
sequential index value for SectionFormat simply specifies the
sequence number for the change. Thus:
Crpe1.SectionFormat[0] :=
‘DETAIL;T;F;F;X;X;X;255.0.0;X’;
when making changes to the DETAIL section only, but
Crpe1.SectionFormat[0] :=
‘HEADER;T;F;F;X;X;X;255.0.0;X’;
Crpe1.SectionFormat[1] :=
‘DETAIL;T;F;F;X;X;X;X;255.0.0;X’;
when making changes to more than one section.
Use the following table as a reference when entering parameter
values for this property:

Parameter Expected value

sectionCode Please refer to the section code table
(see Page 46).
visible T = true, F = False, X = as is*
newPageBefore T = true, F = False, X = as is*
newPageAfter T = true, F = False, X = as is*
backgroundColor Supply a RGB (Red,Green,Blue) value
in the following format:
<R>.<G>.<B>
where R, G, and B are each integers
with a range from 0 to 255. For example:
189.210.100
If you do not want to change the color,
do not place anything in this parameter.
underlaySection T = true, F = False, X = as is*
keepTogether T = true, F = False, X = as is*
suppressBlank T = true, F = False, X = as is*
resetPageNAfter T = true, F = False, X = as is*
printAtPageBottom T = true, F = False, X = as is*
*X
(as is) uses the settings saved with the report.

Chapter 3, Visual Component Library Reference 183

Data Type Arrays of strings

Availability Runtime

Related Topics
Resetting Array Properties 207

SectionLineHeight Property

Description Specifies the line height in twips. A twip is 1/1440 inch; there are 20
twips in a point.

Usage [form.]Report.SectionLineHeight(SequentialIndex)
[:=sectionCode; line; height; ascent];
For example:
Crpe1.SectionLineHeight[0] := ‘GH0; 1; 500; 300’;
«Sets the line height for the second line in the group header zero
section to a height of 500 twips with an ascent of 300 twips.»

Remarks 1. With SectionLineHeight, you can specify changes to one or more

sections at runtime. Those changes then take place sequentially
when you make the "Action := 1" call (see Action Property, Page
135). The sequential index value for SectionLineHeight simply
specifies the sequence number for the change. Thus:
Crpe1.SectionLineHeight[0] :=
‘DETAIL;1;500;300’;
when making changes to the DETAIL section only, but
Crpe1.SectionLineHeight[0] :=
‘HEADER;1;500;300’;
Crpe1.SectionLineHeight[1] :=
‘DETAIL;1;500;300’;
when making changes to more than one section.
2. Use the following table as a guide in supplying the required
values for this property:

184 Crystal Reports Developer’s Reference

 Parameter Explanation
sectionCode Specifies the section code for the report
section(s) for which you want to set a
new line height. Please refer to the
section code table (see Page 46).
lineN Specifies the line(s) for which you want
to set the line height. Line numbers in a
section are 0 origin: the first line
number is 0, the second is 1, etc.
height Specifies the line height in twips. A
twip is 1/1440 inch; there are 20 twips
in a point.
ascent Specifies the ascent in twips. Ascent is
the distance from the top of the allotted
line space (line height) to the baseline of
the font. The ascent parameter is used to
specify the position of the baseline if
you specify an oversized or undersized
line height. If you set ascent to 0, the
program puts the baseline at the top of
the space; if you set ascent to the same
value as height, the program sets the
baseline at the bottom of the space. For
any other baseline, specify the ascent in
twips.

Data Type Arrays of strings

Availability Runtime

Related Topics
Resetting Array Properties 207

SectionMinHeight Property

Description Sets the minimum section height for the specified report section.

Chapter 3, Visual Component Library Reference 185

Usage [form.]Report.SectionMinHeight(SequentialIndex)
[:=sectionCode; minHeight];
For example:
Crpe1.SectionMinHeight[0]:= ‘ALL; 500’;
«Sets the minimum height for all sections to 500 twips.»

Remarks With SectionMinHeight, you can specify changes to one or more

sections at runtime. Those changes then take place sequentially
when you make the "Action := 1" call (see Action Property, Page 135).
The array index value for SectionMinHeight simply specifies the
sequence number for the change. Thus:
Crpe1.SectionMinHeight[0] := ‘DETAIL;500’;
when making changes to the DETAIL section only, but
Crpe1.SectionMinHeight[0] := ‘HEADER;500’;
Crpe1.SectionMinHeight[1] := ‘DETAIL;500’;
when making changes to more than one section.

Data Type Array of strings

Availability Runtime

Related Topics
Resetting Array Properties 207

SelectionFormula Property

Description Specifies the records to be used when printing the report. Whatever
is set in this property gets appended to the original Selection
Formula in the report. It will AND whatever is set to the original
Selection Formula in the report.

Usage [form.]Report.SelectionFormula(SequentialIndex)
[:=SelectionFormula];
Enter the selection formula just as you would enter it in the Formula
Editor in Crystal Reports.

186 Crystal Reports Developer’s Reference

 (Search for the Formula Editor in Crystal Reports online Help.)
For example:
Crpe1.SelectionFormula[0] := '{file.COUNTRY} =
“USA”';
This code limits the report to records that have the value ‘USA’ in the
COUNTRY field (only United States records).

Remarks ● Make certain that you enclose your selection formula in single
quotes.
● If your selection formula includes internal quotes, for example:
{file.STATE} = ‘CA’
change all of the internal single quotes to double quotes and then
surround the entire selection formula in single quotes as follows:
‘{file.STATE} = "CA"’
● If you have created a selection formula in your report at design
time, any selection formula you enter here will be appended to
that selection formula. Thus, your records will be selected based
on a combination of the two selection formulas.

Data Type String

TCrpeString

Availability Design time; Runtime

Related Topics
Resetting TCrpe Array String Properties 208

SortFields Property

Description Specifies the field(s) that are to be used to sort your data when the
report is printed.

Usage [form.]Report.SortFields(ArrayIndex)
[:="{+|-}SortField"];

Chapter 3, Visual Component Library Reference 187

 Enter the fields on which you want the data in your report to be
sorted.
For example, to sort an order database alphabetically by customer,
and then by order date, you can enter code similar to the following:
Crpe1.SortFields[0] := ‘+{orders.CUSTOMER}’;
Crpe1.SortFields[1] := ‘+{orders.ORDERDATE}’;

Remarks ● SortFields is an array property available only at runtime.

● Use a separate line of code to specify each sort field.
● Enter sort fields in the order that you want them to sort your
report. For example, if you want your report to be sorted first on
field A and then on field B, specify sort field A in your first line of
code and sort field B in your second line of code.
● The sort field you specify must be assigned array index 0, the
second sort field must be assigned array index 1, etc.
● The index values you assign must be continuous; no gaps are
allowed (0,1,2 = OK, 0,1,3 = wrong)
● Array index values must be subscripted in the code immediately
after the property name (i.e., Crpe1.SortFields[0] :=).
● If you have specified sort fields for your report at design time,
any sort fields you enter here will replace the sort fields in your
report.
● If you do not use this property, the program will use the sorting
instructions that you specified in the report.
● If you want to clear the sort fields in your report, use an empty
string (Crpe1. SortFields[0] := ‘’;). Use this only if you are certain
that SortFields has already been set. If you’re unsure use the
Crpe1.Clear property or this code:
If Crpe1.SortFields[0] <> ‘’ then
Crpe1.SortFields[0] := ‘’
● Enclose field names in braces.
● Sort fields can be database fields or formula fields. If you sort on a
formula field, use the @ sign before the formula name (i.e.,
{@FORMULANAME}).

Data Type Array of strings

188 Crystal Reports Developer’s Reference

Availability Runtime

Related Topics
Resetting Array Properties 207

SQLQuery Property

Description Sets the SQL query string used by the specified report.

Usage [form.]Report.SQLQuery(SequentialIndex)
[:=SQLQuery];
For example:
Crpe1.SQLQuery[0] := ‘SELECT authors.au_id,
authors.au_lname,’;
Crpe1.SQLQuery[1] := ‘ authors.au_fname FROM
pubs2.dbo.authors’;
Crpe1.SQLQuery[2] := ‘ authors WHERE
authors.au_lname > ‘‘Madison’’’;
«Queries the SQL database to return only the records where the
authors last name falls after Madison alphabetically.»

Remarks ● You may only change the WHERE and FROM sections of an SQL
query. Although the property requires that you enter the entire
SQL query, the SELECT section must not be different from the
original query.
● If you are going to include an ORDER BY clause, you must
precede it with CHR(13) and CHR(10).

Data Type String

TCrpeString

Availability Design time; Runtime

Chapter 3, Visual Component Library Reference 189

 Related Topics
Resetting TCrpe String Properties 208

Status Property

Description Determines the print status for the specified report.

Usage [form.]Report.Status;
For example:
Status := Crpe1.Status;
«Fetches the print status and saves it to the Status variable.»

Remarks The Status property will return one of the following values:
● 0 - The report has not been printed or has not finished printing.
● 3 - The report has finished printing.
● 5 - The report has been cancelled by the user.
When previewing a report, a status of 3 will only be returned when
the user has previewed to the last page of the report.

Data Type Integer

StoredProcParam Property

Description Sets the stored procedure parameters when using a report based on
SQL stored procedures.

Usage [form.]Report.StoredProcParam(Parameter Array

Index)[:=newParameter];
For example:
Crpe1.StoredProcParam[0] := ‘06/14/1989’;
«Sets the first stored procedure parameter to the date June 14,
1989.»

190 Crystal Reports Developer’s Reference

Remarks StoredProcParam sets the value of the specified parameter in a SQL
database table that is based on a stored procedure. Pass the value you
wish to set the parameter to as a string. If the parameter expects a
different data type, you still must pass the value as a string. For
example, to pass the integer value 396, use the string "396". The
Crystal Report Engine will handle converting the value into integer
format.

Data Type Arrays of strings

Availability Runtime

Related Topics
Resetting Array Properties 207
Access Notes Sparse Array Properties 208

UserName Property

Description Enters the name given to a user for logging on to a protected Access
.mdb file to obtain data files needed by the report.

Usage [form.]Report.UserName[:=Name];
For example:
Crpe1.UserName := ‘MIS’;
«Enters the user name "MIS".»

Remarks ● Enter the name you have been assigned.

● The name must be enclosed in quotes if the variable is being
assigned at runtime.

Data Type String

Availability Runtime

Chapter 3, Visual Component Library Reference 191

WindowBorderStyle Property

Description Specifies the type of border for the print window.

Usage [form.]Report.WindowBorderStyle
[:=TFormBorderStyle];
For example:
Crpe1.WindowBorderStyle := bsSizeable;
«Sets a sizeable border style for the print window.»

Remarks Select one of the following border styles for the print window:
● bsNone (creates a window with no border).
● bsSingle (creates a window of a fixed size with a single line
border).
● bsSizeable (creates a window that can be resized by the user).
● bsFialog (creates a window of fixed size with a double line
border).
Select a value here only if you are printing to a window, if
Destination := toWindow (see Destination Property, Page 138).

Data Type Integer (Enumerated)

TFormBorderStyle = (bsNone, bsSingle, bsSizeable, bsDialog);

Availability Design time; Runtime

WindowControlBox Property

Description Specifies whether or not the print window is to have a control

(system menu) box in the upper left hand corner when the report is
printed to a window.

Usage [form.]Report.WindowControlBox[:={True|False}];
For example:
Crpe1.WindowControlBox := True;

192 Crystal Reports Developer’s Reference

 «Specifies that a control box (system menu) is to appear in the
print window.»

Remarks ● Select True if you want the window to contain a control box.
Select False if you do not.
● Select a value here only if you are printing to a window, if
Destination := toWindow (see Destination Property, Page 138).

Data Type Boolean

Availability Design time; Runtime

WindowControls Property

Description Specifies whether or not the print controls are to appear in the Print
window when printing a report to a window.

Usage [form.]Report.WindowControls[:={True|False}];
For example:
Crpe1.WindowControls := True;
«Specifies that print controls are to appear in the Print window.»

Data Type Boolean

Availability Design time; Runtime

WindowHeight Property

Description Sets the height of the print window when the report is printed to a
window.

Usage [form.]Report.WindowHeight[:=Height];

Chapter 3, Visual Component Library Reference 193

 For example:
Crpe1.WindowHeight := 300;
«Sets the height of the print window to 300 pixels.»

Remarks ● If you are not satisfied with the default settings, enter the external
height you want for your print window in pixels.
● Select a value here only if you are printing to a window, if
Destination := toWindow (see Destination Property, Page 138).

Data Type TWindowPosition

Availability Design time; Runtime

WindowLeft Property

Description Sets the distance, in pixels, that the print window is to appear from
the left edge of the parent window. If the print window is a top level
window, then the distance is measured from the left edge of the
screen.

Usage [form.]Report.WindowLeft[:=Distance];
For example:
Crpe1.WindowLeft := 100;
«Sets the left edge of the print window 100 pixels from the left
edge of the screen.»

Remarks ● If you are not satisfied with the default settings, enter the number
of pixels you want between the left edge of the screen and the left
edge of your window.
● Select a value here only if you are printing to a window, if
Destination := toWindow (see Destination Property, Page 138).

Data Type Word

Availability Design time; Runtime

194 Crystal Reports Developer’s Reference

WindowMaxButton Property

Description Specifies whether or not the print window is to have a maximize

button when the report is printed to a window.

Usage [form.]Report.WindowMaxButton[:={True|False}];
For example:
Crpe1.WindowMaxButton := False;
«Specifies that no Maximize button is to appear in the print
window.»

Remarks ● Select True if you want the window to contain a maximize button.
Select False if you do not.
● Select a value here only if you are printing to a window, if
Destination := toWindow (see Destination Property, Page 138).

Data Type TWindowPosition

Availability Design time; Runtime

WindowMinButton Property

Description Specifies whether or not the print window is to have a minimize

button when the report is printed to a window.

Usage [form.]Report.WindowMinButton[:={True|False}];
For example:
Crpe1.WindowMinButton := True;
«Specifies that a Minimize button is to appear in the print
window.»

Chapter 3, Visual Component Library Reference 195

Remarks ● Select True if you want the window to contain a minimize button.
Select False if you do not.
● Select a value here only if you are printing to a window, if
Destination := toWindow (see Destination Property, Page 138).

Data Type Boolean

Availability Design time; Runtime

WindowParentHandle Property

Description Specifies the window handle for the parent window to be used for
this print window (except when the print window is to be a top level
window, in which case this param is 0). The property is for people
who want their report to print to a windowed control (eg. a panel).

Usage [form.]Report.WindowParentHandle[:=handle];
For example:
crpe1.windowparenthandle :=
form1.panel1.handle;
«Prints the report to panel1 inside of form1.»

Data Type Integer

Availability Runtime

WindowState Property

Description Sets the state of the Print window, normal, minimized, or

maximized, when the report is printed to a Print window.

Usage [form.]Report.WindowState[:=TWindowState];

196 Crystal Reports Developer’s Reference

 For example:
Crpe1.WindowState := wsMaximized;
«When the report is printed to a Print window, the Print window
appears maximized when opened.»

Remarks Use the following values to set the WindowState property:

● wsNormal
The Print window appears neither minimized nor maximized. It
appears in a default size and position previously defined by your
application or by Windows.
● wsMinimized
The Print window appears minimized as an icon close to the
lower left hand corner of the screen. The icon can be restored to
display the window in a normal state.
● wsMaximized
The Print window is maximized when opened to fill the entire
screen.

Data Type TWindowState = (wsNormal, wsMinimized, wsMaximized);

Availability Design time; Runtime

WindowTitle Property

Description Specifies the title you want to appear in the print window title bar
when the report is printed to a window.

Usage [form.]Report.WindowTitle[:=Title];
For example:
Crpe1.WindowTitle := ‘Quarterly Earnings’;
«Sets the title of the print window (the string that appears on the
title bar) to "Quarterly Earnings".»

Remarks ● Make sure that the title is enclosed in quotes.

● Select a value here only if you are printing to a window, if
Destination := toWindow (see Destination Property, Page 138).

Chapter 3, Visual Component Library Reference 197

Data Type String

Availability Design time; Runtime

WindowTop Property

Description Sets the distance, in pixels, that the print window is to appear from
the top edge of the parent window. If the print window is a top level
window, then the distance is measured from the top edge of the
screen.

Usage [form.]Report.WindowTop[:=Distance];
For example:
Crpe1.WindowTop := 100;
«Sets the top edge of the print window 100 pixels from the top of
the screen.»

Remarks ● If you are not satisfied with the default setting, enter the number
of pixels you want between the top of the screen and the top of
your window.
● Select a value here only if you are printing to a window, if
Destination := toWindow (see Destination Property, Page 138).

Data Type TWindowPosition

Availability Design time; Runtime

WindowWidth Property

Description Specifies the width of the print window in pixels.

Usage [form.]Report.WindowWidth[:=Width];

198 Crystal Reports Developer’s Reference

 For example:
Crpe1.WindowWidth := 480;
«Specifies a print window 480 pixels wide.»

Remarks ● If you are not satisfied with the default setting, enter the external
width of your window, in pixels.
● Select a value here only if you are printing to a window, if
Destination := toWindow (see Destination Property, Page 138).

Data Type TWindowPosition

Availability Design time; Runtime

ZoomMagnification Method

Description Sets the magnification factor for the report in the print window to a
value from 25% to 400% of the actual size.

Usage [form.]Report.ZoomMagnification :=
[(PercentZoomLevel)]
For example:
Crpe1.ZoomMagnification := 150;
´Sets the magnification/zoom level to 150% for the current
report.ª

Remarks This method is only valid when the report is printed to a Preview
window.
This method must be called after the Action (see Page 135) or Execute
property (see Page 144).

Chapter 3, Visual Component Library Reference 199

ZoomPreviewWindow Property

Description Changes the magnification of the Print window to a specified level.

Usage [form.]Report.ZoomPreviewWindow
[:=TPreviewWindowZoom];
For example:
Crpe1.ZoomPreviewWindow := pwFullSize;

Data Type TPreviewWindowZoom = (pwFullSize, pwFitOneSize,

pwFitBothSides);

Availability Runtime

METHODS
Clear Method

Description This method is used to clear string properties and array properties.

Usage [form.]Report.[StringProperty.]Clear;
For example:
Crpe1.SelectionFormula.Clear;
«This code reinitializes the array of any strings that were
previously set.»

Remarks Resets the VCL if you wish to use the VCL for more than one report.
For example:
Crpe1.Clear;

200 Crystal Reports Developer’s Reference

Availability Runtime

CloseWindow Method

Description This method is used to close the associated print window.

Usage [form.]Report.CloseWindow;
For example:
Crpe1.CloseWindow;
«Closes the current report that is displayed.»

Remarks Closes the current preview window. This method is used mostly
when not using standard window controls.

Availability Runtime

ExportPrintWindow Method

Description Exports the report displayed in the print window. It will bring up the
Export dialog boxes for the user to fill in the required information.

Usage [form.]Report.ExportPrintWindow([{True|False},
{True|False}]);
For example:
Crpe1.ExportPrintWindow(True,True);
«Exports the report that is currently displayed in the window.»

Remarks The first Boolean parameter is to default the method to ExportToMail

and the second is WaitUntilDone and should always be set to true.

Availability Runtime

Chapter 3, Visual Component Library Reference 201

Focused Method

Description This method returns True if the associated print window has the
input focus.

Usage [form.]Report.Focused;
For example:
If Crpe1.Focused then
ShowMessage (‘Preview has focus’);
«Prints the message, "Preview has focus" if the reoprt is in the
forefront with control.»

Availability Runtime

PageCount Method

Description Returns the number of pages in the report.

Usage [form.]Report.PageCount
For example:
NumberofPages := Crpe1.PageCount;

Remarks PageCount must be called after the Action (see Page 135) or Execute
(see Page 144) property to get a valid page count.

PrintWindow Method

Description Prints the report displayed in the print window to the printer.

Usage [form.]Report.PrintWindow([{True|False}]);

202 Crystal Reports Developer’s Reference

 For example:
Crpe1.PrintWindow(True);

Remarks Always set the WaitUntilDone parameter to True.

Availability Runtime

ReportWindowHandle Method

Description Returns a handle to the associated preview window.

Usage [form.]Report.ReportWindowHandle;
For example:
Type
MyWin : hWnd;
Begin
Crpe1.Execute;
MyWin := Crpe1.ReportWindowHandle;
While IsWindow(MyWin) Do
Application.ProcessMessages;
End;
«This sample will halt the execution of the application until the
preview window is closed.»

Availability Runtime

SetFocus Method

Description The SetFocus method gives the input focus to the associated print
window.

Usage [form.]Report.SetFocus;

Chapter 3, Visual Component Library Reference 203

 For example:
If Not Crpe1.Focused then
Crpe1.SetFocus;

Availability Runtime

ShowFirstPage Method

Description The ShowFirstPage method will display the first page in the
associated print window.

Usage [form.]Report.ShowFirstPage;
For example:
Crpe.ShowFirstPage;

Remarks Due to changes in the 5.0 Report Engine, in versions 1.08.21 and
2.00.13.32 and earlier of the Crystal VCL this Method will only be
enabled after the user has previewed to the last page of the report.

Availability Runtime

ShowLastPage Method

Description The ShowLastPage method will display the last page in the
associated print window.

Usage [form.]Report.ShowLastPage;
For example:
Crpe1.ShowLastPage

Remarks Due to changes in the 5.0 Report Engine, in versions 1.08.21 and
2.00.13.32 and earlier of the Crystal VCL this Method will only be
enabled after the user has previewed to the last page of the report.

204 Crystal Reports Developer’s Reference

Availability Runtime

ShowNextPage Method

Description The ShowNextPage method will display the next page in the
associated print window.

Usage [form.]Report.ShowNextPage;
For example:
Crpe1.ShowNextPage;

Remarks Due to changes in the 5.0 Report Engine, in versions 1.08.21 and
2.00.13.32 and earlier of the Crystal VCL this Method will only be
enabled after the user has previewed to the last page of the report.

Availability Runtime

ShowPage Method

Description Displays a specific page of the report in the print window.

Usage [form.]Report.ShowPage [(PageToShow)]

For example:
Crpe1.PageShow(3);
«Shows the third page of the report.»

Remarks This method is only valid when the report is printed to a Preview
window.
This method must be called after the Action (see Page 135) or Execute
(see Page 144) property.

Chapter 3, Visual Component Library Reference 205

ShowPreviousPage Method

Description The ShowPreviousPage method will display the previous page in the
associated print window.

Usage [form.]Report.ShowPreviousPage;
For example:
Crpe1.ShowPreviousPage;

Remarks Due to changes in the Crystal Report Engine for version 5.0, in
versions 1.08.21 and 2.00.13.32 and earlier of the Crystal VCL this
Method will only be enabled after the user has previewed to the last
page of the report.

Availability Runtime

EVENTS
OnExecute Event

Description Called when the control receives either the Execute or Action
Messages (see Action Property, Page 135).

Usage If you double click on this from the Events page, this procedure will
be created:
procedure TForm1.Crpe1Execute(Sender: TObject;
var Cancel: Boolean);
begin
end;

Remarks This procedure will be executed when Action:=1 is set or Execute is

called.
Sender = standard Delphi sending object
Cancel = by setting to true, will cancel printing of report.

206 Crystal Reports Developer’s Reference

Availability Runtime

OnLoadDataFiles Event

Description Called when the current job is open, but not started.

Usage If you double click on this from the Events page, this procedure will
be created:
procedure TForm1.Crpe1LoadDataFiles(Sender:
TObject; const Count: Integer;
var Cancel: Boolean);
begin
end;

Remarks ● This procedure will be executed when Action:=1 (see Action

Property, Page 135) is set or Execute is called.
 Sender = standard Delphi sending object
 Count = the number of tables from the report
 Cancel = by setting to true, will cancel printing of report.
● The DataFilesLocation property will override any changes you
make to the DataFiles property in this event.

Availability Runtime

TUTORIALS
Resetting Array Properties

To clear an array property and release the memory associated with

it, assign an empty string to the first element of the array.
For example, to clear all the strings from the DataFiles property:
Crpe1.DataFiles[0] := EmptyStr;

Chapter 3, Visual Component Library Reference 207

Access Notes Sparse Array Properties

The Nth array element may be set without having to set up to the
previous N-1 elements. For example, the 7th table location may be set
by issuing Crpe1.DataFiles[6] := sTableName; on it's own.

Resetting Sort Array Properties

To clear a Sort Field array property and release the memory

associated with it, assign an empty string to the first element of the
array. This will also clear all the sort fields in your report.
For example, to clear all the strings from the SortFields property:
Crpe1.SortFields[0] := EmptyStr;

Resetting TCrpe String Properties

To clear a TCrpeString String List property and release the memory

associated with it, call the property’s Clear method.
For example, to clear all the strings from the SQLQuery property:
Crpe1.SQLQuery.Clear;

208 Crystal Reports Developer’s Reference

4 Report Engine Class Library
Reference

What you will find in this chapter...

Class Library Support Structures 210
Report Engine Classes 236

Chapter 4, Report Engine Class Library Reference 209

Class Library Support Structures
structure CRPELogOnInfo

This structure is used by member functions:

● CRPEngine::LogOnServer
● CRPEngine::LogOffServer
● CRPEJob::GetNthTableLogonInfo
● CRPEJob::SetNthTableLogonInfo
The structure is used to contain SQL connection information.

Data Members m_serverName

Specifies the logon name for the server used to create the report.
m_databaseName
Specifies the logon name for the database used to create the report.
m_userID
Specifies the user I.D. necessary to log on to the server.
m_password
Specifies the password necessary to log on to the server.

Construction CRPELogOnInfo
Constructs a CRPELogOnInfo structure type.

Related Topics
PELogOnInfo 678

CRPELogOnInfo:CRPELogOnInfo

CRPELogOnInfo ();
CRPELogOnInfo (const char *serverName, const char *databaseName,
const char *userID, const char *password);

210 Crystal Reports Developer’s Reference

Parameters serverName
Specifies the logon name for the server used to create the report.
Assigns this value to the CRPELogOnInfo::m_serverName member.
databaseName
Specifies the logon name for the database used to create the report.
Assigns this value to the CRPELogOnInfo::m_databaseName
member.
userID
Specifies the user I.D. necessary to log on to the server. Assigns this
value to the CRPELogOnInfo::m_userID member.
password
Specifies the password necessary to log on to the server. Assigns this
value to the CRPELogOnInfo::m_password member.

Remarks Constructs a CRPELogOnInfo structure object. Call the constructor

with no parameters to allow the Class Library to initialize all
member variables with default values. Pass parameters to the
constructor to assign specific values to each member variable.

Class CRPELogOnInfo

structure CRPEJobInfo

This structure is used by the CRPEJob::GetJobStatus member

function. Status information concerning the job is returned through
this structure.

Data Members m_numRecordsRead

Specifies the number of records actually processed.
m_numRecordsSelected
Specifies the number of records selected for inclusion in the report
out of the total number of records read.
m_numRecordsPrinted
Specifies the number of records actually printed.

Chapter 4, Report Engine Class Library Reference 211

 m_displayPageN
Specifies the page number of the currently displayed page in the
Preview Window.
m_latestPageN
Specifies the number of the last page that is currently available. Once
the printing is complete, this value is the number of the last page.
m_startPageN
Specifies the number of the starting page. The value is normally 1.
m_printEnded
Specifies whether or not the printing process is completed.

Construction CRPEJobInfo
Constructs a CRPEJobInfo structure type.

Related Topics
PEJobInfo 676

CRPEJobInfo::CRPEJobInfo

CRPEJobInfo ();

Remarks Constructs a CRPEJobInfo structure object. Initializes all required

members of the structure.

Class CRPEJobInfo

structure CRPETableType

This structure is used to determine information about a specific table

used in the report. It is used by the
CRPEJob::GetNthTableSessionInfo.

Data Members m_dllName

Specifies the name of the appropriate database DLL for the table of
interest.

212 Crystal Reports Developer’s Reference

 m_descriptiveName
Specifies the name of the table of interest.
m_dbType
Specifies the type of database that contains the table of interest.

Construction CRPETableType
Constructs a CRPETableType structure type.

Related Topics
PETableType 698

CRPETableType::CRPETableType

CRPETableType ();

Remarks Constructs a CRPETableType structure object. Initializes all

members of the structure.

Class CRPETableType

structure CRPESessionInfo

This structure is used to get and set the session information (user id
and password) for password protected Microsoft Access databases.
It is used with the CRPEJob::GetNthTableSessionInfo and
CRPEJob::SetNthTableSessionInfomember functions.

Data Members m_userID

Specifies the user I.D. needed for logging on to the MS Access
system.
m_password
Specifies the password needed for logging on to the MS Access
system.
m_sessionHandle
The handle to the current MS Access session.

Chapter 4, Report Engine Class Library Reference 213

Construction CRPESessionInfo
Constructs a CRPESessionInfo structure type.

Related Topics
PESessionInfo 693

CRPESessionInfo::CRPESessionInfo

CRPESessionInfo ();
CRPESessionInfo (const char *userID, const char *password,
DWORD sessionHandle);

Parameters userID
Specifies the user I.D. needed for logging on to the MS Access
system. Assigns this value to the CRPESessionInfo::m_userID
member.
password
Specifies the password needed for logging on to the MS Access system.
Assigns this value to the CRPESessionInfo::m_password member.
sessionHandle
The handle to the current MS Access session. Assigns this value to
the CRPESessionInfo::m_sessionHandle member.

Remarks Constructs a CRPESessionInfo structure object. Call the constructor

with no parameters to allow the Class Library to initialize all
member variables with default values. Pass parameters to the
constructor to assign specific values to each member variable.

Class CRPESessionInfo

structure CRPETableLocation

This structure is used to get and set table location information. It is

used with the CRPEJob::GetNthTableLocation and
CRPEJob::SetNthTableLocation functions.

214 Crystal Reports Developer’s Reference

Data Members m_location
Specifies the database location.

Construction CRPETableLocation
Constructs a CRPETableLocation structure type.

Related Topics
PETableLocation 696

CRPETableLocation::CRPETableLocation

CRPETableLocation ();
CRPETableLocation (const char *location);

Parameters location
Specifies the database location. Assigns this value to the
CRPETableLocation::m_location member.

Remarks Constructs a CRPETableLocation structure object. Call the

constructor with no parameters to allow the Class Library to
initialize all member variables with default values. Pass parameters
to the constructor to assign specific values to each member variable.

Class CRPETableLocation

structure CRPEPrintOptions

This structure is used to set the print characteristics of a report. It is

used with the CRPEJob::SetPrintOptions member function.

Data Members m_startPageN

Specifies the first page that you want to print.
m_stopPageN
Specifies the last page that you want to print.

Chapter 4, Report Engine Class Library Reference 215

 m_nReportCopies
Specifies the number of copies that you want to print.
m_collation
Indicates whether or not you want the copies of the report to be
collated (if you are printing multiple copies of a multiple page report.

Construction CRPEPrintOptions
Constructs a CRPEPrintOptions structure type.

Related Topics
PEPrintOptions 688

CRPEPrintOptions::CRPEPrintOptions

CRPEPrintOptions ();
CRPEPrintOptions (unsigned short startPageN, unsigned short
stopPageN, unsigned short nReportCopies, unsigned short
collation);

Parameters startPageN
Specifies the first page that you want to print. Assigns this value to
the CRPEPrintOptions::m_startPageN member.
stopPageN
Specifies the last page that you want to print. Assigns this value to
the CRPEPrintOptions::m_stopPageN member.
nReportCopies
Specifies the number of copies that you want to print. Assigns this
value to the CRPEPrintOptions::m_nReportCopies member.
collation
Indicates whether or not you want the copies of the report to be
collated (if you are printing multiple copies of a multiple page report.
Assigns this value to the CRPEPrintOptions::m_collation member.

216 Crystal Reports Developer’s Reference

 Possible values are:

PEP_UNCOLLATED Prints multiple copies of a

multiple page report
uncollated (Page order =
1,1,1,2,2,2,3,3,3,etc.
PEP_COLLATED Prints multiple copies of a
multiple page report collated
(Page order = 1,2,3...,1,2,3...,
etc.
PEP_DEFAULTCOLLATION Prints multiple copies of a
multiple page report using the
collation settings specified in
the report.

Remarks Constructs a CRPEPrintOptions structure object. Call the constructor

with no parameters to allow the Class Library to initialize all
member variables with default values. Pass parameters to the
constructor to assign specific values to each member variable.

Class CRPEPrintOptions

structure CRPEExportOptions

This structure is used to get and set the export options of a print job.
It is used by member functions CRPEJob::GetExportOptions and
CRPEJob::ExportTo.

Data Members m_formatDLLName

Specifies the name of the format DLL that contains the export format
to be used.
m_formatType
Specifies the export format to be used.
m_formatOptions
Provides additional export information specific to the format type
being used.

Chapter 4, Report Engine Class Library Reference 217

 m_destinationDLLName
Specifies the name of the destination DLL that contains the
destination type to be used.
m_destinationType
Specifies the destination type of the exported report.
m_destinationOptions
Provides additional information specific to the export destination
type.
m_nFormatOptionsBytes
Automatically assigned by CRPEjob::GetExportOptions. Unused
by CRPEJob::SetExportOptions.
m_nDestinationOptionsBytes
Automatically assigned by CRPEjob::GetExportOptions. Unused
by CRPEJob::SetExportOptions.

Construction CRPEExportOptions
Constructs a CRPEExportOptions structure type.

Related Topics
PEExportOptions 662

CRPEExportOptions::CRPEExportOptions

CRPEExportOptions ();
CRPEExportOptions (const char *formatDLLName, DWORD
formatType, void *formatOptions, const char *destinationDLLName,
DWORD destinationType, void *destinationOptions);

Parameters formatDLLName
Specifies the name of the format DLL that contains the export format
to be used. Assigns this value to the
CRPEExportOptions::m_formatDLLName member.

218 Crystal Reports Developer’s Reference

 Select a DLL from the following table:

To export a report in this

format: Use this DLL:

Crystal Reports Format uxfcr.dll

Data Interchange Format uxfdif.dll
Word for Windows Format uxfwordw.dll
Word for DOS Format uxfdoc.dll
WordPerfect Format uxfdoc.dll
Quattro Pro 5.0 (WB1) Format uxfqp.dll
Record Style Format (columns) uxfrec.dll
Rich Text Format uxfrtf.dll
Comma Separated Values uxfsepv.dll
(CSV)
Tab Separated Values uxfsepv.dll
Character Separated Values uxfsepv.dll
Text Format (ASCII) uxftext.dll
Tab Separated Text Format uxftext.dll
Lotus 1-2-3 (WKS) uxfwks.dll
Lotus 1-2-3 (WK1) uxfwks.dll
Lotus 1-2-3 (WK3) uxfwks.dll
Excel 2.1 uxfxls.dl
Excel 3.0 uxfxls.dll
Excel 4.0 uxfxls.dll

formatType
Specifies the export format to be used. Assigns this value to the
CRPEExportOptions::m_formatType member. Select from the
following values:

To export a report in this

Use this for formatType:
format:
Crystal Reports Format UXFCrystalReportType
Data Interchange Format UXFDIFType
Word for Windows Format UXFWordWinType
Word for DOS Format UXFWordDosType
WordPerfect Format UXFWordPerfectType
Quattro Pro 5.0 (WB1) Format UXFQP5Type

Chapter 4, Report Engine Class Library Reference 219

 Record Style Format (columns) UXFRecordType
Rich Text Format UXFRichTextFormatType
Comma Separated Values UXFCommaSeparatedType
(CSV)
Tab Separated Values UXFTabSeparatedType
Character Separated Values UXFCharSeparatedType
Text Format (ASCII) UXFTextType
Tab Separated Text Format UXFTabbedTextType
Lotus 1-2-3 (WKS) UXFLotusWksType
Lotus 1-2-3 (WK1) UXFLotusWk1Type
Lotus 1-2-3 (WK3) UXFLotusWk3Type
Excel 2.1 UXFXls2Type
Excel 3.0 UXFXls3Type
Excel 4.0 UXFXls4Type
formatOptions
Provides additional export information specific to the format type
being used. Assigns this value to the
CRPEExportOptions::m_formatOptions member. This parameter is
required for only certain format types. If you assign NULL to this
parameter, the Report Engine will automatically prompt the user for
format information if needed. Otherwise, use a format options
structure from the following table:

To export a report in
this format: Use this structure:

Data Interchange Format UXFDIFOptions

Record Style Format UXFRecordStyleOptions
(columns)
Comma Separated Values UXFCommaTabSeparatedOptions
(CSV)
Tab Separated Values UXFCommaTabSeparatedOptions
Character Separated UXFCharSeparatedOptions
Values

destinationDLLName
Specifies the name of the destination DLL that contains the
destination type to be used. Assigns this value to the
CRPEExportOptions::m_destinationDLLName member.

220 Crystal Reports Developer’s Reference

 The following options are available:

To export a report to
this destination: Use this DLL name:

Disk File uxddisk.dll

E-mail (MAPI) uxdmapi.dll
E-mail (VIM) uxdvim.dll

destinationType
Specifies the destination type of the exported report. Assigns this
value to the CRPEExportOptions::m_destinationType member. The
following values are available:

To export a report to
this destination: Use this destination type:

Disk File UXDDiskType

E-mail (MAPI) UXDMapiType
E-mail (VIM) UXDVIMType

destinationOptions
Provides additional information specific to the export destination
type. Assigns this value to the
CRPEExportOptions::m_destinationOptions member. If you assign
NULL to this parameter, the Report Engine will automatically
prompt the user for destination information when needed.
Otherwise, use a destination options structure from the following
table:

To export a report to
Use this structure:
this destination:
Disk File UXDDiskOptions
E-mail (MAPI) UXDMAPIOptions
E-mail (VIM) UXDVIMOptions

Remarks Constructs a CRPEExportOptions structure object. Call the

constructor with no parameters to allow the Class Library to
initialize all member variables with default values. Pass parameters
to the constructor to assign specific values to each member variable.

Class CRPEExportOptions

Chapter 4, Report Engine Class Library Reference 221

structure CRPESectionOptions

This structure contains specifications for formatting selected report

sections. This information is used by the methods
CRPEJob::GetSectionFormat and CRPEJob::SetSectionFormat.

Data Members m_visible

Specifies whether or not the selected section is to be visible. Use
TRUE to keep the section visible, FALSE to hide the section.
m_newPageBefore
Specifies whether or not the Report Engine is to insert a page break
before the section is printed. Use TRUE to insert a page break, FALSE
to leave it without a page break.
m_newPageAfter
Specifies whether or not the Report Engine is to insert a page break
after the section is printed. Use TRUE to insert a page break, FALSE
to leave it without a page break.
m_keepTogether
Specifies whether or not the Report Engine is to keep all lines of the
section together, either on the current page (if there is room), or on
the next page. Pass TRUE to keep the lines together, FALSE to allow
the Report Engine to split section data from one page to the next if
necessary.
m_suppressBlankLines
Specifies whether or not the Report Engine is to eliminate lines from
your report that are blank due to fields being suppressed (zeroes,
duplicates, and hidden fields). TRUE eliminates blank lines. FALSE
retains them.
m_resetPageNAfter
Specifies whether or not the Report Engine is to reset the page
number to one (1) for the following page, after it prints a group total.
Use TRUE to reset the page number, FALSE to keep standard
numbering.
m_printAtBottomOfPage
Specifies whether or not the Report Engine is to cause each group
summary value to print only at the bottom of a page. Use TRUE to
print summaries at the bottom of the page, FALSE to print
summaries immediately after the group.

222 Crystal Reports Developer’s Reference

 m_backgroundColor
Specifies the RGB color value contained in the COLORREF structure.
m_underlaySection
Indicates whether or not the specified section is to underlay the
following section(s).

Construction CRPESectionOptions
Constructs a CRPESectionOptions structure type.

Related Topics
PESectionOptions 690

CRPESectionOptions::CRPESectionOptions

CRPESectionOptions ();
CRPESectionOptions (short visible, short newPageBefore, short
newPageAfter, short keepTogether, short suppressBlankLines, short
resetPageNAfter, short printAtBottomOfPage, COLORREF
backgroundColour, short underlaySection);

Parameters visible
Specifies whether or not the selected section is to be visible. Use
TRUE to keep the section visible, FALSE to hide the section. Assigns
this value to the CRPESectionOptions::m_visible member.
newPageBefore
Specifies whether or not the Report Engine is to insert a page break
before the section is printed. Use TRUE to insert a page break, FALSE
to leave it without a page break. Assigns this value to the
CRPESectionOptions::m_newPageBefore member.
newPageAfter
Specifies whether or not the Report Engine is to insert a page break after
the section is printed. Use TRUE to insert a page break, FALSE to leave it
without a page break. Assigns this value to the
CRPESectionOptions::m_newPageAfter member.
keepTogether
Specifies whether or not the Report Engine is to keep all lines of the section
together, either on the current page (if there is room), or on the next page.

Chapter 4, Report Engine Class Library Reference 223

 Pass TRUE to keep the lines together, FALSE to allow the Report Engine
to split section data from one page to the next if necessary. Assigns this
value to the CRPESectionOptions::m_keepTogether member.
suppressBlankLines
Specifies whether or not the Report Engine is to eliminate lines from your
report that are blank due to fields being suppressed (zeroes, duplicates,
and hidden fields). TRUE eliminates blank lines. FALSE retains them.
Assigns this value to the CRPESectionOptions::m_suppressBlankLines
member.
resetPageNAfter
Specifies whether or not the Report Engine is to reset the page number to
one (1) for the following page, after it prints a group total. Use TRUE to
reset the page number, FALSE to keep standard numbering. Assigns this
value to the CRPESectionOptions::m_resetPageNAfter member.
printAtBottomOfPage
Specifies whether or not the Report Engine is to cause each group
summary value to print only at the bottom of a page. Use TRUE to
print summaries at the bottom of the page, FALSE to print
summaries immediately after the group. Assigns this value to the
CRPESectionOptions::m_printAtBottomOfPage member.
backgroundColor
Specifies the RGB color value contained in the COLORREF structure.
Assigns this value to the CRPESectionOptions::m_backgroundColor
member.
underlaySection
Indicates whether or not the specified section is to underlay the
following section(s). Assigns this value to the
CRPESectionOptions::m_underlaySection member.

Remarks Constructs a CRPESectionOptions structure object. Call the

constructor with no parameters to allow the Class Library to
initialize all member variables with default values. Pass parameters
to the constructor to assign specific values to each member variable.
Use PEP_UNCHANGED with any parameter to let the Report
Engine leave the setting as it is specified in the report file.

Class CRPESectionOptions

224 Crystal Reports Developer’s Reference

structure CRPEGraphDataInfo

The CRPEGraphDataInfo structure contains information on what

report data is used by a graph in the report to create the values in the
graph. The structure is used by CRPEJob::GetGraphData to retrieve
information regarding an existing graph and by
CRPEJob::SetGraphData to change the data used by an existing
graph.

Data Members m_rowGroupN

Specifies which group number in the report is used to create the
values in the rows of the graph.
m_colGroupN
Specifies which group number in the report is used to create the
values in the columns of the graph.
m_summarizedFieldN
Specifies which summary field in the report is used to set the values
of the risers in the graph. Summary fields are numbered in order of
their creation.
m_graphDirection
Specifies the graphing direction for Cross-Tab reports. For normal
group/total report, the direction, is always
PE_GRAPH_COLS_ONLY.

Construction CRPEGraphDataInfo
Constructs a CRPEGraphDataInfo structure type

Related Topics
PEGraphDataInfo 668

CRPEGraphDataInfo::CRPEGraphDataInfo

CRPEGraphDataInfo ();
CRPEGraphDataInfo (short rowGroupN, short colGroupN, short
summarizedFieldN, short graphDirection);

Chapter 4, Report Engine Class Library Reference 225

Parameters rowGroupN
Specifies which group number in the report is used to create the
values in the rows of the graph. Assigns this value to the
CRPEGraphDataInfo::m_rowGroupN member variable.
colGroupN
Specifies which group number in the report is used to create the
values in the columns of the graph. Assigns this value to the
CRPEGraphDataInfo::m_colGroupN member variable.
summarizedFieldN
Specifies which summary field in the report is used to set the values
of the risers in the graph. Summary fields are numbered in order of
their creation. Assigns this value to the
CRPEGraphDataInfo::m_summarizedFieldN member variable.
graphDirection
Specifies the graphing direction for Cross-Tab reports. For normal
group/total report, the direction, is always
PEP_GRAPH_COLS_ONLY. Assigns this value to the
CRPEGraphDataInfo::m_graphDirection member variable.
Possible values are:

PEP_GRAPH_ROWS_ONLY Use only row values in

graph.
PEP_GRAPH_COLS_ONLY Use only column values in
graph.
PEP_GRAPH_MIXED_ROW_COL Graph by row values,
then by column values.
PEP_GRAPH_MIXED_COL_ROW Graph by column values,
then by row values.
PEP_GRAPH_UNKNOWN_ The direction of the graph
DIRECTION is unknown.

Remarks Constructs a CRPEGraphDataInfo structure object. Call the

constructor with no parameters to allow the Class Library to
initialize all member variables with default values. Pass parameters
to the constructor to assign specific values to each member variable.

Class CRPEGraphDataInfo

226 Crystal Reports Developer’s Reference

structure CRPEGraphTextInfo

The CRPEGraphTextInfo structure contains information about the

text that appears with a graph. This structure is used with the
methods CRPEJob::GetGraphText and CRPEJob::SetGraphText

Data Members m_graphTitle

Specifies the main title text that will appear above your graph.
m_graphSubTitle
Specifies the sub title text that will appear directly under the main
title.
m_graphFootNote
Specifies the footnote text that will appear under your graph.
m_graphGroupsTitle
Specifies the title of the groups which are being graphed.
m_graphSeriesTitle
Specifies the title of the series which is being graphed.
m_graphXAxisTitle
Specifies the title text that will appear for the X axis. Not valid for Pie
graphs.
m_graphYAxisTitle
Specifies the title text that will appear for the Y axis. Not valid for Pie
graphs.
m_graphZAxisTitle
Specifies the title text that will appear for the Z axis. This value is
only valid for 3D graphs.

Construction CRPEGraphTextInfo
Constructs a CRPEGraphTextInfo structure type.

Related Topics
PEGraphTextInfo 673

Chapter 4, Report Engine Class Library Reference 227

CRPEGraphTextInfo::CRPEGraphTextInfo

CRPEGraphTextInfo ();
CRPEGraphTextInfo (const char *graphSubTitle, const char
*graphFootNote, const char *graphGroupsTitle, const char
*graphSeriesTitle, const char *graphXAxisTitle, const char
*graphYAxisTitle, const char *graphZAxisTitle);

Parameters graphTitle
Specifies the main title text that will appear above your graph.
Assigns this title to the CRPEGraphTextInfo::m_graphTitle
member variable.
graphSubTitle
Specifies the sub title text that will appear directly under the main
title. Assigns this title to the
CRPEGraphTextInfo::m_graphSubTitle member variable.
graphFootNote
Specifies the footnote text that will appear under your graph.
Assigns this text to the CRPEGraphTextInfo::m_graphFootNote
member variable.
graphGroupsTitle
Specifies the title of the groups which are being graphed. Assigns
this title to the CRPEGraphTextInfo::m_graphGroupsTitle member
variable.
graphSeriesTitle
Specifies the title of the series which is being graphed. Assigns this
title to the CRPEGraphTextInfo::m_graphSeriesTitle member
variable.
graphXAxisTitle
Specifies the title text that will appear for the X axis. Not valid for Pie
graphs. Assigns this title to the
CRPEGraphTextInfo::m_graphXAxisTitle member variable.
graphYAxisTitle
Specifies the title text that will appear for the Y axis. Not valid for Pie
graphs. Assigns this title to the
CRPEGraphTextInfo::m_graphYAxisTitle member variable.

228 Crystal Reports Developer’s Reference

 graphZAxisTitle
Specifies the title text that will appear for the Z axis. Only valid for
3D graphs. Assigns this title to the
CRPEGraphTextInfo::m_graphZAxisTitle member variable.

Remarks Constructs a CRPEGraphTextInfo structure object. Call the

constructor with no parameters to allow the Class Library to
initialize all member variables with default values. Pass parameters
to the constructor to assign specific values to each member variable.

Class CRPEGraphTextInfo

structure CRPEGraphOptions

The CRPEGraphOptions structure contains information on several

options available with graphs and charts. This structure is used by
CRPEJob::GetGraphOptions to find out what options have been set
for a graph, and it is used by CRPEJob::SetGraphOptionsto change
the options for a graph.

Data Members m_graphMaxValue

Specifies the maximum value that will appear in the graph. Any
graph values above this value are not charted.
m_graphMinValue
Specifies the minimum value that will appear in the graph. Any
graph values below this value are not charted.
m_showDataValue
Specifies whether or not to display the numerical value associated
with each riser on the chart. If set to TRUE (1), a value appears in the
graph for each riser.
m_showGridLine
Specifies whether or not to display grid lines on the graph.
m_verticalBars
Specifies whether to display the bars in a bar graph vertically or
horizontally.
m_showLegend
Specifies whether or not to display the graph legend.

Chapter 4, Report Engine Class Library Reference 229

 m_fontFaceName
Specifies the font for all text and values in the entire graph.

Construction CRPEGraphOptions
Constructs a CRPEGraphOptions structure type.

Related Properties
PEGraphOptions 671

CRPEGraphOptions::CRPEGraphOptions

CRPEGraphOptions ();
CRPEGraphOptions (double graphMaxValue, double graphMinValue,
BOOL showDataValue, BOOL showGridLine, BOOL verticalBars,
BOOL showLegend, const char *fontFaceName);

Parameters graphMaxValue
Specifies the maximum value that will appear in the graph. Any
graph values above this value are not charted. Assigns this value to
the CRPEGraphOptions::m_graphMaxValue member variable.
graphMinValue
Specifies the minimum value that will appear in the graph. Any
graph values below this value are not charted. Assigns this value to
the CRPEGraphOptions::m_graphMinValue member variable.
showDataValue
Specifies whether or not to display the numerical value associated
with each riser on the chart. If set to TRUE, a value appears in the
graph for each riser. Assigns this value to the
CRPEGraphOptions::m_showDataValue member variable.
showGridLine
Specifies whether or not to display grid lines on the graph. Assigns
this value to the CRPEGraphOptions::m_showGridLine member
variable.
verticalBars
Specifies whether to display the bars in a bar graph vertically or
horizontally. Assigns this value to the
CRPEGraphOptions::m_verticalBars member variable.

230 Crystal Reports Developer’s Reference

 showLegend
Specifies whether or not to display the graph legend. Assigns this
value to the CRPEGraphOptions::m_showLegend member
variable.
fontFaceName
Specifies the font for all text and values in the entire graph. Assigns
this value to the CRPEGraphOptions::m_fontFaceName member
variable.

Remarks Constructs a CRPEGraphOptions structure object. Call the

constructor with no parameters to allow the Class Library to
initialize all member variables with default values. Pass parameters
to the constructor to assign specific values to each member variable.

Class CRPEGraphOptions

structure CRPEParameterFieldInfo

The CRPEParameterFieldInfo structure contains information related

to parameter fields in a report. This structure is used by
CRPEJob::GetNthParameterField to get information about a specific
parameter field, and it is used by CRPEJob::SetNthParameterField to
change a specific parameter field.

Data Members m_ValueType

Specifies the data type of the parameter field. The Report Engine
supports the following data types: number, currency, Boolean, date,
and string. Use the appropriate constant from the list below.

Data Type Constant

Number PEP_PF_NUMBER
Currency PEP_PF_CURRENCY
Boolean PEP_PF_BOOLEAN
Date PEP_PF_DATE
String PEP_PF_STRING
Date/Time PEP_PF_DATETIME
Time PEP_PF_TIME

Chapter 4, Report Engine Class Library Reference 231

 m_DefaultValueSet
Indicates whether or not a default value was set for the parameter
field when the parameter field was created or modified in Crystal
Reports. The value can be either TRUE (1) if the field was given a
default value or FALSE (0) if it was not.
m_CurrentValueSet
If CRPEJob::Start has not been called, this parameter will equal 0
(FALSE). Since the print job hasn’t been started, there is no current
value set by code or by the user.
If PEStartPrintJob has been called, and the user has entered a
parameter and said OK to the prompt, this parameter will equal 1
(TRUE) if the user enters a value at the prompt and 0 (FALSE) if the
user clicks Cancel.
m_Name
Specifies the name of the parameter field assigned by the user when
the parameter was inserted into the report or the name that was set
from code using CRPEJob::SetNthParameterField.
m_Prompt
Specifies the prompting text, if any, that appears when the user runs
the report for the first time or refreshes the data. This will be either
the prompt assigned by the user when the parameter field was
inserted into the report or the prompt that was set from code using
CRPEJob::SetNthParameterField.
m_DefaultValue
Specifies the default value assigned to the parameter field if one was
set. If the m_DefaultValueSet member is FALSE, this value is
meaningless.
m_CurrentValue
If CRPEJob::Start has not been called, this value does not apply.
There is no current value as yet set by code or by the user.
If CRPEJob::Start has been called, this will be the value entered by the
user when the user was prompted. If the user clicked Cancel, this
value is meaningless.

Construction CRPEParameterFieldInfo
Constructs a CRPEParameterFieldInfo structure type.

232 Crystal Reports Developer’s Reference

 Related Topics
PEParameterFieldInfo 680

CRPEParameterFieldInfo::CRPEParameterFieldInfo

CRPEParameterFieldInfo ();
CRPEParameterFieldInfo (WORD ValueType, WORD
DefaultValueSet, WORD CurrentValueSet, const _TCHAR *Name,
const _TCHAR *Prompt, const _TCHAR *DefaultValue, const
_TCHAR *CurrentValue);

Parameters ValueType
Specifies the data type of the parameter field. The Report Engine
supports the following data types: number, currency, Boolean, date,
and string. Assigns this value to the
CRPEParameterFieldInfo::m_ValueType member variable.
Use the appropriate constant from the list below.

Data Type Constant

Number PEP_PF_NUMBER
Currency PEP_PF_CURRENCY
Boolean PEP_PF_BOOLEAN
Date PEP_PF_DATE
String PEP_PF_STRING
Date/Time PEP_PF_DATETIME
Time PEP_PF_TIME

DefaultValueSet
Specifies whether or not a default value is set for the parameter field.
The value can be either TRUE (1) if you want to change the default
value or FALSE (0) if you do not. Assigns this value to the
CRPEParameterFieldInfo::m_DefaultValueSet member variable.
CurrentValueSet
Indicates whether or not a new value is being assigned to the
parameter field. Use TRUE (1) to indicate that a new value is set,
FALSE (0) to indicate no change. Assigns this value to the
CRPEParameterFieldInfo::m_CurrentValueSet member variable.

Chapter 4, Report Engine Class Library Reference 233

 Name
Specifies the name of the parameter field to be assigned a new value.
Assigns this value to the CRPEParameterFieldInfo::m_Name
member variable.
Prompt
Specifies the prompting text, if any, that will appear when the user
runs the report for the first time or refreshes the data. Assigns this
value to the CRPEParameterFieldInfo::m_Prompt member variable.
DefaultValue
Sets the default value assigned to the parameter field. If the
DefaultValueSet member is FALSE, this value is meaningless.
Assigns this value to the
CRPEParameterFieldInfo::m_DefaultValue member variable.
CurrentValue
Assigns a value to the parameter field. If CurrentValueSet is FLASE,
this value is meaningless. Assigns this value to the
CRPEParameterFieldInfo::m_CurrentValue member variable.

Remarks Constructs a CRPEParameterFieldInfo structure object. Call the

constructor with no parameters to allow the Class Library to
initialize all member variables with default values. Pass parameters
to the constructor to assign specific values to each member variable.

Class CRPEParameterFieldInfo

structure CRPEParameterInfo

The CRPEParameterInfo structure contains information about a

parameter for a stored procedure in a SQL database. This structure is
used by CRPEJob::GetNthParamInfo.

Data Members m_Type

Specifies the data type of the parameter. The Report Engine supports
the following data types: number, currency, Boolean, date, and
string. Use the appropriate constant from the list below.

234 Crystal Reports Developer’s Reference

 Data Type Constant
Number PEP_PF_NUMBER
Currency PEP_PF_CURRENCY
Boolean PEP_PF_BOOLEAN
Date PEP_PF_DATE
String PEP_PF_STRING
Date/Time PEP_PF_DATETIME
Time PEP_PF_TIME

m_Name
Specifies the name of the parameter in a null-terminated string.

Construction CRPEParameterInfo
Constructs a CRPEParameterInfo structure type.

Related Topics
PEParameterInfo 685

CRPEParameterInfo::CRPEParameterInfo

CRPEParameterInfo();

Remarks Constructs a CRPEParameterInfo structure object. Assigns default

values to the members of the structure.

Class CRPEParameterInfo

structure CRPESubreportInfo

The CRPESubreportInfo structure contains information on a

subreport that appears in the main report. This structure is used by
CRPEJob::GetSubreportInfo to retrieve information about a subreport.

Data Members m_name

Specifies the name of the subreport. This is the name assigned to the
subreport when it was first created.

Chapter 4, Report Engine Class Library Reference 235

Construction CRPESubreportInfo
Constructs a CRPESubreportInfo structure type.

Related Topics
PESubreportInfo 695

CRPESubreportInfo::CRPESubreportInfo

CRPESubreportInfo();

Remarks Constructs a CRPESubreportInfo structure object. Assigns default

values to the members of the structure.

Class CRPESubreportInfo

Report Engine Classes

class CRPEngine : public CObject

The CRPEngine class is designed so that there should only be one

CRPEngine object in the entire application. The CRPEngine object
contains methods that are common to all print jobs (e.g. SQL connections,
version information, etc.). More importantly, it is responsible for creating
and managing all CRPEJob objects. It is the CRPEJob object that allows
you access to the attributes of a print job.
In order to open a particular report it is first necessary to have an open
Report Engine object in the application. You may then call the
CRPEngine::OpenPrintJob member function specifying the report file
name to open. If successful, you will be returned a pointer to a CRPEJob
object.

Construction CRPEngine
Constructs a CRPEngine object.

236 Crystal Reports Developer’s Reference

class CRPEJob : public CObject

In order to open a particular report it is first necessary to have an open

Report Engine object in the application. You may then call the
CRPEngine::OpenPrintJob member function specifying the report file
name to open. If successful, you will be returned a pointer to a CRPEJob
object. It is through this object that you may modify the print job attributes
as well as output the report in various formats. Almost all of these
methods correspond to similar functions available in the Crystal Report
Engine API. Full documentation on what these methods are used for are
available in the Crystal Reports Developers Reference manual as well as
the on-line help in Crystal Reports.

Construction CRPEJob
Constructs a CRPEJob object. Used internally by
CRPEngine::OpenJob.

CRPEngine::CRPEngine

CRPEngine(BOOL open);

Parameters open
Indicates whether or not the Report Engine should be opened when
the CRPEngine object is created.

Remarks This is the constructor for the class. If open is true, the actual Crystal
Reports DLL is opened (crpe32.dll). Print jobs may only be opened if
the engine itself is open. If originally opened with open = FALSE, the
engine may be opened later with the CRPEngine::Open method.

Class CRPEngine

Chapter 4, Report Engine Class Library Reference 237

CRPEngine::Open

BOOL Open();

Remarks This method opens the Crystal Report Engine. This method is only
necessary if you constructed the CRPEngine object with the open
parameter equal to FALSE. If you set the open parameter to TRUE when
you constructed the CRPEngine object, this method is unnecessary.

Return Value Returns TRUE if the Report Engine was opened successfully, FALSE
if something went wrong.

Class CRPEngine

Related Topics
CRPEngine::CRPEngine 237
PEOpenEngine 536

CRPEngine::Close

void Close();

Remarks This method closes the Crystal Report Engine.

Class CRPEngine

Related Topics
PECloseEngine 438

238 Crystal Reports Developer’s Reference

CRPEngine::GetVersion

short GetVersion(short versionRequested);

Parameters versionRequested
Specifies whether the version number of the Report Engine or the
Report Engine DLL is being requested. Possible values are:

PEP_GV_DLL Returns the version of the DLL.

PEP_GV_ENGINE Returns the version of the Report
Engine.

Remarks This method returns the version number of the Report Engine dll
(crpe32.dll) or the version of the Report Engine itself. The high-order
byte is the major version number and the low-order byte is the minor
version number.
This method can be used whenever you build functionality into a
report that may not be available in earlier versions of the Report
Engine and you need to verify the version number first. The function
can be a handy safeguard for users who have more than one version
of the Report Engine with the older version earlier in the path than
the new version.

Return Value The version number of the currently used Report Engine or Report
Engine DLL.

Class CRPEngine

Related Properties
PEGetVersion 524

CRPEngine::GetEngine

static CRPEngine *GetEngine();

Remarks This method may be used to get a pointer to the current CRPEngine
object being used in the application.

Chapter 4, Report Engine Class Library Reference 239

Return Value A pointer to the current CRPEngine object.

Class CRPEngine

CRPEngine::GetEngineStatus

static Status GetEngineStatus();

Remarks This method may be used to get the current engine status. Possible
values returned are:
engineOpen
The Report Engine is currently open.
engineClosed
The Report Engine has been closed, or is not yet open.
engineMissing
No Report Engine is available. Make sure the Report Engine DLL is
located in a directory that appears in your PATH.

Return Value A value of the Status enumerated type. Indicates the current status of
the Report Engine.

Class CRPEngine

CRPEngine::OpenJob

CRPEJob *OpenJob(const char *reportFileName);

Parameters reportFileNameThe name and path (if necessary) of the report file
being opened for the specified print job.

Remarks This method opens the report specified by reportFileName. A

pointer to a CRPEJob object is returned. Print job attributes may be
referenced through this object.

Return Value A pointer to a CRPEJob object for the opened print job.

240 Crystal Reports Developer’s Reference

Class CRPEngine

Related Properties
PEOpenPrintJob 537

CRPEngine::PrintReport

short PrintReport(const char *reportFilePath, BOOL toPrinter, BOOL

toWindow, const char *title, int left, int top, int width, int height,
DWORD style, CWnd *parentWindow);

Parameters reportFilePath
Specifies the name and path of the report to be printed.
toPrinter
Specifies whether or not the report is to be sent to the default printer.
toWindow
Specifies whether or not the report is to be displayed in a Preview
Window.
title
Specifies the title you want to appear in the title bar if the report is
being sent to a Preview Window.
left
Specifies the x coordinate of the upper left hand corner of the
Preview Window, in device coordinates.
top
Specifies the y coordinate of the upper left hand corner of the
Preview Window, in device coordinates.
width
Specifies the width of the Preview Window, in device coordinates.
height
Specifies the height of the Preview Window, in device coordinates.
style
Specifies the style of the window being created. Style setting can be
combined using the bitwise "OR" operator. Refer to the CWnd class
in the Microsoft Foundation Class Library reference for possible
window styles.

Chapter 4, Report Engine Class Library Reference 241

 parentWindow
Specifies a pointer to the CWnd object for the window that is the
parent of the Preview Window. Specify NULL if the Preview
Window will not have a parent window.

Remarks This method provides a quick but limited way to print a report. The
report may only be output to a printer or Preview Window. Use this
class method any time you simply want to print a report from an
application without giving the user the ability to customize the
report.

Return Value 0 if the call is successful. Returns an error code if something goes
wrong.

Class CRPEngine

Related Topics
PEPrintReport 549

CRPEngine::LogOnServer

BOOL LogOnServer(const char *dllName, const CRPELogOnInfo

*logOnInfo);

Parameters dllName
Specifies the name of the Crystal Reports DLL for the server or
password protected non-SQL table you want to log onto.
logOnInfo
Specifies a pointer to a CRPELogOnInfo structure.

Remarks This method opens a connection to a SQL server. More than one print
job may use this connection to a SQL server. Information required to
establish a connection is provided through the CRPELogOnInfo.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

242 Crystal Reports Developer’s Reference

Class CRPEngine

Related Topics
PELogOnServer 531

CRPEngine::LogOffServer

BOOL LogOffServer(const char *dllName, const CRPELogOnInfo

*logOnInfo);

Parameters dllName
Specifies the name of the Crystal Reports DLL for the server or
password protected non-SQL table you want to log onto.
logOnInfo
Specifies a pointer to a CRPELogOnInfo structure.

Remarks This method closes an existing connection to a SQL server. Connection

information is provided through the CRPELogOnInfo structure.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEngine

Related Topics
PELogOffServer 529

CRPEngine::LogOnSQLServerWithPrivateInfo

BOOL LogOnSQLServerWithPrivateInfo (const char *dllName, void

*privateInfo);

Parameters dllName
Specifies the name of the Crystal Reports DLL that was used when
establishing a connection to the Server when the report was first
created. For example, if a report was created using an ODBC data

Chapter 4, Report Engine Class Library Reference 243

 source, specify the filename "PDSODBC.DLL". For more information
on possible database DLLs, refer to Runtime File Requirements.
privateInfo
Specifies the application’s handle to the Server connection. In your
application, a connection to the Server must already be established
before this method is called. Pass the HDBC (handle to a database
connection) from this connection to the privateInfo parameter.

Remarks Use this class method to allow the Crystal Report Engine to
"piggyback" your application’s existing connection to a Server. This
lowers the number of connections established by a workstation,
reducing application time and network traffic. It also prevents a
Crystal Reports Log Off call from disconnecting an application’s
existing connection to the Server.
The CRPEngine::LogOnSQLServerWithPrivateInfo method can
only be used with database connections established by ODBC or
Q+E Library 2.0. Any other database connections can not be accessed
by this method.
To obtain an HDBC for an ODBC connection, use the following
function calls (see the ODBC SDK 2,0 manual for more information):

SQLAllocEnv initializes the ODBC call level interface

and allocates memory for an
environment handle.
SQLAllocConnect returns an ODBC HDBC

To obtain an HDBC for a Q+E Library connection, use the following

function calls (see the InterSolv DataDirect Developer’s Toolkit for
more information):

qeConnect opens a connection to the server

qeGetODBCHdbc returns the ODBC HDBC

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEngine

244 Crystal Reports Developer’s Reference

CRPEngine::CanClose

BOOL CanClose ();

Remarks Checks to see whether or not the Report Engine is busy. Errors can
occur in your application or on a system if you attempt to close the
Report Engine while it is processing a print job. Use this method
before attempting to close the Report Engine in an application (for
example, when the user tries to exit) to determine if the Report
Engine can be closed safely.

Return Value TRUE if the Report Engine can be closed, FALSE if the Report Engine
is still busy.

Class CRPEngine

CRPEngine::GetNPrintJobs

int GetNPrintJobs ();

Remarks This method returns the number of print job (CRPEJob) objects that
currently exist for the current CRPEngine object.

Return Value The number of CRPEJob objects currently open. Returns -1 if an error
occurs.

Class CRPEngine

CRPEngine::GetErrorCode

short GetErrorCode();

Remarks This method returns the current error code of the Report Engine.
When a call to another function fails, this call gets the error code that
was generated so you can take some action based on that error code.

Chapter 4, Report Engine Class Library Reference 245

Return Value The current Report Engine error code. 0 if no error has occurred.

Class CRPEngine

Related Topics
PEGetErrorCode 452

CRPEngine::GetErrorText

CString GetErrorText();

Remarks This method returns a descriptive Report Engine error message.

Return Value A CString object containing the text for the current error.

Class CRPEngine

Related Topics
PEGetErrorText 453

CRPEJob::CRPEJob

CRPEJob(short jobHandle);

Parameters jobHandle
Handle to the job created by CRPEngine::OpenJob().

Remarks This is the constructor for the class. It also stores the job number
internally for future use in Report Engine API calls.
NOTE: This class constructor is automatically called by
CRPEngine::OpenJob(). Do not call this constructor from within
your own code.

Class CRPEJob

246 Crystal Reports Developer’s Reference

CRPEJob::Start

BOOL Start();

Remarks This method is used to start the processing of the print job and
display the final output of that processing. This is the method that
actually prints or exports the report.

Return Value TRUE if the job is started successfully, FALSE if something goes
wrong.

Class CRPEJob

Related Topics
PEStartPrintJob 613

CRPEJob::Close

void Close();

Remarks This method closes the print job. It also calls the destructor for the
CRPEJob object. If printing has not yet finished when this method is
called, it continues until the job is completely printed. If the Preview
Window is open, it stays open.

Class CRPEJob

Related Topics
PEClosePrintJob 439

CRPEJob::Cancel

void Cancel();

Remarks This method cancels processing of a print job. It can be tied to a

control that allows the user to cancel a print job in progress.

Chapter 4, Report Engine Class Library Reference 247

Class CRPEJob

Related Topics
PECancelPrintJob 431

CRPEJob::GetJobStatus

short GetJobStatus(CRPEJobInfo *jobStatus);

Parameters jobStatus
A pointer to a CRPEJobInfo structure.

Remarks This method gets the current status of the print job. You can use it in
a number of programming situations, for example:
● to trigger error messages, i.e., when a print job fails (due to
insufficient memory, insufficient disk space, etc.) or,
● to trigger screen displays (hourglass, series of graphics, etc.) that
confirm to the user that work is in progress.
● to find out whether a job was cancelled by the user after
CRPEJob::Start was called.

Return Value Returns one of the following values according to the status of the
current print job:

-1 The Report Engine has not been

opened, or a print job has not been
established.
PEP_JOBNOTSTARTED The job has not been started.
PEP_JOBINPROGRESS The job is currently in progress.
PEP_JOBCOMPLETED The job has completed successfully.
PEP_JOBFAILED The job has failed.
PEP_JOBCANCELLED The job has been cancelled by the
user.

Class CRPEJob

248 Crystal Reports Developer’s Reference

 Related Topics
PEGetJobStatus 471

CRPEJob::IsJobFinished

BOOL IsJobFinished();

Remarks This method returns a Boolean value that indicates whether or not
processing has finished for the print job. You can use this method any
time you have a call that is contingent on a print job being finished.

Return Value TRUE if processing has finished, FALSE if the job is in progress.

Class CRPEJob

Related Topics
PEIsPrintJobFinished 528

CRPEJob::GetJobHandle

short GetJobHandle();

Remarks This method returns the job handle for the print job.

Return Value The print job handle for the CRPEJob object.

Class CRPEJob

CRPEJob::ShowNextPage

BOOL ShowNextPage();

Remarks This method shows the next page in the Preview Window. Use this
method to customize how a user moves through pages in a report.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Chapter 4, Report Engine Class Library Reference 249

 Related Topics
PEShowNextPage 608

CRPEJob::ShowFirstPage

BOOL ShowFirstPage();

Remarks This method shows the first page in the Preview Window. Use this
method to customize how a user moves through pages in a report.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEShowFirstPage 608

CRPEJob::ShowPreviousPage

BOOL ShowPreviousPage();

Remarks This method shows the previous page in the Preview Window. Use
this method to customize how a user moves through pages in a
report.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEShowPreviousPage 608

CRPEJob::ShowLastPage

BOOL ShowLastPage();

Remarks This method shows the last page in the Preview Window. Use this
method to customize how a user moves through pages in a report.

250 Crystal Reports Developer’s Reference

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEShowLastPage 608

CRPEJob::ShowPrintControls

BOOL ShowPrintControls(BOOL showControls);

Parameters showControls
TRUE indicates default Print controls are to be displayed in the
Preview Window. FALSE indicates no controls are to be displayed.

Remarks This method toggles the display of the Preview Window control
buttons. Use this to display default controls, or to hide default
controls and provide customized controls.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEShowPrintControls 612

CRPEJob::ZoomPreviewWindow

BOOL ZoomPreviewWindow(short level);

Parameters level
The magnification level to which the Preview Window is to be
"zoomed". Use one of the following values:

PEP_ZOOM_FULL_SIZE Full page.

PEP_ZOOM_SIZE_FIT_ONE_SIDE Fit one side (highest
magnification).
PEP_ZOOM_SIZE_FIT_BOTH_SIDES Fit both sides.

Chapter 4, Report Engine Class Library Reference 251

Remarks This method "zooms" the Preview Window to the specified
magnification level. Use this function when the report has been
printed to a Preview Window and you need to set the magnification
of the Preview Window to a specific level.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEZoomPreviewWindow 617

CRPEJob::NextWindowMagnification

BOOL NextWindowMagnification();

Remarks This method switches to the next print window magnification in

order. Use this function to cycle through the three levels of Preview
Window magnification whenever the report has been printed to a
Preview Window. The three levels of magnification are: Full Page, Fit
One Side, and Fit Both Sides.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PENextPrintWindowMagnification 535

CRPEJob::PrintWindow

BOOL PrintWindow();

Remarks This method prints the report displayed in the Preview Window to
the printer. If you are customizing Preview Window controls, use
this method to enable the user to preview the report in the Preview

252 Crystal Reports Developer’s Reference

 Window, and then, if everything looks satisfactory, to print the
report to the printer (in response to a user event - button click, menu
command, etc.).

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEPrintWindow 552

CRPEJob::ExportPrintWindow

BOOL ExportPrintWindow(BOOL toMail);

Parameters toMail
Specifies whether or not the report file should be exported to an E-
mail address. If TRUE, the file is exported to E-mail. If FALSE, the file
is exported to a disk file.

Remarks This method exports the report displayed in the Preview Window to
a disk file or E-mail address. If you are customizing Preview
Window controls, use this method to enable the user to preview the
report in the Preview Window, and if everything looks satisfactory,
to export the report to a disk file or E-mail address (in response to a
user event - button click, menu command, etc.).

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Chapter 4, Report Engine Class Library Reference 253

CRPEJob::CloseWindow

void CloseWindow();

Remarks This method closes the Preview Window. If you are customizing
Preview Window controls, implement this method to allow the user
to close the Preview Window when finished viewing the report.

Class CRPEJob

Related Topics
PECloseWindow 441

CRPEJob::GetWindowHandle

HWND GetWindowHandle();

Remarks This method returns the Windows handle for the Preview Window.
When this method returns successfully, you can use the HWND
value with any Windows API function that requires a window
handle as a parameter.

Return Value The Windows Handle for the Preview Window.

Class CRPEJob

Related Topics
PEGetWindowHandle 525

CRPEJob::TestNthTableConnectivity

BOOL TestNthTableConnectivity(short tableN);

Parameters tableN
Specifies the number of the table for which you want to test the
connection settings. The first table added to a report is numbered 0,
the second is 1, etc.

254 Crystal Reports Developer’s Reference

Remarks This method tests to see if a valid connection exists to the database
for the specified table in the report. This method is typically used if
you plan to print at a later time, but you want to test now to make
sure everything is in order for logging on to the database table.

Return Value TRUE if the database session, log on, and location info. is all correct.
FALSE if something is wrong.

Class CRPEJob

Related Topics
PETestNthTableConnectivity 615

CRPEJob::GetNTables

short GetNTables();

Remarks This method returns the number of tables in the report.

Return Value The number of tables used in the report. Returns -1 if an error occurs.

Class CRPEJob

Related Topics
PEGetNTables 488

CRPEJob::GetNthTableType

BOOL GetNthTableType(short tableN, CRPETableType *tableType);

Parameters tableN
0 indexed table number indicating which table in the report for
which you want to determine the type.
tableType
A pointer to a CRPETableType structure.

Chapter 4, Report Engine Class Library Reference 255

Remarks This method gets table type information for the specified table.

Return Value TRUE if the call is successful, FALSE if anything goes wrong.

Class CRPEJob

Related Topics
PEGetNthTableType 507

CRPEJob::GetNthTableSessionInfo

BOOL GetNthTableSessionInfo(short tableN, CRPESessionInfo *

sessionInfo);

Parameters tableN
A 0 indexed table number indicating which MS Access table in the
report you wish to obtain the session information for.
sessionnInfo
A pointer to a CRPESessionInfo structure.

Remarks This methods gets session information for the specified Microsoft
Access table. Many MS Access database tables require that a session
be opened before the information in the table can be used. Use this
method to obtain the session information (User ID and Session
Handle) for a particular tab.

Return Value TRUE if the call is successful, FALSE if anything goes wrong.

Class CRPEJob

Related Topics
PEGetNthTableSessionInfo 505

256 Crystal Reports Developer’s Reference

CRPEJob::SetNthTableSessionInfo

BOOL SetNthTableSessionInfo(short tableN, const CRPESessionInfo

* sessionInfo, BOOL propagate);

Parameters tableN
0 indexed table number indicating which MS Access table in the
report the session is being opened for.
sessionInfo
A pointer to a CRPESessionInfo structure.
propagate
TRUE or FALSE value indicating whether the session information
should be used for opening all tables being used in the report.

Remarks This methods sets session information for the specified Microsoft
Access table. Many MS Access database tables require that a session
be opened before the table can be used. Use this method to open the
session.

Return Value TRUE if the call is successful, FALSE if anything goes wrong.

Class CRPEJob

Related Topics
PESetNthTableSessionInfo 505

CRPEJob::GetNthTableLocation

BOOL GetNthTableLocation(short tableN, CRPETableLocation

*tableLocation);

Parameters tableN
Specifies the 0 indexed number of the table for which you want to
retrieve location information.
tableLocation
A pointer to a CRPETableLocationstructure.

Chapter 4, Report Engine Class Library Reference 257

Remarks This method gets table location information for the specified table in
the report. This method is typically combined with the
CRPEJob::SetNthTableLocation method to identify the location of a
table and then to change it.

Return Value TRUE if the call is successful, FALSE if anything goes wrong.

Class CRPEJob

Related Topics
PEGetNthTableLocation 502

CRPEJob::SetNthTableLocation

BOOL SetNthTableLocation(short tableN, const CRPETableLocation

*tableLocation);

Parameters tableN
Specifies the 0 indexed number of the table for which you want to set
a new location.
tableLocation
A pointer to a CRPETableLocation structure.

Remarks This method sets table location information for the specified table in
the report. This method is typically combined with the
CRPEJob::GetNthTableLocation method to identify the location of a
table and then to change it.

Return Value TRUE if the call is successful, FALSE if anything goes wrong.

Class CRPEJob

Related Topics
PESetNthTableLocation 589

258 Crystal Reports Developer’s Reference

CRPEJob::GetNthTableLogOnInfo

BOOL GetNthTableLogonInfo(short tableN, CRPELogOnInfo

*logonInfo);

Parameters tableN
Specifies the 0 indexed number of the table from which you want to
get log on information.
logonInfo
A pointer to a CRPELogOnInfo structure.

Remarks This method gets SQL connection information for the specified table.

Return Value TRUE if the call is successful, FALSE if anything goes wrong.

Class CRPEJob

Related Topics
PEGetNthTableLogOnInfo 504

CRPEJob::SetNthTableLogOnInfo

BOOL SetNthTableLogonInfo(short tableN, const CRPELogOnInfo

*logonInfo, BOOL propagate);

Parameters tableN
Specifies the 0 indexed number of the table for which you want to set
log on information.
logonInfo
A pointer to a CRPELogOnInfo structure.
propagate
TRUE or FALSE value indicating whether the log on information
should be used for opening all tables being used in the report.

Chapter 4, Report Engine Class Library Reference 259

Remarks This method sets SQL connection information for the specified table.
The propagate flag may be used to cause the change to affect all
tables with similar server and database properties.

Return Value TRUE if the call is successful, FALSE if anything goes wrong.

Class CRPEJob

Related Topics
PESetNthTableLogOnInfo 591

CRPEJob::GetFormula

BOOL GetFormula(const char *formulaName, CString &formulaText);

Parameters formulaName
The name of the formula for which you want to retrieve the formula
string.
formulaText
The CString object passed here is loaded with the specified formula
text when CRPEJob::GetFormula completes successfully.

Remarks This method returns the formula text for the specified formula.
CRPEJob::GetFormula is often used with CRPEJob::SetFormula to
identify and then change an existing formula at print time in
response to a user selection.

Return Value TRUE if the call is successful, FALSE if the named formula does not
exist in the report.

Class CRPEJob

Related Topics
PEGetFormula 456

260 Crystal Reports Developer’s Reference

CRPEJob::SetFormula

BOOL SetFormula(const char *formulaName, const char *formulaText);

Parameters formulaName
The name of the formula for which you want to assign new formula
text.
formulaText
The actual formula text that replaces the existing formula string.

Remarks This method sets the formula text for the specified formula.
CRPEJob::SetFormula is often used with CRPEJob::GetFormula to
identify and then change an existing formula at print time in
response to a user selection.

Return Value TRUE if the call is successful, FALSE if the named formula does not
exist in the report, or there is an error in the formula.

Class CRPEJob

Related Topics
PESetFormula 563

CRPEJob::GetSelectionFormula

BOOL GetSelectionFormula(CString &formulaText);

Parameters formulaText
Specifies the existing selection formula for the report.

Remarks This method returns the formula text for the record selection
formula. CRPEJob::GetSelectionFormula is often used with
CRPEJob::SetSelectionFormula to identify and then change an
existing selection formula at print time in response to a user
selection.

Chapter 4, Report Engine Class Library Reference 261

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetSelectionFormula 519

CRPEJob::SetSelectionFormula

BOOL SetSelectionFormula(const char *formulaText);

Parameters formulaText
Specifies the new selection formula to be assigned to the report.

Remarks This method sets the formula text for the record selection formula.
CRPEJob::SetSelectionFormula is often used with
CRPEJob::GetSelectionFormula to identify and then change an
existing selection formula at print time in response to a user
selection.

Return Value TRUE if the call is successful, FALSE if something goes wrong, or
there is an error in the formula.

Class CRPEJob

Related Topics
PESetSelectionFormula 604

CRPEJob::GetGroupSelectionFormula

BOOL GetGroupSelectionFormula(CString &formulaText);

Parameters formulaText
Specifies the existing group selection formula for the report.

262 Crystal Reports Developer’s Reference

Remarks This method returns the formula text for the group selection formula.
CRPEJob::GetGroupSelectionFormula is often used with
CRPEJob::SetGroupSelectionFormula to identify and then change an
existing group selection formula at print time in response to a user
selection.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetGroupSelectionFormula 468

CRPEJob::SetGroupSelectionFormula

BOOL SetGroupSelectionFormula(const char *formulaText);

Parameters formulaText
Specifies the new group selection formula to be assigned to the
report.

Remarks This method sets the formula text for the group selection formula.
CRPEJob::SetGroupSelectionFormula is often used with
CRPEJob::GetGroupSelectionFormula to identify and then change
an existing group selection formula at print time in response to a user
selection.

Return Value TRUE if the call is successful, FALSE if something goes wrong, or
there is an error in the formula.

Class CRPEJob

Related Topics
PESetGroupSelectionFormula 575

Chapter 4, Report Engine Class Library Reference 263

CRPEJob::SetGroupCondition

BOOL SetGroupCondition(short sectionCode, const char

*conditionField, short condition, short sortDirection);

Parameters sectionCode
Specifies the code for the group section for which you want to set the
group condition. Select a section from the table below:

PEP_GROUPHEADER Sets the group condition for the

Group Header section.
PEP_GROUPFOOTER Sets the group condition for the
Group Footer section.

conditionField
Specifies the field that triggers a summary whenever its value
changes. Use the name of the field as indicated in the report file.
condition
Specifies the condition that needs to be met for Date and Boolean
fields. For all field types except Date and Boolean, use
PEP_GC_ANYCHANGE as the condition parameter.
For Date fields, select from the following:

PEP_GC_DAILY Triggers a grouping every time

the date changes.
PEP_GC_WEEKLY Triggers a grouping every time
the date changes from one week
to the next (a week runs from
Sunday through Saturday).
PEP_GC_BIWEEKLY Triggers a grouping every time
the date changes from one two-
week period to the next.
PEP_GC_SEMIMONTHLY Triggers a grouping every time
the date changes from one half-
month period to the next.
PEP_GC_MONTHLY Triggers a grouping every time
the date changes from one month
to the next.
PEP_GC_QUARTERLY Triggers a grouping every time
the date changes from one
calendar quarter to the next.

264 Crystal Reports Developer’s Reference

 PEP_GC_SEMIANNUALLY Triggers a grouping every time
the date changes from one half-
year period to the next.
PEP_GC_ANNUALLY Triggers a grouping every time
the date changes from one year
to the next.
For Boolean fields, select the condition parameter from the
following:

PEP_GC_TOYES Triggers a grouping every time the

sort and group by field changes
from No to Yes.
PEP_GC_TONO Triggers a grouping every time the
sort and group by field changes
from Yes to No.
PEP_GC_EVERYYES Triggers a grouping every time the
group and sort by field value is
Yes.
PEP_GC_EVERYNO Triggers a grouping every time the
group and sort by field value is No.
PEP_GC_NEXTISYES Triggers a grouping every time the
next value in the sort and group by
field is Yes.
PEP_GC_NEXTISNO Triggers a grouping every time the
next value in the sort and group by
field is No.

sortDirection
Specifies one of the following sort directions:

PEP_SF_ASCENDING Sorts data in ascending order (A to

Z, 1 to 9).
PEP_SF_DESCENDING Sorts data in descending order (Z
to A, 9 to 1).

Remarks This method sets the condition of the grouping for the specified
group section. This method can only replace the group condition for
an existing group. It can not create a new group. Use this function
whenever you want to change the grouping at print time, for
example, to print one report grouped in several different ways.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Chapter 4, Report Engine Class Library Reference 265

Class CRPEJob

Related Topics
PESetGroupCondition 566

CRPEJob::GetNSortFields

short GetNSortFields();

Remarks This method gets the number of sort fields in the report.

Return Value The number of sort fields defined in the report. Returns 0 (zero) if
there are no sort fields in the report. Returns -1 if an error occurs.

Class CRPEJob

Related Topics
PEGetNSortFields 485

CRPEJob::GetNthSortField

BOOL GetNthSortField(short sortFieldN, CString &field, short

*direction);

Parameters sortFieldN
Specifies the number of the sort field you want to retrieve. The first
sort field added to the report is field 0, the second is 1, etc.
field
Assigned the name of the sort field if the call completes successfully.
direction
Assigned the sort direction of the sort field if the call completes
successfully. The following values are possible:

PEP_SF_ASCENDING Sorted in ascending order (A to Z, 1

to 9).

266 Crystal Reports Developer’s Reference

 PEP_SF_DESCENDING Sorted in descending order (Z to A,
9 to 1).

Remarks This method gets the name of the sort field at the specified sort field
position and the direction in which data is sorted (ascending or
descending).

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetNthSortField 499

CRPEJob::SetNthSortField

BOOL SetNthSortField(short sortFieldN, const char *field, short

direction);

Parameters sortFieldN
Specifies the number of the sort field you want to set. The first sort
field added to the report is field 0, the second is 1, etc. If the report
has N sort fields, the function can be called with this parameter
between 0 and N-1 to replace an existing sort field. Call the function
with this parameter equal to N to add a new sort field.
field
Specifies the name of the field to be sorted.
direction
Specifies the sort direction. The following values are possible:

PEP_SF_ASCENDING Sorts in ascending order (A to Z, 1

to 9).
PEP_SF_DESCENDING Sorts in descending order (Z to A, 9
to 1).

Remarks This method sorts report data according to the specified field and
direction.

Chapter 4, Report Engine Class Library Reference 267

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetNthSortField 587

CRPEJob::DeleteNthSortField

BOOL DeleteNthSortField(short sortFieldN);

Parameters sortFieldN
Specifies the number of the sort field you want to delete. The first sort
field added to the report is field 0, the second is 1, etc.

Remarks This method deletes the specified sort field from the report. The field
is not deleted from the report, but it is removed from the list of sort
fields, and data in that field no longer appears sorted.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEDeleteNthSortField 444

CRPEJob::GetNGroupSortFields

short GetNGroupSortFields ();

Remarks Returns the number of group sort fields in the specified report. This
method is typically used as one of a series: GetNGroupSortFields
(called once), GetNthGroupSortField (called as many times as
needed to identify the correct group sort field), and
SetNthGroupSortField (called once, when the correct group sort field
is identified). The series can be used to identify and then change an

268 Crystal Reports Developer’s Reference

 existing group sort field and/or sort order at print time in response
to a user selection.

Return Value The number of group sort fields in the report. Returns 0 if there are
no group sort fields. Returns -1 if an error occurs.

Class CRPEJob

Related Topics
PEGetNGroupSortFields 479

CRPEJob::SetNthGroupSortField

BOOL SetNthGroupSortField(short sortFieldN, const char *field, short

direction);

Parameters sortFieldN
Specifies the number of the group sort field you want to set. The first
group sort field added to the report is field 0, the second is 1, etc. If
the report has N group sort fields, the function can be called with this
parameter between 0 and N-1 to replace an existing group sort field.
Call the function with this parameter equal to N to add a new group
sort field.
field
Specifies the name of the group field to be sorted.
direction
Specifies the sort direction. The following values are possible:

PEP_SF_ASCENDING Sorts in ascending order (A to Z, 1

to 9).
PEP_SF_DESCENDING Sorts in descending order (Z to A, 9
to 1).

Remarks This method sorts the specified group summary field in the specified
direction (ascending or descending). This method does not create a
new group, but will sort and existing group summary field.

Chapter 4, Report Engine Class Library Reference 269

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetNthGroupSortField 582

CRPEJob::DeleteNthGroupSortField

BOOL DeleteNthGroupSortField (short sortFieldN);

Parameters sortFieldN
Specifies the number of the group sort field you want to delete. The
first group sort field added to the report is field 0, the second is 1, etc.

Remarks This method deletes the group sort field at the specified position. The
group and group summary are not removed from the report, but the
field is removed from the list of group sort fields, and the summary
data appearing in the group field is no longer sorted.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEDeleteNthGroupSortField 443

CRPEJob::GetSQLQuery

BOOL GetSQLQuery (CString &query);

Parameters query
Assigned the text of the SQL query being sent to the server if the call
completes successfully.

270 Crystal Reports Developer’s Reference

Remarks This method retrieves the sql query that will be sent to the database
server. This method can be used with CRPEJob::SetSQLQuery to
retrieve and then change the SQL query for the report.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetSQLQuery 520

CRPEJob::SetSQLQuery

BOOL SetSQLQuery (const char *query);

Parameters query
The text of the new SQL query to be sent to the server.

Remarks This method sets the SQL query that will be sent to the database
server. This method can be used with CRPEJob::GetSQLQuery to
retrieve and then change the SQL query for the report.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetSQLQuery 606

CRPEJob::GetReportTitle

BOOL GetReportTitle (CString &title);

Parameters title
Assigned the title of the report.

Chapter 4, Report Engine Class Library Reference 271

Remarks This method gets the report title for the print job.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetReportTitle 512

CRPEJob::SetReportTitle

BOOL SetReportTitle (const char *title);

Parameters title
Specifies a new title for the report.

Remarks This method sets the report title for the print job. Use this method
whenever you need to change the title of a report at print time.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetReportTitle 598

CRPEJob::SetPrintDate

BOOL SetPrintDate (short year, short month, short day);

Parameters year
Specifies the year of the new print date.
month
Specifies the month of the new print date.

272 Crystal Reports Developer’s Reference

 day
Specifies the day of the new print date.

Remarks This method sets the print date for the report. This method does not
schedule the report to print at a different time or day, but only
changes the date that appears in any Print Date Field that appears on
the report. Use this method, for example, to post date a report when
it is printed before the day it is distributed.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetPrintDate 595

CRPEJob::SetPrintOptions

BOOL SetPrintOptions (const CRPEPrintOptions *options);

Parameters options
A pointer to a CRPEPrintOptions structure.

Remarks This method may be used to set the print characteristics of a print job.
Use this method any time you want to set the starting page number,
the ending page number, the number of report copies, and/or
collation instructions for a print job at runtime in response to user
specifications.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetPrintOptions 597

Chapter 4, Report Engine Class Library Reference 273

CRPEJob::SetNDetailCopies

BOOL SetNDetailCopies (short nCopies);

Parameters nCopies
Specifies the number of copies of the detail section of the report to be
printed.

Remarks This method sets the number of times the Details section of the report
is to be printed. For example, you can use this method to print
multiple copies of labels for a customer, multiple copies of a
purchase order, or multiple copies of anything set up in the Details
section of the report.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetNDetailCopies 580

CRPEJob::SetMargins

BOOL SetMargins (short left, short right, short top, short bottom);

Parameters left
Specifies the left margin in twips.
right
Specifies the right margin in twips.
top
Specifies the top margin in twips.
bottom
Specifies the bottom margin in twips.

274 Crystal Reports Developer’s Reference

 NOTE: For any of the above parameters, PM_SM_DEFAULT can be
used to specify that the report use default printer margins.

Remarks This method sets the page margins for the print job. Use this method
any time you want to allow the user to change margins.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetMargins 576

CRPEJob::SetMinimumSectionHeight

BOOL SetMinimumSectionHeight (short sectionCode, short height);

Parameters sectionCode
Specifies the section for which you want to specify the minimum
height.
Use one of the following values:

PEP_ALLSECTIONS Sets the minimum section

height for all sections.
PEP_HEADERSECTION Sets the minimum section
height for the Page Header
section
PEP_GROUPHEADER Sets the minimum section
height for the Group Header
section.
PEP_DETAILSECTION Sets the minimum section
height for the Details
section.
PEP_GROUPFOOTER Sets the minimum section
height for the Group Footer
section.

Chapter 4, Report Engine Class Library Reference 275

 PEP_GRANDTOTALSECTION Sets the minimum section
height for the Grand Total
section.
PEP_FOOTERSECTION Sets the minimum section
height for the Page Footer
section.
height
Specifies the minimum height in twips of the specified section.

Remarks This method sets the minimum height for the specified section. For
example, use this command whenever you want to specify a
minimum section height for printing onto preprinted forms or
printing on to any other kind of document with a fixed format.

Return Value TRUE if the call is successful, FALSE if you have specified an invalid
section or something goes wrong.

Class CRPEJob

Related Topics
PESetMinimumSectionHeight 579

CRPEJob::SetFont

BOOL SetFont (short sectionCode, short scopeCode, const char

*faceName, short fontFamily, short fontPitch, short charSet, short
pointSize, short isItalic, short isUnderlined, short isStruckOut, short
weight);

Parameters sectionCode
Specifies the section of the report for which you want to set the font.
Use one of the following values:

PEP_ALLSECTIONS Sets the line height for all

sections.
PEP_HEADERSECTION Sets the line height for the
Page Header section

276 Crystal Reports Developer’s Reference

 PEP_GROUPHEADER Sets the line height for the
Group Header section.
PEP_DETAILSECTION Sets the line height for the
Details section.
PEP_GROUPFOOTER Sets the line height for the
Group Footer section.
PEP_GRANDTOTALSECTION Sets the line height for the
Grand Total section.
PEP_FOOTERSECTION Sets the line height for the
Page Footer section.
scopeCode
Specifies whether the font selected is to apply to fields, to text, or to
both. To specify both, use the bitwise Or operator: |. The following
values are possible:

PEP_FIELDS Sets the default font for fields in the

report section specified.
PEP_TEXT Sets the default font for all text (that has
not been entered as a text field value) in
the report section specified.

faceName
Specifies the actual face name of the font you want to use. The face
name you pass can typically come from a font dialog box, be hard
coded in the application, or be chosen by the application from the
fonts supported on the printer. Example: "Times New Roman".
fontFamily
Specifies the font family for the font you want to use. Use one of the
following values:

FF_DONTCARE No font family or family does not

matter.
FF_ROMAN Variable pitch font with serifs.
FF_SWISS Fixed pitch font without serifs.
FF_MODERN Fixed pitch font, with or without serifs.
FF_SCRIPT Handwriting-like font.
FF_DECORATIVE Fancy display font.

fontPitch
Specifies the font pitch you wish to use. Use one of the following
values:

Chapter 4, Report Engine Class Library Reference 277

 DEFAULT_PITCH Retains the default pitch for the font.
FIXED_PITCH Fixed pitch, each character is the same
width.
VARIABLE_PITCH Variable pitch, the width of each
character varies.

charSet
Specifies the character set you wish to use. Use one of the following
values:

ANSI_CHARSET DEFAULT_CHARSET
SYMBOL_CHARSET SHIFTJIS_CHARSET
HANGEFUL_CHARSET CHINESEBIG5_CHARSET
OEM_CHARSET

pointSize
Specifies the desired point size for the selected font. Use 0 to indicate
no change.
isItalic
Specifies whether the font selected should be italicized. Use 1 for
italics, 0 for no italics, or PEP_UNCHANGED to leave the italics as
set up in the report.
isUnderlined
Specifies whether the font should be underlined. Use 1 to underline,
0 for no underline, or PEP_UNCHANGED to leave underline
settings as specified in the report.
isStruckOut
Specifies whether or not the font should appear struck-out. Use 1 for
strike-out, 0 for no strike out, or PEP_UNCHANGE to leave strike-
out settings as specified in the report.
weight
Specifies the weight of the font. Possible values are:

FW_DONTCARE FW_THIN
FW_EXTRALIGHT FW_LIGHT
FW_NORMAL FW_MEDIUM
FW_SEMIBOLD FW_BOLD
FW_EXTRABOLD FW_HEAVY

278 Crystal Reports Developer’s Reference

 FW_ULTRALIGHT FW_REGULAR
FW_DEMIBOLD FW_ULTRABOLD
FW_BLACK

Remarks This method sets the font and font characteristics for the specified
section. Use any time you need to change a default font at runtime in
response to user input, or to specify a built-in printer font.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetFont 557

CRPEJob::OutputToWindow

BOOL OutputToWindow (const _TCHAR *title, int left, int top, int
width, int height, int style, CWnd *parentWindow);
BOOL OutputToWindow (const char *title, int left, int top, int width,
int height, int style, CMDIFrameWnd *parentWindow);

Parameters title
Specifies the title you want to appear in the title bar.
left
Specifies the x coordinate of the upper left hand corner of the
Preview Window, in device coordinates.
top
Specifies the y coordinate of the upper left hand corner of the
Preview Window, in device coordinates.
width
Specifies the width of the Preview Window, in device coordinates.
height
Specifies the height of the Preview Window, in device coordinates.

Chapter 4, Report Engine Class Library Reference 279

 style
Specifies the style of the window being created. Style setting can be
combined using the bitwise Or operator ( | ). Refer to the CWnd class
in the Microsoft Foundation Class Library reference for possible
window styles.
parentWindow
Specifies a pointer to the CWnd object (in an SDI application) or the
CMDIFrameWnd object (in an MDI application) for the window that
is the parent of the Preview Window. Specify NULL if the Preview
Window will not have a parent window.

Remarks This method sets the output of the print job to the Preview Window
which will have the specified attributes. This method does not print
the report, but specifies that when the report is printed, it will appear
in a Preview Window. To actually print the report, use
CRPEJob::Start.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEOutputToWindow 543

CRPEJob::OutputToPrinter

BOOL OutputToPrinter (short nCopies = 1);

Parameters nCopies
Specifies how many copies of the report are to be printed. Default is
1 copy.

Remarks This method sets the output of the print job to the printer with the
specified number of copies. This method does not print the report,
but specifies that when the report is printed, it will be sent to a
printer. To actually print the report, use CRPEJob::Start.

280 Crystal Reports Developer’s Reference

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEOutputToPrinter 541

CRPEJob::SelectPrinter

BOOL SelectPrinter (const char *driverName, const char *printerName,

const char *portName, const DEVMODE *mode = 0);

Parameters driverName
Specifies the name of the printer driver for the printer being selected.
printerName
Specifies the name of the printer being selected (as indicated in the
Printers Control Panel).
portName
Specifies the name of the port the printer is attached to. For example:
"LPT1:".
mode
A pointer to a DEVMODE structure. The default implementation of
CRPEJob::SelectPrinter ignores this parameter. For more
information on the DEVMODE structure, refer to the Microsoft
Windows SDK.

Remarks This method specifies the printer and/or print characteristics for the
print job. You can use this method to enable the user to select a
printer other than the default printer at print time. One way of doing
this is to have your application call the Windows common Print
Setup dialog box.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Chapter 4, Report Engine Class Library Reference 281

 Related Topics
PESelectPrinter 554

CRPEJob::ExportTo

BOOL ExportTo (const CRPEExportOptions *options);

Parameters options
A pointer to a CRPEExportOptions structure.

Remarks This method sets the output of the print job to be exported. The
export format is specified through the options parameter. This
method does not export the report, but specifies that when the report
is printed, it will be exported to a disk file or E-mail address
according to settings in the options parameter. To actually export the
report, use CRPEJob::Start.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEExportTo 451

CRPEJob::GetExportOptions

BOOL GetExportOptions (CRPEExportOptions *options);

Parameters options
A pointer to a CRPEExportOptions structure.

Remarks This method prompts the user with a series of dialogs to specify the
export options to be used. These options are used by the Class
Library to fill in a CRPEExportOptions structure. The
CRPEJob::ExportTo function can then be used to set the print job
destination using the information in this structure.

282 Crystal Reports Developer’s Reference

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetExportOptions 455

CRPEJob::GetErrorCode

short GetErrorCode ();

Remarks This method gets the error code for the print job. When a call to
another function fails, this call gets the error code that was generated
so you can take some action based on that error code.

Return Value A Crystal Reports Class Library error code. Return 0

(PEP_NOERROR) if no error has occurred.

Class CRPEJob

Related Topics
PEGetErrorCode 452

CRPEJob::GetErrorText

CString GetErrorText ();

Remarks This method returns a descriptive error message for the print job.

Return Value A text description of the current Crystal Reports Class Library error
if an error has occurred.

Class CRPEJob

Chapter 4, Report Engine Class Library Reference 283

 Related Topics
PEGetErrorText 453

CRPEJob::PrintControlsShowing

BOOL PrintControlsShowing (BOOL *controlsShowing);

Parameters controlsShowing
Returns a pointer to a TRUE value if the print controls will be shown
in the Preview Window, FALSE if they will be hidden.

Remarks Checks if the print controls are displayed in the Preview

Window.Tab. Use CRPEJob::ShowPrintControls to change whether
or not print controls will appear in the Preview Window.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEPrintControlsShowing 548

CRPEJob::GetNFormulas

short GetNFormulas ();

Remarks Use this function to fetch the number of formulas in the report. To
fetch the formula by number, use CRPEJob::GetNthFormula.

Return Value The number of formulas in the report. If no formulas exist in the
report, 0 is returned. If an error occurs, -1 is returned.

Class CRPEJob

284 Crystal Reports Developer’s Reference

 Related Topics
PEGetNFormulas 477

CRPEJob::GetNthFormula

BOOL GetNthFormula (short formulaN, CString &formulaName,

CString &formulaText);

Parameters formulaN
Specifies the number of the formula about which you want to gather
information. The first formula added to your report is 0, the second
is 1, etc.
formulaName
Retrieves the name of the formula specified.
formulaText
Retrieves the text of the formula specified.

Remarks Use this function to obtain the formula name and formula text of a
specific formula in the report. Once the formula name is obtained,
formula text can be changed with CRPEJob::SetFormula.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetNthFormula 489

CRPEJob::CheckFormula

BOOL CheckFormula (const char *formulaName);

Parameters formulaName
The name of the formula that you need to check for errors.

Chapter 4, Report Engine Class Library Reference 285

Remarks Use this method to check a formula for validity. This method works
just like the Check button in the Formula Editor. If the named
formula contains an error, the method returns FALSE.

Return Value TRUE if the formula text is okay, FALSE if there is an error in the
formula or something goes wrong.

Class CRPEJob

Related Topics
PECheckFormula 434

CRPEJob::CheckSelectionFormula

BOOL Check SelectionFormula ();

Remarks Use this method to check the record selection formula for the report
for errors. This method works just like the Check button in the
Formula Editor. If the selection formula contains an error, the
method returns FALSE.

Return Value TRUE if the formula text is okay, FALSE if there is an error in the
formula or something goes wrong.

Class CRPEJob

Related Topics
PECheckSelectionFormula 436

CRPEJob::CheckGroupSelectionFormula

BOOL CheckGroupSelectionFormula ();

Remarks Use this method to check the group selection formula for the report
for errors. This method works just like the Check button in the
Formula Editor. If the group selection formula contains an error, the
method returns FALSE.

286 Crystal Reports Developer’s Reference

Return Value TRUE if the formula text is okay, FALSE if there is an error in the
formula or something goes wrong.

Class CRPEJob

Related Topics
PECheckGroupSelectionFormula 435

CRPEJob::GetNGroups

short GetNGroups ();

Remarks Use this method to fetch the number of group sections in the report.

Return Value The number of group sections in the report. Returns -1 if an error
occurs.

Class CRPEJob

Related Topics
PEGetNGroups 478

CRPEJob::GetGroupCondition

BOOL GetGroupCondition (short sectionCode, CString

&conditionField, short *condition, short *sortDirection)

Parameters sectionCode
Specifies the code for the report section for which you want to get the
grouping condition. Possible values are:

PEP_GROUPHEADER Sets the group condition for the

Group Header section.
PEP_GROUPFOOTER Sets the group condition for the
Group Footer section.

Chapter 4, Report Engine Class Library Reference 287

 conditionField
Specifies the name of the group summary field for which you want
to get the grouping condition.
condition
Retrieves the type of field being used as the condition field and the
condition that creates a new group.
Use one of the following masks to separate the condition type from
the group condition in the condition parameter.

PEP_GC_CONDITIONMASK Obtains the group condition

value. Use the bitwise AND
(&) to combine this mask with
the value of the condition
parameter to obtain the group
condition value
PEP_GC_TYPEMASK Obtains the type of field used
for the group condition. Use
the bitwise AND (&) to
combine this mask with the
value of the condition
parameter to obtain a
valuerepresenting the type of
field used by the group
condition.

For group condition field types other than Date and Boolean, the
group condition value of the condition parameter is
PEP_GC_ANYCHANGE.
For a group condition field of the type Date, the group condition
value will be one of the following:

PEP_GC_DAILY Triggers a grouping every time

the date changes.
PEP_GC_WEEKLY Triggers a grouping every time
the date changes from one week
to the next (a week runs from
Sunday through Saturday).
PEP_GC_BIWEEKLY Triggers a grouping every time
the date changes from one two-
week period to the next.
PEP_GC_SEMIMONTHLY Triggers a grouping every time
the date changes from one half-
month period to the next.

288 Crystal Reports Developer’s Reference

 PEP_GC_MONTHLY Triggers a grouping every time
the date changes from one month
to the next.
PEP_GC_QUARTERLY Triggers a grouping every time
the date changes from one
calendar quarter to the next.
PEP_GC_SEMIANNUALLY Triggers a grouping every time
the date changes from one half-
year period to the next.
PEP_GC_ANNUALLY Triggers a grouping every time
the date changes from one year
to the next.
For a group condition field of the type Boolean, the group condition
value will be one of the following:

PEP_GC_TOYES Triggers a grouping every time the

sort and group by field changes
from No to Yes.
PEP_GC_TONO Triggers a grouping every time the
sort and group by field changes
from Yes to No.
PEP_GC_EVERYYES Triggers a grouping every time the
group and sort by field value is
Yes.
PEP_GC_EVERYNO Triggers a grouping every time the
group and sort by field value is No.
PEP_GC_NEXTISYES Triggers a grouping every time the
next value in the sort and group by
field is Yes.
PEP_GC_NEXTISNO Triggers a grouping every time the
next value in the sort and group by
field is No.

The group condition field type portion of the condition parameter

will be one of the following values:

PEP_GC_TYPEOTHER Any field type other than Date or

Boolean. The group condition
portion of the condition
parameter will be
PEP_GC_ANYCHANGE.
PEP_GC_TYPEDATE A Date field is used to create the
group summary field.

Chapter 4, Report Engine Class Library Reference 289

 PEP_GC_TYPEBOOLEAN A Boolean field is used to create
the group summary field.
sortDirection
Obtains the sort direction for the group summary field. Possible
values are:

PEP_SF_ASCENDING Sorts data in ascending order (A to

Z, 1 to 9).
PEP_SF_DESCENDING Sorts data in descending order (Z
to A, 9 to 1).

Remarks Determines the group condition information for a selected group

section in the specified report. Use this method to find out the group
condition for a group section. Use CRPEJob::SetGroupCondition to
change the group condition once it is known.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetGroupCondition 465

CRPEJob::GetNParams

short GetNParams ();

Remarks Use this method whenever you need to know how many parameters
are required by a stored procedure in a SQL database table. This
method is usually used in conjunction with CRPEJob::GetNthParam
or CRPEJob::SetNthParam.

Return Value The number of parameters in the current stored procedure being
used to generate the report.

Class CRPEJob

290 Crystal Reports Developer’s Reference

 Related Topics
PEGetNParams 483

CRPEJob::GetNthParam

BOOL GetNthParam (short paramN, CString &paramValue);

Parameters paramN
Specifies which parameter in the stored procedure you want to get
the value of. The first parameter of a stored procedure is 0, the
second is 1, etc.
paramValue
Retrieves the current value of the specified parameter in the stored
procedure.

Remarks Gets the Nth parameter of a stored procedure. Use this method
whenever you need to find out a particular parameter required by a
stored procedure in a SQL database table.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetNthParam 494

CRPEJob::SetNthParam

BOOL SetNthParam (short paramN, const char *paramValue);

Parameters paramN
Specifies which parameter in the stored procedure you want to set
the value of. The first parameter of a stored procedure is 0, the
second is 1, etc.

Chapter 4, Report Engine Class Library Reference 291

 paramValue
Specifies the new value of the indicated parameter. This value must
be a string. Please see Remarks below.

Remarks Sets the value of a parameter in a stored procedure. Use this method
when working with stored procedures in SQL database tables to set
the value of a parameter in a stored procedure. When passing
parameter values, All parameter values must be passed as string
values. If you wish to pass a numeric value, pass the value in quotes
like this: "100".

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetNthParam 584

CRPEJob::GetPrintDate

BOOL GetPrintDate (short *year, short *month, short *day);

Parameters year
Retrieves the year for the current print date.
month
Retrieves the month for the current print date.
day
Retrieves the day for the current print date.

Remarks Determines the print date (if any) that was specified with the report.
Use this method to fetch the print date and pass back using
CRPEJob::SetPrintDate.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

292 Crystal Reports Developer’s Reference

Class CRPEJob

Related Topics
PEGetPrintDate 509

CRPEJob::GetPrintOptions

BOOL GetPrintOptions (CRPEPrintOptions *options);

Parameters options
A pointer to a CRPEPrintOptions structure.

Remarks Retrieves the print options specified for the report (the options that
are set in the Print Setup common dialog box) and uses them to fill in
the CRPEPrintOptions structure. Use this function to fetch print
options from the report in order to update them and pass back using
CRPEJob::SetPrintOptions.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetPrintOptions 510

CRPEJob::GetNDetailCopies

BOOL GetNDetailCopies (short *nCopies);

Parameters nCopies
Retrieves the current setting for the number of times the Details
section of the report will be printed.

Remarks Returns the number of copies of each Details section in the report
that are to be printed. Use this method to find out how many times

Chapter 4, Report Engine Class Library Reference 293

 each Details section of the report will be printed. To change the
number of times each Details section is printed, use
CRPEJob::SetNDetailCopies.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetNDetailCopies 476

CRPEJob::GetMargins

BOOL GetMargins (short *left, short *right, short *top, short *bottom);

Parameters left
Retrieves the current setting of the left margin in twips.
right
Retrieves the current setting of the right margin in twips.
top
Retrieves the current setting of the top margin in twips.
bottom
Retrieves the current setting of the bottom margin in twips.

Remarks Retrieves the page margin settings for the specified report. Use this
method to find out what the currently set margins for the report are.
Use CRPEJob::SetMargins to change report margins.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetMargins 473

294 Crystal Reports Developer’s Reference

CRPEJob::GetMinimumSectionHeight

BOOL GetMinimumSectionHeight (short sectionCode, short *height);

Parameters sectionCode
Specifies the code for the report section for which you want to
retrieve the minimum height. Possible values are:

PEP_ALLSECTIONS Gets the minimum section

height for all sections.
PEP_HEADERSECTION Gets the minimum section
height for the Page Header
section
PEP_GROUPHEADER Gets the minimum section
height for the Group Header
section.
PEP_DETAILSECTION Gets the minimum section
height for the Details
section.
PEP_GROUPFOOTER Gets the minimum section
height for the Group Footer
section.
PEP_GRANDTOTALSECTION Gets the minimum section
height for the Grand Total
section.
PEP_FOOTERSECTION Gets the minimum section
height for the Page Footer
section.

height
Retrieves the Nminimum height, in twips, for the specified report
section.

Remarks Retrieves minimum section height information for selected sections

in the specified report. Use this method to fetch the minimum section
height and pass back using CRPEJob::SetMinimumSectionHeight.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Chapter 4, Report Engine Class Library Reference 295

Class CRPEJob

Related Topics
PEGetMinimumSectionHeight 474

CRPEJob::GetSelectedPrinter

BOOL GetSelectedPrinter (CString &driverName, CString

&printerName, CString &portName, DEVMODE **mode);

Parameters driverName
Retrieves the name of the printer driver for the currently selected
printer in the report.
printerName
Retrieves the name of the printer currently selected in the report.
portName
Retrieves the name of the port the currently selected printer is
attached to. For example, "LPT1:".
mode
A DEVMODE structure that contains information on the currently
selected printer, if the CRPEJob::GetSelectedPrinter method
completes successfully. For more information on the DEVMODE
structure, refer to the Microsoft Windows Software Development
Kit.

Remarks If a non-default printer is specified in the report, this method

retrieves information about that printer. If you need to know which
printer has been specified with the report, use
CRPEJob::GetSelectedPrinter to obtain the information. This can be
useful to determine if the user has access to the printer specified in
the report and to choose another printer if not.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

296 Crystal Reports Developer’s Reference

 Related Topics
PEGetSelectedPrinter 516

CRPEJob::GetSectionFormat

BOOL GetSectionFormat (short sectionCode, CRPESectionOptions

*options);

Parameters sectionCode
Specifies the code for the report section that you need to obtain
format information for. Possible values are:

PEP_ALLSECTIONS Gets the format information

for all sections.
PEP_HEADERSECTION Gets the format information
for the Page Header section
PEP_GROUPHEADER Gets the format information
for the Group Header
section.
PEP_DETAILSECTION Gets the format information
for the Details section.
PEP_GROUPFOOTER Gets the format information
for the Group Footer section.
PEP_GRANDTOTALSECTION Gets the format information
for the Grand Total section.
PEP_FOOTERSECTION Gets the format information
for the Page Footer section.

options
A pointer to a CRPESectionOptionsstructure.

Remarks Retrieves the section format settings for a selected section in the
specified report and supplies the information by assigning values to
the members of the CRPESectionOptions structure. Use this method
in order to edit and update the section formats and pass information
back using CRPEJob::SetSectionFormat.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Chapter 4, Report Engine Class Library Reference 297

Class CRPEJob

Related Topics
PEGetSectionFormat 515

CRPEJob::SetSectionFormat

BOOL SetSectionFormat (short sectionCode, CRPESectionOptions

*options);

Parameters sectionCode
Specifies the code for the report section that you need to change
format information for. Possible values are:

PEP_ALLSECTIONS Sets the format information

for all sections.
PEP_HEADERSECTION Sets the format information
for the Page Header section
PEP_GROUPHEADER Sets the format information
for the Group Header
section.
PEP_DETAILSECTION Sets the format information
for the Details section.
PEP_GROUPFOOTER Sets the format information
for the Group Footer section.
PEP_GRANDTOTALSECTION Sets the format information
for the Grand Total section.
PEP_FOOTERSECTION Sets the format information
for the Page Footer section.

options
A pointer to a CRPESectionOptions structure.

Remarks Sets the section format settings for selected sections in the specified
report to the values in the CRPESectionOptions structure. This
method can be used to provide specialized formatting for printing
invoices, form letters, printing to pre-printed forms, etc. It allows
you to hide a section, insert a page break either before or after a
section begins, reset the page number to 1 after a group value prints,
prevent page breaks from spreading data from a single record over

298 Crystal Reports Developer’s Reference

 two pages, and to print group values only at the bottom of a page.
For a complete discussion of each of these options, see the
CRPESectionOptions structure.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetSectionFormat 600

CRPEJob::GetGraphType

BOOL GetGraphType (short sectionCode, short graphN, short

*graphType);

Parameters sectionCode
Specifies the section of the report containing the graph you want to
find out the type of. Possible values are:

PEP_ALLSECTIONS Graph appears in all

sections.
PEP_HEADERSECTION Graph appears in the Page
Header section
PEP_GROUPHEADER Graph appears in the Group
Header section.
PEP_DETAILSECTION Graph appears in the Details
section.
PEP_GROUPFOOTER Graph appears in the Group
Footer section.
PEP_GRANDTOTALSECTION Graph appears in the Grand
Total section.
PEP_FOOTERSECTION Graph appears in the Page
Footer section.

graphN
Specifies which graph within the section you want to know the type
of. This value is 0 indexed. Within a section, graphs are numbered
from top to bottom, first, then from left to right if they have the same
top.

Chapter 4, Report Engine Class Library Reference 299

 graphType
Retrieves a value indicating the type of graph that the specified
graph is. Possible values are:

PEP_SIDE_BY_SIDE_BAR_GRAPH Side By Side bar graph

PEP_STACKED_BAR_GRAPH Stacked bar graph
PEP_PERCENT_BAR_GRAPH Percent bar graph
PEP_FAKED_3D_SIDE_BY_SIDE_ 3D Side By Side bar
BAR_GRAPH graph
PEP_FAKED_3D_STACKED_BAR_ 3D Stacked bar graph
GRAPH
PEP_FAKED_3D_PERCENT_BAR_ 3D Percent bar graph
GRAPH
PEP_PIE_GRAPH Pie graph
PEP_MULTIPLE_PIE_GRAPH Multiple Pie graph
PEP_PROPORTIONAL_MULTI_ Weighted Pie graph
PIE_GRAPH
PEP_LINE_GRAPH Line graph
PEP_AREA_GRAPH Area graph
PEP_THREED_BAR_GRAPH 3D bar graph
PEP_USER_DEFINED_GRAPH User Defined graph
type
PEP_UNKNOWN_TYPE_GRAPH Unknown graph type

Remarks Identifies one of the available graph/chart types used for the
specified graph in the specified section. Use this method to find out
what type of graph is being displayed in the report. There are many
types of graphs and charts possible with Crystal Reports. This
method will return the type of graph or chart being displayed.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetGraphType 463

300 Crystal Reports Developer’s Reference

CRPEJob::SetGraphType

BOOL SetGraphType (short sectionCode, short graphN, short

graphType);

Parameters sectionCode
Specifies the section of the report containing the graph you want to
change the type of. Possible values are:

PEP_ALLSECTIONS Graph appears in all

sections.
PEP_HEADERSECTION Graph appears in the Page
Header section
PEP_GROUPHEADER Graph appears in the Group
Header section.
PEP_DETAILSECTION Graph appears in the Details
section.
PEP_GROUPFOOTER Graph appears in the Group
Footer section.
PEP_GRANDTOTALSECTION Graph appears in the Grand
Total section.
PEP_FOOTERSECTION Graph appears in the Page
Footer section.

graphN
Specifies which graph within the section you want to change the type
of. This value is 0 indexed. Within a section, graphs are numbered
from top to bottom, first, then from left to right if they have the same
top.
graphType
Specifies the style of the graph you want to set. Possible values are:

PEP_SIDE_BY_SIDE_BAR_GRAPH Side By Side bar graph

PEP_STACKED_BAR_GRAPH Stacked bar graph
PEP_PERCENT_BAR_GRAPH Percent bar graph
PEP_FAKED_3D_SIDE_BY_SIDE_ 3D Side By Side bar
BAR_GRAPH graph
PEP_FAKED_3D_STACKED_BAR_ 3D Stacked bar graph
GRAPH

Chapter 4, Report Engine Class Library Reference 301

 PEP_FAKED_3D_PERCENT_BAR_ 3D Percent bar graph
GRAPH
PEP_PIE_GRAPH Pie graph
PEP_MULTIPLE_PIE_GRAPH Multiple Pie graph
PEP_PROPORTIONAL_MULTI_ Weighted Pie graph
PIE_GRAPH
PEP_LINE_GRAPH Line graph
PEP_AREA_GRAPH Area graph
PEP_THREED_BAR_GRAPH 3D bar graph
PEP_USER_DEFINED_GRAPH User Defined graph
type
PEP_UNKNOWN_TYPE_GRAPH Unknown graph type

Remarks Changes the type of graph displayed for the specified graph in the
specified section based on one of the available graph/chart types.
Use this method to change the type of graph that is displayed in a
report.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetGraphType 569

CRPEJob::GetGraphData

BOOL GetGraphData (short sectionCode, short graphN,

CRPEGraphDataInfo *graphDataInfo);

Parameters sectionCode
Specifies the section of the report containing the graph you want to
get information from.

302 Crystal Reports Developer’s Reference

 Possible values are:

PEP_ALLSECTIONS Graph appears in all

sections.
PEP_HEADERSECTION Graph appears in the Page
Header section
PEP_GROUPHEADER Graph appears in the Group
Header section.
PEP_DETAILSECTION Graph appears in the Details
section.
PEP_GROUPFOOTER Graph appears in the Group
Footer section.
PEP_GRANDTOTALSECTION Graph appears in the Grand
Total section.
PEP_FOOTERSECTION Graph appears in the Page
Footer section.

graphN
Specifies which graph within the section you want to get graph data
information from. This value is 0 indexed. Within a section, graphs
are numbered from top to bottom, first, then from left to right if they
have the same top.
graphDataInfo
A pointer to a CRPEGraphDataInfo structure.

Remarks Use this method to find out what data in your report is being used by
a specified graph when the graph is created. This information
includes which groups are used to create the rows and columns of
the graph and which summary field in the report is used to set the
values of the risers in the graph.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetGraphData 458

Chapter 4, Report Engine Class Library Reference 303

CRPEJob::SetGraphData

BOOL SetGraphData (short sectionCode, short graphN,

CRPEGraphDataInfo *graphDataInfo);

Parameters sectionCode
Specifies the section of the report containing the graph you want to
change graph data information for. Possible values are:

PEP_ALLSECTIONS Graph appears in all

sections.
PEP_HEADERSECTION Graph appears in the Page
Header section
PEP_GROUPHEADER Graph appears in the Group
Header section.
PEP_DETAILSECTION Graph appears in the Details
section.
PEP_GROUPFOOTER Graph appears in the Group
Footer section.
PEP_GRANDTOTALSECTION Graph appears in the Grand
Total section.
PEP_FOOTERSECTION Graph appears in the Page
Footer section.

graphN
Specifies which graph within the section you want to change graph
data information for. This value is 0 indexed. Within a section,
graphs are numbered from top to bottom, first, then from left to right
if they have the same top.
graphDataInfo
A pointer to a CRPEGraphDataInfo structure.

Remarks Use this method to change what data is used from your report to
create a specified graph. This information includes the groups used
to create the rows and columns of the graph and the summary field
used to set the values of the risers in the graph.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

304 Crystal Reports Developer’s Reference

Class CRPEJob

Related Topics
PESetGraphData 564

CRPEJob::GetGraphText

BOOL GetGraphText (short sectionCode, short graphN,

CRPEGraphTextInfo *graphTextInfo);

Parameters sectionCode
Specifies the section of the report containing the graph you want to
get title text for. Possible values are:

PEP_ALLSECTIONS Graph appears in all

sections.
PEP_HEADERSECTION Graph appears in the Page
Header section
PEP_GROUPHEADER Graph appears in the Group
Header section.
PEP_DETAILSECTION Graph appears in the Details
section.
PEP_GROUPFOOTER Graph appears in the Group
Footer section.
PEP_GRANDTOTALSECTION Graph appears in the Grand
Total section.
PEP_FOOTERSECTION Graph appears in the Page
Footer section.

graphN
Specifies which graph within the section you want to get title text for.
This value is 0 indexed. Within a section, graphs are numbered from
top to bottom, first, then from left to right if they have the same top.
graphTextInfo
A pointer to a CRPEGraphTextInfo structure.

Remarks This method allows you to find out what text appears with a graph.
A graph can have a title, subtitle, footnote, title for groups, title for
series, title for the X axis, title for the Y axis, and title for the Z axis (in
3D graphs).

Chapter 4, Report Engine Class Library Reference 305

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetGraphText 461

CRPEJob::SetGraphText

BOOL SetGraphText (short sectionCode, short graphN,

CRPEGraphTextInfo *graphTextInfo);

Parameters sectionCode
Specifies the section of the report containing the graph you want to
change the text of.
Possible values are:

PEP_ALLSECTIONS Graph appears in all

sections.
PEP_HEADERSECTION Graph appears in the Page
Header section
PEP_GROUPHEADER Graph appears in the Group
Header section.
PEP_DETAILSECTION Graph appears in the Details
section.
PEP_GROUPFOOTER Graph appears in the Group
Footer section.
PEP_GRANDTOTALSECTION Graph appears in the Grand
Total section.
PEP_FOOTERSECTION Graph appears in the Page
Footer section.

graphN
Specifies which graph within the section you want to change the text
of. This value is 0 indexed. Within a section, graphs are numbered
from top to bottom, first, then from left to right if they have the same
top.

306 Crystal Reports Developer’s Reference

 graphTextInfo
A pointer to a CRPEGraphTextInfo structure.

Remarks This method allows you to set or change the text that appears with a
graph. A graph can have a title, subtitle, footnote, title for groups,
title for series, title for the X axis, title for the Y axis, and title for the
Z axis (in 3D graphs).

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetGraphText 568

CRPEJob::GetGraphOptions

BOOL GetGraphOptions (short sectionCode, short graphN,

CRPEGraphOptions *graphOptions);

Parameters sectionCode
Specifies the section of the report containing the graph you want to
get graph display options for. Possible values are:

PEP_ALLSECTIONS Graph appears in all

sections.
PEP_HEADERSECTION Graph appears in the Page
Header section
PEP_GROUPHEADER Graph appears in the Group
Header section.
PEP_DETAILSECTION Graph appears in the Details
section.
PEP_GROUPFOOTER Graph appears in the Group
Footer section.
PEP_GRANDTOTALSECTION Graph appears in the Grand
Total section.
PEP_FOOTERSECTION Graph appears in the Page
Footer section.

Chapter 4, Report Engine Class Library Reference 307

 graphN
Specifies which graph within the section you want to get graph
display options for. This value is 0 indexed. Within a section, graphs
are numbered from top to bottom, first, then from left to right if they
have the same top.
graphOptions
A pointer to a CRPEGraphOptionsstructure.

Remarks Use this method to obtain information about any of several graph
options. These options include the minimum and maximum values
that can appear on the graph, whether grid lines appear, whether
risers are labeled, whether bar graphs have horizontal or vertical
bars, and whether a legend appears on the graph.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetGraphOptions 459

CRPEJob::SetGraphOptions

BOOL SetGraphOptions (short sectionCode, short graphN,

CRPEGraphOptions *graphOptions);

Parameters sectionCode
Specifies the section of the report containing the graph you want to
change display options for. Possible values are:

PEP_ALLSECTIONS Graph appears in all

sections.
PEP_HEADERSECTION Graph appears in the Page
Header section
PEP_GROUPHEADER Graph appears in the Group
Header section.
PEP_DETAILSECTION Graph appears in the Details
section.

308 Crystal Reports Developer’s Reference

 PEP_GROUPFOOTER Graph appears in the Group
Footer section.
PEP_GRANDTOTALSECTION Graph appears in the Grand
Total section.
PEP_FOOTERSECTION Graph appears in the Page
Footer section.
graphN
Specifies which graph within the section you want to change display
options for. This value is 0 indexed. Within a section, graphs are
numbered from top to bottom, first, then from left to right if they
have the same top.
graphOptions
A pointer to a CRPEGraphOptionsstructure.

Remarks Use this function to change any of several graph options. These
options include the minimum and maximum values that can appear
on the graph, whether grid lines appear, whether risers are labeled,
whether bar graphs have horizontal or vertical bars, and whether a
legend appears on the graph.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetGraphOptions 566

CRPEJob::GetNthGroupSortField

BOOL GetNthGroupSortField (short sortFieldN, CString &field, short

*direction);

Parameters sortFieldN
Specifies the number of the group sort field you want to retrieve. The
first group sort field is field 0. If the report has N sort fields, the
function can be called with sortFieldN between 0 and N-1.

Chapter 4, Report Engine Class Library Reference 309

 field
Retrieves the name of the group sort field.
direction
Retrieves a value indicating the sort direction. Possible values are:

PE_SF_ASCENDING Sorted in Ascending order (A to Z,

1 to 9).
PE_SF_DESCENDING Sorted in Descending order (Z to A,
9 to 1).

Remarks Returns information about one of the group sort fields in the
specified report: that is, it returns the name of the field and the
direction (ascending or descending) of the sort. This method is
typically used as one of a series: CRPEJob::GetNGroupSortFields
(called once), CRPEJob::GetNthGroupSortField (called as many
times as needed to identify the correct group sort field), and
CRPEJob::SetNthGroupSortField (called once when the correct sort
field is identified). The series can be used to identify and then change
an existing group sort field and/or sort order at print time in
response to a user selection.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetNthGroupSortField 492

CRPEJob::ShowNthPage

BOOL GetNthParamInfo (short pageN);

Parameters pageN
Specifies the page number of the report that should be displayed in
the Preview window.

Remarks The ShowNthPage function displays the specified page in the

Preview window. The report must already be generated and

310 Crystal Reports Developer’s Reference

 displayed in the Preview window. This function simply changes to
another page in the report.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEShowNthPage 610

CRPEJob::DiscardSavedData

BOOL DiscardSavedData ();

Remarks Discards data that was previously saved with the report. If a report
has been saved with data, you can use this function to discard the
saved data, forcing the Report Engine to retrieve new data when the
report is printed.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEDiscardSavedData 446

CRPEJob::GetNthParamInfo

BOOL GetNthParamInfo (short paramN, CRPEParameterInfo

*paramInfo);

Parameters paramN
Specifies the number of the stored procedure parameter about which
you want to gather information.

Chapter 4, Report Engine Class Library Reference 311

 paramInfo
A pointer to a CRPEParameterInfo structure.

Remarks The GetNthParamInfo function retrieves the name and type of a

specified stored procedure parameter.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetNthParamInfo 497

CRPEJob::GetNSections

short GetNSections ();

Remarks The GetNSections function retrieves the number of sections in the

specified report. By default, each report has five areas, each
containing one section (Report Header, Page Header, Details, Report
Footer, and Page Footer). Thus, if this function were applied to a
default report, the return value would be five (5). As you add groups
to your report or you add sections to one or more areas, the number
of sections in the report increases.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetNSections 484

312 Crystal Reports Developer’s Reference

CRPEJob::GetSectionCode

short GetSectionCode (short sectionN);

Parameters printJob
Specifies the handle of the print job from which you want to identify
a section code.
sectionN
Specifies the number of the section for which you want the section
code. See Working with section codes, Page 428.

Remarks The GetSectionCode function retrieves the section code for the
specified section. A section code indicates the section type (Page
Header, Details, and so forth). If there are multiple group sections it
also identifies the group number, and if there are multiple sections in
an area it identifies the section number.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetSectionCode 513

CRPEJob::HasSavedData

BOOL HasSavedData (BOOL *hasSavedData);

Parameters printJob
Specifies the handle to the print job you want to query to find if it has
saved data.
hasSavedData
Specifies a pointer to a memory address that indicates whether or not
there is data saved with the report.

Chapter 4, Report Engine Class Library Reference 313

Remarks The HasSavedData function queries a report to find if data is saved
with it. With this information, you can determine whether or not the
data needs to be refreshed before the report is printed.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEHasSavedData 526

CRPEJob::GetNPages

short GetNPages ();

Remarks The GetNPages function retrieves the number of pages in the report.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetNPages 481

CRPEJob::SetDialogParentWindow

BOOL SetDialogParentWindow (CWnd *parentWindow);

Parameters parentWindow
A pointer to the CWnd object that is to be the parent of the Preview
Window when the report is printed to a Preview Window.

Remarks The SetDialogParentWindow function specifies the handle for the

parent window for a Print window that is an MDI child.

314 Crystal Reports Developer’s Reference

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetDialogParentWindow 556

CRPEJob::EnableProgressDialog

BOOL EnableProgressDialog (BOOL enable);

Parameters printJob
Specifies the handle to the print job for which you want to enable/
disable the progress dialog box..
enable
Specifies whether or not the progress dialog box is enabled. If enable
is set to TRUE (1), the progress dialog box is enabled. If it’s set to
FALSE (0), the dialog box is disabled.

Remarks The EnableProgressDialog function enables/disables the display of

the Progress dialog box. The Progress dialog box displays the
progress of the report when it is running (records read, records
selected, and so forth).

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEEnableProgressDialog 447

Chapter 4, Report Engine Class Library Reference 315

CRPEJob::GetNParameterFields

short GetNParameterFields ();

Remarks The GetNParameterFields function determines the number of

parameter (prompting) fields used in the report.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetNParameterFields 482

CRPEJob::GetNthParameterField

BOOL GetNthParameterField (short parameterN,

CRPEParameterFieldInfo *parameterInfo);

Parameters parameterN
Specifies the number of the parameter field about which you want to
retrieve information.
parameterInfo
A pointer to a CRPEParameterFieldInfo structure.

Remarks Returns information about one of the parameter fields in the

specified report: that is, it returns the name of the field, the data type,
and information about the value set for the field. The name of the
parameter field is returned as a string handle. This function is
typically used as one of a series of functions: GetNParameterFields
(called once), GetNthParameterField, and SetNthParameterField
(called once when the correct parameter field is identified). The
series can be used in a custom-print link to identify and then change
an existing parameter field value at print time in response to a user
selection.

316 Crystal Reports Developer’s Reference

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetNthParameterField 496

CRPEJob::SetNthParameterField

BOOL SetNthParameterField (short parameterN, const

CRPEParameterFieldInfo *parameterInfo);

Parameters parameterN
Specifies the number of the parameter field about which you want to
retrieve information.
parameterInfo
A pointer to a CRPEParameterFieldInfo structure.

Remarks The SetNthParameterField function sets a value for the specified

parameter field.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetNthParameterField 586

CRPEJob::GetNSubreportsInSection

short GetNSubreportsInSection (short sectionCode);

Parameters print job

Specifies the handle of the primary report from which you want to
fetch information about the number of subreports in a section.

Chapter 4, Report Engine Class Library Reference 317

 sectionCode
Specifies the section code of the section for which you want a
subreport count. See Working with section codes, Page 428.

Remarks The GetNSubreportsInSection function determines the number of

subreports in the specified section.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEGetNSubreportsInSection 487
Working with subreports 36

CRPEJob::GetNthSubreportInSection

DWORD GetNthSubreportInSection (short sectionCode, short

subreportN);

Parameters sectionCode
Specifies the code for the report section that contains the subreport.
See Working with section codes, Page 428.
subreportN
Specifies the number of the subreport in the specified section.
subreportN is zero based. The first report in the section will be 0, the
second will be 1, etc. If there are no subreports in the section, the
function will return 0.

Remarks The GetNthSubreportInSection function retrieves a handle that is

required to retrieve the name of the subreport.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

318 Crystal Reports Developer’s Reference

 Related Topics
PEGetNthSubreportInSection 501
Working with subreports 36

CRPEJob::OpenSubreportJob

CRPEJob *OpenSubreportJob (const _TCHAR *subreportName);

Parameters subreportName
Specifies the name of the subreport you want to access. This name is
retrieved using CRPEJob::GetSubreportInfo.

Remarks The OpenSubreportJob function opens the named subreport and

returns a pointer to a CRPEJob object for the subreport. The CRPEJob
object can be used to make subsequent changes to the subreport.

Return Value A pointer to a CRPEJobclass object for the subreport.

Class CRPEJob

Related Topics
PEOpenSubreport 539
Working with subreports 36

Chapter 4, Report Engine Class Library Reference 319

320 Crystal Reports Developer’s Reference
5 Crystal NewEra Class Library
Reference

What you will find in this chapter:

Crystal NewEra Class Library Overview 322
CLASS CRPELogOnInfo 322
CLASS CRPEJobInfo 324
CLASS CRPETableType 325
CLASS CRPESessionInfo 326
CLASS CRPETableLocation 327
CLASS CRPEPrintOptions 327
CLASS CRPEExportOptions 329
CLASS CRPESectionOptions 333
CLASS CRPEGraphDataInfo 336
CLASS CRPEGraphTextInfo 338
CLASS CRPEGraphOptions 340
CLASS CRPEngine 342
CLASS CRPEJob 343

Chapter 5, Crystal NewEra Class Library Reference 321

Crystal NewEra Class Library Overview
Crystal Reports for Windows includes the Crystal NewEra Class
Library. The Class Library is comprised of two primary classes and
several supporting classes. These classes are wrapped around the
Crystal Report Engine API and insulate the user from some of the
details required to manage reports in an application.
The Crystal NewEra Class Library was installed when you installed
Crystal Reports for Windows in the directory \CRW\INFORMIX by
default. The header files (*.4GH) for the library are located in
\CRW\INFORMIX\CLASS\INCL, while source files (*.4GL) are
located in \CRW\INFORMIX\CLASS\SRC. Copy these files, along
with CRPE.H, to the appropriate location for your NewEra
application, then INCLUDE crystal.4gh in the source file for your
application project that will access the Crystal Report Engine.

The Report Engine As mentioned above, the Crystal NewEra Class Library classes are
wrapped around the Crystal Report Engine API (Page 15), and the
API methods in these classes make direct calls to the functions in the
Report Engine API.

The Crystal The Crystal NewEra Class Library consists of two primary classes.
The CRPEngine class is designed so that there should only be one
NewEra Class CRPEngine object in the entire application. The CRPEngine object
Library classes contains methods that are common to all print jobs (e.g. SQL
connections, version information, etc.). More importantly, it is
responsible for creating and managing all CRPEJob objects. It is the
CRPEJob object that allows you access to the attributes of a print job.
Both of the classes are derived from the Microsoft MFC Library
CObject class and provide all of the functionality of that class,
including runtime class information and object diagnostic output.

CLASS CRPELogOnInfo
This class is used by member functions CRPEngine::LogOnServer,
CRPEngine::LogOffServer, CRPEJob::GetNthTableLogonInfo,
CRPEJob::SetNthTableLogonInfo. The class is used to contain SQL
connection information.

322 Crystal Reports Developer’s Reference

Data Members m_serverName
Specifies the logon name for the server used to create the report.
m_databaseName
Specifies the logon name for the database used to create the report.
m_userID
Specifies the user I.D. necessary to log on to the server.
m_password
Specifies the password necessary to log on to the server.

Construction CRPELogOnInfo
Constructs a CRPELogOnInfo class object.

CRPELogOnInfo::CRPELogOnInfo

CRPELogOnInfo ();
CRPELogOnInfo ( serverName CHAR (*), databaseName CHAR (*),
userID CHAR (*), password CHAR (*));

Parameters serverName
Specifies the logon name for the server or ODBC Datasource Name
used to logon to the server .
Assigns this value to the CRPELogOnInfo::m_serverName member.
databaseName
Specifies the logon name for the database used to run the report.
Assigns this value to the CRPELogOnInfo::m_databaseName
member.
userID
Specifies the user I.D. necessary to log on to the server.
Assigns this value to the CRPELogOnInfo::m_userID member.
password
Specifies the password necessary to log on to the server.
Assigns this value to the CRPELogOnInfo::m_password member.

Remarks Constructs a CRPELogOnInfo class object. Call the constructor with

no parameters to allow the Class Library to initialize all member

Chapter 5, Crystal NewEra Class Library Reference 323

 variables with default values. Pass parameters to the constructor to
assign specific values to each member variable.

Class CRPELogOnInfo

CLASS CRPEJobInfo
This class is used by the CRPEJob::GetJobStatus member function.
Status information concerning the job is returned through this class.

Data Members m_numRecordsRead

Specifies the number of records actually processed.
m_numRecordsSelected
Specifies the number of records selected for inclusion in the report
out of the total number of records read.
m_numRecordsPrinted
Specifies the number of records actually printed.
m_displayPageN
Specifies the page number of the currently displayed page in the
Preview Window.
m_latestPageN
Specifies the number of the last page that is currently available. Once
the printing is complete, this value is the number of the last page.
m_startPageN
Specifies the number of the starting page. The value will normally be
1.
m_printEnded
Specifies whether or not the printing process is completed.

Construction CRPEJobInfo
Constructs a CRPEJobInfo class object:
All INTEGERs & SMALLINTs initialized to zero, printEnded
initialized to FALSE

324 Crystal Reports Developer’s Reference

CRPEJobInfo::CRPEJobInfo

CRPEJobInfo (numRecordsRead INTEGER : 0, numRecordsSelected

INTEGER : 0, numRecordsPrinted INTEGER : 0, displayPageN
SMALLINT : 0, latest PageN SMALLINT : 0, startPageN SMALLINT :
0, printEnded BOOLEAN : FALSE);

Remarks Constructs a CRPEJobInfo class object. Initializes all required

members of the class.

Class CRPEJobInfo

CLASS CRPETableType
This class is used to determine information about a specific table
used in the report. It is used by the
CRPEJob::GetNthTableSessionInfo.

Data Members m_dllName

Specifies the name of the appropriate database DLL for the table of
interest.
m_descriptiveName
Specifies the name of the table of interest.
m_dbType
Specifies the type of database that contains the table of interest.

Construction CRPETableType
Constructs a CRPETableType class object.

CRPETableType::CRPETableType

CRPETableType (dbType SMALLINT : PEP_DT_SQL, dllName

CHAR(*) : NULL, descriptiveName: CHAR(*) : NULL);

Remarks Constructs a CRPETableType class object. Initializes all members of

the class.

Chapter 5, Crystal NewEra Class Library Reference 325

Class CRPETableType

CLASS CRPESessionInfo
This class is used to get and set the session information (user id and
password) for password protected Microsoft Access databases. It is
used with the CRPEJob:GetNthTableSessionInfo and
CRPEJob::SetNthTableSessionInfo member functions.

Data Members m_userID

Specifies the user I.D. needed for logging on to the MS Access
system.
m_password
Specifies the password needed for logging on to the MS Access
system.
m_sessionHandle
The handle to the current MS Access session.

Construction CRPESessionInfo
Constructs a CRPESessionInfo class object.

CRPESessionInfo::CRPESessionInfo

CRPESessionInfo ();
CRPESessionInfo (userID CHAR(*) : NULL, password CHAR(*) :
NULL, sessionHandle INTEGER : 0);

Parameters userID
Specifies the user I.D. needed for logging on to the MS Access
system. Assigns this value to the CRPESessionInfo::m_userID
member.
password
Specifies the password needed for logging on to the MS Access
system. Assigns this value to the CRPESessionInfo::m_password
member.
sessionHandle
The handle to the current MS Access session. Assigns this value to
the CRPESessionInfo::m_sessionHandle member.

326 Crystal Reports Developer’s Reference

Remarks Constructs a CRPESessionInfo class object. Call the constructor with
no parameters to allow the Class Library to initialize all member
variables with default values. Pass parameters to the constructor to
assign specific values to each member variable.

Class CRPESessionInfo

CLASS CRPETableLocation
This class is used to get and set table location information. It is used
with the CRPEJob::GetNthTableLocation and
CRPEJob::SetNthTableLocation functions.

Data Members m_location

Specifies the database location.

Construction CRPETableLocation
Constructs a CRPETableLocation class object.

CRPETableLocation::CRPETableLocation

CRPETableLocation (location CHAR(*) : NULL);

Parameters location
Specifies the database location. Assigns this value to the
CRPETableLocation::m_location member.

Remarks Constructs a CRPETableLocation class object. Call the constructor

with no parameters to allow the Class Library to initialize all
member variables with default values. Pass parameters to the
constructor to assign specific values to each member variable.

Class CRPETableLocation

CLASS CRPEPrintOptions
This class is used to set the print characteristics of a report. It is used
with the CRPEJob::SetPrintOptions member function.

Chapter 5, Crystal NewEra Class Library Reference 327

Data Members m_startPageN
Specifies the first page that you want to print.
m_stopPageN
Specifies the last page that you want to print.
m_nReportCopies
Specifies the number of copies that you want to print.
m_collation
Indicates whether or not you want the copies of the report to be
collated (if you are printing multiple copies of a multiple page report.

Construction CRPEPrintOptions
Constructs a CRPEPrintOptions class object.

CRPEPrintOptions::CRPEPrintOptions

CRPEPrintOptions ();
CRPEPrintOptions (startPageN SMALLINT : 0, stopPageN
SMALLINT : 0, nReportCopies SMALLINT : 0, collation SMALLINT :
PEP_DEFAULTCOLLATION);

Parameters startPageN
Specifies the first page that you want to print. Assigns this value to
the CRPEPrintOptions::m_startPageN member.
stopPageN
Specifies the last page that you want to print. Assigns this value to
the CRPEPrintOptions::m_stopPageN member.
nReportCopies
Specifies the number of copies that you want to print. Assigns this
value to the CRPEPrintOptions::m_nReportCopies member.
collation
Indicates whether or not you want the copies of the report to be
collated (if you are printing multiple copies of a multiple page report.
Assigns this value to the CRPEPrintOptions::m_collation member.

328 Crystal Reports Developer’s Reference

 Possible values are:

Prints multiple copies of a

multiple page report
PEP_UNCOLLATED
uncollated (Page order =
1,1,1,2,2,2,3,3,3,etc.
Prints multiple copies of a
multiple page report collated
PEP_COLLATED
(Page order = 1,2,3...,1,2,3...,
etc.
Prints multiple copies of a
multiple page report using the
PEP_DEFAULTCOLLATION
collation settings specified in
the report.

Remarks Constructs a CRPEPrintOptions class object. Call the constructor

with no parameters to allow the Class Library to initialize all
member variables with default values. Pass parameters to the
constructor to assign specific values to each member variable.

Class CRPEPrintOptions

CLASS CRPEExportOptions
This class is used to get and set the export options of a print job. It is
used by member functions CRPEJob::GetExportOptions and
CRPEJob::ExportTo.

Data Members m_formatType

Specifies the export format to be used.
m_formatDLLName
Specifies the name of the format DLL that contains the export format
to be used.
m_formatOptions
Provides additional export information specific to the format type
being used.
m_nFormatOptionsBytes
Automatically assigned by CRPEjob::GetExportOptions. Unused by
CRPEJob::SetExportOptions.

Chapter 5, Crystal NewEra Class Library Reference 329

 m_destinationType
Specifies the destination type of the exported report.
m_destinationDLLName
Specifies the name of the destination DLL that contains the
destination type to be used.
m_destinationOptions
Provides additional information specific to the export destination
type.
m_nDestinationOptionsBytes
Automatically assigned by CRPEjob::GetExportOptions. Unused by
CRPEJob::SetExportOptions.

Construction CRPEExportOptions
Constructs a CRPEExportOptions class object.

CRPEExportOptions::CRPEExportOptions

CRPEExportOptions ();
CRPEExportOptions (formatDLLName CHAR(*) : NULL, formatType
INTEGER: 0, formatOptions FOREIGN : NULL, destinationDLLName
CHAR(*) : NULL, destinationType INTEGER : 0, destinationOptions
FOREIGN : NULL);

Parameters formatDLLName
Specifies the name of the format DLL that contains the export format
to be used. Assigns this value to the
CRPEExportOptions::m_formatDLLName member. Select a DLL
from the following table:

To export a report in this

Use this DLL:
format:
Crystal Reports Format uxfcr.dll
Data Interchange Format uxfdif.dll
Word for Windows Format uxfwordw.dll
Word for DOS Format uxfdoc.dll
WordPerfect Format uxfdoc.dll
Quattro Pro 5.0 (WB1) Format uxfqp.dll

330 Crystal Reports Developer’s Reference

 Record Style Format (columns) uxfrec.dll
Rich Text Format uxfrtf.dll
Comma Separated Values (CSV) uxfsepv.dll
Tab Separated Values uxfsepv.dll
Character Separated Values uxfsepv.dll
Text Format (ASCII) uxftext.dll
Tab Separated Text Format uxftext.dll
Lotus 1-2-3 (WKS) uxfwks.dll
Lotus 1-2-3 (WK1) uxfwks.dll
Lotus 1-2-3 (WK3) uxfwks.dll
Excel 2.1 uxfxls.dll
Excel 3.0 uxfxls.dll
Excel 4.0 uxfxls.dll
formatType
Specifies the export format to be used. Assigns this value to the
CRPEExportOptions::m_formatType member. Select from the
following values:

To export a report in this Use this for

format: formatType:
Crystal Reports Format UXFCrystalReportType
Data Interchange Format UXFDIFType
Word for Windows Format UXFWordWinType
Word for DOS Format UXFWordDosType
WordPerfect Format UXFWordPerfectType
Quattro Pro 5.0 (WB1) Format UXFQP5Type
Record Style Format (columns) UXFRecordType
Rich Text Format UXFRichTextFormatType
Comma Separated Values (CSV) UXFCommaSeparatedTy
pe
Tab Separated Values UXFTabSeparatedType
Character Separated Values UXFCharSeparatedType
Text Format (ASCII) UXFTextType
Tab Separated Text Format UXFTabbedTextType
Lotus 1-2-3 (WKS) UXFLotusWksType
Lotus 1-2-3 (WK1) UXFLotusWk1Type
Lotus 1-2-3 (WK3) UXFLotusWk3Type

Chapter 5, Crystal NewEra Class Library Reference 331

 Excel 2.1 UXFXls2Type
Excel 3.0 UXFXls3Type
Excel 4.0 UXFXls4Type
formatOptions
Provides additional export information specific to the format type
being used. Assigns this value to the
CRPEExportOptions::m_formatOptions member. This parameter is
required for only certain format types. If you assign NULL to this
parameter, the Report Engine will automatically prompt the user for
format information if needed. Otherwise, use a format options class
from the following table:
To export a report in this
format: Use this class:

Data Interchange Format UXFDIFOptions

Record Style Format (columns) UXFRecordStyleOptions
Comma Separated Values (CSV) UXFCommaTabSeparated
Options
Tab Separated Values UXFCommaTabSeparated
Options
Character Separated Values UXFCharSeparatedOptio
ns

destinationDLLName
Specifies the name of the destination DLL that contains the
destination type to be used. Assigns this value to the
CRPEExportOptions::m_destinationDLLName member. The
following options are available:

To export a report to this Use this DLL name:

destination:
Disk File uxddisk.dll
E-mail (MAPI) uxdmapi.dll
E-mail (VIM) uxdvim.dll

destinationType
Specifies the destination type of the exported report. Assigns this
value to the CRPEExportOptions::m_destinationType member.

332 Crystal Reports Developer’s Reference

 The following values are available:

To export a report to this Use this destination

destination: type:
Disk File UXDDiskType
E-mail (MAPI) UXDMapiType
E-mail (VIM) UXDVIMType

destinationOptions
Provides additional information specific to the export destination
type. Assigns this value to the
CRPEExportOptions::m_destinationOptions member. If you assign
NULL to this parameter, the Report Engine will automatically
prompt the user for destination information when needed.
Otherwise, use a destination options class from thefollowing table:

To export a report to this

Use this class:
destination:
Disk File UXDDiskOptions
E-mail (MAPI) UXDMAPIOptions
E-mail (VIM) UXDVIMOptions

Remarks Constructs a CRPEExportOptions class object. Call the constructor

with no parameters to allow the Class Library to initialize all
member variables with default values. Pass parameters to the
constructor to assign specific values to each member variable.

Class CRPEExportOptions

CLASS CRPESectionOptions
This class contains specifications for formatting selected report
sections. This information is used by the methods
CRPEJob::GetSectionFormat and CRPEJob::SetSectionFormat.

Data Members m_visible

Specifies whether or not the selected section is to be visible. Use
TRUE to keep the section visible, FALSE to hide the section.
m_newPageBefore
Specifies whether or not the Report Engine is to insert a page break
before the section is printed. Use TRUE to insert a page break, FALSE
to leave it without a page break.

Chapter 5, Crystal NewEra Class Library Reference 333

 m_newPageAfter
Specifies whether or not the Report Engine is to insert a page break
after the section is printed. Use TRUE to insert a page break, FALSE
to leave it without a page break.
m_keepTogether
Specifies whether or not the Report Engine is to keep all lines of the
section together, either on the current page (if there is room), or on
the next page. Pass TRUE to keep the lines together, FALSE to allow
the Report Engine to split section data from one page to the next if
necessary.
m_suppressBlankLines
Specifies whether or not the Report Engine is to eliminate lines from
your report that are blank due to fields being suppressed (zeroes,
duplicates, and hidden fields). TRUE eliminates blank lines. FALSE
retains them.
m_resetPageNAfter
Specifies whether or not the Report Engine is to reset the page
number to one (1) for the following page, after it prints a group total.
Use TRUE to reset the page number, FALSE to keep standard
numbering.
m_printAtBottomOfPage
Specifies whether or not the Report Engine is to cause each group
summary value to print only at the bottom of a page. Use TRUE to
print summaries at the bottom of the page, FALSE to print
summaries immediately after the group.

Construction CRPESectionOptions
Constructs a CRPESectionOptions class object.

CRPESectionOptions::CRPESectionOptions

CRPESectionOptions (visible BOOLEAN : FALSE, newPageBefore

BOOLEAN : FALSE, newPageAfter BOOLEAN : FALSE, keepTogether
BOOLEAN : FALSE, suppressBlankLines BOOLEAN : FALSE,
resetPageNAfter BOOLEAN : FALSE, printAtBottomOfPage
BOOLEAN : FALSE)

334 Crystal Reports Developer’s Reference

Parameters visible
Specifies whether or not the selected section is to be visible. Use
TRUE to keep the section visible, FALSE to hide the section. Assigns
this value to the CRPESectionOptions::m_visible member.
newPageBefore
Specifies whether or not the Report Engine is to insert a page break
before the section is printed. Use TRUE to insert a page break, FALSE
to leave it without a page break. Assigns this value to the
CRPESectionOptions::m_newPageBefore member.
newPageAfter
Specifies whether or not the Report Engine is to insert a page break
after the section is printed. Use TRUE to insert a page break, FALSE
to leave it without a page break. Assigns this value to the
CRPESectionOptions::m_newPageAfter member.
keepTogether
Specifies whether or not the Report Engine is to keep all lines of the
section together, either on the current page (if there is room), or on
the next page. Pass TRUE to keep the lines together, FALSE to allow
the Report Engine to split section data from one page to the next if
necessary. Assigns this value to the
CRPESectionOptions::m_keepTogether member.
suppressBlankLines
Specifies whether or not the Report Engine is to eliminate lines from
your report that are blank due to fields being suppressed (zeroes,
duplicates, and hidden fields). TRUE eliminates blank lines. FALSE
retains them. Assigns this value to the
CRPESectionOptions::m_suppressBlankLines member.
resetPageNAfter
Specifies whether or not the Report Engine is to reset the page
number to one (1) for the following page, after it prints a group total.
Use TRUE to reset the page number, FALSE to keep standard
numbering. Assigns this value to the
CRPESectionOptions::m_resetPageNAfter member.
printAtBottomOfPage
Specifies whether or not the Report Engine is to cause each group
summary value to print only at the bottom of a page. Use TRUE to
print summaries at the bottom of the page, FALSE to print
summaries immediately after the group. Assigns this value to the
CRPESectionOptions::m_printAtBottomOfPage member.

Chapter 5, Crystal NewEra Class Library Reference 335

Remarks Constructs a CRPESectionOptions class object. Call the constructor
with no parameters to allow the Class Library to initialize all
member variables with default values. Pass parameters to the
constructor to assign specific values to each member variable.
Use PEP_UNCHANGED with any parameter to let the Report
Engine leave the setting as it is specified in the report file.

Class CRPESectionOptions

CLASS CRPEGraphDataInfo
The CRPEGraphDataInfo class contains information on what report
data is used by a graph in the report to create the values in the graph.
The class is used by CRPEJob::GetGraphData to retrieve information
regarding an existing graph and by CRPEJob::SetGraphData to
change the data used by an existing graph.

Data Members m_rowGroupN

Specifies which group number in the report is used to create the
values in the rows of the graph.
m_colGroupN
Specifies which group number in the report is used to create the
values in the columns of the graph.
m_summarizedFieldN
Specifies which summary field in the report is used to set the values
of the risers in the graph. Summary fields are numbered in order of
their creation.
m_graphDirection
Specifies the graphing direction for Cross-Tab reports. For normal
group/total report, the direction, is always
PE_GRAPH_COLS_ONLY.

Construction CRPEGraphDataInfo
Constructs a CRPEGraphDataInfo class object.

336 Crystal Reports Developer’s Reference

CRPEGraphDataInfo::CRPEGraphDataInfo

CRPEGraphDataInfo (rowGroupN SMALLINT : 0, colGroupN

SMALLINT: 0 summarizedFieldN SMALLINT : 0, graphDirection
SMALLINT : PEP_GRAPH_COLS_ONLY);

Parameters rowGroupN
Specifies which group number in the report is used to create the
values in the rows of the graph. Assigns this value to the
CRPEGraphDataInfo::m_rowGroupN member variable.
colGroupN
Specifies which group number in the report is used to create the
values in the columns of the graph. Assigns this value to the
CRPEGraphDataInfo::m_colGroupN member variable.
summarizedFieldN
Specifies which summary field in the report is used to set the values
of the risers in the graph. Summary fields are numbered in order of
their creation. Assigns this value to the
CRPEGraphDataInfo::m_summarizedFieldN member variable.
graphDirection
Specifies the graphing direction for Cross-Tab reports. For normal
group/total report, the direction, is always
PEP_GRAPH_COLS_ONLY = 1. Assigns this value to the
CRPEGraphDataInfo::m_graphDirection member variable. Possible
values are:

PEP_GRAPH_ROWS_ONLY = 0 Use only row

values in graph.
PEP_GRAPH_COLS_ONLY = 1 Use only column
values in graph.
PEP_GRAPH_MIXED_ROW_COL = 2 Graph by row
values, then by
column values.
PEP_GRAPH_MIXED_COL_ROW = 3 Graph by column
values, then by row
values.
PEP_GRAPH_UNKNOWN_DIRECTION The direction of the
= 20 graph is unknown.

Chapter 5, Crystal NewEra Class Library Reference 337

Remarks Constructs a CRPEGraphDataInfo class object. Call the constructor
with no parameters to allow the Class Library to initialize all
member variables with default values. Pass parameters to the
constructor to assign specific values to each member variable.

Class CRPEGraphDataInfo

CLASS CRPEGraphTextInfo
The CRPEGraphTextInfo class contains information about the text
that appears with a graph. This class is used with the methods
CRPEJob::GetGraphText and CRPEJob::SetGraphText.

Data Members m_graphTitle

Specifies the main title text that will appear above your graph.
m_graphSubTitle
Specifies the sub title text that will appear directly under the main
title.
m_graphFootNote
Specifies the footnote text that will appear under your graph.
m_graphGroupsTitle
Specifies the title of the groups which are being graphed.
m_graphSeriesTitle
Specifies the title of the series which is being graphed.
m_graphXAxisTitle
Specifies the title text that will appear for the X axis. Not valid for Pie
graphs.
m_graphYAxisTitle
Specifies the title text that will appear for the Y axis. Not valid for Pie
graphs.
m_graphZAxisTitle
Specifies the title text that will appear for the Z axis. This value is
only valid for 3D graphs.

Construction CRPEGraphTextInfo
Constructs a CRPEGraphTextInfo class object.

338 Crystal Reports Developer’s Reference

CRPEGraphTextInfo::CRPEGraphTextInfo

CRPEGraphTextInfo ();
CRPEGraphTextInfo (graphSubTitle CHAR(*) : NULL, graphFootNote
CHAR(*) : NULL, graphGroupsTitle CHAR(*) : NULL, graphSeriesTitle
CHAR(*) : NULL, graphXAxisTitle CHAR(*) : NULL, graphYAxisTitle
CHAR(*) : NULL, graphZAxisTitle CHAR(*) : NULL);

Parameters graphTitle
Specifies the main title text that will appear above your graph.
Assigns this title to the CRPEGraphTextInfo::m_graphTitle member
variable.
graphSubTitle
Specifies the sub title text that will appear directly under the main
title. Assigns this title to the CRPEGraphTextInfo::m_graphSubTitle
member variable.
graphFootNote
Specifies the footnote text that will appear under your graph.
Assigns this text to the CRPEGraphTextInfo::m_graphFootNote
member variable.
graphGroupsTitle
Specifies the title of the groups which are being graphed. Assigns
this title to the CRPEGraphTextInfo::m_graphGroupsTitle member
variable.
graphSeriesTitle
Specifies the title of the series which is being graphed. Assigns this
title to the CRPEGraphTextInfo::m_graphSeriesTitle member
variable.
graphXAxisTitle
Specifies the title text that will appear for the X axis. Not valid for Pie
graphs. Assigns this title to the
CRPEGraphTextInfo::m_graphXAxisTitle member variable.
graphYAxisTitle
Specifies the title text that will appear for the Y axis. Not valid for Pie
graphs. Assigns this title to the
CRPEGraphTextInfo::m_graphYAxisTitle member variable.

Chapter 5, Crystal NewEra Class Library Reference 339

 graphZAxisTitle
Specifies the title text that will appear for the Z axis. Only valid for
3D graphs. Assigns this title to the
CRPEGraphTextInfo::m_graphZAxisTitle member variable.

Remarks Constructs a CRPEGraphTextInfo class object. Call the constructor

with no parameters to allow the Class Library to initialize all
member variables with default values. Pass parameters to the
constructor to assign specific values to each member variable.

Class CRPEGraphTextInfo

CLASS CRPEGraphOptions

The CRPEGraphOptions class contains information on several

options available with graphs and charts. This class is used by
CRPEJob::GetGraphOptions to find out what options have been set
for a graph, and it is used by CRPEJob::SetGraphOptions to change
the options for a graph.

Data Members m_graphMaxValue

Specifies the maximum value that will appear in the graph. Any
graph values above this value are not charted.
m_graphMinValue
Specifies the minimum value that will appear in the graph. Any
graph values below this value are not charted.
m_showDataValue
Specifies whether or not to display the numerical value associated
with each riser on the chart. If set to TRUE (1), a value appears in the
graph for each riser.
m_showGridLine
Specifies whether or not to display grid lines on the graph.
m_verticalBars
Specifies whether to display the bars in a bar graph vertically or
horizontally.
m_showLegend
Specifies whether or not to display the graph legend.

340 Crystal Reports Developer’s Reference

 m_fontFaceName
Specifies the font for all text and values in the entire graph.

Construction CRPEGraphOptions
Constructs a CRPEGraphOptions class type.

CRPEGraphOptions::CRPEGraphOptions

CRPEGraphOptions() -- see Remarks

CRPEGraphOptions ( graphMaxValue FLOAT : 0, graphMinValue
FLOAT : 0, showDataValue BOOLEAN : FALSE, showGridLine
BOOLEAN : FALSE, verticalBars BOOLEAN : FALSE, showLegend
BOOLEAN : FALSE, fontFaceName CHAR (*) : NULL)

Parameters graphMaxValue
Specifies the maximum value that will appear in the graph. Any
graph values above this value are not charted. Assigns this value to
the CRPEGraphOptions::m_graphMaxValue member variable.
graphMinValue
Specifies the minimum value that will appear in the graph. Any
graph values below this value are not charted. Assigns this value to
the CRPEGraphOptions::m_graphMinValue member variable.
showDataValue
Specifies whether or not to display the numerical value associated
with each riser on the chart. If set to TRUE, a value appears in the
graph for each riser. Assigns this value to the
CRPEGraphOptions::m_showDataValue member variable.
showGridLine
Specifies whether or not to display grid lines on the graph. Assigns
this value to the CRPEGraphOptions::m_showGridLine member
variable.
verticalBars
Specifies whether to display the bars in a bar graph vertically or
horizontally. Assigns this value to the
CRPEGraphOptions::m_verticalBars member variable.

Chapter 5, Crystal NewEra Class Library Reference 341

 showLegend
Specifies whether or not to display the graph legend. Assigns this
value to the CRPEGraphOptions::m_showLegend member variable.
fontFaceName
Specifies the font for all text and values in the entire graph. Assigns
this value to the CRPEGraphOptions::m_fontFaceName member
variable.

Remarks Constructs a CRPEGraphOptions class object. Call the constructor

with no parameters to allow the Class Library to initialize all
member variables with default values. Pass parameters to the
constructor to assign specific values to each member variable.

Class CRPEGraphOptions

CLASS CRPEngine
The CRPEngine class is designed so that there should only be one
CRPEngine object in the entire application. The CRPEngine class
contains methods that are common to all print jobs (e.g. SQL
connections, version information, etc.). More importantly, it is
responsible for creating and managing all CRPEJob objects. It is the
CRPEJob object that allows you access to the attributes of a print job.
In order to open a particular report it is first necessary to have an
open Report Engine object in the application. You may then call the
CRPEngine::OpenPrintJob member function specifying the report
file name to open. If successful, you will be returned a pointer to a
CRPEJob object.

Construction CRPEngine
Constructs a CRPEngine object.

Engine
Management Open Loads the engine

Functions Close Unloads the engine

GetVersion Checks engine version number

Obtains the current status of the

GetEngineStatus
Report Engine.
Determines if the Report Engine is
CanClose
not busy and can be closed.

342 Crystal Reports Developer’s Reference

Print Job
Management OpenJob Prepares to print a report

Functions PrintReport Prints the report

Obtains the number of print jobs

GetNPrintJobs
currently open.

Server
Management LogOnServer Logs on to server

Functions LogOffServer Logs off of server

Uses an existing
LogOnSQLServerWithPrivateInfo connection to a SQL
Server.

Error
Management Get a number indicating the status
GetErrorCode
of the most recent function called
Functions Inquire on the error text
GetErrorText

CLASS CRPEJob
In order to open a particular report it is first necessary to have an
open Report Engine object in the application. You may then call the
CRPEngine::OpenPrintJob member function specifying the report
file name to open. If successful, you will be returned a pointer to a
CRPEJob object. It is through this object that you may modify the
print job attributes as well as output the report in various formats.
Almost all of these methods correspond to similar functions
available in the Crystal Report Engine API. Full documentation on
what these methods are used for are available in the Developer’s on-
line help.

Construction CRPEJob
Constructs a CRPEJob object. Used internally by
CRPEngine::OpenJob.

Chapter 5, Crystal NewEra Class Library Reference 343

Print Job
Management StartJob Prints the report (custom print link)

Functions Close Closes the print job

Cancel Cancels the print job

GetJobStatus Evaluates the status of a print job

Monitors job to see if it is finished

IsJobFinished
or still in progress
Returns the job handle for the print
GetJobHandle
job.

Preview Window
Customization Displays the first page in the
ShowFirstPage
Preview Window
Functions Displays the previous page in
ShowPreviousPage
the Preview Window
Displays the last page in the
ShowLastPage
Preview Window
Displays the print controls in
ShowPrintControls
the Preview Window
Checks if the print controls are
PrintControlsShowing displayed in the Preview
Window .
Changes Preview Window
ZoomPreviewWindow magnification to a specified
level
Changes Preview Window
NextWindowMagnification magnification to the next level
in order

Preview Window
Management PrintWindow Prints contents of print window

Functions ExportPrintWindow Exports contents of print window

CloseWindow Closes print window

344 Crystal Reports Developer’s Reference

Table Mangement
Functions Test whether a database tables’
TestNthTableConnectivity settings are valid and ready to be
reported on
Returns the number of tables in
GetNTables
the report
Allows the application to
GetNthTableType
determine the type of each table
Get the session info for an MS
GetNthTableSessionInfo
Access table
Set the session info for an MS
SetNthTableSessionInfo
Access table
GetNthTableLocation Gets the Nth table location

SetNthTableLocation Sets the Nth table location

GetNthTableLogonInfo Gets the correct table log on info

SetNthTableLogonInfo Sets the correct table logon info

Formula Functions
Finds the number of formulas in
GetNFormulas
the report to be printed.
Gets a formula’s text and name
GetNthFormula
(formula specified by number).
Get a formula’s text (formula
GetFormula
specified by name).
Set the formula text of a formula
SetFormula
(formula specified by name).
Checks text of a formula for
CheckFormula validity (formula specified by
name).

Selection Formula
Functions Get the record selection
GetSelectionFormula
formula
Set the record selection
SetSelectionFormula
formula
Checks text of record
CheckSelectionFormula selection formula for
validity.

Chapter 5, Crystal NewEra Class Library Reference 345

 Get the group selection
GetGroupSelectionFormula
formula
Set the group selection
SetGroupSelectionFormula
formula
Checks text of group
CheckGroupSelectionFormula selection formula for
validity.

Group
Management Finds the number of groups in the
GetNGroups
report.
Functions Gets the condition information for
GetGroupCondition
the specified report group.
Changes the group condition for a
SetGroupCondition
group section

Sorting Functions
Finds the number of sort fields in
GetNSortFields
the report to be printed
GetNthSortField Gets the specified sort field

SetNthSortField Sets the specified sort field

Removes the specified sort field

DeleteNthSortField
from the sort order
Finds the number of group sort
GetNGroupSortFields
fields in the report to be printed
Gets the specified group sort
GetNthGroupSortField
field
SetNthGroupSortField Sets the specified group sort field

Deletes the specified group sort

DeleteNthGroupSortField
field

Server
Management Returns the current SQL query for
GetSQLQuery
the report
Functions Sets a new SQL query for the report
SetSQLQuery

346 Crystal Reports Developer’s Reference

Stored Procedure
Management Gets the number of parameters in a
GetNParams
stored procedure.
Functions Gets a particular parameter for a
GetNthParam
stored procedure.
Sets the value of a parameter in a
SetNthParam
stored procedure.

Print Format
Management Gets the title string for the
GetReportTitle
current report
Functions Changes the report title to
SetReportTitle the string you supply as a
parameter
Gets the print date set for
GetPrintDate
the report.
Sets a print date different
SetPrintDate from the system calender
date
Gets print options set for
GetPrintOptions
specified report.
Sets print options for the
SetPrintOptions
specified report
Gets format information for
GetSectionFormat
specified section.
Sets format information for
SetSectionFormat
specified section.
Gets the number of times
GetNDetailCopies each detail section is to be
printed.
Prints specified number of
SetNDetailCopies copies of the details section
of the report
Gets page margins set in
GetMargins
specified report.
SetMargins Sets margins for the report

Gets section height set for

GetMinimumSectionHeight
specified report section.

Chapter 5, Crystal NewEra Class Library Reference 347

 Sets the minimum height for
SetMinimumSectionHeight all lines in a given report
section
Gets the height set for the
GetLineHeight
specified report section.
Sets the line height for all
SetLineHeight lines in a given report
section
Finds the number of lines in
GetNLinesInSection
the specified report section.
Sets the font for field and/or
SetFont text characters in the report
section specified.

Print Destination
Functions Selects a printer other than the
SelectPrinter
default printer
Returns the printer currently
GetSelectedPrinter
selected in the report.
Prepares a direct output to the
OutputToWindow
print window
Prepares a direct output to a
OutputToPrinter
selected printer
ExportTo Prepares to export a file

Gets export options from the user

GetExportOptions
to be used with ExportTo

Graph/Chart
Management Identifies which graph/chart type
GetGraphType
is used for a graph.
Functions Changes which graph/chart type is
SetGraphType
used for a graph.
Identifies the data on which a
GetGraphData
graph is based.
Changes the data on which a graph
SetGraphData
is based.
Gets the identifying text that
GetGraphText
appears on a graph.
Changes the identifying text that
SetGraphText
appears on a graph.

348 Crystal Reports Developer’s Reference

 Identifies the display options set
GetGraphOptions
for a graph.
Changes the display options set for
SetGraphOptions
a graph.

Error
Management Get a number indicating the status
GetErrorCode
of the most recent function called
Functions Inquire on the error text
GetErrorText

CRPEngine::CRPEngine

CRPEngine(v_open BOOLEAN : FALSE);

Parameters v_open
Indicates whether or not the Report Engine should be opened when
the CRPEngine object is created.

Remarks This is the constructor for the class. If open is true, the actual Crystal
Reports DLL is opened (crpe32.dll). Print jobs may only be opened
if the engine itself is open. If originally opened with open = FALSE,
the engine may be opened later with the CRPEngine::Open method.

Class CRPEngine

CRPEngine::Open

Open() RETURNING BOOLEAN

Remarks This method opens the Crystal Report Engine. This method is only
necessary if you constructed the CRPEngine object with the open
parameter equal to FALSE. If you set the open parameter to TRUE
when you constructed the CRPEngine object, this method is
unnecessary.

Return Value Returns TRUE if the Report Engine was opened successfully, FALSE
if something went wrong.

Class CRPEngine

Chapter 5, Crystal NewEra Class Library Reference 349

 Related Topics
CRPEngine::CRPEngine
PEOpenEngine

CRPEngine::Close

Close() RETURNING VOID

Remarks This method closes the Crystal Report Engine.

Class CRPEngine

Related Topics
PECloseEngine

CRPEngine::GetVersion

GetVersion( versionRequested SMALLINT) RETURNING

SMALLINT

Parameters versionRequested
Specifies whether the version number of the Report Engine or the
Report Engine DLL is being requested. Possible values are:

PEP_GV_DLL Returns the version of the DLL.

PEP_GV_ENGINE Returns the version of the Report
Engine.

Remarks This method returns the version number of the Report Engine dll
(crpe32.dll) or the version of the Report Engine itself. The high-order
byte is the major version number and the low-order byte is the minor
version number.
This method can be used whenever you build functionality into a
report that may not be available in earlier versions of the Report
Engine and you need to verify the version number first. The function
can be a handy safeguard for users who have more than one version
of the Report Engine with the older version earlier in the path than
the new version.

350 Crystal Reports Developer’s Reference

Return Value The version number of the currently used Report Engine or Report
Engine DLL.

Class CRPEngine

Related Topics
PEGetVersion

CRPEngine::GetEngineStatus

GetEngineStatus() RETURNING SMALLINT

Remarks This method may be used to get the current engine status. Possible
values returned are:
engineOpen
The Report Engine is currently open.
engineClosed
The Report Engine has been closed, or is not yet open.
engineMissing
No Report Engine is available. Make sure the Report Engine DLL is
located in a directory that appears in your PATH.

Return Value A value of the Status enumerated type. Indicates the current status of
the Report Engine.

Class CRPEngine

CRPEngine::OpenJob

OpenJob(reportFileName CHAR(*)) RETURNING CRPEJob

Parameters reportFileName
The name and path (if necessary) of the report file being opened for
the specified print job.

Chapter 5, Crystal NewEra Class Library Reference 351

Remarks This method opens the report specified by reportFileName. A
pointer to a CRPEJob object is returned. Print job attributes may be
referenced through this object.

Return Value CRPEJob object for the opened print job.

Class CRPEngine

Related Topics
PEOpenPrintJob

CRPEngine::PrintReport

PrintReport( reportFilePath CHAR (*), toPrinter BOOLEAN : TRUE,

toWindow BOOLEAN : FALSE, title CHAR (*) : “Crystal Report”, left
SMALLINT : 0,top SMALLINT : 0, width SMALLINT : 0, height
SMALLINT : 0, style INTEGER : 0, parentWindow ixWindow : NULL)
RETURNING SMALLINT

Parameters reportFilePath
Specifies the name and path of the report to be printed.
toPrinter
Specifies whether or not the report is to be sent to the default printer.
toWindow
Specifies whether or not the report is to be displayed in a Preview
Window .
title
Specifies the title you want to appear in the title bar if the report is
being sent to a Preview Window .
left
Specifies the x coordinate of the upper left hand corner of the
Preview Window, in device coordinates.
top
Specifies the y coordinate of the upper left hand corner of the
Preview Window, in device coordinates.

352 Crystal Reports Developer’s Reference

 width
Specifies the width of the Preview Window , in device coordinates.
height
Specifies the height of the Preview Window, in device coordinates.
style
Specifies the style of the window being created. Style setting can be
combined using the bitwise "OR" operator. Refer to the CWnd class
in the Microsoft Foundation Class Library reference for possible
window styles.
parentWindow
Specifies a pointer to the CWnd object for the window that is the
parent of the Preview Window . Specify NULL if the Preview
Window will not have a parent window.

Remarks This method provides a quick but limited way to print a report. The
report may only be output to a printer or Preview Window . Use this
class method any time you simply want to print a report from an
application without giving the user the ability to customize the
report.

Return Value 0 if the call is successful. Returns an error code if something goes
wrong.

Class CRPEngine

Related Topics
PEPrintReport (C Syntax)

CRPEngine::LogOnServer

LogOnServer(dllName CHAR(*), logOnInfo CRPELogOnInfo)

RETURNING BOOLEAN;

Parameters dllName
Specifies the name of the Crystal Reports DLL for the server or
password protected non-SQL table you want to log onto.

Chapter 5, Crystal NewEra Class Library Reference 353

 logOnInfo
Specifies a pointer to a CRPELogOnInfo class.

Remarks This method opens a connection to a SQL server. More than one
print job may use this connection to a SQL server. Information
required to establish a connection is provided through the
CRPELogOnInfo class.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEngine

Related Topics
PELogOnServer

CRPEngine::LogOffServer

LogOffServer( dllName CHAR (*), const CRPELogOnInfo logOnInfo)

RETURNING BOOLEAN

Parameters dllName
Specifies the name of the Crystal Reports DLL for the server or
password protected non-SQL table you want to log onto.
logOnInfo
Specifies a pointer to a CRPELogOnInfo class.

Remarks This method closes an existing connection to a SQL server.

Connection information is provided through the CRPELogOnInfo
class.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEngine

354 Crystal Reports Developer’s Reference

 Related Topics
PELogOffServer

CRPEngine::LogOnSQLServerWithPrivateInfo

LogOnSQLServerWithPrivateInfo ( dllName CHAR (*), FOREIGN

privateInfo) RETURNING BOOLEAN

Parameters dllName
Specifies the name of the Crystal Reports DLL that was used when
establishing a connection to the Server when the report was first
created. For example, if a report was created using an ODBC data
source, specify the filename "PDSODBC.DLL". For more information
on possible database DLLs, refer to Runtime File Requirements in
RUNTIME.HLP.
privateInfo
Specifies the application’s handle to the Server connection. In your
application, a connection to the Server must already be established
before this method is called. Pass the HDBC (handle to a database
connection) from this connection to the privateInfo parameter.

Remarks Use this class method to allow the Crystal Report Engine to
"piggyback" your application’s existing connection to a Server. This
lowers the number of connections established by a workstation,
reducing application time and network traffic. It also prevents a
Crystal Reports Log Off call from disconnecting an application’s
existing connection to the Server.
The CRPEngine::LogOnSQLServerWithPrivateInfo method can
only be used with database connections established by ODBC or
Q+E Library 2.0. Any other database connections can not be accessed
by this method.
To obtain an HDBC for an ODBC connection, use the following
function calls (see the ODBC SDK 2,0 manual for more information):
SQLAllocEnv
Initializes the ODBC call level interface and allocates memory for an
environment handle.
SQLAllocConnect
Returns an ODBC HDBC

Chapter 5, Crystal NewEra Class Library Reference 355

 To obtain an HDBC for a Q+E Library connection, use the following
function calls (see the InterSolv DataDirect Developer’s Toolkit for
more information):
qeConnect
Opens a connection to the server
qeGetODBCHdbc
Returns the ODBC HDBC

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEngine

CRPEngine::CanClose

CanClose () RETURNING BOOLEAN

Remarks Checks to see whether or not the Report Engine is busy. Errors can
occur in your application or on a system if you attempt to close the
Report Engine while it is processing a print job. Use this method
before attempting to close the Report Engine in an application (for
example, when the user tries to exit) to determine if the Report
Engine can be closed safely.

Return Value TRUE if the Report EngineReport Engine can be closed, FALSE if the
Report Engine is still busy.

Class CRPEngine

CRPEngine::GetNPrintJobs

GetNPrintJobs () RETURNING SMALLINT;

Remarks This method returns the number of print job (CRPEJob) objects that
currently exist for the current CRPEngine object.

Return Value The number of CRPEJob objects currently open. Returns -1 if an error
occurs.

356 Crystal Reports Developer’s Reference

Class CRPEngine

CRPEngine::GetErrorCode

GetErrorCode( ) RETURNING SMALLINT

Remarks This method returns the current error code of the Report Engine.
When a call to another function fails, this call gets the error code that
was generated so you can take some action based on that error code.

Return Value The current Report Engine error code. 0 if no error has occurred.

Class CRPEngine

Related Topics
PEGetErrorCode

CRPEngine::GetErrorText

GetErrorText() RETURNING ixString

Remarks This method returns a descriptive Report Engine error message.

Return Value A CString object containing the text for the current error.

Class CRPEngine

Related Topics
PEGetErrorText

Chapter 5, Crystal NewEra Class Library Reference 357

CRPEJob::CRPEJob

CRPEJob(jobHandle SMALLINT);

Parameters jobHandle
Handle to the job created by CRPEngine::OpenJob().

Remarks This is the constructor for the class. It also stores the job number
internally for future use in Report Engine API calls.
NOTE: This class constructor is automatically called by
CRPEngine::OpenJob(). Do not call this constructor from within
your own code.

Class CRPEJob

CRPEJob::StartJob

StartJob() RETURNING BOOLEAN

Remarks This method is used to start the processing of the print job and
display the final output of that processing. This is the method that
actually prints or exports the report.

Return Value TRUE if the job is started successfully, FALSE if something goes
wrong.

Class CRPEJob

Related Topics
PEStartPrintJob

358 Crystal Reports Developer’s Reference

CRPEJob::Close

Close() RETURNING VOID

Remarks This method closes the print job. It also calls the destructor for the
CRPEJob object. If printing has not yet finished when this method is
called, it continues until the job is completely printed. If the Preview
Window is open, it stays open.

Class CRPEJob

Related Topics
PEClosePrintJob

CRPEJob::Cancel

Cancel() RETURNING VOID

Remarks This method cancels processing of a print job. It can be tied to a

control that allows the user to cancel a print job in progress.

Class CRPEJob

Related Topics
PECancelPrintJob (C Syntax)

CRPEJob::GetJobStatus

GetJobStatus() RETURNING SMALLINT, CRPEJobInfo

Remarks This method gets the current status of the print job. You can use it in
a number of programming situations, for example:
 to trigger error messages, i.e., when a print job fails (due to
insufficient memory, insufficient disk space, etc.) or,
 to trigger screen displays (hourglass, series of graphics, etc.)
that confirm to the user that work is in progress.
 to find out whether a job was cancelled by the user after
CRPEJob::Start was called.

Chapter 5, Crystal NewEra Class Library Reference 359

Return Values SMALLINT
Returns one of the following values according to the status of the
current print job:

-1 The Report Engine has not been

opened, or a print job has not been
established.
PEP_JOBNOTSTARTED The job has not been started.
PEP_JOBINPROGRESS The job is currently in progress.
PEP_JOBCOMPLETED The job has completed successfully.
PEP_JOBFAILED The job has failed.
PEP_JOBCANCELLED The job has been cancelled by the
user.

CRPEJobInfo
Class CRPEJobInfo.

Class CRPEJob

Related Topics
PEGetJobStatus

CRPEJob::IsJobFinished

IsJobFinished() RETURNING BOOLELAN

Remarks This method returns a Boolean value that indicates whether or not
processing has finished for the print job. You can use this method
any time you have a call that is contingent on a print job being
finished.

Return Value TRUE if processing has finished, FALSE if the job is in progress.

Class CRPEJob

Related Topics
PEIsPrintJobFinished

360 Crystal Reports Developer’s Reference

CRPEJob::GetJobHandle

GetJobHandle() RETURNING SMALLINT

Remarks This method returns the job handle for the print job.

Return Value The print job handle for the CRPEJob object.

Class CRPEJob

CRPEJob::ShowNextPage

ShowNextPage() RETUNING BOOLEAN

Remarks This method shows the next page in the Preview Window . Use this
method to customize how a user moves through pages in a report.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEShowNextPage

CRPEJob::ShowFirstPage

ShowFirstPage() RETURNING BOOLEAN

Remarks This method shows the first page in the Preview Window . Use this
method to customize how a user moves through pages in a report.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Chapter 5, Crystal NewEra Class Library Reference 361

 Related Topics
PEShowFirstPage

CRPEJob::ShowPreviousPage

ShowPreviousPage() RETURNING BOOLEAN

Remarks This method shows the previous page in the Preview Window . Use
this method to customize how a user moves through pages in a
report.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEShowPreviousPage

CRPEJob::ShowLastPage

ShowLastPage() RETURNING BOOLEAN

Remarks This method shows the last page in the Preview Window . Use this
method to customize how a user moves through pages in a report.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEShowLastPage

362 Crystal Reports Developer’s Reference

CRPEJob::ShowPrintControls

ShowPrintControls(showControls BOOLEAN) RETURNING

BOOLEAN

Parameters showControls
TRUE indicates default Print controls are to be displayed in the
Preview Window. FALSE indicates no controls are to be displayed.

Remarks This method toggles the display of the Preview Window control
buttons. Use this to display default controls, or to hide default
controls and provide customized controls.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEShowPrintControls

CRPEJob::ZoomPreviewWindow

ZoomPreviewWindow(level SMALLINT) RETURNING BOOLEAN

Parameters level
The magnification level to which the Preview Window is to be
"zoomed". Use one of the following values:

PEP_ZOOM_FULL_SIZ Full page.

E
PEP_ZOOM_SIZE_FIT_ Fit one side (highest magnification).
ONE_SIDE
PEP_ZOOM_SIZE_FIT_ Fit both sides.
BOTH_SIDES

Chapter 5, Crystal NewEra Class Library Reference 363

Remarks This method "zooms" the Preview Window to the specified
magnification level. Use this function when the report has been
printed to a Preview Window and you need to set the magnification
of the Preview Window to a specific level.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEZoomPreviewWindow

CRPEJob::NextWindowMagnification

NextWindowMagnification() RETURNING BOOLEAN

Remarks This method switches to the next print window magnification in

order. Use this function to cycle through the three levels of Preview
Window magnification whenever the report has been printed to a
Preview Window . The three levels of magnification are: Full Page,
Fit One Side, and Fit Both Sides.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PENextPrintWindowMagnification

CRPEJob::PrintWindow

PrintWindow() RETURNING BOOLEAN

Remarks This method prints the report displayed in the Preview Window to
the printer. If you are customizing Preview Window controls, use
this method to enable the user to preview the report in the Preview

364 Crystal Reports Developer’s Reference

 Window , and then, if everything looks satisfactory, to print the
report to the printer (in response to a user event - button click, menu
command, etc.).

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEPrintWindow

CRPEJob::ExportPrintWindow

ExportPrintWindow(toMail BOOLEAN) RETURNING BOOLEAN

Parameters toMail
Specifies whether or not the report file should be exported to an E-
mail address. If TRUE, the file is exported to E-mail. If FALSE, the file
is exported to a disk file.

Remarks This method exports the report displayed in the Preview Window to
a disk file or E-mail address. If you are customizing Preview
Window controls, use this method to enable the user to preview the
report in the Preview Window , and if everything looks satisfactory,
to export the report to a disk file or E-mail address (in response to a
user event - button click, menu command, etc.).

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Chapter 5, Crystal NewEra Class Library Reference 365

CRPEJob::CloseWindow

CloseWindow() RETURNING VOID

Remarks This method closes the Preview Window . If you are customizing
Preview Window controls, implement this method to allow the user
to close the Preview Window when finished viewing the report.

Class CRPEJob

Related Topics
PECloseWindow

CRPEJob::TestNthTableConnectivity

TestNthTableConnectivity(tableN SMALLINT) RETURNING

BOOLEAN

Parameters tableN
Specifies the number of the table for which you want to test the
connection settings. The first table added to a report is numbered 0,
the second is 1, etc.

Remarks This method tests to see if a valid connection exists to the database
for the specified table in the report. This method is typically used if
you plan to print at a later time, but you want to test now to make
sure everything is in order for logging on to the database table.

Return Value TRUE if the database session, log on, and location info. is all correct.
FALSE if something is wrong.

Class CRPEJob

Related Topics
PETestNthTableConnectivity

366 Crystal Reports Developer’s Reference

CRPEJob::GetNTables

GetNTables() RETURNING SMALLINT

Remarks This method returns the number of tables in the report.

Return Value The number of tables used in the report. Returns -1 if an error occurs.

Class CRPEJob

Related Topics
PEGetNTables

CRPEJob::GetNthTableType

GetNthTableType(tableN SMALLINT) RETURNING BOOLEAN,

CRPETableType

Parameter tableN
0 indexed table number indicating which table in the report for
which you want to determine the type.

Remarks This method gets table type information for the specified table.

Return Values BOOLEAN

TRUE if the call is successful, FALSE if anything goes wrong.
CRPETableType
Class CRPETableType

Class CRPEJob

Related Topics
PEGetNthTableType

Chapter 5, Crystal NewEra Class Library Reference 367

CRPEJob::GetNthTableSessionInfo

GetNthTableSessionInfo(tableN SMALLINT) RETURNING

BOOLEAN, CRPESessionInfo

Parameters tableN
A 0 indexed table number indicating which MS Access table in the
report you wish to obtain the session information for.

Remarks This methods gets session information for the specified Microsoft
Access table. Many MS Access database tables require that a session
be opened before the information in the table can be used. Use this
method to obtain the session information (User ID and Session
Handle) for a particular tab.

Return Values BOOLEAN

TRUE if the call is successful, FALSE if anything goes wrong.
CRPESessionInfo
Class CRPESessionInfo

Class CRPEJob

Related Topics
PEGetNthTableSessionInfo

CRPEJob::SetNthTableSessionInfo

SetNthTableSessionInfo(tableN SMALLINT, sessionInfo

CRPESessionInfo, propagate BOOLEAN) RETURNING BOOLEAN

Parameters tableN
0 indexed table number indicating which MS Access table in the
report the session is being opened for.
sessionInfo
A pointer to a CRPESessionInfo class.

368 Crystal Reports Developer’s Reference

 propagate
TRUE or FALSE value indicating whether the session information
should be used for opening all tables being used in the report.

Remarks This methods sets session information for the specified Microsoft
Access table. Many MS Access database tables require that a session
be opened before the table can be used. Use this method to open the
session.

Return Value TRUE if the call is successful, FALSE if anything goes wrong.

Class CRPEJob

Related Topics
PESetNthTableSessionInfo

CRPEJob::GetNthTableLocation

GetNthTableLocation(tableN SMALLINT) RETURNING

BOOLEAN, CRPETableLocation

Parameters tableN
Specifies the 0 indexed number of the table for which you want to
retrieve location information.

Remarks This method gets table location information for the specified table in
the report. This method is typically combined with the
CRPEJob::SetNthTableLocation method to identify the location of a
table and then to change it.

Return Values BOOLEAN

TRUE if the call is successful, FALSE if anything goes wrong.
CRPETableLocation
CRPETableLocation class.

Class CRPEJob

Chapter 5, Crystal NewEra Class Library Reference 369

 Related Topics
PEGetNthTableLocation

CRPEJob::SetNthTableLocation

SetNthTableLocation(tableN SMALLINT, tableLocation

CRPETableLocation) RETURNING BOOLEAN

Parameters tableN
Specifies the 0 indexed number of the table for which you want to set
a new location.
tableLocation
A pointer to a CRPETableLocation class.

Remarks This method sets table location information for the specified table in
the report. This method is typically combined with the
CRPEJob::GetNthTableLocation method to identify the location of a
table and then to change it.

Return Value TRUE if the call is successful, FALSE if anything goes wrong.

Class CRPEJob

Related Topics
PESetNthTableLocation

CRPEJob::GetNthTableLogOnInfo

GetNthTableLogonInfo(tableN SMALLINT) RETURNING

BOOLEAN, CRPELogonInfo

Parameters tableN
Specifies the 0 indexed number of the table from which you want to
get log on information.

370 Crystal Reports Developer’s Reference

Remarks This method gets SQL connection information for the specified table.

Return Value BOOLEAN

TRUE if the call is successful, FALSE if anything goes wrong.
logonInfo
CRPELogOnInfo class.

Class CRPEJob

Related Topics
PEGetNthTableLogOnInfo

CRPEJob::SetNthTableLogOnInfo

SetNthTableLogonInfo(tableN SMALLINT, logonInfo

CRPELogOnInfo, propagate BOOLEAN) RETURNING BOOLEAN

Parameters tableN
Specifies the 0 indexed number of the table for which you want to set
log on information.
logonInfo
A pointer to a CRPELogOnInfo class.
propagate
TRUE or FALSE value indicating whether the log on information
should be used for opening all tables being used in the report.

Remarks This method sets SQL connection information for the specified table.
The propagate flag may be used to cause the change to affect all
tables with similar server and database properties.

Return Value TRUE if the call is successful, FALSE if anything goes wrong.

Class CRPEJob

Chapter 5, Crystal NewEra Class Library Reference 371

 Related Topics
PESetNthTableLogOnInfo

CRPEJob::GetFormula

GetFormula(formulaName CHAR(*)) RETURNING BOOLEAN,

ixString

Parameters formulaName
The name of the formula for which you want to retrieve the formula
string.

Remarks This method returns the formula text for the specified formula.
CRPEJob::GetFormula is often used with CRPEJob::SetFormula to
identify and then change an existing formula at print time in
response to a user selection.

Return Values BOOLEAN

TRUE if the call is successful, FALSE if the named formula does not
exist in the report.
ixString
The object passed here is loaded with the specified formula text
when CRPEJob::GetFormula completes successfully.

Class CRPEJob

Related Topics
PEGetFormula

CRPEJob::SetFormula

SetFormula(formulaName CHAR(*), formulaText CHAR(*))

RETURNING BOOLEAN

Parameters formulaName
The name of the formula for which you want to assign new formula
text.

372 Crystal Reports Developer’s Reference

 formulaText
The actual formula text that replaces the existing formula string.

Remarks This method sets the formula text for the specified formula.
CRPEJob::SetFormula is often used with CRPEJob::GetFormula to
identify and then change an existing formula at print time in
response to a user selection.

Return Value TRUE if the call is successful, FALSE if the named formula does not
exist in the report, or there is an error in the formula.

Class CRPEJob

Related Topics
PESetFormula

CRPEJob::GetSelectionFormula

GetSelectionFormula() RETURNING BOOLEAN, ixString

Remarks This method returns the formula text for the record selection
formula. CRPEJob::GetSelectionFormula is often used with
CRPEJob::SetSelectionFormula to identify and then change an
existing selection formula at print time in response to a user
selection.

Return Values BOOLEAN

TRUE if the call is successful, FALSE if something goes wrong.
ixString
Specifies the existing selection formula for the report.

Class CRPEJob

Related Topics
PEGetSelectionFormula

Chapter 5, Crystal NewEra Class Library Reference 373

CRPEJob::SetSelectionFormula

SetSelectionFormula(formulaText CHAR(*)) RETURNING

BOOLEAN

Parameters formulaText
Specifies the new selection formula to be assigned to the report.

Remarks This method sets the formula text for the record selection formula.
CRPEJob::SetSelectionFormula is often used with
CRPEJob::GetSelectionFormula to identify and then change an
existing selection formula at print time in response to a user
selection.

Return Value TRUE if the call is successful, FALSE if something goes wrong, or
there is an error in the formula.

Class CRPEJob

Related Topics
PESetSelectionFormula

CRPEJob::GetGroupSelectionFormula

GetGroupSelectionFormula() RETURNING BOOLEAN, ixString

Remarks This method returns the formula text for the group selection formula.
CRPEJob::GetGroupSelectionFormula is often used with
CRPEJob::SetGroupSelectionFormula to identify and then change an
existing group selection formula at print time in response to a user
selection.

Return Value BOOLEAN

TRUE if the call is successful, FALSE if something goes wrong.
ixString
Specifies the existing group selection formula for the report.

Class CRPEJob

374 Crystal Reports Developer’s Reference

 Related Topics
PEGetGroupSelectionFormula

CRPEJob::SetGroupSelectionFormula

SetGroupSelectionFormula(formulaText CHAR(*)) RETURNING

BOOLEAN

Parameters formulaText
Specifies the new group selection formula to be assigned to the
report.

Remarks This method sets the formula text for the group selection formula.
CRPEJob::SetGroupSelectionFormula is often used with
CRPEJob::GetGroupSelectionFormula to identify and then change
an existing group selection formula at print time in response to a user
selection.

Return Value TRUE if the call is successful, FALSE if something goes wrong, or
there is an error in the formula.

Class CRPEJob

Related Topics
PESetGroupSelectionFormula

CRPEJob::SetGroupCondition

SetGroupCondition(sectionCode SMALLINT,conditionField CHAR(*),

condition SMALLINT, sortDirection SMALLINT) RETURNING
BOOLEAN

Parameters sectionCode
Specifies the code for the group section for which you want to set the
group condition. Select a section from the table below:

PEP_GROUPHEADER Sets the group condition for the

Group Header section.
PEP_GROUPFOOTER Sets the group condition for the
Group Footer section.

Chapter 5, Crystal NewEra Class Library Reference 375

 conditionField
Specifies the field that triggers a summary whenever its value
changes. Use the name of the field as indicated in the report file.
condition
Specifies the condition that needs to be met for Date and Boolean
fields. For all field types except Date and Boolean, use
PEP_GC_ANYCHANGE as the condition parameter. For Date fields,
select from the following:

PEP_GC_DAILY Triggers a grouping every time

the date changes.
PEP_GC_WEEKLY Triggers a grouping every time
the date changes from one
week to the next (a week runs
from Sunday through
Saturday).
PEP_GC_BIWEEKLY Triggers a grouping every time
the date changes from one two-
week period to the next.
PEP_GC_SEMIMONTHLY Triggers a grouping every time
the date changes from one half-
month period to the next.
PEP_GC_MONTHLY Triggers a grouping every time
the date changes from one
month to the next.
PEP_GC_QUARTERLY Triggers a grouping every time
the date changes from one
calendar quarter to the next.
PEP_GC_SEMIANNUALLY Triggers a grouping every time
the date changes from one half-
year period to the next.
PEP_GC_ANNUALLY Triggers a grouping every time
the date changes from one year
to the next.

For Boolean fields, select the condition parameter from the

following:

PEP_GC_TOYES Triggers a grouping every time the

sort and group by field changes from
No to Yes.

376 Crystal Reports Developer’s Reference

 PEP_GC_TONO Triggers a grouping every time the
sort and group by field changes from
Yes to No.
PEP_GC_EVERYYES Triggers a grouping every time the
group and sort by field value is Yes.
PEP_GC_EVERYNO Triggers a grouping every time the
group and sort by field value is No.
PEP_GC_NEXTISYES Triggers a grouping every time the
next value in the sort and group by
field is Yes.
PEP_GC_NEXTISNO Triggers a grouping every time the
next value in the sort and group by
field is No.
sortDirection
Specifies one of the following sort directions:

PEP_SF_ASCENDING Sorts data in ascending order (A to Z,

1 to 9).
PEP_SF_DESCENDING Sorts data in descending order (Z to
A, 9 to 1).

Remarks This method sets the condition of the grouping for the specified
group section. This method can only replace the group condition for
an existing group. It can not create a new group. Use this function
whenever you want to change the grouping at print time, for
example, to print one report grouped in several different ways.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetGroupCondition

CRPEJob::GetNSortFields

GetNSortFields() RETURNING SMALLINT

Remarks This method gets the number of sort fields in the report.

Chapter 5, Crystal NewEra Class Library Reference 377

Return Value The number of sort fields defined in the report. Returns 0 (zero) if
there are no sort fields in the report. Returns -1 if an error occurs.

Class CRPEJob

Related Topics
PEGetNSortFields

CRPEJob::GetNthSortField

GetNthSortField(sortFieldN SMALLINT) RETURNING BOOLEAN,

ixString, SMALLINT

Parameters sortFieldN
Specifies the number of the sort field you want to retrieve. The first
sort field added to the report is field 0, the second is 1, etc.

Remarks This method gets the name of the sort field at the specified sort field
position and the direction in which data is sorted (ascending or
descending).

Return Values BOOLEAN

TRUE if the call is successful, FALSE if something goes wrong.
ixString
Assigned the name of the sort field if the call completes successfully.
SMALLINT
Assigned the sort direction of the sort field if the call completes
successfully.
The following values are possible:

PEP_SF_ASCENDING Sorted in ascending order (A to Z, 1

to 9).
PEP_SF_DESCENDING Sorted in descending order (Z to A, 9
to 1).

Class CRPEJob

378 Crystal Reports Developer’s Reference

 Related Topics
PEGetNthSortField

CRPEJob::SetNthSortField

SetNthSortField(sortFieldN SMALLINT, field CHAR(*), direction

SMALLINT) RETURNING BOOLEAN

Parameters sortFieldN
Specifies the number of the sort field you want to set. The first sort
field added to the report is field 0, the second is 1, etc. If the report
has N sort fields, the function can be called with this parameter
between 0 and N-1 to replace an existing sort field. Call the function
with this parameter equal to N to add a new sort field.
field
Specifies the name of the field to be sorted.
direction
Specifies the sort direction. The following values are possible:

PEP_SF_ASCENDING Sorts in ascending order (A to Z, 1 to

9).
PEP_SF_DESCENDING Sorts in descending order (Z to A, 9
to 1).

Remarks This method sorts report data according to the specified field and
direction.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetNthSortField

Chapter 5, Crystal NewEra Class Library Reference 379

CRPEJob::DeleteNthSortField

DeleteNthSortField(sortFieldN SMALLINT) RETURNING

BOOLEAN

Parameters sortFieldN
Specifies the number of the sort field you want to delete. The first sort
field added to the report is field 0, the second is 1, etc.

Remarks This method deletes the specified sort field from the report. The field
is not deleted from the report, but it is removed from the list of sort
fields, and data in that field no longer appears sorted.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEDeleteNthSortField

CRPEJob::GetNGroupSortFields

GetNGroupSortFields () RETURNING SMALLINT

Remarks Returns the number of group sort fields in the specified report. This
method is typically used as one of a series: GetNGroupSortFields
(called once), GetNthGroupSortField (called as many times as
needed to identify the correct group sort field), and
SetNthGroupSortField (called once, when the correct group sort field
is identified). The series can be used to identify and then change an
existing group sort field and/or sort order at print time in response
to a user selection.

Return Value The number of group sort fields in the report. Returns 0 if there are
no group sort fields. Returns -1 if an error occurs.

Class CRPEJob

380 Crystal Reports Developer’s Reference

 Related Topics
PEGetNGroupSortFields

CRPEJob::SetNthGroupSortField

SetNthGroupSortField(sortFieldN SMALLINT, field CHAR(*),

direction SMALLINT) RETURNING BOOLEAN

Parameters sortFieldN
Specifies the number of the group sort field you want to set. The first
group sort field added to the report is field 0, the second is 1, etc. If
the report has N group sort fields, the function can be called with this
parameter between 0 and N-1 to replace an existing group sort field.
Call the function with this parameter equal to N to add a new group
sort field.
field
Specifies the name of the group field to be sorted.
direction
Specifies the sort direction. The following values are possible:

PEP_SF_ASCENDING Sorts in ascending order (A to Z, 1 to

9).
PEP_SF_DESCENDING Sorts in descending order (Z to A, 9
to 1).

Remarks This method sorts the specified group summary field in the specified
direction (ascending or descending). This method does not create a
new group, but will sort and existing group summary field.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetNthGroupSortField

Chapter 5, Crystal NewEra Class Library Reference 381

CRPEJob::DeleteNthGroupSortField

DeleteNthGroupSortField (sortFieldN SMALLINT) RETURNING

BOOLEAN

Parameters sortFieldN
Specifies the number of the group sort field you want to delete. The
first group sort field added to the report is field 0, the second is 1, etc.

Remarks This method deletes the group sort field at the specified position. The
group and group summary are not removed from the report, but the
field is removed from the list of group sort fields, and the summary
data appearing in the group field is no longer sorted.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEDeleteNthGroupSortField

CRPEJob::GetSQLQuery

GetSQLQuery () RETURNING BOOLEAN, ixString

Remarks This method retrieves the SQL query that will be sent to the database
server. This method can be used with CRPEJob::SetSQLQuery to
retrieve and then change the SQL query for the report.

Return Values TRUE if the call is successful, FALSE if something goes wrong.
ixString
Assigned the text of the SQL query being sent to the server if the call
completes successfully.

Class CRPEJob

382 Crystal Reports Developer’s Reference

 Related Topics
PEGetSQLQuery

CRPEJob::SetSQLQuery

SetSQLQuery (query CHAR(*)) RETURNING BOOLEAN

Parameters query
The text of the new SQL query to be sent to the server.

Remarks This method sets the SQL query that will be sent to the database
server. This method can be used with CRPEJob::GetSQLQuery to
retrieve and then change the SQL query for the report.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetSQLQuery

CRPEJob::GetReportTitle

GetReportTitle () RETURNING BOOLEAN, ixString

Remarks This method gets the report title for the print job.

Return Values TRUE if the call is successful, FALSE if something goes wrong.
ixString
Assigned the title of the report.

Class CRPEJob

Chapter 5, Crystal NewEra Class Library Reference 383

 Related Topics
PEGetReportTitle

CRPEJob::SetReportTitle

SetReportTitle (title CHAR(*)) RETURNING BOOLEAN

Parameter title
Specifies a new title for the report.

Remarks This method sets the report title for the print job. Use this method
whenever you need to change the title of a report at print time.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetReportTitle

CRPEJob::SetPrintDate

SetPrintDate (v_year SMALLINT, v_month SMALLINT, v_day

SMALLINT) RETURNING BOOLEAN

Parameters v_year
Specifies the year of the new print date.
v_month
Specifies the month of the new print date.
v_day
Specifies the day of the new print date.

Remarks This method sets the print date for the report. This method does not
schedule the report to print at a different time or day, but only

384 Crystal Reports Developer’s Reference

 changes the date that appears in any Print Date Field that appears on
the report. Use this method, for example, to post date a report when
it is printed before the day it is distributed.

Return Values TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetPrintDate

CRPEJob::SetPrintOptions

SetPrintOptions (options CRPEPrintOptions) RETURNING

BOOLEAN

Parameters options
A pointer to a CRPEPrintOptions class.

Remarks This method may be used to set the print characteristics of a print job.
Use this method any time you want to set the starting page number,
the ending page number, the number of report copies, and/or
collation instructions for a print job at runtime in response to user
specifications.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetPrintOptions

Chapter 5, Crystal NewEra Class Library Reference 385

CRPEJob::SetNDetailCopies

SetNDetailCopies (nCopies SMALLINT) RETURNING BOOLEAN

Parameters nCopies
Specifies the number of copies of the detail section of the report to be
printed.

Remarks This method sets the number of times the Details section of the report
is to be printed. For example, you can use this method to print
multiple copies of labels for a customer, multiple copies of a
purchase order, or multiple copies of anything set up in the Details
section of the report.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetNDetailCopies

CRPEJob::SetMargins

SetMargins ( left SMALLINT, right SMALLINT, top SMALLINT,

bottom SMALLINT) RETURNING BOOLEAN

Parameters left
Specifies the left margin in twips.
right
Specifies the right margin in twips.
top
Specifies the top margin in twips.
bottom
Specifies the bottom margin in twips.

386 Crystal Reports Developer’s Reference

 NOTE: For any of the above parameters, PM_SM_DEFAULT can be
used to specify that the report use default printer margins.

Remarks This method sets the page margins for the print job. Use this method
any time you want to allow the user to change margins.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetMargins

CRPEJob::SetMinimumSectionHeight

SetMinimumSectionHeight ( sectionCode SMALLINT, height

SMALLINT) RETURNING BOOLEAN

Parameters sectionCode
Specifies the section for which you want to specify the minimum
height. Use one of the following values:

PEP_ALLSECTIONS Sets the minimum section

height for all sections.
PEP_HEADERSECTION Sets the minimum section
height for the Page Header
section
PEP_GROUPHEADER Sets the minimum section
height for the Group Header
section.
PEP_DETAILSECTION Sets the minimum section
height for the Details
section.
PEP_GROUPFOOTER Sets the minimum section
height for the Group Footer
section.
PEP_GRANDTOTALSECTION Sets the minimum section
height for the Grand Total
section.
PEP_FOOTERSECTION Sets the minimum section
height for the Page Footer
section.

Chapter 5, Crystal NewEra Class Library Reference 387

 height
Specifies the minimum height in twips of the specified section.

Remarks This method sets the minimum height for the specified section. For
example, use this command whenever you want to specify a
minimum section height for printing onto preprinted forms or
printing on to any other kind of document with a fixed format.

Return Value TRUE if the call is successful, FALSE if you have specified an invalid
section or something goes wrong.

Class CRPEJob

Related Topics
PESetMinimumSectionHeight

CRPEJob::SetLineHeight

SetLineHeight ( sectionCode SMALLINT, lineN SMALLINT, height

SMALLINT, ascent SMALLINT) RETURNING BOOLEAN

Parameters sectionCode
Specifies the section containing the line for which you want to
specify the height. Use one of the following values:

PEP_ALLSECTIONS Sets the line height for all

sections.
PEP_HEADERSECTION Sets the line height for the
Page Header section
PEP_GROUPHEADER Sets the line height for the
Group Header section.
PEP_DETAILSECTION Sets the line height for the
Details section.
PEP_GROUPFOOTER Sets the line height for the
Group Footer section.
PEP_GRANDTOTALSECTION Sets the line height for the
Grand Total section.
PEP_FOOTERSECTION Sets the line height for the
Page Footer section.

388 Crystal Reports Developer’s Reference

 lineN
Specifies the line for which you are setting the height. The first line
in a section is line number 0, the next is 1, etc. Use PEP_ALLLINES
to specify all lines in the section.
height
Specifies the height, in twips, of the line.
ascent
Specifies the ascent, in twips, of the line. Line ascent is the distance
from the baseline of the font to the top of the line space.

Remarks This method sets the line height for the specified section. This
method can be used for setting up a report to print on preprinted
forms. It can also be used if you want to insure the size of a line with
relation to the font size, for example, to specify a 12 point line with
10 point type.

Return Value TRUE if the call is successful, FALSE if you have specified an invalid
section or something goes wrong.

Class CRPEJob

Related Topics
PESetLineHeight

CRPEJob::SetFont

SetFont ( sectionCode SMALLINT, scopeCode SMALLINT, faceName

CHAR (*), fontFamily SMALLINT, fontPitch SMALLINT, charSet
SMALLINT, pointSize SMALLINT, isItalic SMALLINT, isUnderlined
SMALLINT, isStruckOut SMALLINT, weight SMALLINT)
RETURNING BOOLEAN

Parameters sectionCode
Specifies the section of the report for which you want to set the font.

Chapter 5, Crystal NewEra Class Library Reference 389

 Use one of the following values:

PEP_ALLSECTIONS Sets the line height for all

sections.
PEP_HEADERSECTION Sets the line height for the
Page Header section
PEP_GROUPHEADER Sets the line height for the
Group Header section.
PEP_DETAILSECTION Sets the line height for the
Details section.
PEP_GROUPFOOTER Sets the line height for the
Group Footer section.
PEP_GRANDTOTALSECTION Sets the line height for the
Grand Total section.
PEP_FOOTERSECTION Sets the line height for the
Page Footer section.

scopeCode
Specifies whether the font selected is to apply to fields, to text, or to
both. To specify both, use the bitwise Or operator: |.
The following values are possible:

PEP_FIELDS Sets the default font for fields in the

report section specified.
PEP_TEXT Sets the default font for all text (that
has not been entered as a text field
value) in the report section specified.

faceName
Specifies the actual face name of the font you want to use. The face
name you pass can typically come from a font dialog box, be hard
coded in the application, or be chosen by the application from the
fonts supported on the printer. Example: "Times New Roman".
fontFamily
Specifies the font family for the font you want to use. Use one of the
following values:

FF_DONTCARE No font family or family does not

matter.
FF_ROMAN Variable pitch font with serifs.
FF_SWISS Fixed pitch font without serifs.

390 Crystal Reports Developer’s Reference

 FF_MODERN Fixed pitch font, with or without
serifs.
FF_SCRIPT Handwriting-like font.
FF_DECORATIVE Fancy display font.
fontPitch
Specifies the font pitch you wish to use. Use one of the following
values:

DEFAULT_PITCH Retains the default pitch for the font.

FIXED_PITCH Fixed pitch, each character is the
same width.
VARIABLE_PITCH Variable pitch, the width of each
character varies.

charSet
Specifies the character set you wish to use. Use one of the following
values:

ANSI_CHARSET DEFAULT_CHARSET
SYMBOL_CHARSET SHIFTJIS_CHARSET
HANGEFUL_CHARSET CHINESEBIG5_CHARSET
OEM_CHARSET

pointSize
Specifies the desired point size for the selected font. Use 0 to indicate
no change.
isItalic
Specifies whether the font selected should be italicized. Use 1 for
italics, 0 for no italics, or PEP_UNCHANGED to leave the italics as
set up in the report.
isUnderlined
Specifies whether the font should be underlined. Use 1 to underline,
0 for no underline, or PEP_UNCHANGED to leave underline
settings as specified in the report.
isStruckOut
Specifies whether or not the font should appear struck-out. Use 1 for
strike-out, 0 for no strike out, or PEP_UNCHANGE to leave strike-
out settings as specified in the report.

Chapter 5, Crystal NewEra Class Library Reference 391

 weight
Specifies the weight of the font. Possible values are:

FW_DONTCARE FW_THIN
FW_EXTRALIGHT FW_LIGHT
FW_NORMAL FW_MEDIUM
FW_SEMIBOLD FW_BOLD
FW_EXTRABOLD FW_HEAVY
FW_ULTRALIGHT FW_REGULAR
FW_DEMIBOLD FW_ULTRABOLD
FW_BLACK

Remarks This method sets the font and font characteristics for the specified
section. Use any time you need to change a default font at runtime in
response to user input, or to specify a built-in printer font.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetFont

CRPEJob::OutputToWindow

OutputToWindow ( title CHAR (*), left SMALLINT, top SMALLINT,

width SMALLINT, height SMALLINT, style INTEGER, parentWindow
ixWindow) RETURNING BOOLEAN

Parameters title
Specifies the title you want to appear in the title bar.
left
Specifies the x coordinate of the upper left hand corner of the
Preview Window , in device coordinates.
top
Specifies the y coordinate of the upper left hand corner of the
Preview Window , in device coordinates.

392 Crystal Reports Developer’s Reference

 width
Specifies the width of the Preview Window , in device coordinates.
height
Specifies the height of the Preview Window , in device coordinates.
style
Specifies the style of the window being created. Style setting can be
combined using the bitwise Or operator ( | ). Refer to the CWnd class
in the Microsoft Foundation Class Library reference for possible
window styles.
parentWindow
Specifies a pointer to the CWnd object for the window that is the
parent of the Preview Window . Specify NULL if the Preview
Window will not have a parent window.

Remarks This method sets the output of the print job to the Preview Window
which will have the specified attributes. This method does not print
the report, but specifies that when the report is printed, it will appear
in a Preview Window . To actually print the report, use
CRPEJob::Start.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEOutputToWindow

CRPEJob::OutputToPrinter

OutputToPrinter (nCopies SMALLINT : 1) RETURNING BOOLEAN

Parameters nCopies
Specifies how many copies of the report are to be printed. Default is
1 copy.

Remarks This method sets the output of the print job to the printer with the
specified number of copies. This method does not print the report,
but specifies that when the report is printed, it will be sent to a
printer. To actually print the report, use CRPEJob::Start.

Chapter 5, Crystal NewEra Class Library Reference 393

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEOutputToPrinter

CRPEJob::SelectPrinter

SelectPrinter ( driverName CHAR (*), printerName CHAR (*),

portName CHAR (*), mode FOREIGN) RETURNING BOOLEAN

Parameters driverName
Specifies the name of the printer driver for the printer being selected.
printerName
Specifies the name of the printer being selected (as indicated in the
Printers Control Panel).
PortName
Specifies the name of the port the printer is attached to. For example:
"LPT1:".
mode
A pointer to a DEVMODE class. The default implementation of
CRPEJob::SelectPrinter ignores this parameter. For more
information on the DEVMODE class, refer to the Microsoft Windows
SDK.

Remarks This method specifies the printer and/or print characteristics for the
print job. You can use this method to enable the user to select a
printer other than the default printer at print time. One way of doing
this is to have your application call the Windows common Print
Setup dialog box.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

394 Crystal Reports Developer’s Reference

 Related Topics
PESelectPrinter

CRPEJob::ExportTo

ExportTo (options CRPEExportOptions) RETURNING BOOLEAN

Parameters options
A pointer to a CRPEExportOptions class.

Remarks This method sets the output of the print job to be exported. The
export format is specified through the options parameter. This
method does not export the report, but specifies that when the report
is printed, it will be exported to a disk file or E-mail address
according to settings in the options parameter. To actually export the
report, use CRPEJob::Start.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PEExportTo

CRPEJob::GetExportOptions

GetExportOptions () RETURNING BOOLEAN,

CRPEExportOptions

Remarks This method prompts the user with a series of dialogs to specify the
export options to be used. These options are used by the Class
Library to fill in a CRPEExportOptions class. The
CRPEJob::ExportTo function can then be used to set the print job
destination using the information in th this class.

Return Values BOOLEAN

TRUE if the call is successful, FALSE if something goes wrong.

Chapter 5, Crystal NewEra Class Library Reference 395

 CRPEExportOptions
CRPEExportOptions class.

Class CRPEJob

Related Topics
PEGetExportOptions

CRPEJob::GetErrorCode

GetErrorCode () RETURNING SMALLINT

Remarks This method gets the error code for the print job. When a call to
another function fails, this call gets the error code that was generated
so you can take some action based on that error code.

Return Value A Crystal NewEra Class Library error code. Return 0

(PEP_NOERROR) if no error has occurred.

Class CRPEJob

Related Topics
PEGetErrorCode

CRPEJob::GetErrorText

GetErrorText () RETURNING ixString

Remarks This method returns a descriptive error message for the print job.

Return Value ixString

A text description of the current Crystal NewEra Class Library error
if an error has occurred.

Class CRPEJob

396 Crystal Reports Developer’s Reference

 Related Topics
PEGetErrorText

CRPEJob::PrintControlsShowing

PrintControlsShowing () RETURNING BOOLEAN, SMALLINT

Remarks Checks if the print controls are displayed in the Preview Window .
Use CRPEJob::ShowPrintControls to change whether or not print
controls will appear in the Preview Window .

Return Values BOOLEAN

TRUE if the call is successful, FALSE if something goes wrong.
SMALLINT
Returns a pointer to a TRUE value if the print controls will be shown
in the Preview Window , FALSE if they will be hidden.

Class CRPEJob

Related Topics
PEPrintControlsShowing

CRPEJob::GetNFormulas

GetNFormulas () RETURNING SMALLINT

Remarks Use this function to fetch the number of formulas in the report. To
fetch the formula by number, use CRPEJob::GetNthFormula.

Return Value The number of formulas in the report. If no formulas exist in the
report, 0 is returned. If an error occurs, -1 is returned.

Class CRPEJob

Chapter 5, Crystal NewEra Class Library Reference 397

 Related Topics
PEGetNFormulas

CRPEJob::GetNthFormula

GetNthFormula ( formulaN SMALLINT) RETURNING BOOLEAN,

ixString, ixString

Parameter formulaN
Specifies the number of the formula about which you want to gather
information. The first formula added to your report is 0, the second
is 1, etc.

Remarks Use this function to obtain the formula name and formula text of a
specific formula in the report. Once the formula name is obtained,
formula text can be changed with CRPEJob::SetFormula.

Return Values BOOLEAN

TRUE if the call is successful, FALSE if something goes wrong.
ixString
Retrieves the name of the formula specified.
ixString
Retrieves the text of the formula specified.

Class CRPEJob

Related Topics
PEGetNthFormula

CRPEJob::CheckFormula

CheckFormula ( *formulaName CHAR (*)) RETURNING BOOLEAN

Parameters formulaName
The name of the formula that you need to check for errors.

398 Crystal Reports Developer’s Reference

Remarks Use this method to check a named formula for errors. This method
works just like the Check button in the Formula Editor. If the named
formula contains an error, the method returns FALSE.

Return Value TRUE if the formula text is okay, FALSE if there is an error in the
formula or something goes wrong.

Class CRPEJob

Related Topics
PECheckFormula

CRPEJob::CheckSelectionFormula

CheckSelectionFormula () RETURNING BOOLEAN

Remarks Use this method to check the record selection formula for the report
for errors. This method works just like the Check button in the
Formula Editor. If the selection formula contains an error, the
method returns FALSE.

Return Value TRUE if the formula text is okay, FALSE if there is an error in the
formula or something goes wrong.

Class CRPEJob

Related Topics
PECheckSelectionFormula

CRPEJob::CheckGroupSelectionFormula

CheckGroupSelectionFormula () RETURNING BOOLEAN

Remarks Use this method to check the group selection formula for the report
for errors. This method works just like the Check button in the
Formula Editor. If the group selection formula contains an error, the
method returns FALSE.

Chapter 5, Crystal NewEra Class Library Reference 399

Return Value TRUE if the formula text is okay, FALSE if there is an error in the
formula or something goes wrong.

Class CRPEJob

Related Topics
PECheckGroupSelectionFormula

CRPEJob::GetNGroups

GetNGroups () RETURNING SMALLINT

Remarks Use this method to fetch the number of group sections in the report.

Return Values The number of group sections in the report. Returns -1 if an error
occurs.

Class CRPEJob

Related Topics
PEGetNGroups

CRPEJob::GetGroupCondition

GetGroupCondition ( sectionCode SMALLINT) RETURNING

BOOLEAN, ixString, SMALLINT, SMALLINT

Parameter sectionCode
Specifies the code for the report section for which you want to get the
grouping condition. Possible values are:

PEP_GROUPHEADER Sets the group condition for the

Group Header section.
PEP_GROUPFOOTER Sets the group condition for the
Group Footer section.

400 Crystal Reports Developer’s Reference

Remarks Determines the group condition information for a selected group
section in the specified report. Use this method to find out the group
condition for a group section. Use CRPEJob::SetGroupCondition to
change the group condition once it is known.

Return Values BOOLEAN

TRUE if the call is successful, FALSE if something goes wrong.
ixString
Specifies the name of the group summary field for which you want
to get the grouping condition.
SMALLINT
Retrieves the type of field being used as the condition field and the
condition that creates a new group. Use one of the following masks
to separate the condition type from the group condition in the
condition parameter.

PEP_GC_CONDITIONMASK Obtains the group condition

value. Use the bitwise AND
(&) to combine this mask with
the value of the condition
parameter to obtain the group
condition value.
PEP_GC_TYPEMASK Obtains the type of field used
for the group condition. Use
the bitwise AND (&) to
combine this mask with the
value of the condition
parameter to obtain a
valuerepresenting the type of
field used by the group
condition.

For group condition field types other than Date and Boolean, the
group condition value of the condition parameter is
PEP_GC_ANYCHANGE. For a group condition field of the type
Date, the group condition value will be one of the following:

PEP_GC_DAILY Triggers a grouping every time

the date changes.
PEP_GC_WEEKLY Triggers a grouping every time
the date changes from one week
to the next (a week runs from
Sunday through Saturday).

Chapter 5, Crystal NewEra Class Library Reference 401

 PEP_GC_BIWEEKLY Triggers a grouping every time
the date changes from one two-
week period to the next.
PEP_GC_SEMIMONTHLY Triggers a grouping every time
the date changes from one half-
month period to the next.
PEP_GC_MONTHLY Triggers a grouping every time
the date changes from one
month to the next.
PEP_GC_QUARTERLY Triggers a grouping every time
the date changes from one
calendar quarter to the next.
PEP_GC_SEMIANNUALLY Triggers a grouping every time
the date changes from one half-
year period to the next.
PEP_GC_ANNUALLY Triggers a grouping every time
the date changes from one year
to the next.
For a group condition field of the type Boolean, the group condition
value will be one of the following:

PEP_GC_TOYES Triggers a grouping every time the

sort and group by field changes from
No to Yes.
PEP_GC_TONO Triggers a grouping every time the
sort and group by field changes from
Yes to No.
PEP_GC_EVERYYES Triggers a grouping every time the
group and sort by field value is Yes.
PEP_GC_EVERYNO Triggers a grouping every time the
group and sort by field value is No.
PEP_GC_NEXTISYES Triggers a grouping every time the
next value in the sort and group by
field is Yes.
PEP_GC_NEXTISNO Triggers a grouping every time the
next value in the sort and group by
field is No.

The group condition field type portion of the condition parameter

will be one of the following values:

402 Crystal Reports Developer’s Reference

 PEP_GC_TYPEOTHER Any field type other than Date or
Boolean. The group condition
portion of the condition parameter
will be PEP_GC_ANYCHANGE.
PEP_GC_TYPEDATE A Date field is used to create the
group summary field.
PEP_GC_TYPEBOOLEAN A Boolean field is used to create
the group summary field.

SMALLINT
Obtains the sort direction for the group summary field. Possible
values are:

PEP_SF_ASCENDING Sorts data in ascending order (A to

Z, 1 to 9).
PEP_SF_DESCENDING Sorts data in descending order (Z
to A, 9 to 1).

Class CRPEJob

Related Topics
PEGetGroupCondition

CRPEJob::GetNParams

GetNParams () RETURNING SMALLINT

Remarks Use this method whenever you need to know how many parameters
are required by a stored procedure in a SQL database table. This
method is usually used in conjunction with CRPEJob::GetNthParam
or CRPEJob::SetNthParam.

Return Value The number of parameters in the current stored procedure being
used to generate the report.

Class CRPEJob

Chapter 5, Crystal NewEra Class Library Reference 403

 Related Topics
PEGetNParams

CRPEJob::GetNthParam

GetNthParam ( paramN SMALLINT) RETURNING BOOLEAN,

ixString

Parameter paramN
Specifies which parameter in the stored procedure you want to get
the value of. The first parameter of a stored procedure is 0, the
second is 1, etc.

Remarks Gets the Nth parameter of a stored procedure. Use this method
whenever you need to find out a particular parameter required by a
stored procedure in a SQL database table.

Return Value BOOLEAN

TRUE if the call is successful, FALSE if something goes wrong.
ixString
Retrieves the current value of the specified parameter in the stored
procedure.

Class CRPEJob

Related Topics
PEGetNthParam

CRPEJob::SetNthParam

SetNthParam ( paramN SMALLINT, paramValue CHAR (*))

RETURNING BOOLEAN

Parameters paramN
Specifies which parameter in the stored procedure you want to set
the value of. The first parameter of a stored procedure is 0, the
second is 1, etc.

404 Crystal Reports Developer’s Reference

 paramValue
Specifies the new value of the indicated parameter. This value must
be a string. Please see Remarks below.

Remarks Sets the value of a parameter in a stored procedure. Use this method
when working with stored procedures in SQL database tables to set
the value of a parameter in a stored procedure. When passing
parameter values, All parameter values must be passed as string
values. If you wish to pass a numeric value, pass the value in quotes
like this: "100".

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetNthParam

CRPEJob::GetPrintDate

GetPrintDate () RETURNING BOOLEAN, SMALLINT, SMALLINT,

SMALLINT

Remarks Determines the print date (if any) that was specified with the report.
Use this method to fetch the print date and pass back using
CRPEJob::SetPrintDate.

Return Value BOOLEAN

TRUE if the call is successful, FALSE if something goes wrong.
SMALLINT
Retrieves the year for the current print date.
SMALLINT
Retrieves the month for the current print date.
SMALLINT
Retrieves the day for the current print date.

Chapter 5, Crystal NewEra Class Library Reference 405

Class CRPEJob

Related Topics
PEGetPrintDate

CRPEJob::GetPrintOptions

GetPrintOptions () RETURNING BOOLEAN, CRPEPrintOptions

Remarks Retrieves the print options specified for the report (the options that
are set in the Print Setup common dialog box) and uses them to fill in
the CRPEPrintOptions class. Use this function to fetch print options
from the report in order to update them and pass back using
CRPEJob::SetPrintOptions.

Return Values BOOLEAN

TRUE if the call is successful, FALSE if something goes wrong.
CRPEPrintOptions
A pointer to a CRPEPrintOptions class.

Class CRPEJob

Related Topics
PEGetPrintOptions

CRPEJob::GetNDetailCopies

GetNDetailCopies ( ) RETURNING BOOLEAN, SMALLINT

Remarks Returns the number of copies of each Details section in the report
that are to be printed. Use this method to find out how many times
each Details section of the report will be printed. To change the
number of times each Details section is printed, use
CRPEJob::SetNDetailCopies.

Return Values BOOLEAN

TRUE if the call is successful, FALSE if something goes wrong.

406 Crystal Reports Developer’s Reference

 nCopies
Retrieves the current setting for the number of times the Details
section of the report will be printed.

Class CRPEJob

Related Topics
PEGetNDetailCopies

CRPEJob::GetMargins

GetMargins ( ) RETURNING BOOLEAN, SMALLINT, SMALLINT,

SMALLINT, SMALLINT

Remarks Retrieves the page margin settings for the specified report. Use this
method to find out what the currently set margins for the report are.
Use CRPEJob::SetMargins to change report margins.

Return Value BOOLEAN

TRUE if the call is successful, FALSE if something goes wrong.
SMALLINT
Retrieves the current setting of the left margin in twips.
SMALLINT
Retrieves the current setting of the right margin in twips.
SMALLINT
Retrieves the current setting of the top margin in twips.
SMALLINT
Retrieves the current setting of the bottom margin in twips.

Class CRPEJob

Related Topics
PEGetMargins

Chapter 5, Crystal NewEra Class Library Reference 407

CRPEJob::GetMinimumSectionHeight

GetMinimumSectionHeight ( sectionCode SMALLINT) RETURNING

BOOLEAN, SMALLINT

Parameters sectionCode
Specifies the code for the report section for which you want to
retrieve the minimum height. Possible values are:

PEP_ALLSECTIONS Gets the minimum section

height for all sections.
PEP_HEADERSECTION Gets the minimum section
height for the Page Header
section
PEP_GROUPHEADER Gets the minimum section
height for the Group Header
section.
PEP_DETAILSECTION Gets the minimum section
height for the Details section.
PEP_GROUPFOOTER Gets the minimum section
height for the Group Footer
section.
PEP_GRANDTOTALSECTION Gets the minimum section
height for the Grand Total
section.
PEP_FOOTERSECTION Gets the minimum section
height for the Page Footer
section.

Remarks Retrieves minimum section height information for selected sections

in the specified report. Use this method to fetch the minimum section
height and pass back using CRPEJob::SetMinimumSectionHeight.

Return Values BOOLEAN

TRUE if the call is successful, FALSE if something goes wrong.
SMALLINT
Retrieves the minimum height, in twips, for the specified report
section.

408 Crystal Reports Developer’s Reference

Class CRPEJob

Related Topics
PEGetMinimumSectionHeight

CRPEJob::GetLineHeight

GetLineHeight ( sectionCode SMALLINT, lineN SMALLINT)

RETURNING BOOLEAN, SMALLINT, SMALLINT

Parameters sectionCode
Specifies the code for the report section containing the line you want
to retrieve the height of. Possible values are:

PEP_ALLSECTIONS Gets the line height for all

sections.
PEP_HEADERSECTION Gets the line height for the
Page Header section
PEP_GROUPHEADER Gets the line height for the
Group Header section.
PEP_DETAILSECTION Gets the line height for the
Details section.
PEP_GROUPFOOTER Gets the line height for the
Group Footer section.
PEP_GRANDTOTALSECTION Gets the line height for the
Grand Total section.
PEP_FOOTERSECTION Gets the line height for the
Page Footer section.

lineN
Specifies the line number within the specified section for which you
want to retrieve the height of. The first line in a section is line 0, the
second is 1, etc. Use PEP_ALLLINES to retrieve information on all
lines in a section.

Remarks Gets line height and ascent information for a specified line in a
selected section of the report. You can change and pass back a new
line height and ascent using CRPEJob::SetLineHeight.

Chapter 5, Crystal NewEra Class Library Reference 409

Return Value BOOLEAN
TRUE if the call is successful, FALSE if something goes wrong.
SMALLINT
Retrieves the height, in twips, of the specified line.
SMALLINT
Retrieves the line ascent, in twips, of the specified line. Line ascent is
the distance from the baseline of the font to the top of the line space.

Class CRPEJob

CRPEJob::GetNLinesInSection

GetNLinesInSection (sectionCode SMALLINT) RETURNING

SMALLINT

Parameters sectionCode
Specifies the code for the report section that you need to know the
number of lines for. Possible values are:

PEP_ALLSECTIONS Gets the number of lines in

all sections.
PEP_HEADERSECTION Gets the number of lines in
the Page Header section
PEP_GROUPHEADER Gets the number of lines in
the Group Header section.
PEP_DETAILSECTION Gets the number of lines in
the Details section.
PEP_GROUPFOOTER Gets the number of lines in
the Group Footer section.
PEP_GRANDTOTALSECTION Gets the number of lines in
the Grand Total section.
PEP_FOOTERSECTION Gets the number of lines in
the Page Footer section.

Remarks Use this method to find out how long a specified report section is
according to the number of lines in the section. This is useful when
trying to fit mailing label reports into the labels you are using, for
example.

410 Crystal Reports Developer’s Reference

Return Value The number of lines in the specified section of the report. Returns -1
if an error occurs.

Class CRPEJob

CRPEJob::GetSelectedPrinter

GetSelectedPrinter ( ) RETURNING BOOLEAN, ixString, ixString,

ixString, FOREIGN

Remarks If a non-default printer is specified in the report, this method

retrieves information about that printer. If you need to know which
printer has been specified with the report, use
CRPEJob::GetSelectedPrinter to obtain the information. This can be
useful to determine if the user has access to the printer specified in
the report and to choose another printer if not.

Return Value BOOLEAN

TRUE if the call is successful, FALSE if something goes wrong.
ixString
Retrieves the name of the printer driver for the currently selected
printer in the report.
ixString
Retrieves the name of the printer currently selected in the report.
ixString
Retrieves the name of the port the currently selected printer is
attached to. For example, "LPT1:".
FOREIGN
A DEVMODE class that contains information on the currently
selected printer, if the CRPEJob::GetSelectedPrinter method
completes successfully. For more information on the DEVMODE
class, refer to the Microsoft Windows Software Development Kit.

Class CRPEJob

Chapter 5, Crystal NewEra Class Library Reference 411

 Related Topics
PEGetSelectedPrinter (C Syntax)

CRPEJob::GetSectionFormat

GetSectionFormat ( sectionCode SMALLINT) RETURNING

BOOLEAN, CRPESectionOptions

Parameter sectionCode
Specifies the code for the report section that you need to obtain
format information for. Possible values are:

PEP_ALLSECTIONS Gets the format

information for all
sections.
PEP_HEADERSECTION Gets the format
information for the Page
Header section
PEP_GROUPHEADER Gets the format
information for the
Group Header section.
PEP_DETAILSECTION Gets the format
information for the
Details section.
PEP_GROUPFOOTER Gets the format
information for the
Group Footer section.
PEP_GRANDTOTALSECTION Gets the format
information for the Grand
Total section.
PEP_FOOTERSECTION Gets the format
information for the Page
Footer section.

Remarks Retrieves the section format settings for a selected section in the
specified report and supplies the information by assigning values to
the members of the CRPESectionOptions class. Use this method in
order to edit and update the section formats and pass information
back using CRPEJob::SetSectionFormat.

412 Crystal Reports Developer’s Reference

Return Values BOOLEAN
TRUE if the call is successful, FALSE if something goes wrong.
CRPESectionOptions
CRPESectionOptions class.

Class CRPEJob

Related Topics
PEGetSectionFormat

CRPEJob::SetSectionFormat

SetSectionFormat ( sectionCode SMALLINT, options

CRPESectionOptions) RETURNING BOOLEAN

Parameters sectionCode
Specifies the code for the report section that you need to change
format information for. Possible values are:

PEP_ALLSECTIONS Sets format information for

all sections.
PEP_HEADERSECTION Sets the format information
for the Page Header section
PEP_GROUPHEADER Sets the format information
for the Group Header
section.
PEP_DETAILSECTION Sets the format information
for the Details section.
PEP_GROUPFOOTER Sets the format information
for the Group Footer section.
PEP_GRANDTOTALSECTION Sets the format information
for the Grand Total section.
PEP_FOOTERSECTION Sets the format information
for the Page Footer section.

options
A pointer to a CRPESectionOptions class.

Chapter 5, Crystal NewEra Class Library Reference 413

Remarks Sets the section format settings for selected sections in the specified
report to the values in the CRPESectionOptions class. This method
can be used to provide specialized formatting for printing invoices,
form letters, printing to pre-printed forms, etc. It allows you to hide a
section, insert a page break either before or after a section begins, reset
the page number to 1 after a group value prints, prevent page breaks
from spreading data from a single record over two pages, and to print
group values only at the bottom of a page. For a complete discussion
of each of these options, see the CRPESectionOptions class.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetSectionFormat

CRPEJob::GetGraphType

GetGraphType ( sectionCode SMALLINT, graphN SMALLINT)

RETURNING BOOLEAN, SMALLINT

Parameters sectionCode
Specifies the section of the report containing the graph you want to
find out the type of. Possible values are:

PEP_ALLSECTIONS Graph appears in all

sections.
PEP_HEADERSECTION Graph appears in the Page
Header section
PEP_GROUPHEADER Graph appears in the Group
Header section.
PEP_DETAILSECTION Graph appears in the Details
section.
PEP_GROUPFOOTER Graph appears in the Group
Footer section.
PEP_GRANDTOTALSECTION Graph appears in the Grand
Total section.
PEP_FOOTERSECTION Graph appears in the Page
Footer section.

414 Crystal Reports Developer’s Reference

 graphN
Specifies which graph within the section you want to know the type
of. This value is 0 indexed. Within a section, graphs are numbered
from top to bottom, first, then from left to right if they have the same
top.

Remarks Identifies one of the available graph/chart types used for the
specified graph in the specified section. Use this method to find out
what type of graph is being displayed in the report. There are many
types of graphs and charts possible with Crystal Reports. This
method will return the type of graph or chart being displayed.

Return Value BOOLEAN

TRUE if the call is successful, FALSE if something goes wrong.
SMALLINT
Retrieves a value indicating the type of graph that the specified
graph is. Possible values are:

PEP_SIDE_BY_SIDE_BAR_GRAPH Side By Side bar graph

PEP_STACKED_BAR_GRAPH Stacked bar graph
PEP_PERCENT_BAR_GRAPH Percent bar graph
PEP_FAKED_3D_SIDE_BY_SIDE_ 3D Side By Side bar
BAR_GRAPH graph
PEP_FAKED_3D_STACKED_BAR_ 3D Stacked bar graph
GRAPH
PEP_FAKED_3D_PERCENT_BAR_ 3D Percent bar graph
GRAPH
PEP_PIE_GRAPH Pie graph
PEP_MULTIPLE_PIE_GRAPH Multiple Pie graph
PEP_PROPORTIONAL_MULTI_ Weighted Pie graph
PIE_GRAPH
PEP_LINE_GRAPH Line graph
PEP_AREA_GRAPH Area graph
PEP_THREED_BAR_GRAPH 3D bar graph
PEP_USER_DEFINED_GRAPH User Defined graph
type
PEP_UNKNOWN_TYPE_GRAPH Unknown graph type

Chapter 5, Crystal NewEra Class Library Reference 415

Class CRPEJob

Related Topics
PEGetGraphType

CRPEJob::SetGraphType

SetGraphType ( sectionCode SMALLINT, graphN SMALLINT,

graphType SMALLINT) RETURNING BOOLEAN

Parameters sectionCode
Specifies the section of the report containing the graph you want to
change the type of. Possible values are:

PEP_ALLSECTIONS Graph appears in all

sections.
PEP_HEADERSECTION Graph appears in the
Page Header section
PEP_GROUPHEADER Graph appears in the
Group Header section.
PEP_DETAILSECTION Graph appears in the
Details section.
PEP_GROUPFOOTER Graph appears in the
Group Footer section.
PEP_GRANDTOTALSECTION Graph appears in the
Grand Total section.
PEP_FOOTERSECTION Graph appears in the
Page Footer section.

graphN
Specifies which graph within the section you want to change the type
of. This value is 0 indexed. Within a section, graphs are numbered
from top to bottom, first, then from left to right if they have the same
top.
graphType
Specifies the style of the graph you want to set.

416 Crystal Reports Developer’s Reference

 Possible values are:

PEP_SIDE_BY_SIDE_BAR_GRAPH Side By Side bar graph

PEP_STACKED_BAR_GRAPH Stacked bar graph
PEP_PERCENT_BAR_GRAPH Percent bar graph
PEP_FAKED_3D_SIDE_BY_SIDE_ 3D Side By Side bar
BAR_GRAPH graph
PEP_FAKED_3D_STACKED_BAR_ 3D Stacked bar graph
GRAPH
PEP_FAKED_3D_PERCENT_BAR_ 3D Percent bar graph
GRAPH
PEP_PIE_GRAPH Pie graph
PEP_MULTIPLE_PIE_GRAPH Multiple Pie graph
PEP_PROPORTIONAL_MULTI_ Weighted Pie graph
PIE_GRAPH
PEP_LINE_GRAPH Line graph
PEP_AREA_GRAPH Area graph
PEP_THREED_BAR_GRAPH 3D bar graph
PEP_USER_DEFINED_GRAPH User Defined graph type
PEP_UNKNOWN_TYPE_GRAPH Unknown graph type

Remarks Changes the type of graph displayed for the specified graph in the
specified section based on one of the available graph/chart types.
Use this method to change the type of graph that is displayed in a
report.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetGraphType

Chapter 5, Crystal NewEra Class Library Reference 417

CRPEJob::GetGraphData

GetGraphData ( sectionCode SMALLINT, graphN SMALLINT)

RETURNING BOOLEAN, CRPEGraphDataInfo

Parameters sectionCode
Specifies the section of the report containing the graph you want to
get information from. Possible values are:

PEP_ALLSECTIONS Graph appears in all

sections.
PEP_HEADERSECTION Graph appears in the Page
Header section
PEP_GROUPHEADER Graph appears in the Group
Header section.
PEP_DETAILSECTION Graph appears in the Details
section.
PEP_GROUPFOOTER Graph appears in the Group
Footer section.
PEP_GRANDTOTALSECTION Graph appears in the Grand
Total section.
PEP_FOOTERSECTION Graph appears in the Page
Footer section.

graphN
Specifies which graph within the section you want to get graph data
information from. This value is 0 indexed. Within a section, graphs
are numbered from top to bottom, first, then from left to right if they
have the same top.

Remarks Use this method to find out what data in your report is being used by
a specified graph when the graph is created. This information
includes which groups are used to create the rows and columns of
the graph and which summary field in the report is used to set the
values of the risers in the graph.

Return Values BOOLEAN

TRUE if the call is successful, FALSE if something goes wrong.

418 Crystal Reports Developer’s Reference

 CRPEGraphDataInfo
A pointer to a CRPEGraphDataInfo class.

Class CRPEJob

Related Topics
PEGetGraphData

CRPEJob::SetGraphData

SetGraphData ( sectionCode SMALLINT, graphN SMALLINT,

graphDataInfo CRPEGraphDataInfo) RETURNING BOOLEAN

Parameters sectionCode
Specifies the section of the report containing the graph you want to
change graph data information for. Possible values are:

PEP_ALLSECTIONS Graph appears in all

sections.
PEP_HEADERSECTION Graph appears in the Page
Header section
PEP_GROUPHEADER Graph appears in the Group
Header section.
PEP_DETAILSECTION Graph appears in the Details
section.
PEP_GROUPFOOTER Graph appears in the Group
Footer section.
PEP_GRANDTOTALSECTION Graph appears in the Grand
Total section.
PEP_FOOTERSECTION Graph appears in the Page
Footer section.

graphN
Specifies which graph within the section you want to change graph
data information for. This value is 0 indexed. Within a section,
graphs are numbered from top to bottom, first, then from left to right
if they have the same top.
graphDataInfo
A pointer to a CRPEGraphDataInfo class.

Chapter 5, Crystal NewEra Class Library Reference 419

Remarks Use this method to change what data is used from your report to
create a specified graph. This information includes the groups used
to create the rows and columns of the graph and the summary field
used to set the values of the risers in the graph.

Return Value BOOLEAN

TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetGraphData

CRPEJob::GetGraphText

GetGraphText ( sectionCode SMALLINT, graphN SMALLINT)

RETURNING BOOLEAN, CRPEGraphTextInfo

Parameters sectionCode
Specifies the section of the report containing the graph you want to
get title text for. Possible values are:

PEP_ALLSECTIONS Graph appears in all sections.

PEP_HEADERSECTION Graph appears in the Page
Header section
PEP_GROUPHEADER Graph appears in the Group
Header section.
PEP_DETAILSECTION Graph appears in the Details
section.
PEP_GROUPFOOTER Graph appears in the Group
Footer section.
PEP_GRANDTOTALSECTION Graph appears in the Grand
Total section.
PEP_FOOTERSECTION Graph appears in the Page
Footer section.

graphN
Specifies which graph within the section you want to get title text for.
This value is 0 indexed. Within a section, graphs are numbered from
top to bottom, first, then from left to right if they have the same top.

420 Crystal Reports Developer’s Reference

Remarks This method allows you to find out what text appears with a graph.
A graph can have a title, subtitle, footnote, title for groups, title for
series, title for the X axis, title for the Y axis, and title for the Z axis (in
3D graphs).

Return Values BOOLEAN

TRUE if the call is successful, FALSE if something goes wrong.
CRPEGraphTextInfo
CRPEGraphTextInfo class.

Class CRPEJob

Related Topics
PEGetGraphText

CRPEJob::SetGraphText

SetGraphText ( sectionCode SMALLINT, graphN SMALLINT,

graphTextInfo CRPEGraphTextInfo) RETURNING BOOLEAN

Parameters sectionCode
Specifies the section of the report containing the graph you want to
change the text of. Possible values are:

PEP_ALLSECTIONS Graph appears in all

sections.
PEP_HEADERSECTION Graph appears in the Page
Header section
PEP_GROUPHEADER Graph appears in the Group
Header section.
PEP_DETAILSECTION Graph appears in the
Details section.
PEP_GROUPFOOTER Graph appears in the Group
Footer section.
PEP_GRANDTOTALSECTION Graph appears in the Grand
Total section.
PEP_FOOTERSECTION Graph appears in the Page
Footer section.

Chapter 5, Crystal NewEra Class Library Reference 421

 graphN
Specifies which graph within the section you want to change the text
of. This value is 0 indexed. Within a section, graphs are numbered
from top to bottom, first, then from left to right if they have the same
top.
graphTextInfo
A pointer to a CRPEGraphTextInfo class.

Remarks This method allows you to set or change the text that appears with a
graph. A graph can have a title, subtitle, footnote, title for groups,
title for series, title for the X axis, title for the Y axis, and title for the
Z axis (in 3D graphs).

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetGraphText

CRPEJob::GetGraphOptions

GetGraphOptions ( sectionCode SMALLINT, graphN SMALLINT)

RETURNING BOOLEAN, CRPEGraphOptions

Parameters sectionCode
Specifies the section of the report containing the graph you want to
get graph display options for. Possible values are:

PEP_ALLSECTIONS Graph appears in all

sections.
PEP_HEADERSECTION Graph appears in the Page
Header section
PEP_GROUPHEADER Graph appears in the Group
Header section.
PEP_DETAILSECTION Graph appears in the
Details section.

422 Crystal Reports Developer’s Reference

 PEP_GROUPFOOTER Graph appears in the Group
Footer section.
PEP_GRANDTOTALSECTION Graph appears in the Grand
Total section.
PEP_FOOTERSECTION Graph appears in the Page
Footer section.
graphN
Specifies which graph within the section you want to get graph
display options for. This value is 0 indexed. Within a section, graphs
are numbered from top to bottom, first, then from left to right if they
have the same top.

Remarks Use this method to obtain information about any of several graph
options. These options include the minimum and maximum values
that can appear on the graph, whether grid lines appear, whether
risers are labeled, whether bar graphs have horizontal or vertical
bars, and whether a legend appears on the graph.

Return Value BOOLEAN

TRUE if the call is successful, FALSE if something goes wrong.
graphOptions
CRPEGraphOptions class.

Class CRPEJob

Related Topics
PEGetGraphOptions

CRPEJob::SetGraphOptions

SetGraphOptions ( sectionCode SMALLINT, graphN SMALLINT,

graphOptions CRPEGraphOptions) RETURNING BOOLEAN

Parameters sectionCode
Specifies the section of the report containing the graph you want to
change display options for. Possible values are:

Chapter 5, Crystal NewEra Class Library Reference 423

 PEP_ALLSECTIONS Graph appears in all sections.
PEP_HEADERSECTION Graph appears in the Page
Header section
PEP_GROUPHEADER Graph appears in the Group
Header section.
PEP_DETAILSECTION Graph appears in the Details
section.
PEP_GROUPFOOTER Graph appears in the Group
Footer section.
PEP_GRANDTOTALSECTION Graph appears in the Grand
Total section.
PEP_FOOTERSECTION Graph appears in the Page
Footer section.

graphN
Specifies which graph within the section you want to change display
options for. This value is 0 indexed. Within a section, graphs are
numbered from top to bottom, first, then from left to right if they
have the same top.
graphOptions
A pointer to a CRPEGraphOptions class.

Remarks Use this function to change any of several graph options. These
options include the minimum and maximum values that can appear
on the graph, whether grid lines appear, whether risers are labeled,
whether bar graphs have horizontal or vertical bars, and whether a
legend appears on the graph.

Return Value TRUE if the call is successful, FALSE if something goes wrong.

Class CRPEJob

Related Topics
PESetGraphOptions

424 Crystal Reports Developer’s Reference

CRPEJob::GetNthGroupSortField

GetNthGroupSortField ( sortFieldN SMALLINT) RETURNING

BOOLEAN, ixString, SMALLINT

Parameter sortFieldN
Specifies the number of the group sort field you want to retrieve. The
first group sort field is field 0. If the report has N sort fields, the
function can be called with sortFieldN between 0 and N-1.

Remarks Returns information about one of the group sort fields in the
specified report: that is, it returns the name of the field and the
direction (ascending or descending) of the sort. This method is
typically used as one of a series: CRPEJob::GetNGroupSortFields
(called once), CRPEJob::GetNthGroupSortField (called as many
times as needed to identify the correct group sort field), and
CRPEJob::SetNthGroupSortField (called once when the correct sort
field is identified). The series can be used to identify and then change
an existing group sort field and/or sort order at print time in
response to a user selection.

Return Values BOOLEAN

TRUE if the call is successful, FALSE if something goes wrong.
ixString
Retrieves the name of the group sort field.
SMALLINT
Retrieves a value indicating the sort direction. Possible values are:

PE_SF_ASCENDING Sorted in Ascending order (A to Z, 1

to 9).
PE_SF_DESCENDING Sorted in Descending order (Z to A, 9
to 1).

Class CRPEJob

Related Topics
PEGetNthGroupSortField

Chapter 5, Crystal NewEra Class Library Reference 425

426 Crystal Reports Developer’s Reference
6 Crystal Report Engine
Reference

What you will find in this chapter...

Working with section codes 428
FUNCTIONS 431
STRUCTURES 619

Chapter 6, Crystal Report Engine Reference 427

Working with section codes
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 than the next, Crystal Reports
uses calculated section codes to identify the sections in each report.
The sectionCode parameter is a value that 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). For section type, use any of the following constants

Section Type Constants Value Description

PE_SECT_REPORT_HEADER 1000 Report Header
Section
PE_SECT_PAGE_HEADER 2000 Page Header
Section
PE_SECT_GROUP_HEADER 3000 Group Header
Section
PE_SECT_DETAIL 4000 Detail Section
PE_SECT_GROUP_FOOTER 5000 Group Footer
Section
PE_SECT_PAGE_FOOTER 7000 Page Footer Section
PE_SECT_REPORT_FOOTER 8000 Report Footer
Section
PE_ALLSECTIONS 0 All Report Sections

The program 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.

428 Crystal Reports Developer’s Reference

Encoding

In this example, you know which section you want to format, you
just need the program to create the section code so you can pass it. To
format the second section in the Group Header 1 area, you use code
similar to this:
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, you use the zero
indexed group number 0) and section number (since this is the
second section in the group header, you use the zero indexed section
number 1). The program uses the encoding macro and returns 3025
as the section code which is then passed in the PESetSectionFormat
call.

Decoding

In this example, you retrieve the section codes of each section and
decode them to identify the section of interest, and then you format
that section. You determine the number of sections (using
PEGetNSections), return 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.
Your code would look similar to this:
numSections = PEGetNSections(job);
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:
PESetSectionFormat(job, code,
&mySectionOptions)
NOTE: The macros enable you to have individual control over as
many as 25 Groups and 40 sections per area.

Chapter 6, Crystal Report Engine Reference 429

 NOTE: Earlier versions of 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 Crystal
Reports can run with applications created with the current version.

Section Map

The following map shows the pattern of section code assignment:

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)
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)
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)

430 Crystal Reports Developer’s Reference

 4075 (Fourth Section in Details Area)
GF1
5000 (First Section in First Group Footer Area)
5025 (Second Section in First Group Footer Area)
5050 (Third Section in First Group Footer Area)
5075 (Fourth Section in First Group Footer 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)

FUNCTIONS
PECancelPrintJob

The PECancelPrintJob function cancels the printing of a report. This

function can be tied to a control that allows the user to cancel a print
job in progress.
Use PECancelPrintJob to replace the Cancel button when
PEShowPrintControls disables the Print Control buttons.

Chapter 6, Crystal Report Engine Reference 431

 void CRPE_API PECancelPrintJob (
short printJob //print job handle
);

Parameters printJob
Specifies the handle to the print job.

Return Value None

PECancelPrintJob (Other Declares)

PECancelPrintJob 16-bit
(VB Syntax) Declare Sub PECancelPrintJob Lib "crpe.dll"
(ByVal printJob As Integer)

32-bit
Declare Sub PECancelPrintJob Lib "crpe32.dll"
(ByVal printJob As Integer)

PECancelPrintJob 16-bit
(Delphi Syntax) procedure PECancelPrintJob (
printJob: integer
);

32-bit
procedure PECancelPrintJob (
printJob: Word
)stdcall;

PECancelPrintJob EXTERN CVOID PECancelPrintJob (CWORD) CRPE.DLL

(dBASE for
Windows Syntax)

432 Crystal Reports Developer’s Reference

PECanCloseEngine

This topic is only supported by the Professional Edition of Crystal

Reports.
The PECanCloseEngine function determines whether or not the
Report Engine can be closed. Use this function before calling
PECloseEngine to verify that the engine is no longer processing print
jobs. If the Report Engine closes while a print job is still running, an
error can occur in your application or on the user’s system.
BOOL CRPE_API PECanCloseEngine (void);

Return Value True if the Engine can be closed, False if the Engine is busy.

PECanCloseEngine (Other Declares)

PECanCloseEngine 16-bit
(VB Syntax) Declare Function PECanCloseEngine Lib
"crpe.dll" () As Integer

32-bit
Declare Function PECanCloseEngine Lib
"crpe32.dll" () As Integer

PECanCloseEngine 16-bit
(Delphi Syntax) function PECanCloseEngine: Bool;

32-bit
function PECanCloseEngine: Bool stdcall;

PECanCloseEngine EXTERN CLOGICAL PECanCloseEngine () CRPE.DLL

(dBASE for
Windows Syntax)

Chapter 6, Crystal Report Engine Reference 433

PECheckFormula

The PECheckFormula function checks the text of a named formula

for validity. Use this function to check a named formula for errors.
This function works like the Check button in the Formula Editor. If
the named formula contains an error, the function returns False.
BOOL CRPE_API PECheckFormula (
short printJob, //handle to print job
char FAR *formulaName
//formula to be checked
);

Parameters printJob
The handle of the print job containing the named formula you are
checking.
formulaName
The name of the formula you wish to check for errors.

Return Value TRUE (1) if the formula is correct, FALSE (0) if the formula has an
error.

Remarks ● When specifying the name of the formula, do not use the @
symbol before the name. The @ symbol is only used by Crystal
Reports to separate a formula field from other types of fields.
● PECheckFormula works like the Check button that appears in the
Crystal Reports Formula Editor.

PECheckFormula (Other Declares)

PECheckFormula 16-bit
(VB Syntax) Declare Function PECheckFormula Lib "crpe.dll"
(ByVal printJob As Integer, ByVal FormulaName
As String) As Integer

434 Crystal Reports Developer’s Reference

 32-bit
Declare Function PECheckFormula Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
FormulaName As String) As Integer

PECheckFormula 16-bit
(Delphi Syntax) function PECheckFormula (
printJob: integer;
formulaName: PChar
): Bool;

32-bit
function PECheckFormula (
printJob: Word;
formulaName: PChar
): Bool stdcall;

PECheckFormula EXTERN CLOGICAL PECheckFormula (CWORD, CSTRING)

CRPE.DLL
(dBASE for
Windows Syntax)

PECheckGroupSelectionFormula

The PECheckGroupSelectionFormula function checks the text of the

report's group selection formula for errors. Use this function when
the group selection formula in a report has changed and you need to
check the new group selection formula. If there is an error in the
formula, this function returns a False value.
BOOL CRPE_API PECheckGroupSelectionFormula (
short printJob//handle to print job
);

Parameters printJob
The handle of the print job for the report containing the group
selection formula you wish to check.

Return Value TRUE (1) if there are no errors in the group selection formula, FALSE
(0) if the group selection formula contains an error.

Chapter 6, Crystal Report Engine Reference 435

Remarks This function works just like the Check button that appears in the
Crystal Reports Formula Editor.

PECheckGroupSelectionFormula (Other Declares)

PECheckGroup 16-bit
SelectionFormula Declare Function PECheckGroupSelectionFormula
Lib "crpe.dll" (ByVal printJob As Integer) As
(VB Syntax) Integer

32-bit
Declare Function PECheckGroupSelectionFormula
Lib "crpe32.dll" (ByVal printJob As Integer) As
Integer

PECheckGroup 16-bit
SelectionFormula function PECheckGroupSelectionFormula (
printJob: integer
(Delphi Syntax) ): Bool;

32-bit
function PECheckGroupSelectionFormula (
printJob: Word
): Bool stdcall;

PECheckGroup EXTERN CLOGICAL PECheckGroupSelectionFormula

(CWORD) CRPE.DLL
SelectionFormula
(dBASE for
Windows Syntax)

PECheckSelectionFormula

Checks the text of the report's record selection formula for errors.
Use this function whenever the record selection formula has been
changed and you wish to check the formula for syntax errors. If the
record selection formula contains an error, this function returns a
False value.

436 Crystal Reports Developer’s Reference

 BOOL CRPE_API PECheckSelectionFormula (
short printJob//handle to print job
);

Parameters printJob
The handle of the print job containing the record selection formula
that you are checking.

Return Value TRUE (1) if the selection formula does not have an error, FALSE (0)
if the selection formula contains an error.

Remarks The PECheckSelectionFormula function works like the Check button

that appears in the Crystal Reports Formula Editor.

PECheckSelectionFormula (Other Declares)

PECheckSelection 16-bit
Formula Declare Function PECheckSelectionFormula Lib
"crpe.dll" (ByVal printJob As Integer) As
(VB Syntax) Integer

32-bit
Declare Function PECheckSelectionFormula Lib
"crpe32.dll" (ByVal printJob As Integer) As
Integer

PECheckSelection 16-bit
Formula function PECheckSelectionFormula (
printJob: integer
(Delphi Syntax) ): Bool;

32-bit
function PECheckSelectionFormula (
printJob: Word
): Bool stdcall;

Chapter 6, Crystal Report Engine Reference 437

PECheckSelection EXTERN CLOGICAL PECheckSelectionFormula
(CWORD) CRPE.DLL
Formula (dBASE
for Windows
Syntax)

PECloseEngine

PECloseEngine terminates the Report Engine. All printing is stopped

and all windows are closed.
NOTE: This will only happen if the calling application is the last one
using CRPE.
This function stops the Report Engine from sending output, but the
report may continue to print from data remaining in the spooler.
This function is a necessary part of any custom-print link. It is also
required for any print-only link in which you want the report to print
to a window that is to remain visible after the report is printed. It is
not necessary to use this function with a print-only link where you
are directing the report to a printer.
void CRPE_API PECloseEngine();

Return Value None

Remarks Once this function has been called, no other Report Engine functions
can be called except PEOpenEngine.

PECloseEngine (Other Declares)

PECloseEngine 16-bit
(VB Syntax) Declare Sub PECloseEngine Lib "crpe.dll" ()

32-bit
Declare Sub PECloseEngine Lib "crpe32.dll" ()

438 Crystal Reports Developer’s Reference

PECloseEngine 16-bit
(Delphi Syntax) procedure PECloseEngine;

32-bit
procedure PECloseEngine stdcall;

PECloseEngine EXTERN CVOID PECloseEngine () CRPE.DLL

(dBASE for
Windows Syntax)

PEClosePrintJob

PEClosePrintJob closes the print job. If printing has not yet finished,
it continues; if the print window is open, it stays open. This function
is used as a mandatory part of each custom-print link to shut down
the print job once it has finished printing to screen or to window.
BOOL CRPE_API PEClosePrintJob (
short printJob//handle to print job
);

Parameters printJob
Specifies the handle of the print job you want to close.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks Once this function has been called, most other Report Engine
functions, except PEOpenPrintJob, PECloseEngine, PEGetVersion
and PELogOnServer can not be called.

PEClosePrintJob (Other Declares)

PEClosePrintJob 16-bit
(VB Syntax) Declare Sub PEClosePrintJob Lib "crpe.dll"
(ByVal printJob As Integer)

Chapter 6, Crystal Report Engine Reference 439

 32-bit
Declare Sub PEClosePrintJob Lib "crpe32.dll"
(ByVal printJob As Integer)

PEClosePrintJob 16-bit
(Delphi Syntax) function PEClosePrintJob (
printJob: integer
): Bool;

32-bit
function PEClosePrintJob (
printJob: word
): Bool stdcall;

PEClosePrintJob EXTERN CLOGICAL PEClosePrintJob (CWORD)

CRPE.DLL
(dBASE for
Windows Syntax)

PECloseSubreport

This topic is only supported by the Professional Edition of Crystal

Reports.
The PECloseSubreport command closes the specified subreport.
BOOL CRPE_API PECloseSubreport (
short printJob//handle to subreport
);

Parameters printJob
Specifies the handle to the subreport you want to close.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks Once this function has been called, PEGetSubreportInfo or any other
Report Engine function that applies to the subreport can not be
called.

440 Crystal Reports Developer’s Reference

 Related Topics
Working with subreports 36

PECloseSubreport (Other Declares)

PECloseSubreport 16-bit
(VB Syntax) Declare Function PECloseSubreport Lib
"crpe.dll" (ByVal printJob As Integer) As
Integer

32-bit
Declare Function PECloseSubreport Lib
"crpe32.dll" (ByVal printJob As Integer) As
Integer

PECloseSubreport 16-bit
(Delphi Syntax) function PECloseSubreport (
printJob: integer
): Bool;

32-bit
function PECloseSubreport (
printJob: Word
): Bool stdcall;

PECloseSubreport EXTERN CLOGICAL PECloseSubreport(CWORD)

CRPE.DLL
(dBASE for
Windows Syntax)

PECloseWindow

PECloseWindow closes the print window. Use this function as part

of a custom-print link to enable the user to review the report in the
print window and then to close the window (in response to a user
event).

Chapter 6, Crystal Report Engine Reference 441

 Use PECloseWindow to replace the Close button when
PEShowPrintControls disables the Print Control buttons.
void CRPE_API PECloseWindow (
short printJob//handle to print job
);

Parameters printJob
Specifies the handle to the print job for which you want to close the
print window.

Return Value None

PECloseWindow (Other Declares)

PECloseWindow 16-bit
(VB Syntax) Declare Sub PECloseWindow Lib "crpe.dll" (ByVal
printJob As Integer)

32-bit
Declare Sub PECloseWindow Lib "crpe32.dll"
(ByVal printJob As Integer)

PECloseWindow 16-bit
(Delphi Syntax) procedure PECloseWindow (
printJob: integer
);

32-bit
procedure PECloseWindow (
printJob: Word
)stdcall;

PECloseWindow EXTERN CVOID PECloseWindow (CWORD) CRPE.DLL

(dBASE for
Windows Syntax)

442 Crystal Reports Developer’s Reference

PEDeleteNthGroupSortField

The PEDeleteNthGroupSortField function removes the specified

group sort field from the sort order. This function is used as part of a
custom-print link whenever you want to delete group sort fields that
were established for the report at design time. When you give the
user the ability to delete group sort field(s) at print time, your link
must include code to replace sortFieldN with user-generated values.
This function can be used by itself to delete an existing group sort
field when the sort field number is already known.
The function can also be used as one of a series of functions:
PEGetNGroupSortFields (called once), PEGetNthGroupSortField/
PEGetHandleString (called together as many times as needed to
identify the correct sort field), and PEDeleteNthGroupSortField
(called once, when the correct sort field is identified). The series can
be used in a custom-print link to identify and then delete an existing
group sort field and/or sort order at print time in response to a user
selection.
BOOL CRPE_API PEDeleteNthGroupSortField (
short printJob, //handle to print job
short sortFieldN
//number of sort field to delete
);

Parameters printJob
Specifies the handle of the print job from which you want to delete a
group sort field.
sortFieldN
Specifies the number of the sort field you want to delete. The first
group sort field is field 0. If N = 0, the function will delete the first
group sort field. If the report has N group sort fields, the function can
be called with sortFieldN between 0 and N-1.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Chapter 6, Crystal Report Engine Reference 443

PEDeleteNthGroupSortField (Other Declares)

PEDeleteNth 16-bit
GroupSortField Declare Function PEDeleteNthGroupSortField Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) SortFieldN As Integer) As Integer

32-bit
Declare Function PEDeleteNthGroupSortField Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
SortFieldN As Integer) As Integer

PEDeleteNth 16-bit
GroupSortField function PEDeleteNthGroupSortField (
printJob: integer;
(Delphi Syntax) sortFieldN: integer
): Bool;

32-bit
function PEDeleteNthGroupSortField (
printJob: Word;
sortFieldN: integer
): Bool stdcall;

PEDeleteNth EXTERN CLOGICAL PEDeleteNthGroupSortField

(CWORD, CWORD) CRPE.DLL
GroupSortField
(dBASE for
Windows Syntax)

PEDeleteNthSortField

The PEDeleteNthSortField function removes the specified sort field

from the sort order. This function is used as part of a custom-print
link whenever you want to delete sort fields that were established for
the report at design time. When you give the user the ability to delete
sort field(s) at print time, your link must include code to replace
sortFieldN with user-generated values.

444 Crystal Reports Developer’s Reference

 This function can be used by itself to delete an existing sort field
when the sort field number is already known.
The function can also be used as one of a series of functions:
PEGetNSortFields (called once), PEGetNthSortField/
PEGetHandleString (called together as many times as needed to
identify the correct sort field), and PEDeleteNthSortField (called
once, when the correct sort field is identified). The series can be used
in a custom-print link to identify and then delete an existing sort field
and/or sort order at print time in response to a user selection.
BOOL CRPE_API PEDeleteNthSortField (
short printJob, //handle to print job
short sortFieldN
//number of sort field to delete
);

Parameters printJob
Specifies the handle of the print job from which you want to delete a
sort field.
sortFieldN
Specifies the number of the sort fields you want to delete. The first
sort field is field 0. If N = 0, the function will delete the first sort field,
If the report has N sort fields, you can call the function with
sortFieldN between 0 and N-1.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

PEDeleteNthSortField (Other Declares)

PEDeleteNthSort 16-bit
Field (VB Syntax) Declare Function PEDeleteNthSortField Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
SortFieldN As Integer) As Integer

32-bit
Declare Function PEDeleteNthSortField Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
SortFieldN As Integer) As Integer

Chapter 6, Crystal Report Engine Reference 445

PEDeleteNthSort 16-bit
Field function PEDeleteNthSortField (
printJob: integer;
(Delphi Syntax) sortFieldN: integer
): Bool;

32-bit
function PEDeleteNthSortField (
printJob: Word;
sortFieldN: integer
): Bool stdcall;

PEDeleteNthSort EXTERN CLOGICAL PEDeleteNthSortField (CWORD,

CWORD) CRPE.DLL
Field (dBASE for
Windows Syntax)

PEDiscardSavedData

This topic is only supported by the Professional Edition of Crystal

Reports.
Discards data that was previously saved with the report. If a report
has been saved with data, you can use this function to discard the
saved data, forcing the Report Engine to retrieve new data when the
report is printed.
BOOL CRPE_API PEDiscardSavedData (
short printJob//handle to print job
);

Parameters printJob
Specifies the handle to the print job for which you want to discard
saved data.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

446 Crystal Reports Developer’s Reference

PEDiscardSavedData (Other Declares)

PEDiscardSaved 16-bit
Data (VB Syntax) Declare Function PEDiscardSavedData Lib
"crpe.dll" (ByVal printJob As Integer) As
Integer

32-bit
Declare Function PEDiscardSavedData Lib
"crpe32.dll" (ByVal printJob As Integer) As
Integer

PEDiscardSaved 16-bit
Data function PEDiscardSavedData (
printJob: integer
(Delphi Syntax) ): Bool;

32-bit
function PEDiscardSavedData (
printJob: Word
): Bool stdcall;

PEDiscardSaved EXTERN CLOGICAL PEDiscardSavedData (CWORD)

CRPE.DLL
Data (dBASE for
Windows Syntax)

PEEnableProgressDialog

This topic is only supported by the Professional Edition of Crystal

Reports.
The PEEnableProgressDialog function enables/disables the display
of the Progress dialog box. The Progress dialog box displays the
progress of the report when it is running (records read, records
selected, and so forth).
BOOL CRPE_API PEEnableProgressDialog (
short printJob,//handle to print job
BOOL enable //dialog enabled? (T/F)
);

Chapter 6, Crystal Report Engine Reference 447

Parameters printJob
Specifies the handle to the print job for which you want to enable/
disable the progress dialog box.
enable
Specifies whether or not the progress dialog box is enabled. If enable
is set to TRUE (1), the progress dialog box is enabled. If it’s set to
FALSE (0), the dialog box is disabled.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks This dialog box is enabled by default.

PEEnableProgressDialog (Other Declares)

PEEnableProgress 16-bit
Dialog (VB Syntax) Declare Function PEEnableProgressDialog Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
enable As Integer) As Integer

32-bit
Declare Function PEEnableProgressDialog Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
enable As Integer) As Integer

PEEnableProgress 16-bit
Dialog function PEEnableProgressDialog (
printJob: integer;
(Delphi Syntax) enable: Bool
): Bool;

32-bit
function PEEnableProgressDialog (
printJob: word;
enable: Bool
): Bool stdcall;

448 Crystal Reports Developer’s Reference

PEExportPrintWindow

This topic is only supported by the Professional Edition of Crystal

Reports.
Exports the report displayed in the print window to disk file or E-
mail. This function can be used in a custom-print link to enable the
user to preview the report in the export print window, and then, if
everything looks satisfactory, to export the report to disk file or E-
mail (in response to a user event).
Use PEExportPrintWindow to replace the Export button when
PEShowPrintControls disables the Print Control buttons.
BOOL CRPE_API PEExportPrintWindow (
short printJob,//handle to print job
BOOL toMail, //export to mail (T/F)
BOOL waitUntilDone
//return when printing starts (T/F)
);

Parameters printJob
Specifies the handle to the print job you want to print to a window.
toMail
Indicates whether or not the function is to export to E-mail.
waitUntilDone
Indicates whether or not the function is to return as soon as printing
starts. Use one of the following values:

Value Meaning
TRUE The function returns when printing is
finished. In version 1.1 and higher of
CRPE, "waitUntilDone" must be true.
FALSE The function returns as soon as printing
starts.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Chapter 6, Crystal Report Engine Reference 449

PEExportPrintWindow (Other Declares)

PEExportPrint 16-bit
Window Declare Function PEExportPrintWindow Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) ToMail As Integer, ByVal WaitUntilDone As
Integer) As Integer

32-bit
Declare Function PEExportPrintWindow Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
ToMail As Integer, ByVal WaitUntilDone As
Integer) As Integer

PEExportPrint 16-bit
Window function PEExportPrintWindow(
printJob: integer;
(Delphi Syntax) toMail: Bool;
waitUntilDone: Bool
): Bool;

32-bit
function PEExportPrintWindow (
printJob: Word;
toMail: Bool;
waitUntilDone: Bool
): Bool stdcall;

PEExportPrint EXTERN CLOGICAL PEExportPrintWindow (CWORD,

CLOGICAL, CLOGICAL) CRPE.DLL
Window (dBASE
for Windows
Syntax)

450 Crystal Reports Developer’s Reference

PEExportTo

Exports a print job using the name, format, and destination specified
in the PEExportOptions structure (see Page 662). Use this function
any time you want to print a report to a file or export it for use in
other programs.
BOOL CRPE_API PEExportTo (
short printJob, //handle to print job
struct PEExportOptions Far *options
//pointer to structure
);

Parameters printJob
Specifies the handle of the print job that you want to export.
options
Specifies the pointer to the PEExportOptions structure.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

PEExportTo (Other Declares)

PEExportTo 16-bit
(VB Syntax) Declare Function PEExportTo Lib "crpe.dll"
(ByVal printJob As Integer, ExportOptions As
PEExportOptions) As Integer

32-bit
Declare Function PEExportTo Lib "crpe32.dll"
(ByVal printJob As Integer, ExportOptions As
PEExportOptions) As Integer

PEExportTo 16-bit
(Delphi Syntax) function PEExportTo (
printJob: integer;
var options: PEExportOptions
): Bool;

Chapter 6, Crystal Report Engine Reference 451

 32-bit
function PEExportTo (
printJob: Word;
var options: PEExportOptions
): Bool stdcall;

PEGetErrorCode

Returns a number that indicates the status of the most recent Report
Engine function called. When a call to another function fails, this call
gets the error code that was generated so you can take some action
based on that error code.
short CRPE_API PEGetErrorCode (
short printJob//handle to print job
);

Parameters printJob
Specifies the handle of the print job from which you want to gather
an error code.

Return Value Returns 0 if the function completed without error; returns the code
number of the most recent error for the given job if the function was
unsuccessful.

PEGetErrorCode (Other Declares)

PEGetErrorCode 16-bit
(VB Syntax) Declare Function PEGetErrorCode Lib "crpe.dll"
(ByVal printJob As Integer) As Integer

32-bit
Declare Function PEGetErrorCode Lib
"crpe32.dll" (ByVal printJob As Integer) As
Integer

452 Crystal Reports Developer’s Reference

PEGetErrorCode 16-bit
(Delphi Syntax) function PEGetErrorCode (
printJob: integer
): integer;

32-bit
function PEGetErrorCode (
printJob: Word
): smallint stdcall;

PEGetErrorCode EXTERN CWORD PEGetErrorCode (CWORD) CRPE.DLL

(dBASE for
Windows Syntax)

Remarks If the most recent function was called while no print job was open
(e.g., PEOpenEngine), use 0 for 'printJob'. PEGetErrorCode must be
called immediately after the call to the function which indicated an
error.

PEGetErrorText

Returns a string handle describing the status of the most recent

Report Engine function called. This function is typically used
together with PEGetHandleString. These functions can be used in a
custom-print link to display the error string to the user as part of an
error message.
BOOL CRPE_API PEGetErrorText (
short printJob, //handle to print job
HANDLE FAR *textHandle,
//pointer to error string handle
short Far *textLength
//pointer to error string length
);

Parameters printJob
Specifies the handle of the print job from which you want to retrieve
an error string.
textHandle
Specifies the pointer to the handle of the string containing the error text.

Chapter 6, Crystal Report Engine Reference 453

 textLength
Specifies the pointer to the length of the error string (in bytes)
including the terminating byte.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks If the most recent function was called while no print job was open,
use 0 for 'printJob'.

PEGetErrorText (Other Declares)

PEGetErrorText 16-bit
(VB Syntax) Declare Function PEGetErrorText Lib "crpe.dll"
(ByVal printJob As Integer, TextHandle As
Integer, TextLength As Integer) As Integer

32-bit
Declare Function PEGetErrorText Lib
"crpe32.dll" (ByVal printJob As Integer,
TextHandle As Long, TextLength As Integer) As
Integer

PEGetErrorText 16-bit
(Delphi Syntax) function PEGetErrorText (
printJob: integer;
var textHandle: HWnd;
var textLength: integer
): Bool;

32-bit
function PEGetErrorText (
printJob: Word;
var textHandle: HWnd;
var textLength: Word
): Bool stdcall;

454 Crystal Reports Developer’s Reference

PEGetExportOptions

Gets export options from the user before exporting the report.
PEGetExportOptions can be used to present a series of dialog boxes
that retrieve export options from your users. These options are used
by the Report Engine to fill in the PEExportOptions structure. The
PEExportTo function can then be used to set the print job destination
using the information in the PEExportOptions structure (see Page
662).
BOOL CRPE_API PEGetExportOptions (
short printJob, //handle to print job
struct PEEXportOptionsFAR *options
//pointer to structure
);

Parameters printJob
Specifies the print job from which you want to get export options.
options
Specifies the pointer to the PEExportOptions structure.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

PEGetExportOptions (Other Declares)

PEGetExport 16-bit
Options Declare Function PEGetExportOptions Lib
"crpe.dll" (ByVal printJob As Integer,
(VB Syntax) ExportOptions As PEExportOptions) As Integer

32-bit
Declare Function PEGetExportOptions Lib
"crpe32.dll" (ByVal printJob As Integer,
ExportOptions As PEExportOptions) As Integer

Chapter 6, Crystal Report Engine Reference 455

PEGetExport 16-bit
Options function PEGetExportOptions (
printJob: integer;
(Delphi Syntax) var options: PEExportOptions
): Bool;

32-bit
function PEGetExportOptions (
printJob: Word;
var options: PEExportOptions
): Bool stdcall;

PEGetFormula

Returns the text of the named formula as a string handle. This

function is typically used as one of a series of functions
(PEGetFormula/PEGetHandleString, PESetFormula). The series can
be used in a custom-print link to identify and then change an existing
formula at print time in response to a user selection.
BOOL CRPE_API PEGetFormula (
short printJob, //handle to print job
char *formulaName,
//pointer to formula name string
HANDLE FAR *textHandle,
//pointer to formula string handle
short FAR *textLength
//pointer to formula string length
);

Parameters printJob
Specifies the handle of the print job from which you want to retrieve
the formula string.
formulaName
Specifies a pointer to the null-terminated string that contains the
name of the formula for which you want to retrieve the formula
string.
textHandle
Specifies the pointer to the handle of the string containing the
formula text.

456 Crystal Reports Developer’s Reference

 textLength
Specifies the pointer to the length of the formula string (in bytes)
including the terminating byte.

Return Value TRUE (1) if the call is successful, FALSE (0) if the named formula
does not exist in the report.

PEGetFormula (Other Declares)

PEGetFormula 16-bit
(VB Syntax) Declare Function PEGetFormula Lib "crpe.dll"
(ByVal printJob As Integer, ByVal FormulaName
As String, TextHandle As Integer, TextLength As
Integer) As Integer

32-bit
Declare Function PEGetFormula Lib "crpe32.dll"
(ByVal printJob As Integer, ByVal FormulaName
As String, TextHandle As Long, TextLength As
Integer) As Integer

PEGetFormula 16-bit
(Delphi Syntax) function PEGetFormula (
printJob: integer;
formulaName: PChar;
var textHandle: HWnd;
var textLength: integer
): Bool;

32-bit
function PEGetFormula (
printJob: Word;
formulaName: PChar;
var textHandle: HWnd;
var textLength: Word
): Bool stdcall;

Chapter 6, Crystal Report Engine Reference 457

PEGetGraphData

Identifies the data on which the specified graph in the specified

section is based. Use this function to find out what data in your
report is being used by a specified graph when the graph is created.
This information includes which groups are used to create the rows
and columns of the graph and which summary field in the report is
used to set the values of the risers in the graph.
BOOL CRPE_API PEGetGraphData (
short printJob, //handle to print job
short sectionCode,
//code identifying graph section
short graphN, //number of graph in section
struct PEGraphDataInfo FAR *graphDataInfo
//structure pointer
);

Parameters printJob
Specifies the handle of the print job from which you want to get
information about a graph.
sectionCode
Specifies the code for the report section in which the graph appears.
See the table of section constants supplied with PESetSectionFormat.
graphN
Specifies which graph within the section you want data for. This
value is 0 indexed. Within a section, graphs are numbered from top
to bottom, first, then from left to right if they have the same top.
graphDataInfo
Specifies the pointer to the PEGraphDataInfo structure (see Page
668).

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

458 Crystal Reports Developer’s Reference

PEGetGraphData (Other Declares)

PEGetGraphData 16-bit
(VB Syntax) Declare Function PEGetGraphData Lib "crpe.dll"
(ByVal printJob As Integer, ByVal sectionCode
As Integer, ByVal GraphN As Integer,
GraphDataInfo As PEGraphDataInfo) As Integer

32-bit
Declare Function PEGetGraphData Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
sectionCode As Integer, ByVal GraphN As
Integer, GraphDataInfo As PEGraphDataInfo) As
Integer

PEGetGraphData 16-bit
(Delphi Syntax) function PEGetGraphData (
printJob: integer;
sectionCode: integer;
graphN: integer;
var graphDataInfo:
): Bool;

32-bit
function PEGetGraphData (
printJob: Word;
sectionCode: integer;
graphN: integer;
var graphDataInfo:
): Bool stdcall;

PEGetGraphOptions

Identifies the display options that are set for the specified graph in
the specified section. Use this function to obtain information about
any of several graph options. These options include the minimum
and maximum values that can appear on the graph, whether grid
lines appear, whether risers are labeled, whether bar graphs have
horizontal or vertical bars, and whether a legend appears on the
graph.

Chapter 6, Crystal Report Engine Reference 459

 BOOL CRPE_API PEGetGraphOptions (
short printJob, //handle to print job
short sectionCode,
//code identifying graph section
short graphN, //number of graph in section
struct PEGraphOptionsFAR *graphOptions
//structure pointer
);

Parameters printJob
Specifies the handle of the print job from which you want to get
information about a graph.
sectionCode
Specifies the code for the report section in which the graph appears.
See the table of section constants supplied with PESetSectionFormat.
graphN
Specifies which graph within the section you want information
about. This value is 0 indexed. Within a section, graphs are
numbered from top to bottom, first, then from left to right if they
have the same top.
graphOptions
Specifies the pointer to the PEGraphOptions structure.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

PEGetGraphOptions (Other Declares)

PEGetGraph 16-bit
Options Declare Function PEGetGraphOptions Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) sectionCode As Integer, ByVal GraphN As
Integer, GraphOptions As PEGraphOptions) As
Integer

460 Crystal Reports Developer’s Reference

 32-bit
Declare Function PEGetGraphOptions Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
sectionCode As Integer, ByVal GraphN As
Integer, GraphOptions As PEGraphOptions) As
Integer

PEGetGraph 16-bit
Options function PEGetGraphOptions (
printJob: integer;
(Delphi Syntax) sectionCode: integer;
graphN: integer;
var graphOptions: PEGraphOptions
): Bool;

32-bit
function PEGetGraphOptions (
printJob: Word;
sectionCode: integer;
graphN: integer;
var graphOptions: PEGraphOptions
): Bool stdcall;

PEGetGraphText

Gets the identifying text that appears on the specified graph in the
specified section. This function allows you to find out what text
appears with a graph. A graph can have a title, subtitle, footnote, title
for groups, title for series, title for the X axis, title for the Y axis, and
title for the Z axis (in 3D graphs).
BOOL CRPE_API PEGetGraphText (
short printJob, //handle to print job
short sectionCode,
// code identifying graph section
short graphN, //number of graph in section
struct PEGraphTextInfo FAR *graphTextInfo
//structure pointer
);

Parameters printJob
Specifies the handle of the print job from which you want to get the
text displayed with a graph.

Chapter 6, Crystal Report Engine Reference 461

 sectionCode
Specifies the code for the report section in which the graph appears.
See the table of section constants supplied with PESetSectionFormat.
graphN
Specifies which graph within the section you want the text for. This
value is 0 indexed. Within a section, graphs are numbered from top
to bottom, first, then from left to right if they have the same top.
graphTextInfo
Specifies the pointer to the PEGraphTextInfo structure (see Page
673).

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

PEGetGraphText (Other Declares)

PEGetGraphText 16-bit
(VB Syntax) Declare Function PEGetGraphText Lib "crpe.dll"
(ByVal printJob As Integer, ByVal sectionCode
As Integer, ByVal GraphN As Integer,
GraphTextInfo As PEGraphTextInfo) As Integer

32-bit
Declare Function PEGetGraphText Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
sectionCode As Integer, ByVal GraphN As
Integer, GraphTextInfo As PEGraphTextInfo) As
Integer

PEGetGraphText 16-bit
(Delphi Syntax) function PEGetGraphText (
printJob: integer;
sectionCode: integer;
graphN: integer;
var graphTextInfo: PEGraphTextInfo
): Bool;

462 Crystal Reports Developer’s Reference

 32-bit
function PEGetGraphText (
printJob: Word;
sectionCode: integer;
graphN: integer;
var graphTextInfo: PEGraphTextInfo
): Bool stdcall;

PEGetGraphType

Identifies one of the available graph/chart types used for the

specified graph in the specified section. Use this function to find out
what type of graph is being displayed in the report. There are many
types of graphs and charts possible with Crystal Reports. This
function will return the type of graph or chart being displayed in a
report.
BOOL CRPE_API PEGetGraphType (
short printJob, //handle to print job
short sectionCode,
//code identifying graph section
short graphN, //number of graph in section
short FAR *graphType//pointer to graph type
);

Parameters printJob
Specifies the handle of the print job from which you want to find out
the type of graph being displayed.
sectionCode
Specifies the code for the report section in which the graph appears.
See the table of section constants supplied with PESetSectionFormat.
graphN
Specifies which graph within the section you want to know the type
of. This value is 0 indexed. Within a section, graphs are numbered
from top to bottom, first, then from left to right if they have the same
top.
graphType
Returns a pointer to the type of graph being displayed.

Chapter 6, Crystal Report Engine Reference 463

 Possible graph types appear in the following table:

Graph Type Value Constant

Side By Side 0 PE_SIDE_BY_SIDE_BAR_GRAPH
bar graph
Stacked bar 2 PE_STACKED_BAR_GRAPH
graph
Percent bar 3 PE_PERCENT_BAR_GRAPH
graph
3D Side By 4 PE_FAKED_3D_SIDE_BY_SIDE_
Side bar graph BAR_GRAPH
3D Stacked bar 5 PE_FAKED_3D_STACKED_BAR_
graph GRAPH
3D Percent 6 PE_FAKED_3D_PERCENT_BAR_
bar graph GRAPH
Pie graph 40 PE_PIE_GRAPH
Multiple Pie 42 PE_MULTIPLE_PIE_GRAPH
graph
Weighted Pie 43 PE_PROPORTIONAL_MULTI_
graph PIE_GRAPH
Line graph 80 PE_LINE_GRAPH
Area graph 120 PE_AREA_GRAPH
3D bar graph 160 PE_THREED_BAR_GRAPH
User Defined 500 PE_USER_DEFINED_GRAPH
graph type
Unknown 1000 PE_UNKNOWN_TYPE_GRAPH
graph type

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

PEGetGraphType (Other Declares)

PEGetGraphType 16-bit
(VB Syntax) Declare Function PEGetGraphType Lib "crpe.dll"
(ByVal printJob As Integer, ByVal sectionCode
As Integer, ByVal GraphN As Integer, GraphType
As Integer) As Integer

464 Crystal Reports Developer’s Reference

 32-bit
Declare Function PEGetGraphType Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
sectionCode As Integer, ByVal GraphN As
Integer, GraphType As Integer) As Integer

PEGetGraphType 16-bit
(Delphi Syntax) function PEGetGraphType (
printJob: integer;
sectionCode: integer;
graphN: integer;
var graphType: integer
):Bool;

32-bit
function PEGetGraphType (
printJob: Word;
sectionCode: integer;
graphN: integer;
var graphType: integer
): Bool stdcall;

PEGetGroupCondition

This topic is only supported by the Professional Edition of Crystal

Reports.
Determines the group condition information for a selected group
section in the specified report. Use this function to find out the group
condition for a group section. Use PESetGroupCondition to change
the group condition once it is known.
BOOL CRPE_API PEGetGroupCondition (
short printJob,
//handle to print job
short sectionCode,
//code for group section
HANDLE FAR *conditionFieldHandle,
//field handle pointer
short FAR *conditionFieldLength,
//field length pointer
short FAR *condition, //condition pointer
short FAR *sortDirection
//sort direction pointer
);

Chapter 6, Crystal Report Engine Reference 465

Parameters printJob
Specifies the handle of the print job you want to query to determine
the group conditions for a selected group.
sectionCode
Specifies the code for the report section for which you want to get the
group condition. See the table of section constants supplied with
PESetSectionFormat.
conditionFieldHandle
Specifies a pointer to the handle of the condition field for the selected
group section.
conditionFieldLength
Specifies a pointer to the length of the condition field for the selected
group section.
condition
Specifies a pointer to the condition setting for the selected group
section (date and Boolean fields only).
sortDirection
Specifies a pointer to the sort direction setting for the selected group
section.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks The condition parameter returns a value that encodes both the
condition and the type of the condition field. You need to apply a
condition mask (PE_GC_CONDITIONMASK) or a type mask
(PE_GC_TYPEMASK) against this value using a bitwise AND to
determine the condition or type respectively. For example:
short result;

result = *condition & PE_GC_TYPEMASK;

if (result == PE_GC_TYPEDATE)
{
//what you want it to do
}

466 Crystal Reports Developer’s Reference

 Type can be any of the following

PE_GC_TYPEOTHER Any data type other than date or

Boolean
PE_GC_TYPEDATE Date data type
PE_GC_TYPEBOOLEAN Boolean data type

PEGetGroupCondition (Other Declares)

PEGetGroup 16-bit
Condition Declare Function PEGetGroupCondition Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) sectionCode As Integer, ConditionFieldHandle As
Integer, ConditionFieldLength As Integer,
Condition As Integer, SortDirection As Integer)
As Integer

32-bit
Declare Function PEGetGroupCondition Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
sectionCode As Integer, ConditionFieldHandle As
Long, ConditionFieldLength As Integer,
Condition As Integer, SortDirection As Integer)
As Integer

PEGetGroup 16-bit
Condition function PEGetGroupCondition (
printJob: integer;
(Delphi Syntax) sectionCode: integer;
var conditionFieldHandle: HWnd;
var conditionFieldLength: integer;
var condition: integer;
var sortDirection: integer
): Bool;

32-bit
function PEGetGroupCondition (
printJob: Word;
sectionCode: integer;
var conditionFieldHandle: Hwnd;

Chapter 6, Crystal Report Engine Reference 467

 var conditionFieldLength: Word;
var condition: Word;
var sorDirection: Word
): Bool stdcall;

PEGetGroupSelectionFormula

Returns the string handle for the group selection formula used in the
specified report. This function is typically used as one of a series of
functions (PEGetGroupSelectionFormula, PEGetHandleString,
PESetGroupSelectionFormula). This series can be used in a custom-
print link to identify and then change an existing group selection
formula at print time in response to a user selection.
BOOL CRPE_API PEGetGroupSelectionFormula (
short printJob, //handle to print job
HANDLE FAR *textHandle,
//handle to formula string
short FAR *textLength
//handle to formula string length
);

Parameters printJob
Specifies the handle of the print job for which you want to retrieve
the group selection formula string.
textHandle
Specifies the pointer to the handle of the string containing the
formula text.
textLength
Specifies the pointer to the length of the formula string (in bytes)
including the terminating byte.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

468 Crystal Reports Developer’s Reference

PEGetGroupSelectionFormula (Other Declares)

PEGetGroup 16-bit
SelectionFormula Declare Function PEGetGroupSelectionFormula
Lib "crpe.dll" (ByVal printJob As Integer,
(VB Syntax) TextHandle As Integer, TextLength As Integer)
As Integer

32-bit
Declare Function PEGetGroupSelectionFormula
Lib "crpe32.dll" (ByVal printJob As Integer,
TextHandle As Long, TextLength As Integer) As
Integer

PEGetGroup 16-bit
SelectionFormula function PEGetGroupSelectionFormula (
printJob: integer;
(Delphi Syntax) var textHandle: HWnd;
var textLength: integer
): Bool;

32-bit
function PEGetGroupSelectionFormula (
printJob: Word;
var textHandle: HWnd;
var textLength: Word
): Bool stdcall;

PEGetHandleString

This function will return the text that the string handle is pointing to.
The buffer will contain the normal text. This function is used in
conjunction with functions that return variable length strings. After
your program allocates a buffer of sufficient size, this function moves
the string from the string handle to the buffer.

Chapter 6, Crystal Report Engine Reference 469

 BOOL CRPE_API PEGetHandleString (
HANDLE textHandle,
//pointer to string handle
char FAR *buffer,
//pointer to receiving array
short bufferLength
//pointer to buffer length
);

Parameters textHandle
Specifies the pointer to the handle of the string containing the text of
interest.
buffer
Specifies the pointer to the character array into which you want to
copy the string.
bufferLength
Specifies the pointer to the length of the buffer in bytes, including the
terminating null byte.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks ● You can only use this call once with a given string handle because
the string handle is discarded once the function is called. If you
expect to use the string later, you will need to save it.
● PEGetHandleString will copy at most BufferLength bytes,
ensuring that the string in the buffer is null-terminated.
NOTE: When you call the function that produces the string, it
returns a length that includes a provision for the null byte at the end
of the string. A buffer set to that length will hold the entire string
including the terminating null byte.

PEGetHandleString (Other Declares)

PEGetHandle 16-bit
String (VB Syntax) Declare Function PEGetHandleString Lib
"crpe.dll" (ByVal TextHandle As Integer, ByVal
Buffer As String, ByVal BufferLength As
Integer) As Integer

470 Crystal Reports Developer’s Reference

 32-bit
Declare Function PEGetHandleString Lib
"crpe32.dll" (ByVal TextHandle As Long, ByVal
Buffer As String, ByVal BufferLength As
Integer)As Integer

PEGetHandle 16-bit
String function PEGetHandleString (
textHandle: HWnd;
(Delphi Syntax) buffer: PChar;
bufferLength: integer
): Bool;

32-bit
function PEGetHandleString (
textHandle: HWnd;
buffer: PChar;
bufferLength: integer
): Bool stdcall;

PEGetJobStatus

Evaluates the status of a print job. You can use this function in a
number of programming situations, for example:
● to trigger error messages, i.e., when a print job fails (due to
insufficient memory, insufficient disk space, etc.) or,
● to trigger screen displays (hourglass, series of graphics, etc.) that
confirm to the user that work is in progress, or
● to find out whether a job was cancelled by the user after
PEStartPrintJob returns.
short CRPE_API PEGetJobStatus (
short printJob, //handle to print job
struct PEJobInfoFAR *jobInfo
//pointer to structure
);

Parameters printJob
Specifies the handle to the print job you want to query about its
printing status.

Chapter 6, Crystal Report Engine Reference 471

 jobInfo
Specifies the pointer to the PEJobInfo structure that will capture the
information this function retrieves.

Return Value ● "-1" if PEOpenEngine or PEOpenPrintJob has not been called

successfully.
● "1" if the job has not started yet (PE_JOBNOTSTARTED)
● "2" if the job is in progress (PE_JOBINPROGRESS)
● "3" if the job has completed successfully (PE_JOBCOMPLETED)
● "4" if the job has failed (PE_JOBFAILED)
● "5" if the job has been canceled by the user
(PE_JOBCANCELLED)
● "6" if the report has exceeded the record or time governors
(PE_JOBHALTED)

PEGetJobStatus (Other Declares)

PEGetJobStatus 16-bit
(VB Syntax) Declare Function PEGetJobStatus Lib "crpe.dll"
(ByVal printJob As Integer, JobInfo As
PEJobInfo) As Integer

32-bit
Declare Function PEGetJobStatus Lib
"crpe32.dll" (ByVal printJob As Integer,
JobInfo As PEJobInfo) As Integer

PEGetJobStatus 16-bit
(Delphi Syntax) function PEGetJobStatus (
printJob: integer;
var jobInfo: PEJobInfo
): integer;

32-bit
function PEGetJobStatus (
printJob: Word;
var jobInfo: PEJobInfo
): smallint stdcall;

472 Crystal Reports Developer’s Reference

PEGetMargins

This topic is only supported by the Professional Edition of Crystal

Reports.
Retrieves the page margin settings for the specified report. Use this
function to find out what the currently set margins for the report are.
Use this function with PESetMargins. Use PEGetMargins to obtain
report margins and use PESetMargins to set the report margins.
BOOL CRPE_API PEGetMargins (
short printJob, //handle to print job
short FAR *left,
//pointer to left margin value
short FAR *right,
//pointer to right margin value
short FAR *top,
//pointer to top margin value
short FAR *bottom
//pointer to bottom margin value
);

Parameters printJob
Specifies the handle to the print job you want to query to retrieve
margin information.
left
Specifies a pointer to the value of the left margin.
right
Specifies a pointer to the value of the right margin.
top
Specifies a pointer to the value of the top margin.
bottom
Specifies a pointer to the value of the bottom margin.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Chapter 6, Crystal Report Engine Reference 473

PEGetMargins (Other Declares)

PEGetMargins 16-bit
(VB Syntax) Declare Function PEGetMargins Lib "crpe.dll"
(ByVal printJob As Integer, LeftMargin As
Integer, RightMargin As Integer, TopMargin As
Integer, BottomMargin As Integer) As Integer

32-bit
Declare Function PEGetMargins Lib "crpe32.dll"
(ByVal printJob As Integer, LeftMargin As
Integer, RightMargin As Integer, TopMargin As
Integer, BottomMargin As Integer) As Integer

PEGetMargins 16-bit
(Delphi Syntax) function PEGetMargins (
printJob: integer;
var left: Word;
var right: Word;
var top: Word;
var bottom: Word
): Bool;

32-bit
function PEGetMargins (
printJob: Word;
var left: integer;
var right: integer;
var top: integer;
var bottom: integer
): Bool stdcall;

PEGetMinimumSectionHeight

This topic is only supported by the Professional Edition of Crystal

Reports.
Retrieves the minimum section height information for selected
sections in the specified report. Use PEGetMinimumSectionHeight
to obtain report margins and use PESetMinimumSectionHeight to
set the report margins.

474 Crystal Reports Developer’s Reference

 BOOL CRPE_API PEGetMinimumSectionHeight (
short printJob, //handle to print job
short sectionCode,
//code identifying section
short FAR *minimumHeight
//pointer to minimum height
);

Parameters printJob
Specifies the handle to the print job you want to query to retrieve
information on minimum section height.
sectionCode
Specifies the code for the report section(s) for which you want to
retrieve information on minimum section height. See Working with
Section Codes, Page 428.
minimumHeight
Specifies a pointer to the minimum height you want to set for the
selected section(s).

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

PEGetMinimumSectionHeight (Other Declares)

PEGetMinimum 16-bit
SectionHeight Declare Function PEGetMinimumSectionHeight Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) sectionCode As Integer, MinimumHeight As
Integer) As Integer

32-bit
Declare Function PEGetMinimumSectionHeight Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
sectionCode As Integer, MinimumHeight As
Integer) As Integer

Chapter 6, Crystal Report Engine Reference 475

PEGetMinimum 16-bit
SectionHeight function PEGetMinimumSectionHeight (
printJob: integer;
(Delphi Syntax) sectionCode: integer;
var minimumHeight: integer
): Bool;

32-bit
function PEGetMinimumSectionHeight (
printJob: Word;
sectionCode: integer;
var minimumHeight: Word
): Bool stdcall;

PEGetNDetailCopies

This topic is only supported by the Professional Edition of Crystal

Reports.
Returns the number of copies of each Details section in the report
that are to be printed. Use this function to find out how many times
each Details section of the report will be printed. To change the
number of times each Details section is printed, use
PESetNDetailCopies.
BOOL CRPE_API PEGetNDetailCopies (
short printJob, //handle to print job
short FAR *nDetailCopies
//pointer to number of copies
);

Parameters printJob
Specifies the handle of the print job from which you want to know
how many times each Details section is to be printed.
nDetailCopies
Holds the number of copies of the Details section to be printed.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

476 Crystal Reports Developer’s Reference

PEGetNDetailCopies (Other Declares)

PEGetNDetail 16-bit
Copies (VB Syntax) Declare Function PEGetNDetailCopies Lib
"crpe.dll" (ByVal printJob As Integer,
nDetailCopies As Integer) As Integer

32-bit
Declare Function PEGetNDetailCopies Lib
"crpe32.dll" (ByVal printJob As Integer,
nDetailCopies As Integer) As Integer

PEGetNDetail 16-bit
Copies function PEGetNDetailCopies (
printJob: integer;
(Delphi Syntax) var nDetailCopies: integer
): Bool;

32-bit
function PEGetNDetailCopies(
printJob: Word;
var nDetailCopies: integer
): Bool stdcall;

PEGetNFormulas

Determines the number of formulas in the specified report. Use this

function to fetch the number of formulas in the report. To fetch the
formula by number, use PEGetNthFormula.
short CRPE_API PEGetNFormulas (
short printJob//handle to print job
);

Parameters printJob
Specifies the handle to the print job you want to query to find the
number of formulas it contains.

Return Value The number of formulas in the report.

Chapter 6, Crystal Report Engine Reference 477

PEGetNFormulas (Other Declares)

PEGetNFormulas 16-bit
(VB Syntax) Declare Function PEGetNFormulas Lib "crpe.dll"
(ByVal printJob As Integer) As Integer

32-bit
Declare Function PEGetNFormulas Lib
"crpe32.dll" (ByVal printJob As Integer) As
Integer

PEGetNFormulas 16-bit
(Delphi Syntax) function PEGetNFormulas (
printJob: integer
): integer;

32-bit
function PEGetNFormulas(
printJob: Word
): smallint stdcall;

PEGetNFormulas EXTERN CWORD PEGetNFormulas (CWORD) CRPE.DLL

(dBASE for
Windows Syntax)

PEGetNGroups

This topic is only supported by the Professional Edition of Crystal

Reports.
Determines the number of groups in the specified report.
short CRPE_API PEGetNGroups (
short printJob//handle to print job
);

478 Crystal Reports Developer’s Reference

Parameters printJob
Specifies the handle of the print job you want to query to determine
the number of groups it contains.

Return Value Returns the number of groups in the report.

PEGetNGroups (Other Declares)

PEGetNGroups 16-bit
(VB Syntax) Declare Function PEGetNGroups Lib "crpe.dll"
(ByVal printJob As Integer) As Integer

32-bit
Declare Function PEGetNGroups Lib "crpe32.dll"
(ByVal printJob As Integer) As Integer

PEGetNGroups 16-bit
(Delphi Syntax) function PEGetNGroups (
printJob: integer
): integer;

32-bit
function PEGetNGroups (
printJob: Word
): smallint stdcall;

PEGetNGroups EXTERN CWORD PEGetNGroups (CWORD) CRPE.DLL

(dBASE for
Windows Syntax)

PEGetNGroupSortFields

Returns the number of group sort fields in the specified report. This
function is typically used as one of a series of functions:
PEGetNGroupSortFields (called once), PEGetNthGroupSortField/
PEGetHandleString (called as many times as needed to identify the

Chapter 6, Crystal Report Engine Reference 479

 correct group sort field), and PESetNthGroupSortField (called once,
when the correct group sort field is identified). The series can be used
in a custom-print link to identify and then change an existing group
sort field and/or sort order at print time in response to a user
selection.
NOTE: A group sort field is a summary value or a summarized field
that determines the sort order of groups.
short CRPE_API PEGetNGroupSortFields (
short printJob//handle to print job
);

Parameters printJob
Specifies the handle of the print job you want to query to find out
how many group sort fields it contains.

Return Value If group sort fields have been defined, returns the number of such
fields; if there are no group sort fields defined, returns 0; if an error
occurs, returns -1.

PEGetNGroupSortFields (Other Declares)

PEGetNGroupSort 16-bit
Fields (VB Syntax) Declare Function PEGetNGroupSortFields Lib
"crpe.dll" (ByVal printJob As Integer) As
Integer

32-bit
Declare Function PEGetNGroupSortFields Lib
"crpe32.dll" (ByVal printJob As Integer) As
Integer

PEGetNGroupSort 16-bit
Fields function PEGetNGroupSortFields (
printJob: integer
(Delphi Syntax) ): integer;

480 Crystal Reports Developer’s Reference

 32-bit
function PEGetNGroupSortFields (
printJob: Word
): smallint stdcall;

PEGetNGroupSort EXTERN CWORD PEGetNGroupSortFields (CWORD)

CRPE.DLL
Fields (dBASE for
Windows Syntax)

PEGetNPages

This topic is only supported by the Professional Edition of Crystal

Reports.
The PEGetNPages function retrieves the number of pages in the
report.
short CRPE_API PEGetNPages (
short printJob//handle to print job
);

Parameters printJob
Specifies the handle of the print job for which you want to determine
the number of pages.

Return Value The number of pages in the report.

Remarks This function can only be called after PEStartPrintJob.

PEGetNPages (Other Declares)

PEGetNPages 16-bit
(VB Syntax) Declare Function PEGetNPages Lib "crpe.dll"
(ByVal printJob As Integer) As Integer

Chapter 6, Crystal Report Engine Reference 481

 32-bit
Declare Function PEGetNPages Lib "crpe32.dll"
(ByVal printJob As Integer) As Integer

PEGetNPages 16-bit
(Delphi Syntax) function PEGetNPages (
printJob: integer
): integer;

32-bit
function PEGetNPages (
printJob: Word
): smallint stdcall;

PEGetNParameterFields

The PEGetNParameterFields function determines the number of

parameter (prompting) fields used in the report.
short CRPE_API PEGetNParameterFields (
short printJob//handle to print job
);

Parameters printJob
Specifies the handle of the print job from which you want to retrieve
a parameter field count.

Return Value The number of parameter fields in the report.

PEGetNParameterFields (Other Declares)

PEGetNParameter 16-bit
Fields (VB Syntax) Declare Function PEGetNParameterFields Lib
"crpe.dll" (ByVal printJob As Integer) As
Integer

482 Crystal Reports Developer’s Reference

 32-bit
Declare Function PEGetNParameterFields Lib
"crpe32.dll" (ByVal printJob As Integer) As
Integer

PEGetNParameter 16-bit
Fields function PEGetNParameterFields (
printJob: integer
(Delphi Syntax) ): integer;

32-bit
function PEGetNParameterFields (
printJob: Word
): Smallint stdcall;

PEGetNParams

This topic is only supported by the Professional Edition of Crystal

Reports.
Retrieves the number of parameters needed by a stored procedure.
Use this function whenever you need to know how many parameters
are required by a stored procedure in a SQL database table. This
function is usually used in conjunction with PEGetNthParam or
PESetNthParam.
short CRPE_API PEGetNParams (
short printJob//handle to print job
);

Parameters printJob
Specifies the handle to the print job containing the stored procedure you
need to query to find out the number of parameters required by the
procedure.

Return Value The number of parameters used by a stored procedure. Returns -1 if

an error occurs.

Related Menu Database|Stored Procedure Parameters

Commands

Chapter 6, Crystal Report Engine Reference 483

PEGetNParams (Other Declares)

PEGetNParams 16-bit
(VB Syntax) Declare Function PEGetNParams Lib "crpe.dll"
(ByVal printJob As Integer) As Integer

32-bit
Declare Function PEGetNParams Lib "crpe32.dll"
(ByVal printJob As Integer) As Integer

PEGetNParams 16-bit
(Delphi Syntax) function PEGetNParams (
printJob: integer
): integer;

32-bit
function PEGetNParams (
printJob: Word
): smallint stdcall;

PEGetNParams EXTERN CWORD PEGetNParams (CWORD) CRPE.DLL

(dBASE for
Windows Syntax)

PEGetNSections

The PEGetNSections function retrieves the number of sections in the

specified report. By default, each report has five areas, each
containing one section (Report Header, Page Header, Details, Report
Footer, and Page Footer). Thus, if this function were applied to a
default report, the return value would be five (5). As you add groups
to your report or you add sections to one or more areas, the number
of sections in the report increases.
short CRPE_API PEGetNSections (
short printJob//handle to print job
);

484 Crystal Reports Developer’s Reference

Parameters printJob
Specifies the handle to the print job from which you want to get a
section count.

Return Value The number of sections in the report.

Remarks For information on section codes, see Working with Section Codes,
Page 428.

PEGetNSections (Other Declares)

PEGetNSections 16-bit
(VB Syntax) Declare Function PEGetNSections Lib "crpe.dll"
(ByVal printJob As Integer) As Integer

32-bit
Declare Function PEGetNSections Lib
"crpe32.dll" (ByVal printJob As Integer) As
Integer

PEGetNSections 16-bit
(Delphi Syntax) function PEGetNSections (
printJob: integer
): integer;

32-bit
function PEGetNSections (
printJob: Word
): Smallint stdcall;

PEGetNSortFields

Returns the number of sort fields in the specified report. This

function is typically used as one of a series of functions:
PEGetNSortFields (called once), PEGetNthSortField/
PEGetHandleString (called together as many times as needed to
identify the correct sort field), PESetNthSortField (called once when

Chapter 6, Crystal Report Engine Reference 485

 the correct sort field is identified). The series can be used in a custom-
print link to identify and then change an existing sort field and/or
sort order at print time in response to a user selection.
short CRPE_API PEGetNSortFields (
short printJob//handle to print job
);

Parameters printJob
Specifies the handle to the print job you want to query to find out
how many sort fields it contains.

Return Value If there are sort fields defined, returns the number of sort fields; if
there are no sort fields defined, returns 0; if an error occurs, returns -1.

Related Menu Report|Record Sort Order

Commands

PEGetNSortFields (Other Declares)

PEGetNSortFields 16-bit
(VB Syntax) Declare Function PEGetNSortFields Lib
"crpe.dll" (ByVal printJob As Integer) As
Integer

32-bit
Declare Function PEGetNSortFields Lib
"crpe32.dll" (ByVal printJob As Integer) As
Integer

PEGetNSortFields 16-bit
(Delphi Syntax) function PEGetNSortFields (
printJob: integer
): integer;

32-bit
function PEGetNSortFields (
printJob: Word
): smallint stdcall;

486 Crystal Reports Developer’s Reference

PEGetNSortFields EXTERN CWORD PEGetNSortFields (CWORD) CRPE.DLL
(dBASE for
Windows Syntax)

PEGetNSubreportsInSection

This topic is only supported by the Professional Edition of Crystal

Reports.
The PEGetNSubreportsInSection function determines the number
of subreports in the specified section.
short CRPE_API PEGetNSubreportsInSection (
short printJob,//handle to print job
short sectionCode//code identifying section
);

Parameters print job

Specifies the handle of the primary report from which you want to
fetch information about the number of subreports in a section.
sectionCode
Specifies the section code of the section for which you want a
subreport count. See Working with Section Codes, Page 428.

Return Values The number of subreports in the specified section.

Remarks sectionCode can be retrieved using PEGetSectionCode.

PEGetNSubreportsInSection (Other Declares)

PEGetNSubreports 16-bit
InSection Declare Function PEGetNSubreportsInSection Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) sectionCode As Integer) As Integer

32-bit
Declare Function PEGetNSubreportsInSection Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
sectionCode As Integer) As Integer

Chapter 6, Crystal Report Engine Reference 487

PEGetNSubreports 16-bit
InSection function PEGetNSubreportsInSection (
printJob: integer;
(Delphi Syntax) sectionCode: integer
): Integer;

32-bit
function PEGetNSubreportsInSection (
printJob: Word;
sectionCode: Smallint
): Smallint stdcall;

Related Topics
Working with subreports 36

PEGetNTables

The PEGetNTables function retrieves the number of tables in the

open report. It counts both PC and SQL databases.
This function is one of a series of functions that enable you to retrieve
and update database information in an opened report so that the
report can be printed using different server, database, user, and/or
table location settings.
short CRPE_API PEGetNTables (
short printJob//handle to print job
);

Parameters print job

Specifies the handle of the print job from which you want to retrieve
a table count.

Return Value Returns the number of tables used in the report (1 = 1 table, 2 = 2
tables, etc.); returns -1 if an error occurs.

Remarks This function can be used with all compatible PC databases (e.g.
Paradox, xBase) as well as SQL databases (e.g., SQL Server, Oracle,
Netware).

488 Crystal Reports Developer’s Reference

PEGetNTables (Other Declares)

PEGetNTables 16-bit
(VB Syntax) Declare Function PEGetNTables Lib "crpe.dll"
(ByVal printJob As Integer) As Integer

32-bit
Declare Function PEGetNTables Lib "crpe32.dll"
(ByVal printJob As Integer) As Integer

PEGetNTables 16-bit
(Delphi Syntax) function PEGetNTables (
printJob: integer
): integer;

32-bit
function PEGetNTables (
printJob: Word
): smallint stdcall;

PEGetNTables EXTERN CWORD PEGetNTables (CWORD) CRPE.DLL

(dBASE for
Windows Syntax)

PEGetNthFormula

Retrieves information about a specific formula in the report. Use this

function to obtain the formula name and formula text of a specific
formula in the report. This function can be used to get formula text,
allow the user to edit the formula, then change the formula text with
PESetFormula. The first formula is formula 0.
BOOL CRPE_API PEGetNthFormula (
short printJob, //handle to print job
short formulaN, //number of formula
HANDLE FAR *nameHandle,
//formula name string handle pointer
short FAR *nameLength,

Chapter 6, Crystal Report Engine Reference 489

 //formula name string length pointer
HANDLE FAR *textHandle,
//formula string handle pointer
short FAR *textLength
//formula string length pointer
);

Parameters printJob
Specifies the handle to the print job from which you want to gather
formula information.
formulaN
Specifies the number of the formula about which you want to gather
information.
nameHandle
Specifies a pointer to the handle of the string containing the formula
name.
nameLength
Specifies a pointer to the length of the formula name string (in bytes)
including the terminating byte.
textHandle
Specifies a pointer to the handle of the string containing the formula
text.
textLength
Specifies a pointer to the length of the formula string (in bytes)
including the terminating byte.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Related Menu Insert|Formula Field, Edit|Formula

Commands

490 Crystal Reports Developer’s Reference

PEGetNthFormula (Other Declares)

PEGetNthFormula 16-bit
(VB Syntax) Declare Function PEGetNthFormula Lib "crpe.dll"
(ByVal printJob As Integer, ByVal FormulaN As
Integer, NameHandle As Integer, NameLength As
Integer, TextHandle As Integer, TextLength As
Integer) As Integer

32-bit
Declare Function PEGetNthFormula Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
FormulaN As Integer, NameHandle As Long,
NameLength As Integer, TextHandle As Long,
TextLength As Integer) As Integer

PEGetNthFormula 16-bit
(Delphi Syntax) function PEGetNthFormula (
printJob: integer;
formulaN: integer;
var nameHandle: HWnd;
var nameLength: integer;
var textHandle: HWnd;
var textLength: integer
): Bool;

32-bit
function PEGetNthFormula (
printJob: Word;
formulaN: integer;
var nameHandle: Hwnd;
var nameLength: Word;
var textHandle: Hwnd;
var textLength: Word
): Bool stdcall;

Chapter 6, Crystal Report Engine Reference 491

PEGetNthGroupSortField

Returns information about one of the group sort fields in the

specified report: that is, it returns the name of the field and the
direction (ascending or descending) of the sort. The name of the
group sort field is returned as a string handle. See Functions that
return variable length strings for further information.
This function is typically used as one of a series of functions:
PEGetNGroupSortFields (called once), PEGetNthGroupSortField/
PEGetHandleString (called as many times as needed to identify the
correct group sort field), and PESetNthGroupSortField (called once
when the correct sort field is identified). The series can be used in a
custom-print link to identify and then change an existing group sort
field and/or sort order at print time in response to a user selection.
NOTE: A group sort field is a summary value or a summarized field
that determines the sort order of groups.
BOOL CRPE_API PEGetNthGroupSortField (
short printJob,//handle to print job
short sortFieldN,//group sort field number
HANDLE FAR *nameHandle,
//field name string handle pointer
short FAR *nameLength,
//field name string length pointer
short FAR *direction
//pointer to sort direction setting
);

Parameters printJob
Specifies the handle of the print job from which you want to gather
group sort field information.
sortFieldN
Specifies the number of the group sort field you want to retrieve. The
first group sort field is field 0. If the report has N sort fields, the
function can be called with sortFieldN between 0 and N-1.
nameHandle
Specifies the pointer to the handle of the string containing the sort
field name.
nameLength
Specifies the pointer to the length of the field name string (in bytes)
including the terminating byte.

492 Crystal Reports Developer’s Reference

 direction
Specifies one of the following sort directions:

Value Meaning
PE_SF_ASCENDING Sorts in Ascending order (A to Z, 1 to
9).
PE_SF_DESCENDING Sorts in Descending order (Z to A, 9
to 1).

Return Value TRUE (1) if the call is successful; FALSE (0) if the call fails.

Related Menu Report|Group Sort Order

Commands

PEGetNthGroupSortField (Other Declares)

PEGetNthGroup 16-bit
SortField Declare Function PEGetNthGroupSortField Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) SortFieldN As Integer, NameHandle As Integer,
NameLength As Integer, Direction As Integer) As
Integer

32-bit
Declare Function PEGetNthGroupSortField Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
SortFieldN As Integer, NameHandle As Long,
NameLength As Integer, Direction As Integer) As
Integer

PEGetNthGroup 16-bit
SortField function PEGetNthGroupSortField (
printJob: integer;
(Delphi Syntax) sortFieldN: integer;
var nameHandle: HWnd;
var nameLength: integer;
var direction: integer
): Bool;

Chapter 6, Crystal Report Engine Reference 493

 32-bit
function PEGetNthGroupSortField (
printJob : Word;
sortFieldN: integer;
var nameHandle: HWnd;
var nameLength: Word;
var direction: Word
): Bool stdcall;

PEGetNthParam

This topic is only supported by the Professional Edition of Crystal

Reports.
Gets the Nth parameter of a stored procedure. Use this function
whenever you need to find out a particular parameter required by a
stored procedure in a SQL database table.
BOOL CRPE_API PEGetNthParam (
short printJob,//handle to print job
short paramN,
//parameter # in stored procedure
HANDLE FAR *textHandle,
//parameter string handle pointer
short FAR *textLength
//parameter string length pointer
);

Parameters printJob
Specifies the handle of the print job that contains the stored
procedure for which you are interested in obtaining a parameter.
paramN
0 indexed parameter number, indicates which parameter in the
stored procedure you wish to know.
textHandle
Specifies the pointer to the handle of the string containing the sort
procedure parameter.
textLength
Specifies the pointer to the length of the parameter string (in bytes)
including the terminating null byte.

494 Crystal Reports Developer’s Reference

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks ● This function is usually used with PEGetHandleString to obtain a

text string containing the parameter in a stored procedure.
● Use PEGetNParams to find out the number of parameters
required by a stored procedure.
● Use PESetNthParam to set the value of a parameter in a stored
procedure.

Related Menu Database|Stored Procedure Parameters

Commands

PEGetNthParam (Other Declares)

PEGetNthParam 16-bit
(VB Syntax) Declare Function PEGetNthParam Lib "crpe.dll"
(ByVal printJob As Integer, ByVal ParamN As
Integer, TextHandle As Integer, TextLength As
Integer) As Integer

32-bit
Declare Function PEGetNthParam Lib "crpe32.dll"
(ByVal printJob As Integer, ByVal paramN As
Integer, TextHandle As Long, TextLength As
Integer) As Integer

PEGetNthParam 16-bit
(Delphi Syntax) function PEGetNthParam (
printJob: integer;
paramN: integer;
var textHandle: HWnd;
var textLength: integer
): Bool;

32-bit
function PEGetNthParam(
printJob: Word;
paramN: integer;

Chapter 6, Crystal Report Engine Reference 495

 var textHandle: HWnd;
var textLength: Word
): Bool stdcall;

PEGetNthParameterField

Returns information about one of the parameter fields in the

specified report: that is, it returns the name of the field, the data type,
and information about the value set for the field. The name of the
parameter field is returned as a string handle. This function is
typically used as one of a series of functions:
PEGetNParameterFields (called once), PEGetNthParameterField,
PEGetHandleString (called together as many times as needed to
identify the correct parameter field), and PESetNthParameterField
(called once when the correct parameter field is identified). The
series can be used in a custom-print link to identify and then change
an existing parameter field value at print time in response to a user
selection.
BOOL CRPE_API PEGetNthParameterField (
short printJob,//handle to print job
short parameterN,//parameter field number
struct PEParameterFieldInfo FAR
*parameterInfo //structure pointer
);

Parameters printJob
Specifies the handle of the print job that contains the parameter field
about which you want to retrieve information.
parameterN
Specifies the number of the parameter field about which you want to
retrieve information.
parameterInfo
Specifies a pointer to the PEParameterFieldInfo structure (see Page
680) that is used to store the information you retrieve.

Return Value TRUE (1) if the call is successful; FALSE (0) if the call fails.

496 Crystal Reports Developer’s Reference

PEGetNthParameterField (Other Declares)

PEGetNth 16-bit
ParameterField Declare Function PEGetNthParameterField Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) varN As Integer, varInfo As
PEParameterFieldInfo) As Integer

32-bit
Declare Function PEGetNthParameterField Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
varN As Integer, varInfo As
PEParameterFieldInfo) As Integer

PEGetNth 16-bit
ParameterField function PEGetNthParameterField (
printJob: integer;
(Delphi Syntax) varN: integer;
var varInfo: PEParameterFieldInfo
): Bool;

32-bit
function PEGetNthParameterField (
printJob: Word;
varN: Smallint;
var varInfo: PEParameterFieldInfo
): Bool stdcall;

PEGetNthParamInfo

This topic is only supported by the Professional Edition of Crystal

Reports.
The PEGetNthParamInfo function retrieves the name and type of a
specified stored procedure parameter.
BOOL CRPE_API PEGetNthParamInfo (
short printJob,//handle to print job
short paramN,
//stored procedure parameter number
struct PEParameterInfo FAR *paramInfo
//structure pointer
);

Chapter 6, Crystal Report Engine Reference 497

Parameters printJob
Specifies the handle to the print job from which you want to gather
information about a stored procedure parameter.
paramN
Specifies the number of the stored procedure parameter about which
you want to gather information.
paramInfo
Specifies the structure that will hold the retrieved information.

Return Value TRUE (1) if the call is successful; FALSE (0) if the call fails.

PEGetNthParamInfo (Other Declares)

PEGetNthParam 16-bit
Info (VB Syntax) Declare Function PEGetNthParamInfo Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
ParamN As Integer, paramInfo As
PEParameterInfo) As Integer

32-bit
Declare Function PEGetNthParamInfo Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
paramN As Integer, paramInfo As
PEParameterInfo) As Integer

PEGetNth 16-bit
ParamInfo function PEGetNthParamInfo (
printJob: integer;
(Delphi Syntax) paramN: integer;
var paramInfo: PEParameterInfo
):Bool;

32-bit
function PEGetNthParamInfo (
printJob: Word;
paramN: Smallint;
var paramInfo: PEParameterInfo
): Bool stdcall;

498 Crystal Reports Developer’s Reference

PEGetNthSortField

Returns information about one of the sort fields in the specified

report: that is, it returns the name of the field and the direction
(ascending or descending) of the sort. The name of the sort field is
returned as a string handle. This function is typically used as one of
a series of functions: PEGetNSortFields (called once),
PEGetNthSortField, PEGetHandleString (called together as many
times as needed to identify the correct sort field), and
PESetNthSortField (called once when the correct sort field is
identified). The series can be used in a custom-print link to identify
and then change an existing sort field and/or sort order at print time
in response to a user selection.
BOOL CRPE_API PEGetNthSortField (
short printJob,//handle to print job
short sortFieldN,//number of sort field
HANDLE FAR *nameHandle,
//field name string handle pointer
short FAR *nameLength,
//field name string length pointer
short FAR *direction
//pointer to sort direction setting
);

Parameters printJob
Specifies the handle to the print job from which you want to retrieve
sort field information.
sortFieldN
Specifies the number of the sort field you want to retrieve. The first
sort field is field 0. If the report has N sort fields, the function can be
called with sortFieldN between 0 and N-1.
nameHandle
Specifies the pointer to the handle of the string containing the sort
field name.
nameLength
Specifies the pointer to the length of the field name string (in bytes)
including the terminating byte.
direction
Specifies the sort direction. Use one of the following values:

Chapter 6, Crystal Report Engine Reference 499

 Value Meaning
PE_SF_ASCENDING Sorts in Ascending order (A to Z, 1 to
9).
PE_SF_DESCENDING Sorts in Descending order (Z to A, 9 to
1).

Return Value TRUE (1) if the call is successful; FALSE (0) if the call fails.

Related Menu Report|Record Sort Order

Commands

PEGetNthSortField (Other Declares)

PEGetNthSortField 16-bit
(VB Syntax) Declare Function PEGetNthSortField Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
SortNumber As Integer, NameHandle As Integer,
NameLength As Integer, Direction As Integer) As
Integer

32-bit
Declare Function PEGetNthSortField Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
SortNumber As Integer, NameHandle As Long,
NameLength As Integer, Direction As Integer) As
Integer

PEGetNthSortField 16-bit
(Delphi Syntax) function PEGetNthSortField (
printJob: integer;
sortFieldN: integer;
var nameHandle: HWnd;
var nameLength:integer;
var direction: integer
): Bool;

500 Crystal Reports Developer’s Reference

 32-bit
function PEGetNthSortField (
printJob: Word;
sortFieldN: integer;
var nameHandle: HWnd;
var nameLength: Word;
var direction: Word
): Bool stdcall;

PEGetNthSubreportInSection

This topic is only supported by the Professional Edition of Crystal

Reports.
The PEGetNthSubreportInSection function retrieves a handle that
is required to retrieve the name of the subreport.
DWORD CRPE_API PEGetNthSubreportInSection (
short printJob,
//handle to the primary report
short sectionCode,
//code identifying section
short subreportN
//number of subreport in section
);

Parameters printJob
Specifies the handle of the primary report
sectionCode
Specifies the code for the report section that contains the subreport.
See Working with Section Codes, Page 428.
subreportN
Specifies the number of the subreport in the specified section.
subreportN is zero based. The first report in the section will be 0, the
second will be 1, etc. If there are no subreports in the section, the
function will return 0.

Remarks Use PEGetSubreportInfo to retrieve information about the subreport

by passing the subreport handle returned by
PEGetNthSubreportInSection.

Chapter 6, Crystal Report Engine Reference 501

PEGetNthSubreportInSection (Other Declares)

PEGetNth 16-bit
Subreport Declare Function PEGetNthSubreportInSection
Lib "crpe.dll" (ByVal printJob As Integer,
InSection ByVal sectionCode As Integer, ByVal subreportN
(VB Syntax) As Integer) As Long

32-bit
Declare Function PEGetNthSubreportInSection
Lib "crpe32.dll" (ByVal printJob As Integer,
ByVal sectionCode As Integer, ByVal subreportN
As Integer) As Long

PEGetNth 16-bit
SubreportIn function PEGetNthSubreportInSection (
printJob: integer;
Section sectionCode: integer;
(Delphi Syntax) subreportN: integer
): Longint;

32-bit
function PEGetNthSubreportInSection (
printJob: Word;
sectionCode: Smallint
subreportN: Smallint
): DWord stdcall;

Related Topics
Working with subreports 36

PEGetNthTableLocation

The PEGetNthTableLocation function determines the location of a

selected table used in the specified print job. This function is typically
combined with PESetNthTableLocation to identify the location of a
table and then to change it.

502 Crystal Reports Developer’s Reference

 BOOL CRPE_API PEGetNthTableLocation (
short printJob,//handle to print job
short tableN, //number of table
struct PETableLocation FAR *location
//structure pointer
);

Parameters printJob
Specifies the handle of the print job from which you want to retrieve
information about a table’s location.
tableN
Specifies the number of the table for which you want to retrieve
location information. The first table is table 0.
location
Specifies the pointer to the PETableLocation structure (see Page 696).

Return Value TRUE (1) if the call is successful; FALSE (0) if the call fails.

Related Menu Database|Set Location

Commands

PEGetNthTableLocation (Other Declares)

PEGetNthTable 16-bit
Location Declare Function PEGetNthTableLocation Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) TableN As Integer, Location As PETableLocation)
As Integer

32-bit
Declare Function PEGetNthTableLocation Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
TableN As Integer, Location As PETableLocation)
As Integer

Chapter 6, Crystal Report Engine Reference 503

PEGetNthTable 16-bit
Location function PEGetNthTableLocation (
printJob: integer;
(Delphi Syntax) tableN: integer;
var location: PETableLocation
): Bool;

32-bit
function PEGetNthTableLocation(
printJob: Word;
tableN: integer;
var location: PETableLocation
): Bool stdcall;

PEGetNthTableLogOnInfo

The PEGetNthTableLogOnInfo function retrieves into the

PELogOnInfo structure the log on information required by a report.
BOOL CRPE_API PEGetNthTableLogOnInfo (
short printJob,//handle to print job
short tableN,//number of table
struct PELogOnInfo FAR *logOnInfo
//structure pointer
);

Parameters printJob
Specifies the handle of the print job for which you want to get table
log on information.
tableN
Specifies the number of the table from which you want to get log on
information. The first table is table 0.
logOnInfo
Specifies the pointer to the PELogOnInfo structure.

Return Value TRUE (1) if the call is successful; FALSE (0) if the call fails.

Remarks ● This function must be called after PEOpenPrintJob (so you have
the job handle) and before PEStartPrintJob (which needs the
password set to print the report).

504 Crystal Reports Developer’s Reference

 ● You must initialize the structSize member to be the size of
whatever it is. For example:
logOnInfo.structSize = PE_SIZEOF_LOGON_INFO

PEGetNthTableLogOnInfo (Other Declares)

PEGetNthTable 16-bit
LogOnInfo Declare Function PEGetNthTableLogOnInfo Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) TableN As Integer, LogOnInfo As PELogOnInfo) As
Integer

32-bit
Declare Function PEGetNthTableLogOnInfo Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
TableN As Integer, LogOnInfo As PELogOnInfo) As
Integer

PEGetNthTable 16-bit
LogOnInfo function PEGetNthTableLogOnInfo (
printJob: integer;
(Delphi Syntax) tableN: integer;
var logOnInfo: PELogOnInfo
): Bool;

32-bit
function PEGetNthTableLogOnInfo (
printJob: Word;
tableN: integer;
var logOnInfo: PELogOnInfo
): Bool stdcall;

PEGetNthTableSessionInfo

The PEGetNthTableSessionInfo function gets the session

information for a Microsoft Access table being used in your report.
Many MS Access database tables require that a session be opened
before the information in the table can be used. Use
PEGetNthTableSessionInfo to obtain the session information (User
ID, Password, and Session Handle) for a particular table.

Chapter 6, Crystal Report Engine Reference 505

 BOOL CRPE_API PEGetNthTableSessionInfo (
short printJob,//handle to print job
short tableN,//table number
struct PESessionInfo FAR *sessionInfo
//structure pointer
);

Parameters printJob
Identifies the handle of the print job that uses the table for which you
need to obtain the session information.
tableN
0 indexed table number indicating which table in the report you wish
to obtain the session information for.
sessionInfo
Refer to the PESessionInfo structure for further information.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks This function is only applicable for MS Access databases which

require a session to be opened before the database is accessed.

PEGetNthTableSessionInfo (Other Declares)

PEGetNthTable 16-bit
SessionInfo Declare Function PEGetNthTableSessionInfo Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) TableN As Integer, SessionInfo As
PESessionInfo) As Integer

32-bit
Declare Function PEGetNthTableSessionInfo Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
TableN As Integer, SessionInfo As
PESessionInfo) As Integer

506 Crystal Reports Developer’s Reference

PEGetNthTable 16-bit
SessionInfo function PEGetNthTableSessionInfo (
printJob: integer;
(Delphi Syntax) tableN: integer;
var sessionInfo: PESessionInfo
): Bool;

32-bit
function PEGetNthTableSessionInfo (
printJob: Word;
tableN: integer;
var sessionInfo: PESessionInfo
): Bool stdcall;

PEGetNthTableType

The PEGetNthTableType function allows the application to

determine the type of each table.
This function is one of a series of functions that enable you to retrieve
and update database information in an opened report so that the
report can be printed using different server, database, user, and/or
table location settings.
BOOL CRPE_API PEGetNthTableType (
short printJob,//handle to print job
short tableN, //number of table
struct PETableType FAR *tableType
//structure pointer
);

Parameters printJob
Specifies the handle of the print job for which you want to determine
a table type.
tableN
Specifies the number of the table for which you want to determine
the type. Table numbers start at 0. For example, if PEGetNTables
returns 2, call PEGetNthTableType twice with table numbers of 0
and 1.
tableType
Specifies the pointer to the PETableType structure.

Chapter 6, Crystal Report Engine Reference 507

Return Value TRUE (1) if the call is successful, FALSE (0) if anything goes wrong.

Remarks The application can test DBType in the PETableType structure, or

test the database DLL name used to create the report. DBType is the
structure returned by PEGetNthTableType. DLL names have the
following naming convention:
● PDB*.DLL for standard (non-SQL) databases,
● PDS*.DLL for SQL/ODBC databases.
NOTE: While there are some differences in naming conventions
between 16-bit and 32-bit versions, you can always use the 16-
convention (above) and be confident that it will work.
● In the case of ODBC (PDSODBC.DLL) the DescriptiveName
includes the ODBC data source name.
All strings must be null-terminated.
You must initialize the structure struct size member to be the size
of whatever it is. For example:
tableType.structSize = PE_SIZEOF_TABLE_TYPE

PEGetNthTableType (Other Declares)

PEGetNthTable 16-bit
Type (VB Syntax) Declare Function PEGetNthTableType Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
TableN As Integer, TableType As PETableType) As
Integer

32-bit
Declare Function PEGetNthTableType Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
TableN As Integer, TableType As PETableType) As
Integer

PEGetNthTable 16-bit
Type function PEGetNthTableType (
printJob: integer;
(Delphi Syntax) tableN: integer;
var tableType: PETableType
): Bool;

508 Crystal Reports Developer’s Reference

 32-bit
function PEGetNthTableType (
printJob: Word;
tableN: integer;
var tableType: PETableType
): Bool stdcall;

PEGetPrintDate

Determines the print date (if any) that was specified with the report.
Use this function to fetch the print date and pass back using
PESetPrintDate.
BOOL CRPE_API PEGetPrintDate (
short printJob,//handle to print job
short FAR *year,
//pointer to print date year component
short FAR *month,
//pointer to print date month component
short FAR *day
//pointer to print date day component
);

Parameters printJob
Specifies the handle of the print job you want to query to determine
its print date setting.
year
Specifies a pointer to the year component of the print date.
month
Specifies a pointer to the month component of the print date.
day
Specifies a pointer to the day component of the print date.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks You change the print date, typically, when you want to run the
report today yet have it appear to have been run on a different date.
An example would be, if you were out of town on the last day of the
previous month and you later want to run a report for that month
and make it appear as if it were run on the last day of the month.

Chapter 6, Crystal Report Engine Reference 509

Related Menu Report|Set Print Date
Commands

PEGetPrintDate (Other Declares)

PEGetPrintDate 16-bit
(VB Syntax) Declare Function PEGetPrintDate Lib "crpe.dll"
(ByVal printJob As Integer, Date_Year As
Integer, Date_Month As Integer, Date_Day As
Integer) As Integer

32-bit
Declare Function PEGetPrintDate Lib
"crpe32.dll" (ByVal printJob As Integer,
Date_Year As Integer, Date_Month As Integer,
Date_Day As Integer) As Integer

PEGetPrintDate 16-bit
(Delphi Syntax) function PEGetPrintDate (
printJob: integer;
var year: integer;
var month: integer;
var day: integer
): Bool;

32-bit
function PEGetPrintDate (
printJob: Word;
var year: Word;
var month: Word;
var day: Word
): Bool stdcall;

PEGetPrintOptions

This topic is only supported by the Professional Edition of Crystal

Reports.

510 Crystal Reports Developer’s Reference

 Retrieves the print options specified for the report (the options that
are set in the Print common dialog box) and uses them to fill in the
PEPrintOptions structure. Use this function to fetch print options
from the report in order to update them and pass back using
PESetPrintOptions.
BOOL CRPE_API PEGetPrintOptions (
short printJob,//handle to print job
struct PEPrintOptions FAR *options
//structure pointer
);

Parameters printJob
Specifies the handle of the print job you want to query to find out
which print options have been set using the Print common dialog
box.
options
Specifies the pointer to the PEPrintOptions structure.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Related Menu File|Print|Printer

Commands

PEGetPrintOptions (Other Declares)

PEGetPrintOptions 16-bit
(VB Syntax) Declare Function PEGetPrintOptions Lib
"crpe.dll" (ByVal printJob As Integer, Options
As PEPrintOptions) As Integer

32-bit
Declare Function PEGetPrintOptions Lib
"crpe32.dll" (ByVal printJob As Integer,
Options As PEPrintOptions) As Integer

Chapter 6, Crystal Report Engine Reference 511

PEGetPrintOptions 16-bit
(Delphi Syntax) function PEGetPrintOptions (
printJob: integer;
var options: PEPrintOptions
): Bool;

32-bit
function PEGetPrintOptions (
printJob: Word;
var options: PEPrintOptions
): Bool stdcall;

PEGetReportTitle

This topic is only supported by the Professional Edition of Crystal

Reports.
Returns the handle of the title string that is to appear on the window
title bar of the specified report when the report prints to a print
window. This function is typically used as one of a series of functions
(PEGetReportTitle/PEGetHandleString, PESetReportTitle). The
series can be used in a custom-print link to identify and then change
an existing report title at print time in response to a user selection.
BOOL CRPE_API PEGetReportTitle (
short printJob,//handle to print job
HANDLE FAR *titleHandle,
//pointer to title string handle
short FAR *titleLength
//pointer to title string length
);

Parameters printJob
Specifies the handle of the print job for which you want to get the
report title.
titleHandle
Specifies a pointer to the handle of the string containing the window
title.
titleLength
Specifies a pointer to the length of the window title string (in bytes)
including the terminating byte.

512 Crystal Reports Developer’s Reference

Return Value TRUE (1) if the call is successful; FALSE (0) if the call fails.

Related Menu Report|Report Title

Commands

PEGetReportTitle (Other Declares)

PEGetReportTitle 16-bit
(VB Syntax) Declare Function PEGetReportTitle Lib
"crpe.dll" (ByVal printJob As Integer,
TitleHandle As Integer, TitleLength As Integer)
As Integer

32-bit
Declare Function PEGetReportTitle Lib
"crpe32.dll" (ByVal printJob As Integer,
TitleHandle As Long, TitleLength As Integer) As
Integer

PEGetReportTitle 16-bit
(Delphi Syntax) function PEGetReportTitle (
printJob: integer;
var titleHandle: HWnd;
var titleLength: integer
): Bool;

32-bit
function PEGetReportTitle (
printJob: Word;
var titleHandle: HWnd;
var titleLength: Word
): Bool stdcall;

PEGetSectionCode

The PEGetSectionCode function retrieves the section code for the

specified section. A section code indicates the section type (Page
Header, Details, and so forth). If there are multiple group sections it

Chapter 6, Crystal Report Engine Reference 513

 also identifies the group number, and if there are multiple sections in
an area it identifies the section number.
short CRPE_API PEGetSectionCode (
short printJob, //handle to print job
short sectionN
//number of section you want code for
);

Parameters printJob
Specifies the handle of the print job from which you want to identify
a section code.
sectionN
Specifies the number of the section for which you want the section
code. See Working with Section Codes, Page 428.

Return value The section code for the specified section. See Working with Section
Codes, Page 428.

PEGetSectionCode (Other Declares)

PEGetSectionCode 16-bit
(VB Syntax) Declare Function PEGetSectionCode Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
sectionN As Integer) As Integer

32-bit
Declare Function PEGetSectionCode Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
sectionN As Integer) As Integer

PEGetSectionCode 16-bit
(Delphi Syntax) function PEGetSectionCode (
printJob: integer;
sectionN: integer
): integer;

514 Crystal Reports Developer’s Reference

 32-bit
function PEGetSectionCode (
printJob: Word;
sectionN: Smallint
): Smallint stdcall;

PEGetSectionFormat

This topic is only supported by the Professional Edition of Crystal

Reports.
Retrieves the section format settings for selected sections in the
specified report and supplies them as member values for the
PESectionOptions structure. Use this function in order to update the
section formats and pass them back using PESetSectionFormat.
BOOL CRPE_API PEGetSectionFormat (
short printJob,//handle to print job
short sectionCode,
//code identifying section
struct PESectionOptions FAR *options
//structure pointer
);

Parameters printJob
Specifies the handle of the print job you want to query to find what
section options have been set for the report using the Format Section
dialog box.
sectionCode
Specifies the code for the report section(s) for which you want to get
section format information. See Working with Section Codes, Page 428.
options
Specifies the pointer to the PESectionOptions structure.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Related Menu Format|Section

Commands

Chapter 6, Crystal Report Engine Reference 515

PEGetSectionFormat (Other Declares)

PEGetSection 16-bit
Format Declare Function PEGetSectionFormat Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) sectionCode As Integer, Options As
PESectionOptions) As Integer

32-bit
Declare Function PEGetSectionFormat Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
sectionCode As Integer, Options As
PESectionOptions) As Integer

PEGetSection 16-bit
Format function PEGetSectionFormat (
printJob: integer;
(Delphi Syntax) sectionCode: integer;
var options: PESectionOptions
): Bool;

32-bit
function PEGetSectionFormat (
printJob: Word;
sectionCode: integer;
var options: PESectionOptions
): Bool stdcall;

PEGetSelectedPrinter

This topic is only supported by the Professional Edition of Crystal

Reports.
If the printer has been specified in Crystal Reports using the
File|Printer Setup|Specific printer option, the call will return
information about that printer if the same driver is installed on the
machine. If the driver has not been installed on the machine, it will
return information about the default printer specified under
Windows Control Panel|Printers.

516 Crystal Reports Developer’s Reference

 BOOL CRPE_API PEGetSelectedPrinter (
short printJob,//handle to print job
HANDLE FAR *driverHandle,
//pointer to driver handle
short FAR *driverLength,
//pointer to driver name length
HANDLE FAR *printerHandle,
//pointer to printer handle
short FAR *printerLength,
//pointer to printer name length
HANDLE FAR *portHandle,
//pointer to printer port handle
short FAR *portLength,
//pointer to printer port name length
DEVMODE FAR *FAR *mode//structure pointer
);

Parameters printJob
Specifies the handle to the print job that you want to query to get
information on the non-default printer that has been selected with
the report.
driverHandle
Specifies a pointer to the handle of the printer driver for the printer
that is selected with the print job.
driverLength
Specifies a pointer to the length of the printer driver name.
printerHandle
Specifies a pointer to the handle of the printer that is selected with
the print job.
printerLength
Specifies a pointer to the length of the printer name.
portHandle
Specifies a pointer to the handle of the port to which the selected
printer is connected.
portLength
Specifies a pointer to the length of the port name.
mode
Specifies the pointer to the DEVMODE structure.

Chapter 6, Crystal Report Engine Reference 517

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Related Menu File|Printer Setup

Commands

PEGetSelectedPrinter (Other Declares)

PEGetSelected 16-bit
Printer Declare Function PEGetSelectedPrinter Lib
"crpe.dll" (ByVal printJob As Integer,
(VB Syntax) DriverHandle As Integer, DriverLength As
Integer, PrinterHandle As Integer,
PrinterLength As Integer, PortHandle As
Integer, PortLength As Integer, DevMode As Any)
As Integer

32-bit
Declare Function PEGetSelectedPrinter Lib
"crpe32.dll" (ByVal printJob As Integer,
DriverHandle As Long, DriverLength As Integer,
PrinterHandle As Long, PrinterLength As
Integer, PortHandle As Long, PortLength As
Integer, DevMode As Any) As Integer

PEGetSelected 16-bit
Printer function PEGetSelectedPrinter (
printJob: integer;
(Delphi Syntax) var driverHandle: HWnd;
var driverLength: integer;
var printerHandle: HWnd;
var printerLength: integer;
var portHandle: HWnd;
var portLength: integer;
var mode: PDevMode
): Bool;

518 Crystal Reports Developer’s Reference

 32-bit
function PEGetSelectedPrinter (
printJob: Word;
var driverHandle: Hwnd;
var driverLength: Word;
var printerHandle: Hwnd;
var printerLength: Word;
var portHandle: Hwnd;
var portLength: Word;
var mode: PDeviceMode
): Bool stdcall;

PEGetSelectionFormula

Returns the string handle for the selection formula used in the
specified report. This function is typically used as one of a series of
functions (PEGetSelectionFormula, PEGetHandleString,
PESetSelectionFormula). The series can be used in a custom-print
link to identify and then change an existing record selection formula
at print time in response to a user selection.
BOOL CRPE_API PEGetSelectionFormula (
short printJob,//handle to print job
HANDLE FAR *textHandle,
//pointer to formula string handle
short FAR *textLength
//pointer to formula string length
);

Parameters printJob
Specifies the handle of the print job for which you want to retrieve
the selection formula string.
textHandle
Specifies the pointer to the handle of the string containing the
formula text.
textLength
Specifies the pointer to the length of the formula string (in bytes)
including the terminating byte.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Chapter 6, Crystal Report Engine Reference 519

Related Menu Report|Edit Record Selection Formula
Commands

PEGetSelectionFormula (Other Declares)

PEGetSelection 16-bit
Formula Declare Function PEGetSelectionFormula Lib
"crpe.dll" (ByVal printJob As Integer,
(VB Syntax) TextHandle As Integer, TextLength As Integer)
As Integer

32-bit
Declare Function PEGetSelectionFormula Lib
"crpe32.dll" (ByVal printJob As Integer,
TextHandle As Long, TextLength As Integer) As
Integer

PEGetSelection 16-bit
Formula function PEGetSelectionFormula (
printJob: integer;
(Delphi Syntax) var textHandle: HWnd;
var textLength: integer
): Bool;

32-bit
function PEGetSelectionFormula (
printJob: Word;
var textHandle: HWnd;
var textLength: Word
): Bool stdcall;

PEGetSQLQuery

This topic is only supported by the Professional Edition of Crystal

Reports.
The PEGetSQLQuery function returns the same query that appears
in the Show SQL Query dialog box in Crystal Reports, in a syntax
that’s specific to the database driver you’re using.

520 Crystal Reports Developer’s Reference

 You can use this function to retrieve the SQL query that will be
generated to print the report, and you can update the query using
PESetSQLQuery.
BOOL CRPE_API PEGetSQLQuery (
short printJob,//handle to print job
HANDLE FAR *textHandle,
//pointer to query string handle
short FAR *textLength
//pointer to query string length
);

Parameters printJob
Specifies the handle to the print job from which you want to retrieve
the SQL query.
textHandle
Specifies the pointer to the handle of the string containing the SQL
query string.
textLength
Specifies the pointer to the length of the SQL query string (in bytes)
including the terminating byte.

Return Value TRUE (1) if the call is successful, (0) if an error occurs.

Related Menu Database|Show SQL Query

Commands

PEGetSQLQuery (Other Declares)

PEGetSQLQuery 16-bit
(VB Syntax) Declare Function PEGetSQLQuery Lib "crpe.dll"
(ByVal printJob As Integer, TextHandle As
Integer, TextLength As Integer) As Integer

Chapter 6, Crystal Report Engine Reference 521

 32-bit
Declare Function PEGetSQLQuery Lib "crpe32.dll"
(ByVal printJob As Integer, TextHandle As Long,
TextLength As Integer) As Integer

PEGetSQLQuery 16-bit
(Delphi Syntax) function PEGetSQLQuery (
printJob: integer;
var textHandle: HWnd;
var textLength: integer
): Bool;

32-bit
function PEGetSQLQuery (
printJob: Word;
var textHandle: HWnd;
var textLength: Word
): Bool stdcall;

PEGetSubreportInfo

This topic is only supported by the Professional Edition of Crystal

Reports.
The PEGetSubreportInfo function retrieves information about the
specified subreport.
BOOL CRPE_API PEGetSubreportInfo (
short printJob,//handle to primary report
DWORD subreportHandle,//handle to subreport
struct PESubreportInfo FAR *subreportInfo
//structure pointer
);

Parameters printJob
Specifies the handle of the primary report that contains the subreport
about which you want to retrieve information.
subreportHandle
Specifies the handle of the subreport about which you want to
retrieve information.

522 Crystal Reports Developer’s Reference

 subreportInfo
Specifies a pointer to the structure that will be used for holding the
information once it is retrieved.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

PEGetSubreportInfo (Other Declares)

PEGetSubreport 16-bit
Info (VB Syntax) Declare Function PEGetSubreportInfo Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
subreportHandle As Long, subreportInfo As
PESubreportInfo) As Integer

32-bit
Declare Function PEGetSubreportInfo Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
subreportHandle As Long, subreportInfo As
PESubreportInfo) As Integer

PEGetSubreport 16-bit
Info function PEGetSubreportInfo (
printJob: integer;
(Delphi Syntax) subreportHandle: Longint;
var subreportInfo: PESubreportInfo
): Bool;

32-bit
function PEGetSubreportInfo (
printJob: Word;
subreportHandle: DWord;
var subreportInfo: PESubreportInfo
): Bool stdcall;

Related Topics
Working with subreports 36

Chapter 6, Crystal Report Engine Reference 523

PEGetVersion

Returns the version number of the DLL or the Report Engine. The
high-order byte is the major version number and the low-order byte
is the minor version number. This function can be used whenever
you build functionality into a report that may not be available in
earlier versions of the Report Engine and you need to verify the
version number first. The function can be a handy safeguard for
users who have more than one version of the Report Engine with the
older version earlier in the path than the new version.
short CRPE_API PEGetVersion (
short versionRequested
//code specifying DLL or Report Engine
);

Parameters versionRequested
Specifies whether the DLL or Report Engine version is being
requested. Use one of the following values:

Value Meaning
PE_GV_DLL Returns the version of the DLL
(CRPE.DLL/CRPE32.DLL).
PE_GV_ENGINE Returns the version of the Report
Engine.

Return Value The version number of the DLL or the Crystal Report Engine.

PEGetVersion (Other Declares)

PEGetVersion 16-bit
(VB Syntax) Declare Function PEGetVbVersion Lib "crpe.dll"
(ByVal Version As Integer) As Integer

32-bit
Declare Function PEGetVbVersion Lib
"crpe32.dll" (ByVal Version As Integer) As
Integer

524 Crystal Reports Developer’s Reference

PEGetVersion 16-bit
(Delphi Syntax) function PEGetVersion (
versionRequested: integer
): integer;

32-bit
function PEGetVersion (
versionRequested: integer
): smallint stdcall;

PEGetVersion EXTERN CWORD PEGetVersion (CWORD) CRPE.DLL

(dBASE for
Windows Syntax)

PEGetWindowHandle

Returns the handle of the print window. This function can be used in
a custom-print link if you want to do something with the print
window (move it, change its size, etc.)
PEGetWindowHandle can also be used to determine if the user has
already closed the print window.
HWND CRPE_API PEGetWindowHandle (
short printJob//handle to print job
);

Parameters printJob
Specifies the handle of the print job from which you want to retrieve
the print window handle. If two or more print windows are open,
this function applies only to the most recently created print window.

Return Value This function returns the print window handle if it is successful, 0 if
an error occurs or if the print window has already been closed.

Remarks This function can be used after the PEStartPrintJob call, and then,
only if you have created a print window.

Chapter 6, Crystal Report Engine Reference 525

PEGetWindowHandle (Other Declares)

PEGetWindow 16-bit
Handle Declare Function PEGetWindowHandle Lib
"crpe.dll" (ByVal printJob As Integer) As
(VB Syntax) Integer

32-bit
Declare Function PEGetWindowHandle Lib
"crpe32.dll" (ByVal printJob As Integer) As
Integer

PEGetWindow 16-bit
Handle function PEGetWindowHandle (
printJob: integer
(Delphi Syntax) ): HWnd;

32-bit
function PEGetWindowHandle (
printJob: Word
): HWnd stdcall;

PEGetWindow EXTERN CHANDLE PEGetWindowHandle (CWORD)

CRPE.DLL
Handle (dBASE
for Windows
Syntax)

PEHasSavedData

This topic is only supported by the Professional Edition of Crystal

Reports.
The PEHasSavedData function queries a report to find if data is
saved with it. With this information, you can determine whether or
not the data needs to be refreshed before the report is printed.

526 Crystal Reports Developer’s Reference

 BOOL CRPE_API PEHasSavedData (
short printJob,//handle to print job
BOOL FAR *hasSavedData
//pointer to "data saved?" setting
);

Parameters printJob
Specifies the handle to the print job you want to query to find if it has
saved data.
hasSavedData
Specifies a pointer to a memory address that indicates whether or not
there is data saved with the report.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks A report may or may not have saved data when a print job is first
opened from a report file. Since data is saved during a print,
however, it will always have saved data immediately after a report
is printed.
Use PEDiscardSavedData to release the saved data associated with a
report. The next time the report is printed, it will get current data
from the database.
The default behavior is for a report to use its saved data rather than
refresh its data from the database when printing a report.

Related Menu File|Save Data with Report

Commands

PEHasSavedData (Other Declares)

PEHasSavedData 16-bit
(VB Syntax) Declare Function PEHasSavedData Lib "crpe.dll"
(ByVal printJob As Integer, HasSavedData As
Integer) As Integer

Chapter 6, Crystal Report Engine Reference 527

 32-bit
Declare Function PEHasSavedData Lib
"crpe32.dll" (ByVal printJob As Integer,
HasSavedData As Integer) As Integer

PEHasSavedData 16-bit
(Delphi Syntax) function PEHasSavedData (
printJob: integer;
var hasSavedData: Bool
):Bool;

32-bit
function PEHasSavedData(
printJob: Word;
var hasSavedData: Bool
): Bool stdcall;

PEIsPrintJobFinished

Monitors the print job to see if it is finished or still in progress. You

can use this function any time you have a call that is contingent on a
print job being finished.
BOOL CRPE_API PEIsPrintJobFinished (
short printJob//handle to print job
);

Parameters printJob
Specifies the handle to the print job you are querying to find if it has
finished printing.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks PEIsPrintJobFinished will return TRUE immediately after the report

has been displayed in the print window, even if that print window is
still open.

528 Crystal Reports Developer’s Reference

PEIsPrintJobFinished (Other Declares)

PEIsPrintJob 16-bit
Finished Declare Function PEIsPrintJobFinished Lib
"crpe.dll" (ByVal printJob As Integer) As
(VB Syntax) Integer

32-bit
Declare Function PEIsPrintJobFinished Lib
"crpe32.dll" (ByVal printJob As Integer) As
Integer

PEIsPrintJob 16-bit
Finished function PEIsPrintJobFinished (
printJob: integer
(Delphi Syntax) ):Bool;

32-bit
function PEIsPrintJobFinished (
printJob: Word
): Bool stdcall;

PEIsPrintJob EXTERN CLOGICAL PEIsPrintJobFinished (CWORD)

CRPE.DLL
Finished (dBASE
for Windows
Syntax)

PELogOffServer

Logs off the specified server. Use any time you have to log off a
specified server.
BOOL CRPE_API PELogOffServer (
char FAR *dllName,//pointer to name of
datasource DLL
struct PELogOnInfo FAR *logOnInfo
//structure pointer
);

Chapter 6, Crystal Report Engine Reference 529

Parameters dllName
Specifies the name of the Crystal Reports DLL for the datasource you
want to log off, for example, "PDSODBC.DLL". Note that the
dllName must be enclosed in quotes. DLL names have the following
naming convention: PDB*.DLL for standard (non-SQL) databases,
PDS*.DLL for SQL/ODBC databases (16-bit and 32-bit).
logOnInfo
Specifies the pointer to the PELogOnInfo structure.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks ● PELogOnServer and PELogOffServer can be called at any time to

log on and off a database server. These functions are not required
if the function PESetNthTableLogOnInfo was already used to log
on to a table.
● This function requires a database DLL name which can be
retrieved using PEGetNthTableType.

Related Menu Database|Log Off Server

Commands

PELogOffServer (Other Declares)

PELogOffServer 16-bit
(VB Syntax) Declare Function PELogOffServer Lib "crpe.dll"
(ByVal DLLName As String, LogOnInfo As
PELogOnInfo) As Integer

32-bit
Declare Function PELogOffServer Lib
"crpe32.dll" (ByVal DLLName As String,
LogOnInfo As PELogOnInfo) As Integer

530 Crystal Reports Developer’s Reference

PELogOffServer 16-bit
(Delphi Syntax) function PELogOffServer (
dllName:PChar;
var logOnInfo: PELogOnInfo
):Bool;

32-bit
function PELogOffServer(
dllName: PChar;
var logOnInfo: PELogOnInfo
): Bool stdcall;

PELogOnServer

The PELogOnServer function logs on to the specified server.

BOOL CRPE_API PELogOnServer (
char FAR *dllName,
//pointer to name of datasource DLL
struct PELogOnInfo FAR *logOnInfo
//structure pointer
);

Parameters dllName
Specifies the name of the Crystal Reports DLL for the server or
password protected non-SQL table you want to log onto, for
example, "PDSODBC.DLL". Note that the dllName must be enclosed
in quotes. DLL names have the following naming convention:
PDB*.DLL for standard (non-SQL) databases, PDS*.DLL for SQL/
ODBC databases.
logOnInfo
Specifies the pointer to the PELogOnInfo structure.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks ● PELogOnServer and PELogOffServer can be called at any time to

log on and off a database server. These functions are not required
if the function PESetNthTableLogOnInfo was already used to set
the password for a table.

Chapter 6, Crystal Report Engine Reference 531

 ● This function requires a database DLL name, which can be
retrieved using PEGetNthTableType.
● This function can also be used for non-SQL tables, such as
password-protected Paradox tables. Call this function to set the
password for the Paradox DLL before beginning printing.
● When printing using PEStartPrintJob, the ServerName passed in
PELogOnServer must agree exactly with the server name stored
in the report. If this is not true, use PESetNthTableLogOnInfo to
perform logging on instead.
● The following points need to be considered when deciding
whether to use PELogOnServer or PESetNthTableLogOnInfo:
 PELogOnServer is easier to call than
PESetNthTableLogOnInfo and it can be called at any time.
You must know the database DLL name to make this call,
however.
 PESetNthTableLogOnInfo is more flexible than
PELogOnServer. It allows you to override any of the log on
parameters. This call must be called after PEOpenPrintJob.

Remarks The actual file name is needed for both 32-bit and 16-bit.

Related Menu Database|Log On Server

Commands

PELogOnServer (Other Declares)

PELogOnServer 16-bit
(VB Syntax) Declare Function PELogOnServer Lib "crpe.dll"
(ByVal DLLName As String, LogOnInfo As
PELogOnInfo) As Integer

32-bit
Declare Function PELogOnServer Lib "crpe32.dll"
(ByVal DLLName As String, LogOnInfo As
PELogOnInfo) As Integer

532 Crystal Reports Developer’s Reference

PELogOnServer 16-bit
(Delphi Syntax) function PELogOnServer (
dllName: PChar;
var logOnInfo: PELogOnInfo
):Bool;

32-bit
function PELogOnServer(
dllName: PChar;
var logOnInfo: PELogOnInfo
): Bool stdcall;

PELogOnSQLServerWithPrivateInfo

This topic is only supported by the Professional Edition of Crystal

Reports.
Enables the Report Engine to "piggyback" your application’s existing
connection to a Server. If you are already logged on, this function
lowers the number of connections established by a workstation, thus
reducing application time and network traffic. It also prevents a
Crystal Reports Log Off call from disconnecting an application’s
existing connection to the Server.
BOOL CRPE_API PELogOnSQLServerWithPrivateInfo (
char FAR *dllName,
//pointer to name of datasource DLL
void FAR *privateInfo
//pointer to database connect handle
);

Parameters dllName
Specifies the name of the Crystal Reports DLL that was used in
establishing the connection to the server when the report was first
created. Thus, if a report was created using an ODBC datasource, the
Crystal Reports DLL is PDSODBC.DLL.
privateInfo
In the application, a connection to the server has to have been
established and this in turn generates a Handle to a Database
Connection (HDBC). This parameter specifies the application’s
handle to the connection. This makes Crystal Reports aware of the
existing connection so it can use it instead of establishing a new one.

Chapter 6, Crystal Report Engine Reference 533

 Since the reports with which this function works are based on ODBC,
this parameter is actually an ODBC HDBC.

Return Value TRUE (1) if the call is successful; FALSE (0) if the call fails.

Remarks This function can only be used with database connections

established by ODBC or Q+E Library 2.0. Any other database
connections can not be accessed by this function.
If the application uses the Q+E Library to connect, get the ODBC
HDBC by using the following function calls:
qeConnect (opens a connection to the server)
qeGetODBCHdbc (returns the ODBC hdbc)
NOTE: See the Intersolv DataDirect Developer’s Toolkit for more
information.
If the application uses ODBC to connect, get the ODBC HDBC by
using the following function calls:
SQLAllocEnv
(initializes the ODBC call level interface and allocates memory
for an environment handle)
SQLAllocConnect
(returns an ODBC HDBC)
NOTE: See the ODBC documentation for more information.

PELogOnSQLServerWithPrivateInfo (Other Declares)

PELogOnSQL 16-bit
ServerWithPrivate Declare Function
PELogOnSQLServerWithPrivateInfo Lib "crpe.dll"
Info (VB Syntax) (ByVal DLLName As String, ByVal PrivateInfo As
Long) As Integer

32-bit
Declare Function
PELogOnSQLServerWithPrivateInfo Lib
"crpe32.dll" (ByVal DLLName As String, ByVal
PrivateInfo As Long) As Integer

534 Crystal Reports Developer’s Reference

PELogOnSQL 16-bit
ServerWithPrivate function PELogOnSQLServerWithPrivateInfo (
dllName : PChar;
Info privateInfo: Pointer
(Delphi Syntax) ):Bool;

32-bit
function PELogOnSQLServerWithPrivateInfo (
dllName: PChar;
privateInfo: Pointer
): Bool stdcall;

PENextPrintWindowMagnification

This topic is only supported by the Professional Edition of Crystal

Reports.
Changes the print window magnification to the next magnification
level in order. Use this function to cycle through the three levels of
print window magnification whenever the report has been printed to
a print window. The three levels of magnification are: Full Page, Fit
One Side, and Fit Both Sides.
BOOL CRPE_API PENextPrintWindowMagnification (
short printJob//handle to print job
);

Parameters printJob
The handle of the print job for the report appearing in the print
window.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks ● This function cycles to the next level of magnification according

to the following order: Full Page, Fit One Side, Fit Both Sides, Full
Page, etc. Each time the function is called, the print window
cycles to the next magnification level in order.
● This function works like the Magnifying Glass control button
that appears for the print window.

Chapter 6, Crystal Report Engine Reference 535

PENextPrintWindowMagnification (Other Declares)

PENextPrint 16-bit
Window Declare Function
PENextPrintWindowMagnification Lib "crpe.dll"
Magnification (ByVal printJob As Integer) As Integer
(VB Syntax)
32-bit
Declare Function
PENextPrintWindowMagnification Lib
"crpe32.dll" (ByVal printJob As Integer) As
Integer

PENextPrint 16-bit
Window function PENextPrintWindowMagnification (
printJob: integer
Magnification ):Bool;
(Delphi Syntax)
32-bit
function PENextPrintWindowMagnification (
printJob: Word
): Bool stdcall;

PENextPrint EXTERN CLOGICAL PENextPrintWindowMagnification

(CWORD) CRPE.DLL
Window
Magnification
(dBASE for
Windows Syntax)

PEOpenEngine

Prepares the Report Engine for requests. This function is a necessary

part of any custom-print link. It is also required for any print-only
link in which you want the report to print to a window that is to
remain visible after the report is printed. It is not necessary to use this
function with a print-only link where you are directing the report to
a printer.

536 Crystal Reports Developer’s Reference

 BOOL CRPE_API PEOpenEngine ();

Return Value TRUE (1) if Action is satisfactory, FALSE (0) if the call fails.

Remarks This function must be called before any other Report Engine
function. If an error occurs in the PEOpenEngine function call,
PEGetErrorCode can be passed a print job value of zero to obtain
error information.

PEOpenEngine (Other Declares)

PEOpenEngine 16-bit
(VB Syntax) Declare Function PEOpenEngine Lib "crpe.dll" ()
As Integer

32-bit
Declare Function PEOpenEngine Lib "crpe32.dll"
() As Integer

PEOpenEngine 16-bit
(Delphi Syntax) function PEOpenEngine: Bool;

32-bit
function PEOpenEngine: Bool stdcall;

PEOpenEngine EXTERN CLOGICAL PEOpenEngine () CRPE.DLL

(dBASE for
Windows Syntax)

PEOpenPrintJob

Prepares to print a report and returns a number which identifies the

particular print job. The number returned is called a print job handle,
and must be used in all subsequent calls related to the new print job
(where a print job handle is required). This function is used as a
mandatory part of a custom-print link to generate the return of a

Chapter 6, Crystal Report Engine Reference 537

 print job handle. The handle is then used as the printJob parameter
in each additional custom-print link function call (where a printJob
parameter is required).
short PEOpenPrintJob (
char *reportFilePath
//pointer to filename and path
);

Parameters reportFilePath
Specifies the file name and path of the report you want to open. You
must enclose this parameter in quotes.

Return Value Returns the job number if no error occurs; returns 0 if the report file
does not exist or if an error occurs.

Remarks ● This function must be called before most other Report Engine
functions are used.
● Only one print job can be configured at a time.
● PEClosePrintJob must be called later to close the job.
● Report Path\Filename must be enclosed in quotes, for example:
PEOpenPrintJob
("C:\CRW\REPORT1.RPT");
NOTE: In C or C++ the slashes in the string (\) must each be entered
as a double slash (\\).
This function opens the print job with the printer selected in the
report (via the Print|Select Printer menu command) or the default
printer (if no replacement printer has been selected in the report).

PEOpenPrintJob (Other Declares)

PEOpenPrintJob 16-bit
(VB Syntax) Declare Function PEOpenPrintJob Lib "crpe.dll"
(ByVal RptName As String) As Integer

538 Crystal Reports Developer’s Reference

 32-bit
Declare Function PEOpenPrintJob Lib
"crpe32.dll" (ByVal RptName As String) As
Integer

PEOpenPrintJob 16-bit
(Delphi Syntax) function PEOpenPrintJob (
reportFilePath: PChar
):integer;

32-bit
function PEOpenPrintJob (
reportFilePath: PChar
): smallint stdcall;

PEOpenPrintJob EXTERN CWORD PEOpenPrintJob (CSTRING) CRPE.DLL

(dBASE for
Windows Syntax)

PEOpenSubreport

This topic is only supported by the Professional Edition of Crystal

Reports.
The PEOpenSubreport function opens the named subreport and
returns a number which identifies the subreport. The number
returned is called a print job handle, and must be used in all
subsequent calls related to the subreport (where a print job handle is
required).
short CRPE_API PEOpenSubreport (
short parentJob,//handle to primary report
char FAR *subreportName
//pointer to subreport name
);

Parameters parentJob
Specifies the handle of the primary report (the report that contains
the subreport). This is the handle returned from PEOpenPrintJob.
subreportName

Chapter 6, Crystal Report Engine Reference 539

 Specifies a pointer to the name of the subreport you want to open.
This is retrieved using PEGetSubreportInfo.

Return Value Returns the job number of the subreport if no error occurs; returns 0
if the subreport does not exist or if an error occurs.

Remarks ● This function must be called before any other Report Engine
functions related to the subreport are used.
● PECloseSubreport must be called later to close the job.

PEOpenSubreport (Other Declares)

PEOpenSubreport 16-bit
(VB Syntax) Declare Function PEOpenSubreport Lib "crpe.dll"
(ByVal parentJob As Integer, ByVal
subreportName As String) As Integer

32-bit
Declare Function PEOpenSubreport Lib
"crpe32.dll" (ByVal parentJob As Integer, ByVal
subreportName As String) As Integer

PEOpenSubreport 16-bit
(Delphi Syntax) function PEOpenSubreport (
parentJob: integer;
subreportName: PChar
): Integer;

32-bit
function PEOpenSubreport (
parentJob: Word;
subreportName: PChar
): Word stdcall;

Related Topics
Working with subreports 36

540 Crystal Reports Developer’s Reference

PEOutputToPrinter

The PEOutputToPrinter function prepares to direct printed output to

a printer.
● If a printer has been specified via the PESelectPrinter function,
output will be sent to that printer.
● If there is no PESelectPrinter selection but there is a printer
specified in the report via the Print|Select Printer menu
command, output will be sent to that printer.
● If there is no PESelectPrinter selection, and there is no printer
specified in the report, output will be to the Windows default
printer.
● PEOpenPrintJob opens the print job with the printer specified in
the report (if there is one) or with the Windows default printer (if
no printer is specified in the report).
NOTE: The sequence of calls that follows may help to explain printer
output concepts as well as potential problems. Assume that a printer
is specified in the report via the Print|Select Printer menu command.

PEOpenPrintJob
// Opens the job with printer
// specified in report, or,
// if none is specified, the
// Windows default printer.
// The printer the job opens
// with is Printer #1.

PEOutputToWindow
// Directs the output to the
// print window.

PEStartPrintJob
// Report is printed in the
// print window based on
// Printer #1.

PEOutputToPrinter
// Directs output to the
// printer.

Chapter 6, Crystal Report Engine Reference 541

 PESelectPrinter
// Specifies 2nd printer,
// Printer #2. This overrides
// Printer #1.

PEStartPrintJob
// Report is printed on
// Printer #2. Window output
// and printer output are
// based on two different
// printers and may cause
// confusion.

PEClosePrintJob
If one printer is set for landscape output, for example, and the other
for portrait output, the sequence of calls above will print an entirely
different report in the print window than what actually appears on
paper.
Make certain to sequence your function calls to get the output
desired.
BOOL CRPE_API PEOutputToPrinter (
short printJob,//handle to print job
short nCopies
//number of copies to be printed
);

Parameters printJob
Specifies the handle of the print job you want to send to a printer.
nCopies
Specifies the number of report copies you want printed.

Return Value TRUE (1) if the output can be sent to the printer successfully, FALSE
(0) if the output can not be sent to the printer.

Remarks This function supersedes PEOutputToDefaultPrinter which was

available in earlier versions of the Report Engine.

542 Crystal Reports Developer’s Reference

PEOutputToPrinter (Other Declares)

PEOutputTo 16-bit
Printer Declare Function PEOutputToPrinter Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) NCopies As Integer) As Integer

32-bit
Declare Function PEOutputToPrinter Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
nCopies As Integer) As Integer

PEOutputTo 16-bit
Printer function PEOutputToPrinter (
printJob: integer;
(Delphi Syntax) nCopies: integer
):Bool;

32-bit
function PEOutputToPrinter (
printJob: Word;
nCopies: integer
): Bool stdcall;

PEOutputTo EXTERN CLOGICAL PEOutputToPrinter (CWORD,

CWORD) CRPE.DLL
Printer (dBASE for
Windows Syntax)

PEOutputToWindow

Prepares to direct printed output to a print window. This function is

used as part of a custom-print link to whenever you want the report
printed to the print window instead of to the printer.
BOOL CRPE_API PEOutputToWindow (
short printJob,//handle to print job
char FAR *title,//pointer to title string
short left,

Chapter 6, Crystal Report Engine Reference 543

 //x coordinate, top left of print window
short top,
//y coordinate, top left of print window
short width,//width of print window
short height,//height of print window
long style, //window style setting
HWND parentWindow
//handle to parent window (if any)
);

Parameters printJob
Specifies the handle of the print job you want to print in the print
window.
title
Specifies a pointer to the null-terminated string that contains the title
you want to appear in the print window title bar.
left
Specifies the x coordinate of the upper left corner of the print
window, in twips.*, **
top
Specifies the y coordinate of the upper left corner of the print
window, in twips..*, **
width
Specifies the width of the print window, in twips..*
height
Specifies the height of the print window, in twips..*
*A twip is 1/1440th of an inch or 1/20th of a point. To specify a width
of 5", for example, you would pass a value of 7200.
**For a top-level print window, the top left corner is relative to the
origin of the screen. For an MDI child print window, the top left
corner is relative to the origin of the frame window’s client area. For
a child print window, the top left corner is relative to the origin of the
parent window’s client area.
style
Specifies the style of the window being created. Style settings can be
combined using the bitwise "OR" operator.

544 Crystal Reports Developer’s Reference

 You can specify any of the following window styles:

Decimal
Value Style Setting Action

536870912 WS_MINIMIZE Make a window of

minimum size.
268435456 WS_VISIBLE Make a window that is
visible when it first
appears (for overlapping
and Pop-up windows).
134217728 WS_DISABLED Make a window that is
disabled when it first
appears.
67108864 WS_CLIPSIBLINGS Clip child windows with
respect to one another.
33554432 WS_CLIPCHILDREN Exclude the area
occupied by child
windows when drawing
inside the parent
window.
16777216 WS_MAXIMIZE Make a window of
maximum size.
12582912 WS_CAPTION Make a window that
includes a title bar.
8388608 WS_BORDER Make a window that
includes a border.
4194304 WS_DLGFRAME Make a window that has
a double border but no
title.
2097152 WS_VSCROLL Make a window that
includes a vertical scroll
bar.
1048576 WS_HSCROLL Make a window that
includes a horizontal
scroll bar.
524288 WS_SYSMENU Include the system
menu box.
262144 WS_THICKFRAME Include the thick frame
that can be used to size
the window.
131072 WS_MINIMIZEBOX Include the minimize
box.

Chapter 6, Crystal Report Engine Reference 545

 65536 WS_MAXIMIZEBOX Include the maximize
box.
-32768 CW_USEDFAULT Assign the child
window the default
horizontal and vertical
position, and the default
height and width.
parentWindow
Specifies the handle to the parentWindow if the print window is a
child of that window.

Return Value TRUE (1) if the output can be sent to the window successfully,
FALSE (0) if the output can not be sent to the window.

Remarks ● If parentWindow is null, the print window is a top-level window

(i.e., not a child of any other window). For a top-level print
window, the top left corner is relative to the origin of the screen.
left and top can be CW_USDEFAULT to put the window at a
default location. width and height can also be CW_USEDEFAULT
to give the window a default size.
● If parentWindow is the handle of an MDI frame window, the print
window is an MDI child window. For an MDI child print
window, the top left corner is relative to the origin of the frame
window's client area. left and top can be CW_USEDEFAULT to
put the window at a default location. width and height can also be
CW_USEDEFAULT to give the window a default size.
NOTE: Visual Basic developers can cut and paste a declaration for
CW_USEDEFAULT into their application.
● For VB 4(32-bit), cut the declaration from
c:\vb\winapi\win32api.txt
● For VB 4 (16-bit), cut the declaration from
c:\vb\winapi\win31api.txt
● For VB 3, cut the declaration from c:\vb\winapi\win30api.txt
● If parentWindow is the handle of some other window, the print
window is a child of that window. For a child print window, the
top left corner is relative to the origin of the parent window's
client area.
If the print window is a top-level window or an MDI child window
and style is 0, a style of:

546 Crystal Reports Developer’s Reference

 (WS_VISIBLE | WS_THICKFRAME | WS_SYSMENU |
WS_MAXIMIZEBOX | WS_MINIMIZEBOX)
is used instead.
● 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 a maximize and minimize box.
● The print window is created when PEStartPrintJob is called.

PEOutputToWindow (Other Declares)

PEOutputTo 16-bit
Window Declare Function PEOutputToWindow Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) Title As String, ByVal Left As Integer, ByVal
Top As Integer, ByVal Width As Integer, ByVal
Height As Integer, ByVal Style As Long, ByVal
PWindow As Integer) As Integer

32-bit
Declare Function PEOutputToWindow Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
Title As String, ByVal Left As Long, ByVal Top
As Long, ByVal Width As Long, ByVal Height As
Long, ByVal style As Long, ByVal PWindow As
Long) As Integer

PEOutputTo 16-bit
Window function PEOutputToWindow (
printJob: integer;
(Delphi Syntax) title: PChar;
left: integer;
top: integer;
width: integer;
height: integer;
style: longint;
parentWindow: HWnd
):Bool;

Chapter 6, Crystal Report Engine Reference 547

 32-bit
function PEOutputToWindow (
printJob: Word;
title: PChar;
left: longint;
top: longint;
width: longint;
height: longint;
style: longint;
parentWindow: HWnd
): Bool stdcall;

PEOutputTo EXTERN CLOGICAL PEOutputToWindow (CWORD,

CSTRING, CWORD, CWORD, CWORD, CWORD, CLONG,
Window (dBASE CHANDLE) CRPE.DLL
for Windows
Syntax)

PEPrintControlsShowing

This topic is only supported by the Professional Edition of Crystal

Reports.
Checks if the print controls are displayed in the print window. Use
this function to fetch the visible print controls and pass back using
PEShowPrintControls.
BOOL CRPE_API PEPrintControlsShowing (
short printJob,//handle to print job
BOOL FAR *controlsShowing
//"show controls?" setting pointer
);

Parameters printJob
Specifies the handle for the print job for which you want to check if
the print controls will be displayed when the job is sent to a print
window.
controlsShowing
Returns a pointer to TRUE (1) if the print controls will be shown,
FALSE (0) if they will be hidden.

548 Crystal Reports Developer’s Reference

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

PEPrintControlsShowing (Other Declares)

PEPrintControls 16-bit
Showing Declare Function PEPrintControlsShowing Lib
"crpe.dll" (ByVal printJob As Integer,
(VB Syntax) ControlsShowing As Integer) As Integer

32-bit
Declare Function PEPrintControlsShowing Lib
"crpe32.dll" (ByVal printJob As Integer,
ControlsShowing As Integer) As Integer

PEPrintControls 16-bit
Showing function PEPrintControlsShowing (
printJob: integer;
(Delphi Syntax) var controlsShowing: Bool
):Bool;

32-bit
function PEPrintControlsShowing (
printJob: Word;
var controlsShowing: Bool
): Bool stdcall;

PEPrintReport

Prints the specified report to either the printer or to a print window.

This function establishes a print-only link where changes are made
during runtime by other PE calls are ignored. Use any time you
simply want to print a report from an application without giving the
user the ability to customize the report.
short CRPE_API PEPrintReport (
char FAR *reportFilePath,
//pointer to path string
BOOL toDefaultPrinter,
//send to default printer setting
BOOL toWindow,

Chapter 6, Crystal Report Engine Reference 549

 //send to window setting
char FAR *title,
//pointer to title string
int left,
//x coordinate of window top left corner
int top,
//y coordinate of window top left corner
int width, //width of window
int height, //height of window
DWORD style,//window style
HWND parentWindow//parent window handle
);

Parameters reportFilePath
Specifies a pointer to the null-terminated string that contains the
name and path of the report you want to print.
toDefaultPrinter
Specifies whether or not the report is to be sent to the default printer.
toWindow
Specifies whether or not the report is to be displayed in the print
window.
title
Specifies a pointer to the null-terminated string that contains the title
you want to appear on the title bar if you are printing the report to a
window.
left
Specifies the x coordinate of the upper left hand corner of the print
window, in twips. A twip is 1/1440th of an inch or 1/20th of a point.
To specify a width of 5", for example, you would pass a value of 7200.
top
Specifies the y coordinate of the upper left hand corner of the print
window, in twips. A twip is 1/1440th of an inch or 1/20th of a point.
To specify a width of 5", for example, you would pass a value of 7200.
width
Specifies the width of the print window, in pixels.
height
Specifies the height of the print window, in pixels.

550 Crystal Reports Developer’s Reference

 style
Specifies the style of the window being created. Style settings can be
combined using the bitwise "OR" operator. Select your style from the
list that appears with the PEOutputToWindow function.
parentWindow
Specifies the handle to the Parent Window if the print window is a
child of that window.

Return Value 0 if the call is successful; returns an error code if an error occurs.

PEPrintReport (Other Declares)

PEPrintReport 16-bit
(VB Syntax) Declare Function PEPrintReport Lib "crpe.dll"
(ByVal RptName As String, ByVal Printer As
Integer, ByVal Window As Integer, ByVal Title As
String, ByVal Left As Integer, ByVal Top As
Integer, ByVal Width As Integer, ByVal Height As
Integer, ByVal Style As Long, ByVal
ParentWindow As Integer) As Integer

32-bit
Declare Function PEPrintReport Lib "crpe32.dll"
(ByVal RptName As String, ByVal Printer As
Integer, ByVal Window As Integer, ByVal Title As
String, ByVal Left As Integer, ByVal Top As
Integer, ByVal Width As Integer, ByVal Height As
Integer, ByVal style As Long, ByVal
ParentWindow As Long) As Integer

PEPrintReport 16-bit
(Delphi Syntax) function PEPrintReport (
reportFilePath: PChar;
toDefaultPrinter: Bool;
toWindow: Bool;
title: Pchar;
left: integer;
top: integer;
width; integer;

Chapter 6, Crystal Report Engine Reference 551

 height: integer;
style: longint;
parentWindow: HWnd
):integer;

32-bit
function PEPrintReport (
reportFilePath: PChar;
toDefaultPrinter: Bool;
toWindow: Bool;
title: PChar;
left: integer;
top: integer;
width: integer;
height: integer;
style: longint;
parentWindow: HWnd
): smallint stdcall;

PEPrintReport EXTERN CWORD PEPrintReport (CSTRING, CLOGICAL,

CLOGICAL, CSTRING, CWORD, CWORD, CWORD, CWORD,
(dBASE for CLONG, CHANDLE) CRPE.DLL
Windows Syntax)
PEPrintWindow

Prints the report displayed in the print window. This function can be
used in a custom-print link to enable the user to preview the report
in the print window, and then, if everything looks satisfactory, to
print the report to the printer (in response to a user event).
BOOL CRPE_API PEPrintWindow (
short printJob,//handle to print job
BOOL waitUntilDone
//return when printing starts? (T/F)
);

Parameter printJob
Specifies the handle to the print job you want to print to a window.
waitUntilDone
Indicates whether or not the function is to return as soon as printing
starts. Use one of the following values:

552 Crystal Reports Developer’s Reference

 Value Meaning
TRUE The function returns when printing
is finished. In version 1.1 and
higher of CRPE, "waitUntilDone"
must be True.
FALSE The function returns as soon as
printing starts.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

PEPrintWindow (Other Declares)

PEPrintWindow 16-bit
(VB Syntax) Declare Function PEPrintWindow Lib "crpe.dll"
(ByVal printJob As Integer, ByVal WaitNoWait As
Integer) As Integer

32-bit
Declare Function PEPrintWindow Lib "crpe32.dll"
(ByVal printJob As Integer, ByVal WaitNoWait As
Integer) As Integer

PEPrintWindow 16-bit
(Delphi Syntax) function PEPrintWindow (
printJob: integer;
waitUntilDone: Bool
):Bool;

32-bit
function PEPrintWindow (
printJob: Word;
waitUntilDone: Bool
): Bool stdcall;

PEPrintWindow EXTERN CLOGICAL PEPrintWindow (CWORD, CLOGICAL)

CRPE.DLL
(dBASE for
Windows Syntax)

Chapter 6, Crystal Report Engine Reference 553

PESelectPrinter

Specifies a printer other than the default printer as a print

destination. You can use this function to enable the user to select a
printer other than the default printer at print time. One way of doing
this is to have your application call the common printer selection
dialog box.
BOOL CRPE_API PESelectPrinter (
short printJob,//handle to print job
char FAR *driverName,
//pointer to driver name string
char FAR *printerName,
//pointer to printer name string
char FAR *portName,
//pointer to port name string
DEVMODE FAR *mode//structure pointer
);

Parameters printJob
Specifies the handle to the print job for which you want to select a
printer.
driverName*
Specifies a pointer to a null-terminated string that contains the name
of the printer driver for the selected printer.
printerName*
Specifies a pointer to a null-terminated string that contains the
printer name for the selected printer.
portName*
Specifies a pointer to a null-terminated string that contains the port
name for the port to which the selected printer is attached.
mode*
Specifies the pointer to the DEVMODE structure.
*The PRINTDLG structure, returned by the Windows API PrintDlg
function, contains handles to DEVMODE and DEVNAMES
structures. This information can be used to obtain driverName,
printerName, portName, and mode values for PESelectPrinter.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

554 Crystal Reports Developer’s Reference

Remarks ● Your code must parse the return from the dialog box selection
and insert the returned Printer Driver Name, Printer Name, and
Port Name as parameters in the call.
● After selecting the printer with this call, you can direct the output
to that printer (using the PEOutputToPrinter call) or to the print
window (using the PEOutputToWindow call).
● This call will override a printer selection that you built into the
report at design time via the Crystal Reports Select Printer menu
command.
● If you follow this call with the PEOutputToWindow call, the
report appears in the print window formatted for the selected
printer.
● To revert to the default printer, pass zeros (0) for each parameter.
● The driver name and printer name must exist on your machine.
● You can specify a different printer port than that assigned to the
selected printer on your machine.
● For Mode, use 0 for the default mode or create a DEVMODE
structure to customize (if your development tool supports such a
structure.) For additional information on DEVMODE structures,
see the documentation that comes with the Microsoft Windows
Software Development Kit (SDK).

PESelectPrinter (Other Declares)

PESelectPrinter 16-bit
(VB Syntax) Declare Function PESelectPrinter Lib "crpe.dll"
(ByVal printJob As Integer, ByVal PrinterDriver
As String, ByVal PrinterName As String, ByVal
PortName As String, ByVal DevMode As Any) As
Integer

32-bit
Declare Function PESelectPrinter Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
PrinterDriver As String, ByVal PrinterName As
String, ByVal PortName As String, ByVal DevMode
As Any) As Integer

Chapter 6, Crystal Report Engine Reference 555

PESelectPrinter 16-bit
(Delphi Syntax) function PESelectPrinter (
printJob: integer;
driverName: PChar;
printerName: PChar;
portName: PChar;
mode: PDevMode
):Bool;

32-bit
function PESelectPrinter(
printJob: Word;
driverName: PChar;
printerName: PChar;
portName: PChar;
mode: PDeviceMode
): Bool stdcall;

PESetDialogParentWindow

This topic is only supported by the Professional Edition of Crystal

Reports.
The PESetDialogParentWindow function specifies the handle for
the parent window for a Print window that is an MDI child.
BOOL CRPE_API PESetDialogParentWindow (
short printJob,//handle to print job
HWND parentWindow//handle to parent window
);

Parameters printJob
Specifies the handle of the print job for which you want to specify a
parent window.
parentWindow
Specifies the handle of the parent window.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

556 Crystal Reports Developer’s Reference

PESetDialogParentWindow (Other Declares)

PESetDialogParent 16-bit
Window Declare Function PESetDialogParentWindow Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) parentWindow As Long) As Integer

32-bit
Declare Function PESetDialogParentWindow Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
parentWindow As Long) As Integer

PESetDialogParent 16-bit
Window function PESetDialogParentWindow (
printJob: integer;
(Delphi Syntax) parentWindow: HWnd
): Bool;

32-bit
function PESetDialogParentWindow (
printJob: Word;
parentWindow: HWnd
): Bool stdcall;

PESetFont

This topic is only supported by the Professional Edition of Crystal

Reports
The PESetFont function sets the font for field and/or text characters
in the report section(s) specified. Use any time you need to change a
default font at runtime in response to user input or to specify a built-
in printer font.
BOOL CRPE_API PESetFont (
short printJob,//handle to print job
short sectionCode,
//code identifying section
short scopeCode,
//code identifying scope of changes
char FAR *faceName,

Chapter 6, Crystal Report Engine Reference 557

 //pointer to face name of font
short fontFamily,
//font family of selected font
short fontPitch,//pitch of selected font
short charSet,
//default or Windows.h character set
short pointSize,
//point size of selected font
short isItalic,//is font italic? setting
short isUnderlined,
//is font underlined? setting
short isStruckOut,
//is font struck out? setting
short weight //weight of selected font
);

Parameters printJob
Specifies the handle of the print job for which you want to select a
font.
sectionCode
Specifies the code for the report section(s) for which you want to
select a font. See Working with Section Codes, Page 428.
scopeCode
Specifies whether the font selected is to apply to fields, to text, or to
both. To specify both fields and text, use the OR operator. Select your
code from the following:

Value Meaning
PE_FIELDS Sets the default font for all field
values in the report section
specified.
PE_TEXT Sets the default font for all text
(that has not been entered as a field
value) in the report section
specified.

For example: PE_FIELDS OR PE_TEXT.

faceName
Specifies the actual face name of the font you want to use. The face
name you pass can typically come from a Font dialog box, be hard
coded in the application or be chosen by the application from the

558 Crystal Reports Developer’s Reference

 fonts supported on the printer. Example: "Times New Roman". Pass
0 for no change.
fontFamily
Specifies the font family for the font you want to use. Use one of the
following constant values:

Value Meaning
FF_DONTCARE No change.
FF_ROMAN Variable pitch font with serifs.
FF_SWISS Fixed pitch font without serifs.
FF_MODERN Fixed-pitch font, with or without
serifs.
FF_SCRIPT Handwriting-like font.
FF_DECORATIVE Fancy display font.

fontPitch
Specifies the font pitch you wish to use. Use a constant value for the
font pitch as defined in Windows.h.
Use DEFAULT_PITCH if you wish to retain the current default.

Value Meaning
DEFAULT_PITCH 0X00
FIXED_PITCH 0X01
VARIABLE_PITCH 0X02

charSet
Specifies the character set you wish to use. Use a constant value for
the character set as defined in Windows.h. Use
DEFAULT_CHARSET if you wish to retain the current default.

Value Meaning
ANSI_CHARSET 0
DEFAULT_CHARSET 1
SYMBOL_CHARSET 2
SHIFTJIS_CHARSET 128
HANGEUL_CHARSET 129
CHINESEBIG5_CHARSET 136
OEM_CHARSET 255

Chapter 6, Crystal Report Engine Reference 559

 pointSize
Specifies the desired point size for the selected font. Enter 0 for no
change.
isItalic
Specifies whether the font selected should be italicized. Use 1 for
True (the font is italic), 0 for False (the font is not italic), or
PE_UNCHANGED (if there is no change from the current default).
isUnderlined
Specifies whether the font selected should be underlined. Use 1 for
True (the font is underlined), 0 for False (the font is not underlined),
or PE_UNCHANGED (if there is no change from the current
default).
isStruckOut
Specifies whether the font selected should be struck out. Use 1 for
True (the font is struck out), 0 for False (the font is not struck out), or
PE_UNCHANGED (if there is no change from the default).
weight
Specifies the weight of the font. Use a constant value from the weight
values defined in Windows.h. Use 0 if you wish to retain the current
default.

Value Meaning
FW_DONTCARE 0
FW_THIN 100
FW_EXTRALIGHT 200
FW_LIGHT 300
FW_NORMAL 400
FW_MEDIUM 500
FW_SEMIBOLD 600
FW_BOLD 700
FW_EXTRABOLD 800
FW_HEAVY 900
FW_ULTRALIGHT FW_EXTRALIGHT
FW_REGULAR FW_NORMAL
FW_DEMIBOLD FW_SEMIBOLD
FW_ULTRABOLD FW_EXTRABOLD
FW_BLACK FW_HEAVY

560 Crystal Reports Developer’s Reference

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks This command includes a number of parameters:

● For the fontFamily, fontPitch, charSet, and weight parameters,
use constant values from the font family, pitch, character set, and
width defined in Windows.h. Use 0 for each parameter that is not
to be changed from the current default.
● For the faceName parameter, enter the actual name of the font.
Enter 0 for no change.
● faceName, fontFamily, fontPitch, and charSet should all be
specified whenever one of these parameters is specified. Use
fontFamily = FF_DONTCARE (0), fontPitch = DEFAULT_PITCH
(0), or charSet = DEFAULT_CHARSET (1) to leave the default
values unchanged.

Related Menu File|Options|Fonts Tab

Commands

PESetFont (Other Declares)

PESetFont 16-bit
(VB Syntax) Declare Function PESetFont Lib "crpe.dll"
(ByVal printJob As Integer, ByVal sectionCode
As Integer, ByVal ScopeCode As Integer, ByVal
FaceName As String, ByVal FontFamily As
Integer, ByVal FontPitch As Integer, ByVal
CharSet As Integer, ByVal PointSize As Integer,
ByVal isItalic As Integer, ByVal isUnderlined
As Integer, ByVal isStruckOut As Integer, ByVal
Weight As Integer) As Integer

32-bit
Declare Function PESetFont Lib "crpe32.dll"
(ByVal printJob As Integer, ByVal sectionCode
As Integer, ByVal ScopeCode As Integer, ByVal
FaceName As String, ByVal FontFamily As
Integer, ByVal FontPitch As Integer, ByVal
CharSet As Integer, ByVal PointSize As Integer,

Chapter 6, Crystal Report Engine Reference 561

 ByVal isItalic As Integer, ByVal isUnderlined
As Integer, ByVal isStruckOut As Integer, ByVal
Weight As Integer) As Integer

PESetFont 16-bit
(Delphi Syntax) function PESetFont (
printJob: integer;
sectionCode: integer;
scopeCode: integer;
faceName: PChar;
fontFamily: integer;
fontPitch: integer;
charSet: integer;
pointSize: integer;
isItalic: integer;
isUnderlined: integer;
isStruckOut: integer;
weight: integer
):Bool;

32-bit
function PESetFont(
printJob: Word;
sectionCode: integer;
scopeCode: integer;
faceName: PChar;
fontFamily: integer;
fontPitch: integer;
charSet: integer;
pointSize: integer;
isItalic: integer;
isUnderlined: integer;
isStruckOut: integer;
weight: integer
): Bool stdcall;

PESetFont EXTERN CLOGICAL PESetFont (CWORD, CWORD, CWORD,

CSTRING, CWORD, CWORD, CWORD, CWORD, CWORD,
(dBASE for CWORD, CWORD, CWORD) CRPE.DLL
Windows Syntax)

562 Crystal Reports Developer’s Reference

PESetFormula

Changes the specified formula to the formula string you supply as a

parameter. This function will only change the text of a formula which
already exists in the report; you can not use it to add a formula. This
function can be used by itself to replace the formula string for a
known formula.
This function can also be used as one of a series of functions
(PEGetFormula, PEGetHandleString, PESetFormula). The series can
be used in a custom-print link to identify and then change an existing
formula at print time in response to a user selection.
When you give the user the ability to change the formula at print
time, your link must include code to replace formulaString with a
user-generated value.
BOOL CRPE_API PESetFormula (
short printJob,//handle to print job
char *formulaName,
//pointer to formula name string
char FAR *formulaString
//pointer to new formula string
);

Parameters printJob
Specifies the handle of the print job for which you want to set a new
formula string.
formulaName
Specifies a pointer to the null-terminated string that contains the
name of the formula for which you want to set a new formula string.
formulaString
Specifies a pointer to the null-terminated string that you want to
replace the existing formula string.

Return Value TRUE (1) if the call is successful, FALSE (0) if the named formula
does not exist or if there is an error in the new formula.
NOTE: If the formula does not exist, the program generates a
PE_ERR_BADFORMULANAME code. If there is an error in the
formula, the program generates a PE_ERR_BADFORMULATEXT
code. Refer to Report Engine Error Codes for further information.

Chapter 6, Crystal Report Engine Reference 563

PESetFormula (Other Declares)

PESetFormula 16-bit
(VB Syntax) Declare Function PESetFormula Lib "crpe.dll"
(ByVal printJob As Integer, ByVal FormulaName
As String, ByVal FormulaString As String) As
Integer

32-bit
Declare Function PESetFormula Lib "crpe32.dll"
(ByVal printJob As Integer, ByVal FormulaName
As String, ByVal FormulaString As String) As
Integer

PESetFormula 16-bit
(Delphi Syntax) function PESetFormula (
printJob: integer;
formulaName: PChar;
formulaString: PChar
): Bool;

32-bit
function PESetFormula (
printJob: Word;
formulaName: PChar;
formulaString: PChar
): Bool stdcall;

PESetFormula EXTERN CLOGICAL PESetFormula (CWORD, CSTRING,

CSTRING) CRPE.DLL
(dBASE for
Windows Syntax)

PESetGraphData

Changes the data on which the specified graph in the specified

section is based. Use this function to change what data is used from
your report to create a specified graph. This information includes the
groups used to create the rows and columns of the graph and the
summary field used to set the values of the risers in the graph.

564 Crystal Reports Developer’s Reference

 BOOL CRPE_API PESetGraphData (
short printJob,//handle to print job
short sectionCode,
//code identifying section
short graphN, //number of graph in section
struct PEGraphDataInfo FAR *graphDataInfo
//structure pointer
);

Parameters printJob
Specifies the handle of the print job for the report containing the
graph that you are changing.
sectionCode
Specifies the code for the report section in which the graph appears.
See Working with Section Codes, Page 428.
graphN
Specifies which graph within the section you are changing. This
value is 0 indexed. Within a section, graphs are numbered from top
to bottom, first, then from left to right if they have the same top.
graphDataInfo
Specifies the pointer to the PEGraphDataInfo structure.

Return Value TRUE (1) if the call is successful, FALSE(0) if an error occurs.

PESetGraphData (Other Declares)

PESetGraphData 16-bit
(VB Syntax) Declare Function PESetGraphData Lib "crpe.dll"
(ByVal printJob As Integer, ByVal sectionCode
As Integer, ByVal GraphN As Integer,
GraphDataInfo As PEGraphDataInfo) As Integer

32-bit
Declare Function PESetGraphData Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
sectionCode As Integer, ByVal GraphN As
Integer, GraphDataInfo As PEGraphDataInfo) As
Integer

Chapter 6, Crystal Report Engine Reference 565

PESetGraphData 16-bit
(Delphi Syntax) function PESetGraphData (
printJob: integer;
sectionCode: integer;
graphN: integer;
var graphDataInfo: PEGraphDataInfo
):Bool;

32-bit
function PESetGraphData (
printJob: Word;
sectionCode: integer;
graphN: integer;
graphDataInfo: PEGraphDataInfo
): Bool stdcall;

PESetGraphOptions

Changes the display options set for the specified graph in the
specified section. Use this function to change any of several graph
options. These options include the minimum and maximum values
that can appear on the graph, whether grid lines appear, whether
risers are labeled, whether bar graphs have horizontal or vertical
bars, and whether a legend appears on the graph.
BOOL CRPE_API PESetGraphOptions (
short printJob,//handle to print job
short sectionCode,
//code identifying section
short graphN, //number of graph in section
struct PEGraphOptions FAR *graphOptions
//structure pointer
);

Parameters printJob
Specifies the handle of the print job for the report containing the
graph you are changing.
sectionCode
Specifies the code for the report section in which the graph appears.
See Working with Section Codes, Page 428.

566 Crystal Reports Developer’s Reference

 graphN
Specifies which graph within the section you want to change. This
value is 0 indexed. Within a section, graphs are numbered from top
to bottom, first, then from left to right if they have the same top.
graphOptions
Specifies the pointer to the PEGraphOptions structure.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

PESetGraphOptions (Other Declares)

PESetGraph 16-bit
Options Declare Function PESetGraphOptions Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) sectionCode As Integer, ByVal GraphN As
Integer, GraphOptions As PEGraphOptions) As
Integer

32-bit
Declare Function PESetGraphOptions Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
sectionCode As Integer, ByVal GraphN As
Integer, GraphOptions As PEGraphOptions) As
Integer

PESetGraph 16-bit
Options function PESetGraphOptions (
printJob: integer;
(Delphi Syntax) sectionCode: integer;
graphN: integer;
var graphOptions: PEGraphOptions
): Bool;

32-bit
function PESetGraphOptions (
printJob: Word;
sectionCode: integer;
graphN: integer;
graphOptions: PEGraphOptions
): Bool stdcall;

Chapter 6, Crystal Report Engine Reference 567

PESetGraphText

Changes the identifying text that appears on the specified graph in

the specified section. This function allows you to set or change the
text that appears with a graph. A graph can have a title, subtitle,
footnote, title for groups, title for series, title for the X axis, title for
the Y axis, and title for the Z axis (in 3D graphs).
BOOL CRPE_API PESetGraphText (
short printJob,//handle to print job
short sectionCode,
//code identifying section
short graphN, //number of graph in section
struct PEGraphTextInfo FAR *graphTextInfo
//structure pointer
);

Parameters printJob
Specifies the handle of the print job for the report containing the
graph that you are changing the text for.
sectionCode
Specifies the code for the report section in which the graph appears.
See Working with Section Codes, Page 428.
graphN
Specifies which graph within the section you are changing the text
for. This value is 0 indexed. Within a section, graphs are numbered
from top to bottom, first, then from left to right if they have the same
top.
graphTextInfo
Specifies the pointer to the PEGraphTextInfo structure.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

568 Crystal Reports Developer’s Reference

PESetGraphText (Other Declares)

PESetGraphText 16-bit
(VB Syntax) Declare Function PESetGraphText Lib "crpe.dll"
(ByVal printJob As Integer, ByVal sectionCode
As Integer, ByVal GraphN As Integer,
GraphTextInfo As PEGraphTextInfo) As Integer

32-bit
Declare Function PESetGraphText Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
sectionCode As Integer, ByVal GraphN As
Integer, GraphTextInfo As PEGraphTextInfo) As
Integer

PESetGraphText 16-bit
(Delphi Syntax) function PESetGraphText (
printJob: integer;
sectionCode: integer;
graphN: integer;
var graphTextInfo: PEGraphTextInfo
): Bool;

32-bit
function PESetGraphText (
printJob: Word;
sectionCode: integer;
graphN: integer;
graphTextInfo: PEGraphTextInfo
): Bool stdcall;

PESetGraphType

Changes the type of graph displayed for the specified graph in the
specified section based on one of the available graph/chart types.
Use this function to change the type of graph that is displayed in the
report. There are many types of graphs and charts possible with
Crystal Reports. This function allows you to change which type of
graph or chart is being displayed.

Chapter 6, Crystal Report Engine Reference 569

 BOOL CRPE_API PESetGraphType (
short printJob,//handle to print job
short sectionCode,
//code identifying section
short graphN, //number of graph in section
short FAR *graphType
//pointer to graph type setting
);

Parameters printJob
Specifies the handle of the print job for the report containing the
graph for which you want to change the type.
sectionCode
Specifies the code for the report section in which the graph appears.
See Working with Section Codes, Page 428.
graphN
Specifies which graph within the section for which you want to
change the type. This value is 0 indexed. Within a section, graphs are
numbered from top to bottom, first, then from left to right if they
have the same top.
graphType
Specifies a pointer to the type of graph you want to be displayed. For a list
of possible graph types, refer to the chart under PEGetGraphType.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

PESetGraphType (Other Declares)

PESetGraphType 16-bit
(VB Syntax) Declare Function PESetGraphType Lib "crpe.dll"
(ByVal printJob As Integer, ByVal sectionCode
As Integer, ByVal GraphN As Integer, GraphType
As Integer) As Integer

570 Crystal Reports Developer’s Reference

 32-bit
Declare Function PESetGraphType Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
sectionCode As Integer, ByVal GraphN As
Integer, GraphType As Integer) As Integer

PESetGraphType 16-bit
(Delphi Syntax) function PESetGraphType (
printJob: integer;
sectionCode: integer;
graphN: integer;
var graphType: integer
): Bool;

32-bit
function PESetGraphType (
printJob: Word;
sectionCode: integer;
graphN: integer;
graphType: integer
): Bool stdcall;

PESetGroupCondition

This topic is only supported by the Professional Edition of Crystal

Reports.
Changes the group condition for a group section. Use this function
whenever you want to change the grouping at print time, for
example, to print one report grouped in several different ways.
BOOL CRPE_API PESetGroupCondition (
short printJob,//handle to print job
short sectionCode,
//code identifying section
char FAR *conditionField,
//pointer to "trigger" field
short condition,
//condition setting (date/Boolean)
short sortDirection//sort direction setting
);

Chapter 6, Crystal Report Engine Reference 571

Parameters printJob
Specifies the handle of the print job for which you want to change the
group condition for a group section.
sectionCode
Specifies the code for the report section for which you want to set the
group condition. See Working with Section Codes, Page 428.
conditionField
Specifies the field is a condition that triggers a summary whenever
its value changes.
condition
Specifies the condition ("weekly", "monthly", "change to Yes",
"change to No", etc.) that needs to be met for Date and Boolean fields.
For all field types except Date and Boolean, use
PE_GC_ANYCHANGE as the condition parameter.
For Date fields, select the condition parameter from the following
table:

Value Meaning
PE_GC_DAILY Triggers a grouping every time
the date changes.
PE_GC_WEEKLY Triggers a grouping every time
the date changes from one week
to the next. (A week runs from
Sunday through Saturday.)
PE_GC_BIWEEKLY Triggers a grouping every time
the date changes from one two-
week period to the next. (Weeks
run from Sunday through
Saturday.)
PE_GC_SEMIMONTHLY Triggers a grouping every time
the date changes from one half-
month period to the next.
PE_GC_MONTHLY Triggers a grouping every time
the date changes from one month
to the next.
PE_GC_QUARTERLY Triggers a grouping every time
the date changes from one
calendar quarter to the next.

572 Crystal Reports Developer’s Reference

 PE_GC_SEMIANNUALLY Triggers a grouping every time
the date changes from one half-
year period to the next.
PE_GC_ANNUALLY Triggers a grouping every time
the date changes from one year
to the next.
For Boolean fields, select the condition parameter form the
following table:
Value Meaning
PE_GC_TOYES Triggers a grouping every time the
sort and group by field value
changes from No to Yes.
PE_GC_TONO Triggers a grouping every time the
sort and group by field value
changes from Yes to No.
PE_GC_EVERYYES Triggers a grouping every time the
sort and group by field value is
Yes.
PE_GC_EVERYNO Triggers a grouping every time the
sort and group by field value is No.
PE_GC_NEXTISYES Triggers a grouping every time the
next value in the sort and group by
field is Yes.
PE_GC_NEXTISNO Triggers a grouping every time the
next value in the sort and group by
field is No.

sortDirection
Specifies one of the following sort directions:

Value Meaning
PE_SF_ASCENDING Sorts data in ascending order (A to
Z, 1 to 9).
PE_SF_DESCENDING Sorts data in descending order (Z to
A, 9 to 1).

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks No default values are allowed. You must specify all three parameters
when you use this function.

Chapter 6, Crystal Report Engine Reference 573

 If you have a formula that references a summary field and you
change the condition on the summary field without fixing the
formula, you will get an error.

Related Menu Edit|Group Section

Commands

PESetGroupCondition (Other Declares)

PESetGroup 16-bit
Condition Declare Function PESetGroupCondition Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) sectionCode As Integer, ByVal ConditionField As
String, ByVal Condition As Integer, ByVal
SortDirection As Integer) As Integer

32-bit
Declare Function PESetGroupCondition Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
sectionCode As Integer, ByVal ConditionField As
String, ByVal Condition As Integer, ByVal
SortDirection As Integer) As Integer

PESetGroup 16-bit
Condition function PESetGroupCondition (
printJob: integer;
(Delphi Syntax) sectionCode: integer;
conditionField: PChar;
condition: integer;
sortDirection: integer
): Bool;

32-bit
function PESetGroupCondition (
printJob: Word;
sectionCode: integer;
conditionField: PChar;
condition: integer;
sortDirection: integer
): Bool stdcall;

574 Crystal Reports Developer’s Reference

PESetGroup EXTERN CLOGICAL PESetGroupCondition (CWORD,
CWORD, CSTRING, CWORD, CWORD) CRPE.DLL
Condition (dBASE
for Windows
Syntax)

PESetGroupSelectionFormula

Changes the group selection formula to the formula string you

supply as a parameter. This function can be used by itself to replace
a known group selection formula.
This function can also be used as one of a series of functions
(PEGetGroupSelectionFormula, PEGetHandleString,
PESetGroupSelectionFormula). The series can be used in a custom-
print link to identify and then change an existing group selection
formula at print time in response to a user selection.
When you give the user the ability to change the group selection
formula at print time, your link must include code to replace
formulaString with a user-generated value.
BOOL CRPE_API PESetGroupSelectionFormula (
short printJob,//handle to print job
char FAR *formulaString
//pointer to new formula string
);

Parameters printJob
Specifies the handle of the print job from which you want to set a
new group selection formula.
formulaString
Specifies a pointer to the null-terminated string you want to assign
to the group selection formula.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails or if there
is an error in the new formula.
NOTE: If there is an error in the formula, the program generates a
PE_ERR_BADFORMULATEXT code. For information on this code,
see Report Engine Error Codes.
NOTE: A group sort field is a summary value or a summarized field
that determines the sort order of groups.

Chapter 6, Crystal Report Engine Reference 575

PESetGroupSelectionFormula (Other Declares)

PESetGroup 16-bit
SelectionFormula Declare Function PESetGroupSelectionFormula
Lib "crpe.dll" (ByVal printJob As Integer,
(VB Syntax) ByVal FormulaString As String) As Integer

32-bit
Declare Function PESetGroupSelectionFormula
Lib "crpe32.dll" (ByVal printJob As Integer,
ByVal FormulaString As String) As Integer

PESetGroup 16-bit
SelectionFormula function PESetGroupSelectionFormula (
printJob: integer;
(Delphi Syntax) formulaString: PChar
): Bool;

32-bit
function PESetGroupSelectionFormula (
printJob: Word;
formulaString: PChar
): Bool stdcall;

PESetGroup EXTERN CLOGICAL PESetGroupSelectionFormula

(CWORD, CSTRING) CRPE.DLL
SelectionFormula
(dBASE for
Windows Syntax)

PESetMargins

This topic is only supported by the Professional Edition of Crystal

Reports. For further information, see Upgrade Information.
The PESetMargins function sets the page margins for the specified
report to the values you supply as parameters. Use this function any
time you want to set the printer margins at runtime in response to
user specifications.

576 Crystal Reports Developer’s Reference

 BOOL CRPE_API PESetMargins (
short printJob,//handle to print job
short left, //left margin setting
short right,//right margin setting
short top, //top margin setting
short bottom//bottom margin setting
);

Parameters printJob
Specifies the handle of the print job for which you want to set new
margins.
left
Specifies the left margin.*
right
Specifies the right margin.*
top
Specifies the top margin.*
bottom
Specifies the bottom margin.*

Value Meaning
PM_SM_DEFAULT You can use PM_SM_DEFAULT for
any of the margin parameters. For
each margin you specify in this way,
the program will use the appropriate
default margin for the currently
selected printer.

*Left, right, top, and bottom values are all in twips. A twip is 1/1440
of an inch; there are 20 twips in a point. To set .5" margins, for
example, you would enter the value 720.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Chapter 6, Crystal Report Engine Reference 577

PESetMargins (Other Declares)

PESetMargins 16-bit
(VB Syntax) Declare Function PESetMargins Lib "crpe.dll"
(ByVal printJob As Integer, ByVal LeftMargin As
Integer, ByVal RightMargin As Integer, ByVal
TopMargin As Integer, ByVal BottomMargin As
Integer) As Integer

32-bit
Declare Function PESetMargins Lib "crpe32.dll"
(ByVal printJob As Integer, ByVal LeftMargin As
Integer, ByVal RightMargin As Integer, ByVal
TopMargin As Integer, ByVal BottomMargin As
Integer) As Integer

PESetMargins 16-bit
(Delphi Syntax) function PESetMargins (
printJob: integer;
left: Word;
right: Word;
top: Word;
bottom: Word
):Bool;

32-bit
function PESetMargins (
printJob: Word;
left: integer;
right: integer;
top: integer;
bottom: integer
): Bool stdcall;

PESetMargins EXTERN CLOGICAL PESetMargins (CWORD, CWORD,

CWORD, CWORD, CWORD) CRPE.DLL
(dBASE for
Windows Syntax)

578 Crystal Reports Developer’s Reference

PESetMinimumSectionHeight

This topic is only supported by the Professional Edition of Crystal

Reports. For further information, see Upgrade Information.
Sets the minimum height for specified report sections to the value
supplied as a parameter. Use this command whenever you want to
specify a minimum section height for printing onto preprinted forms
or printing on to any other kind of document with a fixed format.
BOOL CRPE_API PESetMinimumSectionHeight (
short printJob,//handle to print job
short sectionCode,
//code identifying section
short minimumHeight
//minimum height setting for section
);

Parameters printJob
Specifies the handle to the print job for which you want to set the
minimum section height.
sectionCode
Specifies the code for the report section(s) for which you want to set
minimum section height. See Working with Section Codes, Page 428.
minimumHeight
Specifies the minimum section height (in twips) for the section(s)
selected. A twip is 1/1440 inch - there are 20 twips to a point.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

PESetMinimumSectionHeight (Other Declares)

PESetMinimum 16-bit
SectionHeight Declare Function PESetMinimumSectionHeight Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) sectionCode As Integer, ByVal MinimumHeight As
Integer) As Integer

Chapter 6, Crystal Report Engine Reference 579

 32-bit
Declare Function PESetMinimumSectionHeight Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
sectionCode As Integer, ByVal MinimumHeight As
Integer) As Integer

PESetMinimum 16-bit
SectionHeight function PESetMinimumSectionHeight (
printJob: integer;
(Delphi Syntax) sectionCode: integer;
minimumHeight: integer
):Bool;

32-bit
function PESetMinimumSectionHeight (
printJob: Word;
sectionCode: integer;
minimumHeight: integer
): Bool stdcall;

PESetMinimum EXTERN CLOGICAL PESetMinimumSectionHeight

(CWORD, CWORD, CWORD) CRPE.DLL
SectionHeight
(dBASE for
Windows Syntax)

PESetNDetailCopies

This topic is only supported by the Professional Edition of Crystal

Reports. For further information, see Upgrade Information.
Prints multiple copies of the Details section of the report. You can use
this function to print multiple copies of labels for a customer,
multiple copies of a purchase order, or multiple copies of anything
set up in the Details section of your report.
BOOL CRPE_API PESetNDetailCopies (
short printJob,//handle to print job
short nDetailCopies
//number of copies to print
);

580 Crystal Reports Developer’s Reference

Parameters printJob
Specifies the handle of the print job for which you want set the
number of copies to print.
nDetailCopies
Specifies the number of report copies you want to print.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

PESetNDetailCopies (Other Declares)

PESetNDetail 16-bit
Copies (VB Syntax) Declare Function PESetNDetailCopies Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
nDetailCopies As Integer) As Integer

32-bit
Declare Function PESetNDetailCopies Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
nDetailCopies As Integer) As Integer

PESetNDetail 16-bit
Copies function PESetNDetailCopies (
printJob: integer;
(Delphi Syntax) nCopies: integer
):Bool;

32-bit
function PESetNDetailCopies(
printJob: Word;
nCopies: integer;
): Bool stdcall;

PESetNDetail EXTERN CLOGICAL PESetNDetailCopies (CWORD,

CWORD) CRPE.DLL
Copies (dBASE for
Windows Syntax)

Chapter 6, Crystal Report Engine Reference 581

PESetNthGroupSortField

Sets one of the group sort fields in the specified report. This function
can be used by itself to set a sort field/direction when there is not one
already set, or to modify an existing sort field/ direction when the
sort field number, name, and direction are known.
The function can also be used as one of a series of functions:
PEGetNGroupSortFields (called once), PEGetNthGroupSortField/
PEGetHandleString (called as many times as needed to identify the
correct group sort field), and PESetNthGroupSortField (called once,
when the correct group sort field is identified). The series can be used
in a custom-print link to identify and then change an existing group
sort field and/or sort order at print time in response to a user
selection.
When you give the user the ability to specify group sort field(s) and/
or direction at print time, your link must include code to replace
name, and/or direction with user-generated values.
BOOL CRPE_API PESetNthGroupSortField (
short printJob,//handle to print job
short sortFieldN,//number of sort field
char FAR *name,
//pointer to group sort field name
short direction//sort direction setting
);

Parameters printJob
Specifies the handle to the print job for which you want to set a group
sort field.
sortFieldN
Specifies the number of the sort field you want to set. The first sort
field is field 0. If the report has N sort fields, the function can be
called with sortFieldN between 0 and N-1. If the report has N sort
fields, you can call the function with sortFieldN = N to add a new
sort field to the end of the list of existing sort fields. If N=0, the
function will add the first sort field.
name
Specifies a pointer to the null-terminated string that contains the
name of the group sort field.

582 Crystal Reports Developer’s Reference

 direction
Specifies one of the following sort directions:

Value Meaning
PE_SF_ASCENDING Sorts in Ascending order (A to Z, 1
to 9).
PE_SF_DESCENDING Sorts in Descending order (Z to A,
9 to 1).

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Related Menu Report|Group Sort Order

Commands

PESetNthGroupSortField (Other Declares)

PESetNthGroup 16-bit
SortField Declare Function PESetNthGroupSortField Lib
"CRPE.DLL" (ByVal printJob As Integer, ByVal
(VB Syntax) sortFieldN As Integer, ByVal name As String,
ByVal direction As Integer) As Integer

32-bit
Declare Function PESetNthGroupSortField Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
SortFieldN As Integer, ByVal SortGroupName As
String, ByVal Direction As Integer) As Integer

PESetNthGroup 16-bit
SortField function PESetNthGroupSortField (
printJob: integer;
(Delphi Syntax) sortFieldN: integer;
name: PChar;
direction: integer
):Bool;

Chapter 6, Crystal Report Engine Reference 583

 32-bit
function PESetNthGroupSortField (
printJob: Word;
sortFieldN: integer;
name: PChar;
direction: integer
): Bool stdcall;

PESetNthGroup EXTERN CLOGICAL PESetNthGroupSortField (CWORD,

CWORD, CSTRING, CWORD) CRPE.DLL
SortField (dBASE
for Windows
Syntax)

PESetNthParam

This topic is only supported by the Professional Edition of Crystal

Reports. For further information, see Upgrade Information.
Sets the value of a parameter in a stored procedure. Use this function
when working with stored procedures in SQL database tables to set
the value of a parameter in a stored procedure.
BOOL CRPE_API PESetNthParam (
short printJob,//handle to print job
short paramN, //parameter number
LPCSTR szParamValue//parameter value
);

Parameters printJob
Specifies the handle of the print job that contains the stored
procedure which you want to set the value of a parameter.
paramN
0 indexed parameter number, indicates which parameter you want
to set the value for.
szParamValue
String representation of the value you are assigning to the parameter.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

584 Crystal Reports Developer’s Reference

Remarks ● All parameter values must be passed as string values. If you wish
to pass a numeric value, pass the value in quotes like this: "100".
The Report Engine will treat this as the value 100.
● Use PEGetNParams to obtain the number of parameters in a
stored procedure.
● Use PEGetNthParam to obtain a particular parameter required by
a stored procedure.

Related Menu Database|Stored Procedure Parameters

Commands

PESetNthParam (Other Declares)

PESetNthParam 16-bit
(VB Syntax) Declare Function PESetNthParam Lib "crpe.dll"
(ByVal printJob As Integer, ByVal ParamN As
Integer, ByVal ParamValue As String) As Integer

32-bit
Declare Function PESetNthParam Lib "crpe32.dll"
(ByVal printJob As Integer, ByVal paramN As
Integer, ByVal ParamValue As String) As Integer

PESetNthParam 16-bit
(Delphi Syntax) function PESetNthParam(
printJob: integer;
paramN: integer;
szParamValue: PChar
): Bool;

32-bit
function PESetNthParam(
printJob: Word;
paramN: integer;
szParamValue: PChar
): Bool stdcall;

Chapter 6, Crystal Report Engine Reference 585

PESetNthParam EXTERN CLOGICAL PESetNthPARAM (CWORD, CWORD,
CSTRING) CRPE.DLL
(dBASE for
Windows Syntax)

PESetNthParameterField

The PESetNthParameterField function sets a value for the specified

parameter field.
BOOL CRPE_API PESetNthParameterField (
short printJob,//handle to print job
short parameterN,
//number of parameter field
struct PEParameterFieldInfo FAR
*parameterInfo
//structure pointer
);

Parameters printJob
Specifies the handle of the print job for which you want to set a
parameter field value.
parameterN
Specifies the number of the parameter field in the report.
parameterInfo
Specifies a pointer to the structure used to pass the parameter field
value information.

Return value TRUE (1) if the call is successful, FALSE (0) if the call fails.

PESetNthParameterField (Other Declares)

PESetNth 16-bit
ParameterField Declare Function PESetNthParameterField Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) varN As Integer, varInfo As
PEParameterFieldInfo) As Integer

586 Crystal Reports Developer’s Reference

 32-bit
Declare Function PESetNthParameterField Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
varN As Integer, varInfo As
PEParameterFieldInfo) As Integer

PESetNth 16-bit
ParameterField function PESetNthParameterField (
printJob: integer;
(Delphi Syntax) varN: integer;
var varInfo: PEParameterFieldInfo
): Bool;

32-bit
function PESetNthParameterField (
printJob: Word;
varN: Smallint;
var varInfo: PEParameterFieldInfo
): Bool stdcall;

PESetNthSortField

Sets one of the sort fields in the specified report. This function can be
used by itself to set a sort field/direction when there is not one
already set, or to change a sort field/direction when the number and
name of the sort field are known.
The function can also be used as one of a series of functions: PEGet-
NSortFields (called once), PEGetNthSortField/PEGetHandleString
(called together as many times as needed to identify the correct sort
field), and PESetNthSortField (called once when the correct sort field
is identified). The series can be used in a custom-print link to identify
and then change an existing sort field and/or sort order at print time
in response to a user selection.
When you give the user the ability to specify sort field(s) and/or
direction at print time, your link must include code to replace name,
and/or direction with user-generated values.
BOOL CRPE_API PESetNthSortField (
short printJob,//handle to print job
short sortFieldN,//number of sort field
char FAR *name,//pointer to sort field name
short direction//sort direction setting
);

Chapter 6, Crystal Report Engine Reference 587

Parameters printJob
Specifies the handle of the print job for which you want to set sort
field information.
sortFieldN
Specifies the number of the sort fields you want to set. The first sort
field is field 0. If the report has N sort fields, the function can be
called with sortFieldN between 0 and N-1 to replace an existing sort
field. If the report has N sort fields, you can call the function with
"sortFieldN" = N to add a new sort field to the end of the list of
existing sort fields. If N=0, the function will add the first sort field.
name
Specifies a pointer to the null-terminated string that contains the
name of the sort field.
direction
Specifies the sort direction. Use one of the following values:

Value Meaning
PE_SF_ASCENDING Sorts in Ascending order (A to Z, 1 to
9).
PE_SF_DESCENDING Sorts in Descending order (Z to A, 9
to 1).

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Related Menu Report|Record Sort Order

Commands

PESetNthSortField (Other Declares)

PESetNthSortField 16-bit
(VB Syntax) Declare Function PESetNthSortField Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
SortNumber As Integer, ByVal SortFieldName As
String, ByVal Direction As Integer) As Integer

588 Crystal Reports Developer’s Reference

 32-bit
Declare Function PESetNthSortField Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
SortNumber As Integer, ByVal SortFieldName As
String, ByVal Direction As Integer) As Integer

PESetNthSortField 16-bit
(Delphi Syntax) function PESetNthSortField (
printJob: integer;
sortFieldN: integer;
name: PChar;
direction: integer
):Bool;

32-bit
function PESetNthSortField (
printJob: Word;
sortFieldN: integer;
name: PChar;
direction: integer
): Bool stdcall;

PESetNthSortField EXTERN CLOGICAL PESetNthSortField (CWORD,

CWORD, CSTRING, CWORD) CRPE.DLL
(dBASE for
Windows Syntax)

PESetNthTableLocation

The PESetNthTableLocation function sets the location for a selected

table in the specified print job. This function is typically combined
with PEGetNthTableLocation to identify the location of a table and
then to change it.
BOOL CRPE_API PESetNthTableLocation (
short printJob,//handle to print job
short tableN,//table number
struct PETableLocation FAR *location
//structure pointer
);

Chapter 6, Crystal Report Engine Reference 589

Parameters printJob
Specifies the handle of the print job for which you want to set a
table’s location.
tableN
Specifies the number of the table for which you want to set a new
location.
location
Specifies the pointer to the PETableLocation structure.

Return Value TRUE (1) if the call is successful; FALSE (0) if the call fails.

Related Menu Database|Set Location

Commands

PESetNthTableLocation (Other Declares)

PESetNthTable 16-bit
Location Declare Function PESetNthTableLocation Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) TableN As Integer, Location As PETableLocation)
As Integer

32-bit
Declare Function PESetNthTableLocation Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
TableN As Integer, Location As PETableLocation)
As Integer

PESetNthTable 16-bit
Location function PESetNthTableLocation (
printJob: integer;
(Delphi Syntax) tableN: integer;
var location: PETableLocation
):Bool;

590 Crystal Reports Developer’s Reference

 32-bit
function PESetNthTableLocation(
printJob: Word;
tableN: integer;
var location: PETableLocation
): Bool stdcall;

PESetNthTableLogOnInfo

The PESetNthTableLogOnInfo function sets the log on information

for the specified print job to the values in the PELogOnInfo structure.
BOOL CRPE_API PESetNthTableLogOnInfo (
short printJob,//handle to print job
short tableN,//table number
struct PELogOnInfo FAR *logOnInfo,
//structure pointer
BOOL propagateAcrossTables
//"apply to other tables" setting
);

Parameters printJob
Specifies the handle of the print job for which you want to set table
log on information.
tableN
Specifies the number of the table for which you want to set log on
information. The first table is table 0. The last table is N-1.
logOnInfo
Specifies the pointer to the PELogOnInfo structure.
propagateAcrossTables
Indicates whether or not the program should apply the new log on
information to any other tables in the report that had the same
original server and database names as the specified table. You may
use either of the following values:

Value Meaning
TRUE Program will apply log on
information to all other tables that
have the same original server and
database names.

Chapter 6, Crystal Report Engine Reference 591

 Value Meaning
FALSE Program will update only the
selected table.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks ● See PELogOnServer comments for the logOnInfo struct

definition.
● The program logs on when printing the report, but you must first
set the correct log on information using
PESetNthTableLogOnInfo.
● You must supply at least the password with this function with
empty strings for the other parameters. Additionally, you can
change the server, database, and/or user name by entering the
appropriate values.
● Logging off is performed automatically when the print job is
closed.
● PESetNthTableLogOnInfo allows you to override any of the log
on parameters.
● When you create a report off a single database (for example, one
MDB file with multiple tables), set the propagateAcrossTables
parameter to TRUE. This insures that the changes are made to all
tables in the MDB file (thus avoiding the necessity to code the
changes for each table individually).

PESetNthTableLogOnInfo (Other Declares)

PESetNthTable 16-bit
LogOnInfo Declare Function PESetNthTableLogOnInfo Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) TableN As Integer, LogOnInfo As PELogOnInfo,
ByVal Propagate As Integer) As Integer

32-bit
Declare Function PESetNthTableLogOnInfo Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
TableN As Integer, LogOnInfo As PELogOnInfo,
ByVal Propagate As Integer) As Integer

592 Crystal Reports Developer’s Reference

PESetNthTable 16-bit
LogOnInfo function PESetNthTableLogOnInfo (
printJob: integer;
(Delphi Syntax) tableN: integer;
var logOnInfo: PELogOnInfo;
propagateAcrossTables: Bool
):Bool;

32-bit
function PESetNthTableLogOnInfo (
printJob: Word;
tableN: integer;
var logOnInfo: PELogOnInfo;
propagateAcrossTables: Bool
): Bool stdcall;

PESetNthTableSessionInfo

Sets the specified session information when opening a Microsoft

Access table. Many MS Access database tables require that a session
be opened before the table can be used. Use
PESetNthTableSessionInfo to open the session.
BOOL CRPE_API PESetNthTableSessionInfo (
short printJob,//handle to print job
short tableN,//table number
struct PESessionInfo FAR *sessionInfo,
//structure pointer
BOOL propagateAcrossTables
//"apply to other tables" setting
);

Parameters printJob
Specifies the handle of the print job for which you want to change the
MS Access session information.
tableN
0 based table number specifying which table the session is being
opened for.
sessionInfo
Refer to the PESessionInfo structure for further information.

Chapter 6, Crystal Report Engine Reference 593

 propagateAcrossTables
TRUE or FALSE value indicating whether the session information
should be used for opening all tables being used in the report.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks This function is only applicable for secured MS Access databases

which require a session to be opened before the database is accessed.

PESetNthTableSessionInfo (Other Declares)

PESetNthTable 16-bit
SessionInfo Declare Function PESetNthTableSessionInfo Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) TableN As Integer, SessionInfo As
PESessionInfo, ByVal PropagateAcrossTables As
Integer) As Integer

32-bit
Declare Function PESetNthTableSessionInfo Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
TableN As Integer, SessionInfo As
PESessionInfo, ByVal PropagateAcrossTables As
Integer) As Integer

PESetNthTable 16-bit
SessionInfo function PESetNthTableSessionInfo (
printJob: integer;
(Delphi Syntax) tableN: integer;
var sessionInfo: PESessionInfo;
propagateAcrossTables: Bool
):Bool;

32-bit
function PESetNthTableSessionInfo (
printJob: Word;
tableN: integer;
var sessionInfo: PESessionInfo;
propagateAcrossTables: Bool
): Bool stdcall;

594 Crystal Reports Developer’s Reference

PESetPrintDate

Sets a print date that may be different than the system calendar date.
Use this function any time you want to show a print date (or use a
print date in formulas) other than the actual date of printing.
BOOL CRPE_API PESetPrintDate (
short printJob,//handle to print job
short year, //print date year component
short month,//print date month component
short day //print date day component
);

Parameters printJob
Specifies the handle of the print job for which you want to set the
print date.
year
Specifies the year component of the print date. Enter a 4 digit year
value (1994, 1993, etc.).
month
Specifies the month component of the print date. Months are
numbered from 1 to 12, where January = 1 and December = 12. To use
July as the print month, for example, you would enter the value 7.
day
Specifies the day component of the print date. Enter the actual day of
the month you want to use (7, 18, 28, etc.).

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks You change the print date, typically, when you want to run the
report today yet have it appear to have been run on a different date.
An example would be, if you were out of town on the last day of the
previous month and you later want to run a report for that month
and make it appear as if it were run on the last day of the month.

Related Menu Report|Set Print Date

Commands

Chapter 6, Crystal Report Engine Reference 595

PESetPrintDate (Other Declares)

PESetPrintDate 16-bit
(VB Syntax) Declare Function PESetPrintDate Lib "crpe.dll"
(ByVal printJob As Integer, ByVal Date_Year As
Integer, ByVal Date_Month As Integer, ByVal
Date_Day As Integer) As Integer

32-bit
Declare Function PESetPrintDate Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
Date_Year As Integer, ByVal Date_Month As
Integer, ByVal Date_Day As Integer) As Integer

PESetPrintDate 16-bit
(Delphi Syntax) function PESetPrintDate (
printJob: integer;
year: integer;
month: integer;
day: integer
):Bool;

32-bit
function PESetPrintDate (
printJob: Word;
year: integer;
month: integer;
day: integer
): Bool stdcall;

PESetPrintDate EXTERN CLOGICAL PESetPrintDate (CWORD, CWORD,

CWORD, CWORD) CRPE.DLL
(dBASE for
Windows Syntax)

596 Crystal Reports Developer’s Reference

PESetPrintOptions

This topic is only supported by the Professional Edition of Crystal

Reports. For further information, see Upgrade Information.
Sets the print options for the report to the values supplied in the
PEPrintOptions structure. Use this function any time you want to set
the starting page number, the ending page number, the number of
report copies, and/or collation instructions for a print job at runtime
in response to user specifications.
BOOL CRPE_API PESetPrintOptions (
short printJob,//handle to print job
struct PEPrintOptions FAR *options
//structure pointer
);

Parameters printJob
Specifies the handle of the print job for which you want to set
printing options.
options
Specifies the pointer to the PEPrintOptions structure. NOTE: If this
parameter is set to 0 (null), the function prompts the user for these
options. Using this, you can get the behavior of the print-to-printer
button in the print window by calling PESetPrintOptions with a null
pointer and then calling PEPrintWindow.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Related Menu File|Print|Printer

Commands

PESetPrintOptions (Other Declares)

PESetPrintOptions 16-bit
(VB Syntax) Declare Function PESetPrintOptions Lib
"crpe.dll" (ByVal printJob As Integer, Options
As PEPrintOptions) As Integer

Chapter 6, Crystal Report Engine Reference 597

 32-bit
Declare Function PESetPrintOptions Lib
"crpe32.dll" (ByVal printJob As Integer,
Options As PEPrintOptions) As Integer

PESetPrintOptions 16-bit
(Delphi Syntax) function PESetPrintOptions (
printJob: integer;
var options: PEPrintOptions
): Bool;

32-bit
function PESetPrintOptions (
printJob: Word;
var options: PEPrintOptions
): Bool stdcall;

PESetReportTitle

This topic is only supported by the Professional Edition of Crystal

Reports. For further information, see Upgrade Information.
Changes the print window title to the title string you supply as a
parameter. This function can be used by itself to replace a known
report title.
It can also be used as one of a series of functions (PEGetReportTitle,
PEGetHandleString, PESetReportTitle). This series can be used in a
custom-print link to identify and then change an existing report title
at print time in response to a user selection.
BOOL CRPE_API PESetReportTitle (
short printJob,//handle to print job
char FAR *title
//pointer to new title string
);

Parameters printJob
Specifies the handle of the print job for which you want to set the
report title.
title
Specifies a null-terminated string containing the new title you want
to assign to the report.

598 Crystal Reports Developer’s Reference

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks When you give the user the ability to change the report title at print
time, your link must include code to replace texturing with a user-
generated value.

Related Menu Report|Report Title

Commands

PESetReportTitle (Other Declares)

PESetReportTitle 16-bit
(VB Syntax) Declare Function PESetReportTitle Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
Title As String) As Integer

32-bit
Declare Function PESetReportTitle Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
Title As String) As Integer

PESetReportTitle 16-bit
(Delphi Syntax) function PESetReportTitle (
printJob: integer;
title: PChar
):Bool;

32-bit
function PESetReportTitle (
printJob: Word;
title: PChar
): Bool stdcall;

PESetReportTitle EXTERN CLOGICAL PESetReportTitle (CWORD,

CSTRING) CRPE.DLL
(dBASE for
Windows Syntax)

Chapter 6, Crystal Report Engine Reference 599

PESetSectionFormat

This topic is only supported by the Professional Edition of Crystal

Reports. For further information, see Upgrade Information.
Sets the section format settings for selected sections in the specified
report to the values in the PESectionOptions structure. This function
can be used to provide specialized formatting for printing invoices,
form letters, printing to pre-printed forms, etc. It allows you to hide
a section, insert a page break either before or after a section begins,
reset the page number to 1 after a group value prints, prevent page
breaks from spreading data from a single record over two pages, and
to print group values only at the bottom of a page.
BOOL CRPE_API PESetSectionFormat (
short printJob,//handle to print job
short sectionCode,
//code identifying section
struct PESectionOptions FAR *options
//structure pointer
);

Parameters printJob
Specifies the handle of the print job for which you want to set section
formatting options.
sectionCode
Specifies the code for the report section(s) for which you want to set
formatting options. See Working with Section Codes, Page 428.
options
Specifies the pointer to the PESectionOptions structure. You use this
structure to set your section options.
*There can be multiple group header and group footer sections in a
given report. When you have multiple group sections, the first group
header section is designated 3000, the second is designated 3001, etc.
Likewise, the first group footer section is designated 5000, the second
is designated 5001, etc.
**There can be multiple Detail sections in a given report. When you
have multiple Detail sections, the first Detail section is designated
4000, the second is designated 4001, etc.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

600 Crystal Reports Developer’s Reference

Related Menu Format|Section
Commands

PESetSectionFormat (Other Declares)

PESetSection 16-bit
Format Declare Function PESetSectionFormat Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) sectionCode As Integer, Options As
PESectionOptions) As Integer

32-bit
Declare Function PESetSectionFormat Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
sectionCode As Integer, Options As
PESectionOptions) As Integer

PESetSection 16-bit
Format function PESetSectionFormat (
printJob: integer;
(Delphi Syntax) sectionCode: integer;
var options: PESectionOptions
): Bool;

32-bit
function PESetSectionFormat (
printJob: Word;
sectionCode: integer;
var options: PESectionOptions
): Bool stdcall;

PESetSectionFormatFormula

The PESetSectionFormatFormula function changes the specified

section format formula to the formula string you supply as a
parameter. This function will only change the text of a formula which
already exists in the report; you can not use it to add a formula.

Chapter 6, Crystal Report Engine Reference 601

 When you give the user the ability to change the formula at print
time, your link must include code to replace formulaString with a
user-generated value.
BOOL CRPE_API PESetSectionFormatFormula (
short printJob,//handle to print job
short sectionCode,
//code identifying section
short formulaName,
//constant identifying formula
char FAR *formulaString//new formula string
);

Parameters printJob
Specifies the handle of the print job for which you want to set a new
selection formula string.
sectionCode
Specifies the code for the report section(s) for which you want to set
formatting options. See Working with Section Codes, Page 428.
formulaName
Specifies the name of the formula for which you want to supply a
new string. Use one of the following constants:

Constant Value Description

SECTION_VISIBILITY 58 Determines
when the
section is
visible.
NEW_PAGE_BEFORE 60 Determines
when a page
break occurs
before the
section.
KEEP_SECTION_TOGETHER 61 Determines
when to
prevent the
section from
breaking
across pages.

602 Crystal Reports Developer’s Reference

 Constant Value Description
SUPPRESS_BLANK_SECTION 62 Determines
when to
suppress
(hide) the
section if it is
blank.
RESET_PAGE_N_AFTER 63 Determines
when to reset
the page
number after
the section.
PRINT_AT_BOTTOM_OF_PAGE 64 Determines
when to print
the section at
the bottom of
the page.
UNDERLAY_SECTION 65 Determines
when to force
the section to
underlay the
following
sections.
SECTION_BACK_COLOUR 66 Determines
when to
change the
background
color of the
section.
formulaString
Specifies a pointer to the null-terminated string that you want to
assign to the format formula.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails or if there
is an error in the new formula.
NOTE: If the formula does not exist, the program generates a
PE_ERR_BADFORMULANAME code. If there is an error in the
formula, the program generates a PE_ERR_BADFORMULATEXT
code. Refer to Report Engine Error Codes for further information.

Chapter 6, Crystal Report Engine Reference 603

PESetSectionFormatFormula (Other Declares)

PESetSection 16-bit
FormatFormula Declare Function PESetSectionFormatFormula Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) sectionCode As Integer, ByVal formulaName As
Integer, ByVal FormulaString As String) As
Integer

32-bit
Declare Function PESetSectionFormatFormula Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
sectionCode As Integer, ByVal formulaName As
Integer, ByVal FormulaString As String) As
Integer

PESetSelection 16-bit
Formula function PESetSectionFormatFormula (
printJob: integer;
(Delphi Syntax) sectionCode: integer;
formulaName: integer;
formulaString: integer
):Bool;

32-bit
function PESetSectionFormatFormula (
printJob: Word;
sectionCode: integer;
formulaName: integer;
formulaString: integer
):Bool stdcall;

PESetSelectionFormula

Changes the selection formula to the formula string you supply as a

parameter. This function can be used by itself to replace a known
record selection formula.
The function can also be used as one of a series of functions
(PEGetSelectionFormula, PEGetHandleString,

604 Crystal Reports Developer’s Reference

 PESetSelectionFormula). The series can be used in a custom-print
link to identify and then change an existing record selection formula
at print time in response to a user selection.
When you give the user the ability to change the record selection
formula at print time, your link must include code to replace
formulaString with a user-generated value.
BOOL CRPE_API PESetSelectionFormula (
short printJob,//handle to print job
char FAR *formulaString
//pointer to new formula string
);

Parameters printJob
Specifies the handle of the print job for which you want to set a new
selection formula string.
formulaString
Specifies a pointer to the null-terminated string that you want to
assign to the selection formula.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails or if there
is an error in the new formula.
NOTE: If there is an error in the formula, the program generates a
PE_ERR_BADFORMULATEXT code. Refer to Report Engine Error
Codes for further information.

PESetSelectionFormula (Other Declares)

PESetSelection 16-bit
Formula Declare Function PESetSelectionFormula Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) FormulaString As String) As Integer

32-bit
Declare Function PESetSelectionFormula Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
FormulaString As String) As Integer

Chapter 6, Crystal Report Engine Reference 605

PESetSelection 16-bit
Formula function PESetSelectionFormula (
printJob: integer;
(Delphi Syntax) formulaString: PChar
):Bool;

32-bit
function PESetSelectionFormula (
printJob: Word;
formulaString: PChar
): Bool stdcall;

PESetSelection EXTERN CLOGICAL PESetSelectionFormula (CWORD,

CSTRING) CRPE.DLL
Formula (dBASE
for Windows
Syntax)

PESetSQLQuery

This topic is only supported by the Professional Edition of Crystal

Reports. For further information, see Upgrade Information.
The PESetSQLQuery function changes the SQL query to the query
string you supply as a parameter. Use this function to update the
SQL query that will be used to print the report, typically to add
optimizations to the WHERE clause.
BOOL CRPE_API PESetSQLQuery (
short printJob,//handle to print job
char FAR *queryString
//pointer to new query string
);

Parameters printJob
Specifies the handle to the print job for which you want to modify the
SQL query.
queryString
Specifies a pointer to the null-terminated string that you want to use
to replace the existing SQL query.

606 Crystal Reports Developer’s Reference

Return Value TRUE (1) if the call is successful; FALSE (0) if the call fails.

Remarks This function is mostly useful for reports with SQL queries that were
explicitly edited in the Show SQL Query dialog box in Crystal
Reports, i.e., those reports that needed database-specific selection
criteria or joins. Otherwise it is usually best to continue using
function calls such as PESetSelectionFormula and let Crystal Reports
build the SQL query automatically.
PESetSQLQuery has the same restrictions as editing in the Show SQL
Query dialog box. In particular, changes are accepted in the FROM,
WHERE, and ORDER BY clauses but they are ignored in the SELECT
list of fields.
NOTE: This call only applies to reports created against an ODBC
source or on a native SQL database connection.

PESetSQLQuery (Other Declares)

PESetSQLQuery 16-bit
(VB Syntax) Declare Function PESetSQLQuery Lib "crpe.dll"
(ByVal printJob As Integer, ByVal QueryString
As String) As Integer

32-bit
Declare Function PESetSQLQuery Lib "crpe32.dll"
(ByVal printJob As Integer, ByVal QueryString
As String) As Integer
NOTE: If you are going to include an ORDER BY clause, you must
precede it with CHR(13) and CHR(10).

PESetSQLQuery 16-bit
(Delphi Syntax) function PESetSQLQuery (
printJob: integer;
queryString: PChar
):Bool;

Chapter 6, Crystal Report Engine Reference 607

 32-bit
function PESetSQLQuery (
printJob: Word;
queryString: PChar
): Bool stdcall;
NOTE: If you are going to include an ORDER BY clause, you must
precede it with CHR(13) and CHR(10).

PESetSQLQuery EXTERN CLOGICAL PESetSQLQuery (CWORD, CSTRING)

CRPE.DLL
(dBASE for
Windows Syntax)

PEShow Functions

This topic is only supported by the Professional Edition of Crystal

Reports. For further information, see Upgrade Information.
Displays the specified page in the print window. Use these functions
any time you want to display specific pages of a report in the print
window or give the user the ability to move forward and backward
through a report in the print window. PEShowNthPage has some
additional considerations and so it is presented in a separate topic.
BOOL CRPE_API PEShowNextPage (
short printJob//handle to print job
);
BOOL CRPE_API PEShowFirstPage (
short printJob//handle to print job
);
BOOL CRPE_API PEShowPreviousPage (
short printJob//handle to print job
);
BOOL CRPE_API PEShowLastPage (
short printJob//handle to print job
);

Parameters printJob
Specifies the handle for the print job for which you want to indicate
the page to be displayed.

608 Crystal Reports Developer’s Reference

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

PEShow Functions (Other Declares)

PEShow Functions 16-bit

(VB Syntax) Declare Function PEShowNextPage Lib "crpe.dll"
(ByVal printJob As Integer) As Integer
Declare Function PEShowFirstPage Lib "crpe.dll"
(ByVal printJob As Integer) As Integer
Declare Function PEShowPreviousPage Lib
"crpe.dll" (ByVal printJob As Integer) As
Integer
Declare Function PEShowLastPage Lib "crpe.dll"
(ByVal printJob As Integer) As Integer

32-bit
Declare Function PEShowFirstPage Lib
"crpe32.dll" (ByVal printJob As Integer) As
Integer
Declare Function PEShowLastPage Lib
"crpe32.dll" (ByVal printJob As Integer) As
Integer
Declare Function PEShowNextPage Lib
"crpe32.dll" (ByVal printJob As Integer) As
Integer
Declare Function PEShowPreviousPage Lib
"crpe32.dll" (ByVal printJob As Integer) As
Integer

PEShow Functions 16-bit

(Delphi Syntax) function PEShowNextPage (
printJob: integer
):Bool;
function PEShowFirstPage (
printJob: integer
):Bool;
function PEShowPreviousPage (
printJob: integer
):Bool;

Chapter 6, Crystal Report Engine Reference 609

 function PEShowLastPage (
printJob: integer
):Bool;

32-bit
function PEShowFirstPage (
printJob: Word
): Bool stdcall;
function PEShowLastPage (
printJob: Word
): Bool stdcall;
function PEShowNextPage (
printJob: Word
): Bool stdcall;
function PEShowPreviousPage (
printJob: Word
): Bool stdcall;

PEShow Functions EXTERN CLOGICAL PEShowNextPage (CWORD) CRPE.DLL

EXTERN CLOGICAL PEShowFirstPage (CWORD)
(dBASE for CRPE.DLL
Windows Syntax) EXTERN CLOGICAL PEShowPreviousPage (CWORD)
CRPE.DLL
EXTERN CLOGICAL PEShowLastPage (CWORD) CRPE.DLL

PEShowNthPage

This topic is only supported by the Professional Edition of Crystal

Reports. For further information, see Upgrade Information.
The PEShowNthPage function displays the specified report page.
BOOL CRPE_API PEShowNthPage (
short printJob, //handle to print job
short pageN //page you want displayed
);

Parameters printJob
Specifies the handle to the print job from which you want to display
a page.

610 Crystal Reports Developer’s Reference

 pageN
Specifies the report page you want to display.

Return value TRUE (1) if the call is successful, FALSE(0) if an error occurs.

Remarks Using PEGetJobStatus, you will be able to determine how many

pages the given report has. Using this information, you can then
ensure that the pageN parameter above does not exceed the total
number of pages.

PEShowNthPage (Other Declares)

PEShowNthPage 16-bit
(VB Syntax) Declare Function PEShowNthPage Lib "crpe.dll"
(ByVal printJob As Integer, ByVal pageN As
Integer) As Integer

32-bit
Declare Function PEShowNthPage Lib "crpe32.dll"
(ByVal printJob As Integer, ByVal pageN As
Integer) As Integer

PEShowNthPage 16-bit
(Delphi Syntax) function PEShowNthPage (
printJob: integer;
pageN: integer
): Bool;

32-bit
function PEShowNthPage (
printJob: Word;
pageN: Smallint
): Bool stdcall;

Chapter 6, Crystal Report Engine Reference 611

PEShowPrintControls

This topic is only supported by the Professional Edition of Crystal

Reports. For further information, see Upgrade Information.
Displays the print controls (the First, Previous, Next, and Last Page
buttons as well as the buttons for Cancel, Close, Export, and Print to
Printer). Use any time you want to provide control over whether
print controls are displayed or not.
BOOL CRPE_API PEShowPrintControls (
short printJob,//handle to print job
BOOL showPrintControls
//"show print controls" setting
);

Parameters printJob
Specifies the handle to the print job for which you want to display
print controls.
showPrintControls
Indicates whether or not the function is to display print controls. You
may use either of the following values:

Value Meaning
TRUE The function displays the print
controls.
FALSE The function hides the print controls.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks Print controls are displayed by default. It is not necessary to use this
function simply to display controls but only if you want the user to
control whether or not the controls are visible.

612 Crystal Reports Developer’s Reference

PEShowPrintControls (Other Declares)

PEShowPrint 16-bit
Controls Declare Function PEShowPrintControls Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) ShowPrintControls As Integer) As Integer

32-bit
Declare Function PEShowPrintControls Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
ShowPrintControls As Integer) As Integer

PEShowPrint 16-bit
Controls function PEShowPrintControls (
printJob: integer;
(Delphi Syntax) showPrintControls: Bool
):Bool;

32-bit
function PEShowPrintControls(
printJob: Word;
showPrintControls: Bool
): Bool stdcall;

PEShowPrint EXTERN CLOGICAL PEShowPrintControls (CWORD,

CLOGICAL) CRPE.DLL
Controls (dBASE
for Windows
Syntax)

PEStartPrintJob

Starts the printing of a report. This function is used as a mandatory

part of each custom-print link to trigger the printing of a report to the
printer or to the print window.
BOOL CRPE_API PEStartPrintJob (
short printJob, //handle to print job
BOOL waitUntilDone
//"return when printing starts?" setting
);

Chapter 6, Crystal Report Engine Reference 613

Parameters printJob
Specifies the handle to the print job you want to start.
waitUntilDone
Indicates if the function is to return as soon as printing starts. Use one
of the following values:

Value Meaning
TRUE The function returns when printing
is finished. In version 1.1 and higher
of CRPE, "waitUntilDone" must be
true.
FALSE The function returns as soon as
printing starts.

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Remarks A print job can be started only once. Once started, the only function
that can be used is PEClosePrintJob.

PEStartPrintJob (Other Declares)

PEStartPrintJob 16-bit
(VB Syntax) Declare Function PEStartPrintJob Lib "crpe.dll"
(ByVal printJob As Integer, ByVal WaitOrNot As
Integer) As Integer

32-bit
Declare Function PEStartPrintJob Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
WaitOrNot As Integer) As Integer

PEStartPrintJob 16-bit
(Delphi Syntax) function PEStartPrintJob (
printJob: integer;
waitUntilDone: Bool
):Bool;

614 Crystal Reports Developer’s Reference

 32-bit
function PEStartPrintJob (
printJob: Word;
waitUntilDone: Bool
): Bool stdcall;

PEStartPrintJob EXTERN CLOGICAL PEStartPrintJob (CWORD,

CLOGICAL) CRPE.DLL
(dBASE for
Windows Syntax)

PETestNthTableConnectivity

The PETestNthTableConnectivity function tests whether a database

table's settings are valid and ready to be reported on. This function is
typically used if you plan to print at a later time but you want to test
now to make sure everything is in order for logging on.
BOOL CRPE_API PETestNthTableConnectivity (
short printJob,//handle to print job
short tableN//table number
);

Parameters printJob
Specifies the handle of the print job for which you want to test a
table’s connection settings.
tableN
Specifies the number of the table for which you want to test the
connection settings.

Return Value TRUE (1) if the database session, log on, and location info is all
correct, FALSE (0) if something is wrong.

Remarks This function may require a significant amount of time to complete,

since it will first open a user session (if required), then log on to the
database server (if required), and then open the appropriate
database table (to test that it exists). It does not read any data and
closes the table immediately once successful. Logging off is
performed when the print job is closed.

Chapter 6, Crystal Report Engine Reference 615

 ● If it fails in any of these steps, the error code set indicates which
database info needs to be updated using the functions indicated:
 If it is unable to begin a session, it sets
PE_ERR_DATABASESESSION. The application should
update with PESetNthTableSessionInfo.
 If it is unable to log on to a server, it sets
PE_ERR_DATABASELOGON. The application should
update with PESetNthTableLogOnInfo.
 If it is unable to open the table, it sets
PE_ERR_DATABASELOCATION. The application should
update with PESetNthTableLocation.

PETestNthTableConnectivity (Other Declares)

PETestNthTable 16-bit
Connectivity Declare Function PETestNthTableConnectivity
Lib "crpe.dll" (ByVal printJob As Integer,
(VB Syntax) ByVal TableN As Integer) As Integer

32-bit
Declare Function PETestNthTableConnectivity
Lib "crpe32.dll" P (ByVal printJob As Integer,
ByVal TableN As Integer) As Integer

PETestNthTable 16-bit
Connectivity function PETestNthTableConnectivity (
printJob: integer;
(Delphi Syntax) tableN: integer
):Bool;

32-bit
function PETestNthTableConnectivity (
printJob: Word;
tableN: integer
): Bool stdcall;

616 Crystal Reports Developer’s Reference

PETestNthTable EXTERN CLOGICAL PETestNthTableConnectivity
(CWORD, CWORD) CRPE.DLL
Connectivity
(dBASE for
Windows Syntax)

PEZoomPreviewWindow

This topic is only supported by the Professional Edition of Crystal

Reports. For further information, see Upgrade Information.
Changes the magnification of the print window to a specified level.
Use this function when the report has been printed to a print window
and you need to set the magnification of the print window to a
specific level. There are three possible magnifications for the print
window: Full Page, Fit One Side, and Fit Both Sides.
BOOL CRPE_API PEZoomPreviewWindow (
short printJob,//handle to print job
short level //magnification level
);

Parameters printJob
The handle of the print job for which you wish to set the zoom level
of the print window.
level
The zoom level you wish to set the print window at. This value can
be one of the following constants:

Constant Zoom Level

PE_ZOOM_FULL_SIZE Full Page
PE_ZOOM_SIZE_FIT_ONE_SIDE Fit One Side
PE_ZOOM_SIZE_FIT_BOTH_SIDES Fit Both Sides

Return Value TRUE (1) if the call is successful, FALSE (0) if the call fails.

Chapter 6, Crystal Report Engine Reference 617

PEZoomPreviewWindow (Other Declares)

PEZoomPreview 16-bit
Window Declare Function PEZoomPreviewWindow Lib
"crpe.dll" (ByVal printJob As Integer, ByVal
(VB Syntax) ZoomLevel As Integer) As Integer

32-bit
Declare Function PEZoomPreviewWindow Lib
"crpe32.dll" (ByVal printJob As Integer, ByVal
ZoomLevel As Integer) As Integer

PEZoomPreview 16-bit
Window function PEZoomPreviewWindow (
printJob: integer;
(Delphi Syntax) level: integer
):Bool

32-bit
function PEZoomPreviewWindow (
printJob: Word;
level: Smallint
): Bool stdcall;

PEZoomPreview EXTERN CLOGICAL PEZoomPreviewWindow (CWORD,

CWORD)CRPE.DLL
Window (dBASE
for Windows
Syntax)

618 Crystal Reports Developer’s Reference

STRUCTURES
COLORREF

The COLORREF structure is a 32-bit value that is used for specifying

Red, Green or Blue values. Please refer to the Windows Software
Development Kit for complete details on this structure.

DEVMODE

Description The DEVMODE Structure is a Windows API structure that contains

information about a printer driver's initialization and environment
data. An application passes this structure to the DeviceCapabilities
and ExtDeviceMode functions. It is used by the PESelectPrinter and
PEGetSelectedPrinter functions.

16-bit
struct tagDEVMODE
{
char dmDeviceName[CCHDEVICENAME];
UINT dmSpecVersion;
UINT dmDriverVersion;
UINT dmSize;
UINT dmDriverExtra;
DWORD dmFields;
int dmOrientation;
int dmPaperSize;
int dmPaperLength;
int dmPaperWidth;
int dmScale;
int dmCopies;
int dmDefaultSource;
int dmPrintQuality;
int dmColor;
int dmDuplex;
int dmYResolution;
int dmTTOption;
};
NOTE: This version of the DEVMODE structure was obtained from
Windows 95 SDK.

Chapter 6, Crystal Report Engine Reference 619

Members dmDeviceName
Specifies the name of the device the driver supports--for example,
"PCL/HP LaserJet" in the case of the Hewlett-Packard LaserJet. Each
driver has a unique string.
dmSpecVersion
Specifies the version number of the DEVMODE structure. For
Windows version 3.1, this value should be 0x30A
dmDriverVersion
Specifies the printer driver version number assigned by the printer
driver developer.
dmSize
Specifies the size, in bytes, of the DEVMODE structure. (This value
does not include the optional dmDriverData member for device-
specific data, which can follow the structure.) If an application
manipulates only the driver-independent portion of the data, it can
use this member to find out the length of the structure without
having to account for different versions.
dmDriverExtra
Specifies the size, in bytes, of the optional dmDriverData member for
device-specific data, which can follow the structure. If an application
does not use device-specific information, it should set this member
to zero.
dmFields
Specifies a set of flags that indicate which of the remaining members
in the DEVMODE structure have been initialized. It can be any
combination (or it can be none) of the following values:

DM_ORIENTATION 0x0000001L
DM_PAPERSIZE 0x0000002L
DM_PAPERLENGTH 0x0000004L
DM_PAPERWIDTH 0x0000008L
DM_SCALE 0x0000010L
DM_COPIES 0x0000100L
DM_DEFAULTSOURCE 0x0000200L
DM_PRINTQUALITY 0x0000400L
DM_COLOR 0x0000800L
DM_DUPLEX 0x0001000L
DM_YRESOLUTION 0x0002000L
DM_TTOPTION 0x0004000L

620 Crystal Reports Developer’s Reference

 NOTE: A printer driver supports only those members that are
appropriate for the printer technology.
dmOrientation
Specifies the orientation of the paper. It can be either
DMORIENT_PORTRAIT or DMORIENT_LANDSCAPE.
dmPaperSize
Specifies the size of the paper to print on. This member may be set to
zero if the length and width of the paper are specified by the
dmPaperLength and dmPaperWidth members, respectively.
Otherwise, the dmPaperSize member can be set to one of the
following predefined values:

Constant Description
DMPAPER_FIRST
DMPAPER_LETTER
DMPAPER_LETTER Letter, 8 1/2 x 11 in.
DMPAPER_LETTERSMALL Letter Small, 8 1/2 x
11 in.
DMPAPER_TABLOID Tabloid, 11 x 17 in.
DMPAPER_LEDGER Ledger, 17 x 11 in.
DMPAPER_LEGAL Legal, 8 1/2 x 14 in.
DMPAPER_STATEMENT Statement, 5 1/2 x 8
1/2 in.
DMPAPER_EXECUTIVE Executive, 7 1/2 x 10
1/2 in.
DMPAPER_A3 A3, 297 x 420 mm
DMPAPER_A4 A4, 210 x 297 mm
DMPAPER_A4SMALL A4 Small, 210 x 297
mm
DMPAPER_A5 A5, 148 x 210 mm
DMPAPER_B4 B4, 250 x 354 mm
DMPAPER_B5 B5, 182 x 257 mm
DMPAPER_FOLIO Folio, 8 1/2 x 13 in.
DMPAPER_QUARTO Quarto, 215 x 275
mm
DMPAPER_10X14 10 x 14 in.
DMPAPER_11X17 11 x 17 in.
DMPAPER_NOTE Note, 8 1/2 x 11 in.

Chapter 6, Crystal Report Engine Reference 621

 Constant Description
DMPAPER_ENV_9 Envelope #9, 3 7/8 x
8 7/8 in.
DMPAPER_ENV_10 Envelope #10, 4 1/8
x 9 1/2 in.
DMPAPER_ENV_11 Envelope #11, 4 1/2
x 10 3/8 in.
DMPAPER_ENV_12 Envelope #12, 4 1/2
x 11 in.
DMPAPER_ENV_14 Envelope #14, 5 x 11
1/2 in.
DMPAPER_CSHEET C size sheet
DMPAPER_DSHEET D size sheet
DMPAPER_ESHEET E size sheet
DMPAPER_ENV_DL Envelope DL, 110 x
220 mm
DMPAPER_ENV_C3 Envelope C3, 324 x
458 mm
DMPAPER_ENV_C4 Envelope C4, 229 x
324 mm
DMPAPER_ENV_C5 Envelope C5, 162 x
229 mm
DMPAPER_ENV_C6 Envelope C6, 114 x
162 mm
DMPAPER_ENV_C65 Envelope C65, 114 x
229 mm
DMPAPER_ENV_B4 Envelope B4, 250 x
353 mm
DMPAPER_ENV_B5 Envelope B5, 176 x
250 mm
DMPAPER_ENV_B6 Envelope B6, 176 x
125 mm
DMPAPER_ENV_ITALY Envelope, 110 x 230
mm
DMPAPER_ENV_MONARCH Envelope Monarch,
3 7/8 x 7 1/2 in.
DMPAPER_ENV_PERSONAL Envelope, 3 5/8 x 6
1/2 in.

622 Crystal Reports Developer’s Reference

 Constant Description
DMPAPER_FANFOLD_US U.S. Standard
Fanfold, 14 7/8 x 11
in.
DMPAPER_FANFOLD_STD_GERMAN German Standard
Fanfold, 8 1/2 x 12
in.
DMPAPER_FANFOLD_LGL_GERMAN German Legal
Fanfold, 8 1/2 x 13
in.
DMPAPER_LAST German Legal
Fanfold, 8 1/2 x 13
in.
DMPAPER_USER User-defined
dmPaperLength
Specifies a paper length, in tenths of a millimeter. This parameter
overrides the paper length specified by the dmPaperSize member,
either for custom paper sizes or for such devices as dot-matrix
printers that can print on a variety of page sizes.
dmPaperWidth
Specifies a paper width, in tenths of a millimeter. This parameter
overrides the paper width specified by the dmPaperSize member.
dmScale
Specifies the factor by which the printed output is to be scaled. The
apparent page size is scaled from the physical page size by a factor
of dmScale/100. For example, a letter-size paper with a dmScale
value of 50 would contain as much data as a page of size 17 by 22
inches because the output text and graphics would be half their
original height and width.
dmCopies
Specifies the number of copies printed if the device supports
multiple-page copies.
dmDefaultSource
Specifies the default bin from which the paper is fed. The application
can override this value by using the GETSETPAPERBINS escape.
This member can be one of the following values:

DMBIN_AUTO
DMBIN_LOWER
DMBIN_CASSETTE

Chapter 6, Crystal Report Engine Reference 623

 DMBIN_MANUAL
DMBIN_ENVELOPE
DMBIN_MIDDLE
DMBIN_ENVMANUAL
DMBIN_ONLYONE
DMBIN_FIRST
DMBIN_SMALLFMT
DMBIN_LARGECAPACITY
DMBIN_TRACTOR
DMBIN_LARGEFMT
DMBIN_UPPER
DMBIN_LAST
NOTE: A range of values is reserved for device-specific bins. To be
consistent with initialization information, the GETSETPAPERBINS
and ENUMPAPERBINS escapes use these values.
dmPrintQuality
Specifies the printer resolution. Following are the four predefined
device-independent values:

Constant Value
DMRES_HIGH (-4)
DMRES_MEDIUM (-3)
DMRES_LOW (-2)
DMRES_DRAFT (-1)

NOTE: If a positive value is given, it specifies the number of dots per

inch (DPI) and is therefore device-dependent.
NOTE: If the printer initializes the dmYResolution member, the
dmPrintQuality member specifies the x-resolution of the printer, in
dots per inch.
dmColor
Specifies whether a color printer is to render color or monochrome
output. Possible values are:

Constant Value
DMCOLOR_COLOR (1)
DMCOLOR_MONOCH (2)
ROME

624 Crystal Reports Developer’s Reference

 dmDuplex
Specifies duplex (double-sided) printing for printers capable of
duplex printing. This member can be one of the following values:

DMDUP_SIMPLEX (1)
DMDUP_HORIZONTAL (2)
DMDUP_VERTICAL (3)

dmYResolution
Specifies the y-resolution of the printer, in dots per inch. If the printer
initializes this member, the dmPrintQuality member specifies the x-
resolution of the printer, in dots per inch.
dmTTOption
Specifies how TrueType fonts should be printed. It can be one of the
following values:

DMTT_BITMAP Print TrueType fonts as graphics.

This is the default action for dot-
matrix printers.
DMTT_DOWNLOAD Download TrueType fonts as soft
fonts. This is the default action for
Hewlett-Packard printers that use
Printer Control Language (PCL).
DMTT_SUBDEV Substitute device fonts for TrueType
fonts. This is the default action for
PostScript printers.

Remarks ● Only drivers that are fully updated for Windows versions 3.0 and
later and that export the ExtDeviceMode function use the
DEVMODE structure.
● An application can retrieve the paper sizes and names supported
by a printer by calling the DeviceCapabilities function with the
DC_PAPERS, DC_PAPERSIZE, and DC_PAPERNAMES values.
● Before setting the value of the dmTTOption member, applications
should find out how a printer driver can use TrueType fonts by
calling the DeviceCapabilities function with the DC_TRUETYPE
value.
● Drivers can add device-specific data immediately following the
DEVMODE structure.

Chapter 6, Crystal Report Engine Reference 625

 32-bit
struct _devicemode
{
BCHAR dmDeviceName[CCHDEVICENAME];
WORD dmSpecVersion;
WORD dmDriverVersion;
WORD dmSize;
WORD dmDriverExtra;
DWORD dmFields;
short dmOrientation;
short dmPaperSize;
short dmPaperLength;
short dmPaperWidth;
short dmScale;
short dmCopies;
short dmDefaultSource;
short dmPrintQuality;
short dmColor;
short dmDuplex;
short dmYResolution;
short dmTTOption;
short dmCollate;
BCHAR dmFormName[CCHFORMNAME];
WORD dmLogPixels;
DWORD dmBitsPerPel;
DWORD dmPelsWidth;
DWORD dmPelsHeight;
DWORD dmDisplayFlags;
DWORD dmDisplayFrequency;
#if(WINVER >= 0x0400)
DWORD dmICMMethod;// Windows 95 only
DWORD dmICMIntent;// Windows 95 only
DWORD dmMediaType;// Windows 95 only
DWORD dmDitherType;// Windows 95
only
DWORD dmReserved1;// Windows 95 only
DWORD dmReserved2;// Windows 95 only
#endif /* WINVER >= 0x0400 */
};
dmDeviceName
Specifies the name of the device the driver supports--for example,
"PCL/HP LaserJet" in the case of the Hewlett-Packard LaserJet. Each
driver has a unique string.

626 Crystal Reports Developer’s Reference

 dmSpecVersion
Specifies the version number of the DEVMODE structure. For
Windows version 3.1, this value should be 0x30A
dmDriverVersion
Specifies the printer driver version number assigned by the printer
driver developer.
dmSize
Specifies the size, in bytes, of the DEVMODE structure. (This value
does not include the optional dmDriverData member for device-
specific data, which can follow the structure.) If an application
manipulates only the driver-independent portion of the data, it can
use this member to find out the length of the structure without
having to account for different versions.
dmDriverExtra
Specifies the size, in bytes, of the optional dmDriverData member for
device-specific data, which can follow the structure. If an application
does not use device-specific information, it should set this member
to zero.
dmFields
Specifies a set of flags that indicate which of the remaining members
in the DEVMODE structure have been initialized. It can be any
combination (or it can be none) of the following values:

DM_ORIENTATION 0x0000001L
DM_PAPERSIZE 0x0000002L
DM_PAPERLENGTH 0x0000004L
DM_PAPERWIDTH 0x0000008L
DM_SCALE 0x0000010L
DM_COPIES 0x0000100L
DM_DEFAULTSOURCE 0x0000200L
DM_PRINTQUALITY 0x0000400L
DM_COLOR 0x0000800L
DM_DUPLEX 0x0001000L
DM_YRESOLUTION 0x0002000L
DM_TTOPTION 0x0004000L

NOTE: A printer driver supports only those members that are

appropriate for the printer technology.

Chapter 6, Crystal Report Engine Reference 627

 dmOrientation
Specifies the orientation of the paper. It can be either
DMORIENT_PORTRAIT or DMORIENT_LANDSCAPE.
dmPaperSize
Specifies the size of the paper to print on. This member may be set to
zero if the length and width of the paper are specified by the
dmPaperLength and dmPaperWidth members, respectively.
Otherwise, the dmPaperSize member can be set to one of the
following predefined values:

DMPAPER_FIRST
DMPAPER_LETTER
DMPAPER_LETTER Letter, 8 1/2 x 11 in.
DMPAPER_LETTERSMALL Letter Small, 8 1/2 x
11 in.
DMPAPER_TABLOID Tabloid, 11 x 17 in.
DMPAPER_LEDGER Ledger, 17 x 11 in.
DMPAPER_LEGAL Legal, 8 1/2 x 14 in.
DMPAPER_STATEMENT Statement, 5 1/2 x 8
1/2 in.
DMPAPER_EXECUTIVE Executive, 7 1/2 x
10 1/2 in.
DMPAPER_A3 A3, 297 x 420 mm
DMPAPER_A4 A4, 210 x 297 mm
DMPAPER_A4SMALL A4 Small, 210 x 297
mm
DMPAPER_A5 A5, 148 x 210 mm
DMPAPER_B4 B4, 250 x 354 mm
DMPAPER_B5 B5, 182 x 257 mm
DMPAPER_FOLIO Folio, 8 1/2 x 13 in.
DMPAPER_QUARTO Quarto, 215 x 275
mm
DMPAPER_10X14 10 x 14 in.
DMPAPER_11X17 11 x 17 in.
DMPAPER_NOTE Note, 8 1/2 x 11 in.
DMPAPER_ENV_9 Envelope #9, 3 7/8 x
8 7/8 in.
DMPAPER_ENV_10 Envelope #10, 4 1/8
x 9 1/2 in.

628 Crystal Reports Developer’s Reference

 DMPAPER_ENV_11 Envelope #11, 4 1/2
x 10 3/8 in.
DMPAPER_ENV_12 Envelope #12, 4 1/2
x 11 in.
DMPAPER_ENV_14 Envelope #14, 5 x 11
1/2 in.
DMPAPER_CSHEET C size sheet
DMPAPER_DSHEET D size sheet
DMPAPER_ESHEET E size sheet
DMPAPER_ENV_DL Envelope DL, 110 x
220 mm
DMPAPER_ENV_C3 Envelope C3, 324 x
458 mm
DMPAPER_ENV_C4 Envelope C4, 229 x
324 mm
DMPAPER_ENV_C5 Envelope C5, 162 x
229 mm
DMPAPER_ENV_C6 Envelope C6, 114 x
162 mm
DMPAPER_ENV_C65 Envelope C65, 114 x
229 mm
DMPAPER_ENV_B4 Envelope B4, 250 x
353 mm
DMPAPER_ENV_B5 Envelope B5, 176 x
250 mm
DMPAPER_ENV_B6 Envelope B6, 176 x
125 mm
DMPAPER_ENV_ITALY Envelope, 110 x 230
mm
DMPAPER_ENV_MONARCH Envelope Monarch,
3 7/8 x 7 1/2 in.
DMPAPER_ENV_PERSONAL Envelope, 3 5/8 x 6
1/2 in.
DMPAPER_FANFOLD_US U.S. Standard
Fanfold, 14 7/8 x 11
in.
DMPAPER_FANFOLD_STD_GERMAN German Standard
Fanfold, 8 1/2 x 12
in.

Chapter 6, Crystal Report Engine Reference 629

 DMPAPER_FANFOLD_LGL_GERMAN German Legal
Fanfold, 8 1/2 x 13
in.
DMPAPER_LAST German Legal
Fanfold, 8 1/2 x 13
in.
DMPAPER_USER User-defined
dmPaperLength
Specifies a paper length, in tenths of a millimeter. This parameter
overrides the paper length specified by the dmPaperSize member,
either for custom paper sizes or for such devices as dot-matrix
printers that can print on a variety of page sizes.
dmPaperWidth
Specifies a paper width, in tenths of a millimeter. This parameter
overrides the paper width specified by the dmPaperSize member.
dmScale
Specifies the factor by which the printed output is to be scaled. The
apparent page size is scaled from the physical page size by a factor
of dmScale/100. For example, a letter-size paper with a dmScale
value of 50 would contain as much data as a page of size 17 by 22
inches because the output text and graphics would be half their
original height and width.
dmCopies
Specifies the number of copies printed if the device supports
multiple-page copies.
dmDefaultSource
Specifies the default bin from which the paper is fed.
The application can override this value by using the
GETSETPAPERBINS escape. This member can be one of the
following values:

DMBIN_AUTO
DMBIN_LOWER
DMBIN_CASSETTE
DMBIN_MANUAL
DMBIN_ENVELOPE
DMBIN_MIDDLE
DMBIN_ENVMANUAL

630 Crystal Reports Developer’s Reference

 DMBIN_ONLYONE
DMBIN_FIRST
DMBIN_SMALLFMT
DMBIN_LARGECAPACITY
DMBIN_TRACTOR
DMBIN_LARGEFMT
DMBIN_UPPER
DMBIN_LAST
NOTE: A range of values is reserved for device-specific bins. To be
consistent with initialization information, the GETSETPAPERBINS
and ENUMPAPERBINS escapes use these values.
dmPrintQuality
Specifies the printer resolution. Following are the four predefined
device-independent values:

Constant Value
DMRES_DRAFT (-1)
DMRES_LOW (-2)
DMRES_MEDIUM (-3)
DMRES_HIGH (-4)

NOTE: If a positive value is given, it specifies the number of dots per

inch (DPI) and is therefore device-dependent.
NOTE: If the printer initializes the dmYResolution member, the
dmPrintQuality member specifies the x-resolution of the printer, in
dots per inch.
dmColor
Specifies whether a color printer is to render color or monochrome
output. Possible values are:

Constant Value
DMCOLOR_COLOR (1)
DMCOLOR_MONOCH (2)
ROME

dmDuplex
Specifies duplex (double-sided) printing for printers capable of
duplex printing. This member can be one of the following values:

Chapter 6, Crystal Report Engine Reference 631

 Constant Value
DMDUP_SIMPLEX (1)
DMDUP_HORIZONTAL (2)
DMDUP_VERTICAL (3)

dmYResolution
Specifies the y-resolution of the printer, in dots per inch. If the printer
initializes this member, the dmPrintQuality member specifies the x-
resolution of the printer, in dots per inch.
dmTTOption
Specifies how TrueType fonts should be printed. It can be one of the
following values:

Constant Description
DMTT_BITMAP Print TrueType fonts as graphics.
This is the default action for dot-
matrix printers.
DMTT_DOWNLOAD Download TrueType fonts as soft
fonts. This is the default action for
Hewlett-Packard printers that use
Printer Control Language (PCL).
DMTT_SUBDEV Substitute device fonts for TrueType
fonts. This is the default action for
PostScript printers.

dmCollate
Specifies whether collation should be used when printing multiple
copies. (This member is ignored unless the printer driver indicates
support for collation by setting the dmFields member to
DM_COLLATE.) This member can be one of the following values:

Constant Description
DMCOLLATE_TRUE Collate when printing multiple
copies.
DMCOLLATE_FALSE Do not collate when printing
multiple copies.

NOTE: Using DMCOLLATE_TRUE provides faster, more efficient

output for collation, since the data is sent to the device driver just
once, no matter how many copies are required. The printer is told to
simply print the page again.

632 Crystal Reports Developer’s Reference

 dmFormName
Windows NT: Specifies the name of the form to use; for
example,"Letter" or "Legal". A complete set of names can be retrieved
by using the EnumForms function. Windows 95: Printer drivers do
not use this member.
dmLogPixels
Specifies the number of pixels per logical inch.
dmBitsPerPel
Windows NT: Specifies the color resolution, in bits per pixel, of the
display device (for example: 4 bits for 16 colors, 8 bits for 256colors,
or 16 bits for 65536 colors). Windows 95: Display drivers use this
member, for example, in the ChangeDisplaySettings function.
Printer drivers do not use this member.
dmPelsWidth
Windows NT: Specifies the width, in pixels, of the visible device
surface. Windows 95: Display drivers use this member, for example,
in the ChangeDisplaySettings function. Printer drivers do not use
this member.
dmPelsHeight
Windows NT: Specifies the height, in pixels, of the visible device
surface. Windows 95: Display drivers use this member, for example,
in the ChangeDisplaySettings function. Printer drivers do not use
this member.
dmDisplayFlags
Windows NT: Specifies the device's display mode. This member can
Boone of the following values:

Constant Description
DM_GRAYSCALE Specifies that the display is a NON-
color device. If this flag is not set,
color is assumed.
DM_INTERLACED Specifies that the display mode is
interlaced. If the flag is not set, NON-
interlaced is assumed. Windows 95:
Display drivers use this member, for
example, in the
ChangeDisplaySettings function.
Printer drivers do not use this
member.

Chapter 6, Crystal Report Engine Reference 633

 dmDisplayFrequency
Windows NT: Specifies the frequency, in hertz (cycles per second), of
the display device in a particular mode. Windows 95: Display drivers
use this member, for example, in the ChangeDisplaySettings
function. Printer drivers do not use this member.
dmICMMethod
Windows 95: Specifies how ICM (Image Color Matching) is handled.
For a non-ICM application, this member determines if ICM is
enabled or disabled. For ICM applications, Windows examines this
member to determine how to handle ICM support.This member can
be one of the following predefined values, or a driver-defined value
greater than the value of DMICMMETHOD_USER:
Windows NT: This member is not supported on Windows NT.

DMICMMETHOD_NONE Windows 95 only: Specifies that

ICM is disabled.
DMICMMETHOD_SYSTEM Windows 95 only: Specifies that
ICM is handled by Windows.
DMICMMETHOD_DRIVER Windows 95 only: Specifies that
ICM is handled by the device
driver.
DMICMMETHOD_DEVICE Windows 95 only: Specifies that
ICM is handled by the
destination device. The printer
driver must provide a user
interface for setting this member.
Most printer drivers support
only the
DMICMMETHOD_SYSTEM or
DMICMMETHOD_NONE
value. Drivers for PostScript
printers support all values.

dmICMIntent
Windows 95: Specifies which of the three possible color matching
methods, or intents, should be used by default. This member is
primarily for non-ICM applications. ICM applications can establish
intents by using the ICM functions. This member can be one of the
following predefined values, or a driver defined value greater than
the value of DMICM_USER:

634 Crystal Reports Developer’s Reference

 Windows NT: This member is not supported on Windows NT.

DMICM_SATURATE Windows 95 only: Color matching

should optimize for color
saturation. This value is the most
appropriate choice for business
graphs when dithering is not
desired.
DMICM_CONTRAST Windows 95 only: Color matching
should optimize for color contrast.
This value is the most appropriate
choice for scanned or photographic
images when dithering is desired.
DMICM_COLORMETRIC Windows 95 only: Color matching
should optimize to match the exact
color requested. This value is most
appropriate for use with business
logos or other images when an
exact color match is desired.

dmMediaType
Windows 95: Specifies the type of media being printed on. The
member can be one of the following predefined values, or a driver-
defined value greater than the value of DMMEDIA_USER:
Windows NT: This member is not supported on Windows NT.

DMMEDIA_STANDARD Windows 95 only: Plain paper.

DMMEDIA_GLOSSY Windows 95 only: Glossy paper.
DMMEDIA_TRANSPAR Windows 95 only: Transparent film.
ENCY

dmDitherType
Windows 95: Specifies how dithering is to be done. The member can
be one of the following predefined values, or a driver-defined value
greater than the value of DMDITHER_USER:
Windows NT: This member is not supported on Windows NT.

DMDITHER_NONE Windows 95 only: No dithering.

DMDITHER_COARSE Windows 95 only: Dithering with
a coarse brush.
DMDITHER_FINE Windows 95 only: Dithering with
a fine brush.

Chapter 6, Crystal Report Engine Reference 635

 DMDITHER_LINEART Windows 95 only: Line art
dithering, a special dithering
method that produces well
defined borders between black,
white, and gray scalings. It is not
suitable for images that include
continuous graduations in
intensity and hue such as scanned
photographs.
DMDITHER_GRAYSCALE Windows 95 only: Device does
grayscaling.
dmReserved1
Windows 95: Not used; must be zero.
Windows NT: This member is not supported on Windows NT.
dmReserved2
Windows 95: Not used; must be zero.
Windows NT: This member is not supported on Windows NT.

Remarks A device driver's private data follows the public portion of the
DEVMODE structure. The size of the public data can vary for
different versions of the structure. The dmSize member specifies the
number of bytes of public data, and the dmDriverExtra member
specifies the number of bytes of private data.

DEVMODE (Other Declares)

DEVMODE 16-bit
(VB Type Listing) Type DEVMODE
dmDeviceName As String * 32
dmSpecVersion As Integer
dmDriverVersion As Integer
dmSize As Integer
dmDriverExtra As Integer
dmFields As Long
dmOrientation As Integer
dmPaperSize As Integer
dmPaperLength As Integer
dmPaperWidth As Integer
dmScale As Integer

636 Crystal Reports Developer’s Reference

 dmCopies As Integer
dmDefaultSource As Integer
dmPrintQuality As Integer
dmColor As Integer
dmDuplex As Integer
dmYResolution As Integer
dmTTOption As Integer
End Type
dmDeviceName
Specifies the name of the device the driver supports--for example,
"PCL/HP LaserJet" in the case of the Hewlett-Packard LaserJet. Each
driver has a unique string.
dmSpecVersion
Specifies the version number of the DEVMODE structure. For
Windows version 3.1, this value should be 0x30A.
dmDriverVersion
Specifies the printer driver version number assigned by the printer
driver developer.
dmSize
Specifies the size, in bytes, of the DEVMODE structure. (This value
does not include the optional dmDriverData member for device-
specific data, which can follow the structure.) If an application
manipulates only the driver-independent portion of the data, it can
use this member to find out the length of the structure without
having to account for different versions.
dmDriverExtra
Specifies the size, in bytes, of the optional dmDriverData member for
device-specific data, which can follow the structure. If an application
does not use device-specific information, it should set this member
to zero.
dmFields
Specifies a set of flags that indicate which of the remaining members
in the DEVMODE structure have been initialized. It can be any
combination (or it can be none) of the following values:

DM_ORIENTATION &H1&
DM_PAPERSIZE &H2&
DM_PAPERLENGTH &H4&
DM_PAPERWIDTH &H8&
DM_SCALE &H10&

Chapter 6, Crystal Report Engine Reference 637

 DM_COPIES &H100&
DM_DEFAULTSOURCE &H200&
DM_PRINTQUALITY &H400&
DM_COLOR &H800&
DM_DUPLEX &H1000&
DM_YRESOLUTION &H2000&
DM_TTOPTION &H4000&
NOTE: A printer driver supports only those members that are
appropriate for the printer technology.
dmOrientation
Specifies the orientation of the paper. It can be either of the following:

DMORIENT_PORTRAIT
DMORIENT_LANDSCAPE

dmPaperSize
Specifies the size of the paper to print on. This member may be set
to zero if the length and width of the paper are specified by the
dmPaperLength and dmPaperWidth members, respectively.
Otherwise, the dmPaperSize member can be set to one of the
following predefined values:

Constant Value Description

DMPAPER_FIRST 1 DMPAPER_
LETTER
DMPAPER_LETTER 1 { Letter 8 1/2 x 11 in }
DMPAPER_LETTERSMALL 2 { Letter Small 8 1/2 x
11 in }
DMPAPER_TABLOID 3 { Tabloid 11 x 17 in }
DMPAPER_LEDGER 4 { Ledger 17 x 11 in }
DMPAPER_LEGAL 5 { Legal 8 1/2 x 14 in }
DMPAPER_STATEMENT 6 { Statement 5 1/2 x 8
1/2 in }
DMPAPER_EXECUTIVE 7 { Executive"7 1/2 x
10 in }
DMPAPER_A3 8 { A3 297 x 420 mm }
DMPAPER_A4 9 { A4 210 x 297 mm }
DMPAPER_A4SMALL 10 { A4 Small 210 x 297
mm }

638 Crystal Reports Developer’s Reference

 Constant Value Description
DMPAPER_A5 11 { A5 148 x 210 mm }
DMPAPER_B4 12 { B4 250 x 354 }
DMPAPER_B5 13 { B5 182 x 257 mm }
DMPAPER_FOLIO 14 { Folio 8 1/2 x 13 in }
DMPAPER_QUARTO 15 { Quarto 215 x 275
mm }
DMPAPER_10X14 16 { 10x14 in }
DMPAPER_11X17 17 { 11x17 in }
DMPAPER_NOTE 18 { Note 8 1/2 x 11 in }
DMPAPER_ENV_9 19 { Envelope #9 3 7/8 x
8 7/8 }
DMPAPER_ENV_10 20 { Envelope #10 4 1/8
x 9 1/2 }
DMPAPER_ENV_11 21 { Envelope #11 4 1/2
x 10 3/8 }
DMPAPER_ENV_12 22 { Envelope #12 4
\276 x 11 }
DMPAPER_ENV_14 23 { Envelope #14 5 x 11
1/2 }
DMPAPER_CSHEET 24 { C size sheet }
DMPAPER_DSHEET 25 { D size sheet }
DMPAPER_ESHEET 26 { E size sheet }
DMPAPER_ENV_DL 27 Envelope DL, 110 x
220 mm
DMPAPER_ENV_C3 29 Envelope C3, 324 x
458 mm
DMPAPER_ENV_C4 30 Envelope C4, 229 x
324 mm
DMPAPER_ENV_C5 28 Envelope C5, 162 x
229 mm
DMPAPER_ENV_C6 31 Envelope C6, 114 x
162 mm
DMPAPER_ENV_C65 32 Envelope C65, 114 x
229 mm
DMPAPER_ENV_B4 33 Envelope B4, 250 x
353 mm

Chapter 6, Crystal Report Engine Reference 639

 Constant Value Description
DMPAPER_ENV_B5 34 Envelope B5, 176 x
250 mm
DMPAPER_ENV_B6 35 Envelope B6, 176 x
125 mm
DMPAPER_ENV_ITALY 36 Envelope, 110 x 230
mm
DMPAPER_ENV_MONARCH 37 Envelope Monarch,
3 7/8 x 7 1/2 in
DMPAPER_ENV_PERSONAL 38 Envelope, 3 5/8 x 6
1/2 in
DMPAPER_FANFOLD_US 39 U.S. Standard
Fanfold, 14 7/8 x 11
in
DMPAPER_FANFOLD_STD_ 40 German Standard
GERMAN Fanfold, 8 1/2 x 12
in.
DMPAPER_FANFOLD_LGL_ 41 German Legal
GERMAN Fanfold, 8 1/2 x 13
in.
DMPAPER_LAST DMP German Legal
APER Fanfold, 8 1/2 x 13
_FAN in.
FOLD
_LGL
_GER
MAN
DMPAPER_USER 256 User-defined
dmPaperLength
Specifies a paper length, in tenths of a millimeter. This parameter
overrides the paper length specified by the dmPaperSize member,
either for custom paper sizes or for such devices as dot-matrix
printers that can print on a variety of page sizes.
dmPaperWidth
Specifies a paper width, in tenths of a millimeter. This parameter
overrides the paper width specified by the dmPaperSize member.
dmScale
Specifies the factor by which the printed output is to be scaled. The
apparent page size is scaled from the physical page size by a factor

640 Crystal Reports Developer’s Reference

 of dmScale/100. For example, a letter-size paper with a dmScale
value of 50 would contain as much data as a page of size 17 by 22
inches because the output text and graphics would be half their
original height and width.
dmCopies
Specifies the number of copies printed if the device supports
multiple-page copies.
dmDefaultSource
Specifies the default bin from which the paper is fed. The application
can override this value by using the GETSETPAPERBINS escape.
This member can be one of the following values:

Constant Value Value

DMBIN_AUTO 7 DMBIN_LOWER
DMBIN_CASSETTE 14 DMBIN_MANUAL
DMBIN_ENVELOPE 5 DMBIN_MIDDLE
DMBIN_ENVMANUAL 6 DMBIN_ONLYONE
DMBIN_FIRST 1 DMBIN_SMALLFMT
DMBIN_ 11 DMBIN_TRACTOR
LARGECAPACITY
DMBIN_LARGEFMT 10 DMBIN_UPPER
DMBIN_LAST DMBIN_CASSETTE

NOTE: A range of values is reserved for device-specific bins. To be

consistent with initialization information, the GETSETPAPERBINS
and ENUMPAPERBINS escapes use these values.
dmPrintQuality
Specifies the printer resolution. Following are the four predefined
device-independent values:

Constant Value
DMRES_DRAFT -1
DMRES_LOW -2
DMRES_MEDIUM -3
DMRES_HIGH -4

NOTE: If a positive value is given, it specifies the number of dots per

inch (DPI) and is therefore device-dependent.
NOTE: If the printer initializes the dmYResolution member, the
dmPrintQuality member specifies the x-resolution of the printer, in
dots per inch.

Chapter 6, Crystal Report Engine Reference 641

 dmColor
Specifies whether a color printer is to render color or monochrome
output. Possible values are:

Constant Value
DMCOLOR_MONOCHROME 1
DMCOLOR_COLOR 2

dmDuplex
Specifies duplex (double-sided) printing for printers capable of
duplex printing. This member can be one of the following values:

Constant Value
DMDUP_SIMPLEX 1
DMDUP_VERTICAL 2
DMDUP_HORIZONTAL 3

DEVMODE 16-bit
(Delphi Record The TDevMode record is defined under the WINTYPES.PAS file in
Delphi. You do not need to define this record in your own
Listing) application, simply verify that your application includes
WINTYPES.PAS. Documentation of TDevMode is provided here for
your own information only.
type
TDevMode = record
dmDeviceName: array[0..cchDeviceName-1] of
Char;
dmSpecVersion: Word;
dmDriverVersion: Word;
dmSize: Word;
dmDriverExtra: Word;
dmFields: LongInt;
dmOrientation: Integer;
dmPaperSize: Integer;
dmPaperLength: Integer;
dmPaperWidth: Integer;
dmScale: Integer;
dmCopies: Integer;
dmDefaultSource: Integer;
dmPrintQuality: Integer;
dmColor: Integer;
dmDuplex: Integer;
end;

642 Crystal Reports Developer’s Reference

 dmDeviceName:
Specifies the name of the device the driver supports--for example,
"PCL/HP LaserJet" in the case of the Hewlett-Packard LaserJet. Each
driver has a unique string.
dmSpecVersion
Specifies the version number of the DEVMODE structure. For
Windows version 3.1, this value should be 0x30A
dmDriverVersion
Specifies the printer driver version number assigned by the printer
driver developer.
dmSize
Specifies the size, in bytes, of the DEVMODE structure. (This value
does not include the optional dmDriverData member for device-
specific data, which can follow the structure.) If an application
manipulates only the driver-independent portion of the data, it can
use this member to find out the length of the structure without
having to account for different versions.
dmDriverExtra
Specifies the size, in bytes, of the optional dmDriverData member for
device-specific data, which can follow the structure. If an application
does not use device-specific information, it should set this member
to zero.
dmFields
Specifies a set of flags that indicate which of the remaining members
in the DEVMODE structure have been initialized. It can be any
combination (or it can be none) of the following values:

dm_Orientation $0000001
dm_PaperSize $0000002
dm_PaperLength $0000004
dm_PaperWidth $0000008
dm_Scale $0000010
dm_Copies $0000100
dm_DefaultSource $0000200
dm_PrintQuality $0000400
dm_Color $0000800
dm_Duplex $0001000

Chapter 6, Crystal Report Engine Reference 643

 NOTE: A printer driver supports only those members that are
appropriate for the printer technology.
dmOrientation
Specifies the orientation of the paper. It can be either of the following:

dmorient_Portrait 1
dmorient_Landscape 2

dmPaperSize
Specifies the size of the paper to print on. This member may be set
to zero if the length and width of the paper are specified by the
dmPaperLength and dmPaperWidth members, respectively.
Otherwise, the dmPaperSize member can be set to one of the
following predefined values:

Constant Value Description

dmpaper_First 1
dmpaper_Letter 1 { Letter 8 1/2 x 11 in }
dmpaper_LetterSmall 2 { Letter Small 8 1/2 x 11 in }
dmpaper_Tabloid 3 { Tabloid 11 x 17 in }
dmpaper_Ledger 4 { Ledger 17 x 11 in }
dmpaper_Legal 5 { Legal 8 1/2 x 14 in }
dmpaper_Statement 6 { Statement 5 1/2 x 8 1/2 in }
dmpaper_Executive 7 { Executive"7 1/2 x 10 in }
dmpaper_A3 8 { A3 297 x 420 mm }
dmpaper_A4 9 { A4 210 x 297 mm }
dmpaper_A4Small 10 { A4 Small 210 x 297 mm }
dmpaper_A5 11 { A5 148 x 210 mm }
dmpaper_B4 12 { B4 250 x 354 }
dmpaper_B5 13 { B5 182 x 257 mm }
dmpaper_Folio 14 { Folio 8 1/2 x 13 in }
dmpaper_Quarto 15 { Quarto 215 x 275 mm }
dmpaper_10X14 16 { 10x14 in }
dmpaper_11X17 17 { 11x17 in }
dmpaper_Note 18 { Note 8 1/2 x 11 in }
dmpaper_Env_9 19 { Envelope #9 3 7/8 x 8 7/8 }
dmpaper_Env_10 20 { Envelope #10 4 1/8 x 9 1/2
}

644 Crystal Reports Developer’s Reference

 Constant Value Description
dmpaper_Env_11 21 { Envelope #11 4 1/2 x 10 3/
8}
dmpaper_Env_12 22 { Envelope #12 4 \276 x 11 }
dmpaper_Env_14 23 { Envelope #14 5 x 11 1/2 }
dmpaper_CSheet 24 { C size sheet }
dmpaper_DSheet 25 { D size sheet }
dmpaper_ESheet 26 { E size sheet }
dmpaper_Last dmpaper_ESheet
dmpaper_User 256
dmPaperLength
Specifies a paper length, in tenths of a millimeter. This parameter
overrides the paper length specified by the dmPaperSize member,
either for custom paper sizes or for such devices as dot-matrix
printers that can print on a variety of page sizes.
dmPaperWidth
Specifies a paper width, in tenths of a millimeter. This parameter
overrides the paper width specified by the dmPaperSize member.
dmScale
Specifies the factor by which the printed output is to be scaled. The
apparent page size is scaled from the physical page size by a factor
of dmScale/100. For example, a letter-size paper with a dmScale
value of 50 would contain as much data as a page of size 17 by 22
inches because the output text and graphics would be half their
original height and width.
dmCopies
Specifies the number of copies printed if the device supports
multiple-page copies.
dmDefaultSource
Specifies the default bin from which the paper is fed. The application
can override this value by using the GETSETPAPERBINS escape.
This member can be one of the following values:

Constant Value
dmbin_First 1
dmbin_Upper 1
dmbin_OnlyOne 1

Chapter 6, Crystal Report Engine Reference 645

 Constant Value
dmbin_Lower 2
dmbin_Middle 3
dmbin_Manual 4
dmbin_Envelope 5
dmbin_EnvManual 6
dmbin_Auto 7
dmbin_Tractor 8
dmbin_SmallFmt 9
dmbin_LargeFmt 10
dmbin_LargeCapacity 11
dmbin_Cassette 14
dmbin_Last dmbin_Cassette
dmbin_User 256
NOTE: A range of values is reserved for device-specific bins. To be
consistent with initialization information, the GETSETPAPERBINS
and ENUMPAPERBINS escapes use these values.
dmPrintQuality
Specifies the printer resolution. Following are the four predefined
device-independent values:

Constant Value
dmres_Draft -1
dmres_Low -2
dmres_Medium -3
dmres_High -4

NOTE: If a positive value is given, it specifies the number of dots per

inch (DPI) and is therefore device-dependent.
NOTE: If the printer initializes the dmYResolution member, the
dmPrintQuality member specifies the x-resolution of the printer, in
dots per inch.
dmColor
Specifies whether a color printer is to render color or monochrome
output. Possible values are:

646 Crystal Reports Developer’s Reference

 Constant Value
dmcolor_Monochrome 1
dmcolor_Color 2

dmDuplex
Specifies duplex (double-sided) printing for printers capable of
duplex printing. This member can be one of the following values:

dmdup_Simplex (1)
dmdup_Vertical (2)
dmdup_Horizontal (3)

32-bit
type
PDeviceMode = PDeviceModeA;
dmDeviceName: array[0..CCHDEVICENAME - 1]
of AnsiChar;
dmSpecVersion: Word;
dmDriverVersion: Word;
dmSize: Word;
dmDriverExtra: Word;
dmFields: DWORD;
dmOrientation: SHORT;
dmPaperSize: SHORT;
dmPaperLength: SHORT;
dmPaperWidth: SHORT;
dmScale: SHORT;
dmCopies: SHORT;
dmDefaultSource: SHORT;
dmPrintQuality: SHORT;
dmColor: SHORT;
dmDuplex: SHORT;
dmYResolution: SHORT;
dmTTOption: SHORT;
dmCollate: SHORT;
dmFormName: array[0..CCHFORMNAME - 1] of
AnsiChar;
dmLogPixels: Word;
dmBitsPerPel: DWORD;
dmPelsWidth: DWORD;
dmPelsHeight: DWORD;
dmDisplayFlags: DWORD;
dmDisplayFrequency: DWORD;

Chapter 6, Crystal Report Engine Reference 647

 dmICMMethod: DWORD;
dmICMIntent: DWORD;
dmMediaType: DWORD;
dmDitherType: DWORD;
dmReserved1: DWORD;
dmReserved2: DWORD;
end;
dmDeviceName
Specifies the name of the device the driver supports--for example,
"PCL/HP LaserJet" in the case of the Hewlett-Packard LaserJet. Each
driver has a unique string.
dmSpecVersion
Specifies the version number of the DEVMODE structure. For
Windows version 3.1, this value should be 0x30A
dmDriverVersion
Specifies the printer driver version number assigned by the printer
driver developer.
dmSize
Specifies the size, in bytes, of the DEVMODE structure. (This value
does not include the optional dmDriverData member for device-
specific data, which can follow the structure.) If an application
manipulates only the driver-independent portion of the data, it can
use this member to find out the length of the structure without
having to account for different versions.
dmDriverExtra
Specifies the size, in bytes, of the optional dmDriverData member for
device-specific data, which can follow the structure. If an application
does not use device-specific information, it should set this member
to zero.
dmFields
Specifies a set of flags that indicate which of the remaining members
in the DEVMODE structure have been initialized. It can be any
combination (or it can be none) of the following values:

Constant Value
DM_ORIENTATION 1
DM_PAPERSIZE 2
DM_PAPERLENGTH 4
DM_PAPERWIDTH 8

648 Crystal Reports Developer’s Reference

 Constant Value
DM_SCALE $10
DM_COPIES $100
DM_DEFAULTSOURCE $200
DM_PRINTQUALITY $400
DM_COLOR $800
DM_DUPLEX $1000
DM_YRESOLUTION $2000
DM_TTOPTION $4000
DM_COLLATE $8000
DM_FORMNAME $10000
DM_LOGPIXELS $20000
DM_BITSPERPEL $40000
DM_PELSWIDTH $80000
DM_PELSHEIGHT $100000
DM_DISPLAYFLAGS $200000
DM_DISPLAYFREQUENCY $400000
DM_RESERVED1 $800000
DM_RESERVED2 $1000000
DM_ICMMETHOD $2000000
DM_ICMINTENT $4000000
DM_MEDIATYPE $8000000
DM_DITHERTYPE $10000000
NOTE: A printer driver supports only those members that are
appropriate for the printer technology.
dmOrientation
Specifies the orientation of the paper. It can be either of the following:

Constant Value
DMORIENT_PORTRAIT 1
DMORIENT_LANDSCAPE 2

dmPaperSize
Specifies the size of the paper to print on. This member may be set
to zero if the length and width of the paper are specified by the
dmPaperLength and dmPaperWidth members, respectively.
Otherwise, the dmPaperSize member can be set to one of the
following predefined values:

Chapter 6, Crystal Report Engine Reference 649

 Constant Value Description
DMPAPER_LETTER 1 { Letter 8 12 x
11 in}
DMPAPER_FIRST DMPAPER_
LETTER
DMPAPER_LETTERSMALL 2 { Letter Small 8
12 x 11 in}
DMPAPER_TABLOID 3 { Tabloid 11 x
17 in}
DMPAPER_LEDGER 4 { Ledger 17 x
11 in}
DMPAPER_LEGAL 5 { Legal 8 12 x
14 in}
DMPAPER_STATEMENT 6 { Statement 5
12 x 8 12 in}
DMPAPER_EXECUTIVE 7 { Executive 7
14 x 10 12 in}
DMPAPER_A3 8; { A3 297 x 420
mm}
DMPAPER_A4 9 { A4 210 x 297
mm}
DMPAPER_A4SMALL 10 { A4 Small 210
x 297 mm}
DMPAPER_A5 11 { A5 148 x 210
mm}
DMPAPER_B4 12 { B4 (JIS) 250 x
354}
DMPAPER_B5 13 { B5 (JIS) 182 x
257 mm}
DMPAPER_FOLIO 14 { Folio 8 12 x
13 in}
DMPAPER_QUARTO 15 { Quarto 215 x
275 mm}
DMPAPER_10X14 16 { 10x14 in}
DMPAPER_11X17 17 { 11x17 in}
DMPAPER_NOTE 18 { Note 8 12 x
11 in}
DMPAPER_ENV_9 19 { Envelope #9
3 78 x 8 78}

650 Crystal Reports Developer’s Reference

 Constant Value Description
DMPAPER_ENV_10 20 { Envelope
#10 4 18 x 9 12}
DMPAPER_ENV_11 21 { Envelope
#11 4 12 x 10
38}
DMPAPER_ENV_12 22 { Envelope
#12 4 \276 x
11}
DMPAPER_ENV_14 23 { Envelope
#14 5 x 11 12}
DMPAPER_CSHEET 24 { C size sheet}
DMPAPER_DSHEET 25 { D size sheet}
DMPAPER_ESHEET 26 { E size sheet}
DMPAPER_ENV_DL 27 { Envelope DL
110 x 220mm}
DMPAPER_ENV_C5 28 { Envelope C5
162 x 229 mm}
DMPAPER_ENV_C3 29 {Envelope C3
324 x 458 mm}
DMPAPER_ENV_C4 30 {Envelope C4
229 x 324 mm}
DMPAPER_ENV_C6 31 {Envelope C6
114 x 162 mm}
DMPAPER_ENV_C65 32; {Envelope
C65 114 x 229
mm}
DMPAPER_ENV_B4 33 {Envelope B4
250 x 353 mm}
DMPAPER_ENV_B5 34 {Envelope B5
176 x 250 mm}
DMPAPER_ENV_B6 35 {Envelope B6
176 x 125 mm}
DMPAPER_ENV_ITALY 36 {Envelope 110
x 230 mm}
DMPAPER_ENV_MONARCH 37 { Envelope
Monarch
3.875 x 7.5 in}

Chapter 6, Crystal Report Engine Reference 651

 Constant Value Description
DMPAPER_ENV_PERSONAL 38 { 6 34
Envelope 3 58
x 6 12 in}
DMPAPER_FANFOLD_US 39 { S Std
Fanfold 14 78 x
11 in}
DMPAPER_FANFOLD_STD_ 40 { German Std
GERMAN Fanfold 8 12 x
12 in}
DMPAPER_FANFOLD_LGL_ 41 { German
GERMAN Legal Fanfold
8 12 x 13 in}
DMPAPER_ISO_B4 42 { B4 (ISO) 250
x 353 mm}
DMPAPER_JAPANESE_ 43 { Japanese
POSTCARD Postcard 100 x
148 mm}
DMPAPER_9X11 44 { 9 x 11 in}
DMPAPER_10X11 45 { 10 x 11 in}
DMPAPER_15X11 46 { 15 x 11 in}
DMPAPER_ENV_INVITE 47 { Envelope
Invite 220 x
220 mm}
DMPAPER_RESERVED_48 48 { RESERVED--
DO NOT USE}
DMPAPER_RESERVED_49 49 { RESERVED--
DO NOT USE}
DMPAPER_LETTER_EXTRA 50 { Letter Extra
9 \275 x 12 in}
DMPAPER_LEGAL_EXTRA 51 { Legal Extra 9
\275 x 15 in}
DMPAPER_TABLOID_EXTRA 52 { Tabloid
Extra 11.69 x
18 in}
DMPAPER_A4_EXTRA 53 { A4 Extra 9.27
x 12.69
in }

652 Crystal Reports Developer’s Reference

 Constant Value Description
DMPAPER_LETTER_ 54 {Letter
TRANSVERSE Transverse 8
\275 x 11 in}
DMPAPER_A4_TRANSVERSE 55 { A4
Transverse
210 x 297 mm}
DMPAPER_LETTER_EXTRA_ 56 { Letter Extra
TRANSVERSE Transverse
9\275 x 12 in}
DMPAPER_A_PLUS 57 { SuperA-
SuperAA4 227 x
356 mm}
DMPAPER_B_PLUS 58 { SuperB-
SuperBA3 305
x 487 mm}
DMPAPER_LETTER_PLUS 59 { Letter Plus
8.5 x 12.69 in}
DMPAPER_A4_PLUS 60 { A4 Plus 210 x
330 mm}
DMPAPER_A5_TRANSVERSE 61 { A5
Transverse
148 x 210 mm}
DMPAPER_B5_TRANSVERSE 62 { B5 (JIS)
Transverse
182 x 257 mm}
DMPAPER_A3_EXTRA 63 { A3 Extra 322
x 445 mm}
DMPAPER_A5_EXTRA $40 { A5 Extra 174
x 235 mm}
DMPAPER_B5_EXTRA 65 { B5 (ISO)
Extra 201 x 276
mm}
DMPAPER_A2 66 { A2 420 x 594
mm}
DMPAPER_A3_TRANSVERSE 67 { A3
Transverse
297 x 420 mm}
DMPAPER_A3_EXTRA_ 68 { A3 Extra
TRANSVERSE Transverse
322 x 445 mm}

Chapter 6, Crystal Report Engine Reference 653

 Constant Value Description
DMPAPER_LAST
DMPAPER_A3_EXTRA_ DMPAPER_ $100
TRANSVERSE USER
dmPaperLength
Specifies a paper length, in tenths of a millimeter. This parameter
overrides the paper length specified by the dmPaperSize member,
either for custom paper sizes or for such devices as dot-matrix
printers that can print on a variety of page sizes.
dmPaperWidth
Specifies a paper width, in tenths of a millimeter. This parameter
overrides the paper width specified by the dmPaperSize member.
dmScale
Specifies the factor by which the printed output is to be scaled. The
apparent page size is scaled from the physical page size by a factor
of dmScale/100. For example, a letter-size paper with a dmScale
value of 50 would contain as much data as a page of size 17 by 22
inches because the output text and graphics would be half their
original height and width.
dmCopies
Specifies the number of copies printed if the device supports
multiple-page copies.
dmDefaultSource
Specifies the default bin from which the paper is fed. The application
can override this value by using the GETSETPAPERBINS escape.
This member can be one of the following values:

Constant Value
DMBIN_UPPER 1
DMBIN_FIRST DMBIN_UPPER
DMBIN_ONLYONE 1
DMBIN_LOWER 2
DMBIN_MIDDLE 3
DMBIN_MANUAL 4
DMBIN_ENVELOPE 5
DMBIN_ENVMANUAL 6
DMBIN_AUTO 7

654 Crystal Reports Developer’s Reference

 Constant Value
DMBIN_TRACTOR 8
DMBIN_SMALLFMT 9
DMBIN_LARGEFMT 10
DMBIN_LARGECAPACITY 11
DMBIN_CASSETTE 14
DMBIN_FORMSOURCE 15
DMBIN_LAST DMBIN_FORMSOURCE
DMBIN_USER $100 { device specific bins start
here }
NOTE: A range of values is reserved for device-specific bins. To be
consistent with initialization information, the GETSETPAPERBINS
and ENUMPAPERBINS escapes use these values.
dmPrintQuality
Specifies the printer resolution. Following are the four predefined
device-independent values:

Constant Value
DMRES_DRAFT (-1)
DMRES_LOW (-2)
DMRES_MEDIUM (-3)
DMRES_HIGH (-4)

NOTE: If a positive value is given, it specifies the number of dots per

inch (DPI) and is therefore device-dependent.
NOTE: If the printer initializes the dmYResolution member, the
dmPrintQuality member specifies the x-resolution of the printer, in
dots per inch.
dmColor
Specifies whether a color printer is to render color or monochrome
output. Possible values are:

Constant Value
DMCOLOR_MONOCHROME 1
DMCOLOR_COLOR 2

dmDuplex
Specifies duplex (double-sided) printing for printers capable of
duplex printing. This member can be one of the following values:

Chapter 6, Crystal Report Engine Reference 655

 Constant Value
DMDUP_SIMPLEX (1)
DMDUP_VERTICAL (2)
DMDUP_HORIZONTAL (3)

dmYResolution
Specifies the y-resolution of the printer, in dots per inch. If the printer
initializes this member, the dmPrintQuality member specifies the x-
resolution of the printer, in dots per inch.
dmTTOption
Specifies how TrueType fonts should be printed. It can be one of the
following values:

Constant Value Description

DMTT_BITMAP 1 { print TT fonts as
graphics }
DMTT_DOWNLOAD 2 { download TT fonts
as soft fonts }
DMTT_SUBDEV 3 { substitute device
fonts for TT fonts }
DMTT_DOWNLOAD_ 4 { download TT fonts
OUTLINE as outline soft fonts }

dmCollate
Specifies whether collation should be used when printing multiple
copies. (This member is ignored unless the printer driver indicates
support for collation by setting the dmFields member to
DM_COLLATE.) This member can be one of the following values:

Constant Description
DMCOLLATE_FALSE 0
DMCOLLATE_TRUE 1
NOTE: Using DMCOLLATE_TRUE provides faster, more efficient
output for collation, since the data is sent to the device driver just
once, no matter how many copies are required. The printer is told to
simply print the page again.
dmFormName
Windows NT: Specifies the name of the form to use; for
example,"Letter" or "Legal". A complete set of names can be
retrieved by using the EnumForms function. Windows 95: Printer
drivers do not use this member.

656 Crystal Reports Developer’s Reference

 dmLogPixels
Specifies the number of pixels per logical inch.
dmBitsPerPel
Windows NT: Specifies the color resolution, in bits per pixel, of the
display device (for example: 4 bits for 16 colors, 8 bits for 256colors,
or 16 bits for 65536 colors). Windows 95: Display drivers use this
member, for example, in the ChangeDisplaySettings function.
Printer drivers do not use this member.
dmPelsWidth
Windows NT: Specifies the width, in pixels, of the visible device
surface. Windows 95: Display drivers use this member, for example,
in the ChangeDisplaySettings function. Printer drivers do not use
this member.
dmPelsHeight
Windows NT: Specifies the height, in pixels, of the visible device
surface. Windows 95: Display drivers use this member, for example,
in the ChangeDisplaySettings function. Printer drivers do not use
this member.
dmDisplayFlags
Windows NT: Specifies the device's display mode. This member can
be one of the following values:

Constant Value Description

DM_GRAYSCALE 1 Specifies that the
display is a NON-color
device. If this flag is not
set, color is assumed.
DM_INTERLACED 2 Specifies that the
display mode is
interlaced. If the flag is
not set, NON-
interlaced is assumed.
Windows 95: Display
drivers use this
member, for example,
in the
ChangeDisplaySettings
function. Printer
drivers do not use this
member.

Chapter 6, Crystal Report Engine Reference 657

 dmDisplayFrequency
Windows NT: Specifies the frequency, in hertz (cycles per second), of
the display device in a particular mode. Windows 95: Display
drivers use this member, for example, in the ChangeDisplaySettings
function. Printer drivers do not use this member.
dmICMMethod
Windows 95: Specifies how ICM is handled. For a non-ICM
application, this member determines if ICM is enabled or disabled.
For ICM applications, Windows examines this member to determine
how to handle ICM support. This member can be one of the
following predefined values, or a driver-defined value greater than
the value of DMICMMETHOD_USER:
Windows NT: This member is not supported on Windows NT.

Constant Value Description

DMICMMETHOD_NONE 1 Windows 95 only:
Specifies that ICM is
disabled.
DMICMMETHOD_SYSTEM 2 Windows 95 only:
Specifies that ICM is
handled by
Windows.
DMICMMETHOD_DRIVER 3 Windows 95 only:
Specifies that ICM is
handled by the
device driver.
DMICMMETHOD_DEVICE 4 Windows 95 only:
Specifies that ICM is
handled by the
destination device.
The printer driver
must provide a user
interface for setting
this member. Most
printer drivers
support only the
DMICMMETHOD_S
YSTEM or
DMICMMETHOD_N
ONE value. Drivers
for PostScript
printers support all
values.

658 Crystal Reports Developer’s Reference

 Constant Value Description
DMICMMETHOD_USER $100 Device-specific
methods start here
dmICMIntent
Windows 95: Specifies which of the three possible color matching
methods, or intents, should be used by default. This member is
primarily for non-ICM applications. ICM applications can establish
intents by using the ICM functions. This member can be one of the
following predefined values, or a driver defined value greater than
the value of DMICM_USER:
Windows NT: This member is not supported on Windows NT.

DMICM_SATURATE 1 { Maximize color

saturation }
DMICM_CONTRAST 2 {Maximize color contrast }
DMICM_COLORMETRIC 3 {Use specific color metric}
DMICM_USER $100 {Device-specific intents
start here}

dmMediaType
Windows 95: Specifies the type of media being printed on. The
member can be one of the following predefined values, or a driver-
defined value greater than the value of DMMEDIA_USER:
Windows NT: This member is not supported on Windows NT.

Constant Value Description

DMMEDIA_STANDARD 1 Standard paper
DMMEDIA_TRANSPARENCY 2 Transparency
DMMEDIA_GLOSSY 3 Glossy paper

dmDitherType
Windows 95: Specifies how dithering is to be done. The member can
be one of the following predefined values, or a driver-defined value
greater than the value of DMDITHER_USER:
Windows NT: This member is not supported on Windows NT.

Constant Value Description

DMDITHER_NONE 1 No dithering
DMDITHER_COARSE 2 Dither with a
coarse brush

Chapter 6, Crystal Report Engine Reference 659

 Constant Value Description
DMDITHER_FINE 3 Dither with a fine
brush
DMDITHER_LINEART 4 LineArt dithering
DMDITHER_ 5 LineArt dithering
ERRORDIFFUSION
DMDITHER_RESERVED6 6 LineArt dithering
DMDITHER_RESERVED7 7 LineArt dithering
DMDITHER_RESERVED8 8 LineArt dithering
DMDITHER_RESERVED9 9 LineArt dithering
DMDITHER_GRAYSCALE 10 Device does gray-
scaling
DMDITHER_USER 256 Device-specific
dithers start here
dmReserved1
Windows 95: Not used; must be zero.
Windows NT: This member is not supported on Windows NT.
dmReserved2
Windows 95: Not used; must be zero.
Windows NT: This member is not supported on Windows NT.

Remarks: A device driver's private data follows the public portion of the
DEVMODE structure. The size of the public data can vary for
different versions of the structure. The dmSize member specifies the
number of bytes of public data, and the dmDriverExtra member
specifies the number of bytes of private data.

PECharSepFileOptions

Description The PECharSepFileOptions structure contains number and date

information used by the PEOutputToFile function when you select
character separated as your output file format.

660 Crystal Reports Developer’s Reference

VB Type Listing 16-bit
type PECharSepFileOptions
structSize As Integer
UseReportNumberFmt As Integer
UseReportDateFormat As Integer
StringDelimiter As String
FieldDelimiter As String *
(PE_FIELDDELIMITER)
End Type

32-bit
type PECharSepFileOptions
structSize As Integer
UseReportNumberFmt As Integer
reserved1 As Integer
UseReportDateFormat As Integer
reserved2 As Integer
StringDelimiter As String * 1
FieldDelimiter As String *
(PE_FIELDDELIMLEN)
End Type

Members structSize
Specifies the size of the PECharSepFileOptions structure. You must
initialize this number to be the size of whatever it is, for example,
options.structSize = PE_SIZEOF_CHAR_SEP_FILE_OPTIONS.
UseReportNumberFmt
Indicates whether or not the program should save numbers in the
same format (decimal places, negatives, etc.) that you have used in
the report. Pass TRUE if you want the program to use the same
format used in the report, FALSE if you want number saved in a
format that has been optimized for the file format you have selected.
reserved1
(32-bit only. Reserved member used internally. Do not set a value.
UseReportDateFormat
Indicates whether or not the program should save dates in the same
format (MDY, DMY, etc.) that you used in the report. Pass TRUE if
you want the program to use the same format as used in the report,
FALSE if you want dates saved in a format that has been optimized
for the file format you have selected.

Chapter 6, Crystal Report Engine Reference 661

 reserved2
(32-bit only. Reserved member used internally. Do not set a value.
StringDelimeter
Specifies the character you want to use to enclose Alphanumeric
field data in the character separated values format. You can use
whatever character you wish and it must be enclosed in quotes.
FieldDelimiter
Specifies the string you want to use to separate the fields in the
character separated value format. Your string may be up to 16
characters long and must be enclosed in quotes.

PEExportOptions

The PEExportOptions structure contains file format and output

destination information that is used by the PEGetExportOptions and
PEExportTo functions. The information can be gathered by the
PEGetExportOptions function and it is used by the PEExportTo
function for exporting reports.
struct PEExportOptions
{
WORD structSize;
char FAR *formatDLLName;
DWORD formatType;
void FAR *formatOptions;
char FAR *destinationDLLName;
DWORD destinationType;
void FAR *destinationOptions;
};

Members structSize
Specifies the size of the PEExportOptions structure. You must
initialize the member to be the size of whatever it is, for example,
options.structSize = PE_SIZEOF_EXPORT_OPTIONS.
formatDLLName
Specifies the pointer to the null-terminated string that contains the
format DLL name. The DLL you use is determined by the format in
which you want to export your report.

662 Crystal Reports Developer’s Reference

 Select the appropriate DLL name from the table below:

To export in this Use this DLL Use this DLL

format 16-bit 32-bit
Crystal Reports uxfcr.dll u2fcr.dll
Format
Data Interchange uxfwordw.dll u2fwordw.dll
Format
Word for uxfwordw.dll u2fwordw.dll
Windows Format
Word for DOS uxfdoc.dll u2fdoc.dll
Format 16-bit only)
WordPerfect uxfdoc.dll u2fdoc.dll
Format {16-bit
only)
Quattro Pro 5.0 uxfqp.dll u2fqp.dll
(WB1) Format {16-
bit only)
Record Style uxfrec.dll u2frec.dll
Format (column of
values)
Rich Text Format uxfrtf.dll u2frtf.dll
Comma Separated uxfsepv.dll u2fsepv.dll
Values Format
(CSV)
Tab Separated uxfsepv.dll u2fsepv.dll
Values Format
Character uxfsepv.dll u2fsepv.dll
Separated Values
Format
Text Format uxftext.dll u2ftext.dll
(ASCII)
Paginated Text uxftext.dll u2ftext.dll
Format (ASCII)
Tab Separated uxftext.dll u2ftext.dll
Text Format
Lotus 1-2-3 (WKS) uxfwks.dll u2fwks.dll
Lotus 1-2-3 (WK1) uxfwks.dll u2fwks.dll
Lotus 1-2-3 (WK3) uxfwks.dll u2fwks.dll
Excel 2.1 uxfxls.dll u2fxls.dll

Chapter 6, Crystal Report Engine Reference 663

 To export in this Use this DLL Use this DLL
format 16-bit 32-bit
Excel 3.0 uxfxls.dll u2fxls.dll
Excel 4.0 uxfxls.dll u2fxls.dll
Excel 5.0 uxfxls.dll u2fxls.dll
ODBC uxfodbc.dll u2fodbc.dll
HTML uxfhtml.dll u2fhtml.dll
formatType
Specifies the type of format you want to use from those types
supported by the selected DLL. Whether the format DLL you select
supports only one format type (for example, uxfcr.dll) or multiple
format types (for example, uxfdoc.dll), you must still fill in this
member. Select the format type you want to use from the table below:

To export a report in
Use this formatType
this format
Crystal Reports Format UXFCrystalReportType
Data Interchange UXFDIFType
Format
Word for Windows UXFWordWinType
Format
Word for DOS Format UXFWordDosType
WordPerfect Format UXFWordPerfectType
Quattro Pro 5.0 (WB1) UXFQP5Type
Format
Record Style Format UXFRecordType
(column of values)
Rich Text Format UXFRichTextFormatType
Comma Separated UXFCommaSeparatedType
Values Format (CSV)
Tab Separated Values UXFTabSeparatedType
Format
Character Separated UXFCharSeparatedType
Values Format
Text Format (ASCII) UXFTextType
Paginated Text Format UXFPaginatedTextType
(ASCII)
Tab Separated Text UXFTabbedTextType
Format

664 Crystal Reports Developer’s Reference

 To export a report in
Use this formatType
this format
Lotus 1-2-3 (WKS) UXFLotusWksType
Lotus 1-2-3 (WK1) UXFLotusWk1Type
Lotus 1-2-3 (WK3) UXFLotusWk3Type
Excel 2.1 UXFXls2Type
Excel 3.0 UXFXls3Type
Excel 4.0 UXFXls4Type
Excel 5.0 UXFXls5Type
ODBC UXFODBCType
HTML UXFHTML3Type
Microsoft Internet UXFExplorer2Type
Explorer 2 HTML
Netscape 2 HTML UXFNetscape2Type
formatType1 & 2
Visual Basic 32-bit only
formatOptions
Specifies a pointer to a structure that supplies date and number
information. This information is used by the PEExportOptions
structure when you want to export in one of the formats that support
date and number options and you want to hard code your options.
Select the appropriate structure (if needed) from the table below:

To export a report in Use this structure if you want to

this format hard code formatOptions
Data Interchange UXFDIFOptions
Format
Record Style Format UXFRecordStyleOptions
(column of values)
Comma Separated UXFCommaTabSeparatedOptions
Values (CSV)
Tab Separated Values UXFCommaTabSeparatedOptions
Character Separated UXFCharSeparatedOptions
Values
Paginated Text UXFPaginatedTextOptions
ODBC Format UXFODBCOptions
HTML Format UXFHTML3Options

Chapter 6, Crystal Report Engine Reference 665

 WARNING: formatOptions must be pointing to a valid address until
PEStartPrintJob is called.
formatOptions1 & 2
Visual Basic 32-bit only
destinationDLLName
Specifies a pointer to the null-terminated string that contains the
destination DLL name. The DLL you use is determined by the
destination to which you want to export your report. Select the
appropriate DLL name from the table below:

To export a
Use this DLL Use this DLL
report to this name 16-bit name 32-bit
destination
Disk File uxddisk.dll u2ddisk.dll
E-Mail (MAPI) uxdmapi.dll u2dmapi.dll
E-Mail (VIM) uxdvim.dll u2dvim.dll
Microsoft uxdpost.dll u2dpost.dll
Exchange

destinationType
Specifies the type of destination you want to use from those types
supported by the selected DLL. Even if the destinationDLL name
you select supports only one destination type, you must still fill in
this member.
Select the destination type you want to use from the table below:

To export a report to
Use this destinationType
this destination
Disk File UXDDiskType
E-Mail (MAPI) UXDMAPIType
E-Mail (VIM) UXDVIMType
Microsoft Exchange UXDExchFolderType

destinationType1 & 2
Visual Basic 32-bit only
destinationOptions
Specifies a pointer to a structure supplying information used by the
PEExportOptions structure. This information is needed to export a report
and hard code the file name (when exporting to Disk File) or E-mail
message information (when exporting to MAPI or VIM destination).

666 Crystal Reports Developer’s Reference

 Select the appropriate structure (if needed) from the table below:

To export a report to Use this structure if you want to

this destination hard code destinationOptions
Disk File UXDDiskOptions
E-Mail (MAPI) UXDMAPIOptions
E-Mail (VIM) UXDVIMOptions
Microsoft Exchange UXDPostFolderOptions

destinationOptions1 & 2
Visual Basic 32-bit only
WARNING: destinationOptions must be pointing to a valid address
until PEStartPrintJob is called.
NOTE: formatOptions and destinationOptions must be pointing to
valid addresses until PEStartPrintJob is called.

PEExportOptions (Other Declares)

PEExportOptions 16-bit
(VB Type Listing) Type PEExportOptions
StructSize As Integer
FormatDLLName As String * PE_DLL_NAME_LEN
FormatType As Long
FormatOptions As Long
DestinationDLLName As String *
PE_DLL_NAME_LEN
DestinationType As Long
DestinationOptions As Long
NFormatOptionsBytes As Integer
NDestinationOptionsBytes As Integer
End Type

32-bit
Type PEExportOptions
StructSize As Integer
FormatDLLName As String * PE_DLL_NAME_LEN
FormatType1 As Integer
FormatType2 As Integer
FormatOptions1 As Integer
FormatOptions2 As Integer

Chapter 6, Crystal Report Engine Reference 667

 DestinationDLLName As String *
PE_DLL_NAME_LEN
DestinationType1 As Integer
DestinationType2 As Integer
DestinationOptions1 As Integer
DestinationOptions2 As Integer
NFormatOptionsBytes As Integer
NDestinationOptionsBytes As Integer
End Type

PEExportOptions 16-bit
(Delphi Record type
PEExportOptions = record
Listing) structSize: Word;
formatDLLName: PEDllNameType;
formatType: longint;
formatOptions: Pointer;
destinationDLLName: PEDllNameType;
destinationType: longint;
destinationOptions: Pointer;
nFormatOptionsBytes: Word;
nDestinationOptionsBytes: Word;
end;

32-bit
type
PEExportOptions = record
structSize: Word;
formatDLLName: PEDllNameType;
formatType: DWord;
formatOptions: Pointer;
destinationDLLName: PEDllNameType;
destinationType: DWord;
destinationOptions: Pointer;
nFormatOptionsBytes: Word;
nDestinationOptionsBytes: Word;
end;

PEGraphDataInfo

The PEGraphDataInfo structure contains information on the report

data that is used by a graph. The structure is used by
PEGetGraphData to retrieve current data information and by
PESetGraphData to pass new information.

668 Crystal Reports Developer’s Reference

 struct PEGraphDataInfo
{
WORD structSize
short rowGroupN,
colGroupN,
summarizedFieldN,
graphDirection;
};

Members structSize
Specifies the size of the PEGraphDataInfo structure. You must
initialize this member to be the size of the structure, for example:
info.structSize = PE_SIZEOF_GRAPH_DATA_INFO.
rowGroupN
Specifies which group number in the report is used to create the
values in the rows of the graph. Use
PE_GRAPH_DATA_NULL_SELECTION if you don’t want to
specify a value.
colGroupN
Specifies which group number in the report is used to create the
values in the columns of the graph. Use
PE_GRAPH_DATA_NULL_SELECTION if you don’t want to
specify a value.
summarizedFieldN
Specifies which summary field in the report is used to set the values
of the risers in the graph. Summary fields are numbered in order of
their creation. Use PE_GRAPH_DATA_NULL_SELECTION if you
don’t want to specify a value.
graphDirection
For normal group/total report, the direction, is always
PE_GRAPH_COLS_ONLY.
For Cross-Tab reports, use any of the following constant values:

Constant Meaning
PE_GRAPH_ROWS_ONLY Use only row values in
graph.
PE_GRAPH_COLS_ONLY Use only column values in
graph.

Chapter 6, Crystal Report Engine Reference 669

 Constant Meaning
PE_GRAPH_MIXED_ROW_COL Graph by row values, then
by column values.
PE_GRAPH_MIXED_COL_ROW Graph by column values,
then by row values.
PE_GRAPH_UNKNOWN_ The direction of the graph
DIRECTION is unknown.

PEGraphDataInfo (Other Declares)

PEGraphDataInfo 16-bit
(VB Type Listing) Type PEGraphDataInfo
structSize As Integer
RowGroupN As Integer
ColGroupN As Integer
SummarizedFieldN As Integer
GraphDirection As Integer
End Type

32-bit
Type PEGraphDataInfo
structSizeAs Integer
RowGroupNAs Integer
ColGroupNAs Integer
SummarizedFieldN As Integer
GraphDirection As Integer
End Type

PEGraphDataInfo 16-bit
(Delphi Record type
PEGraphDataInfo = record
Listing) structSize: integer;
rowGroupN: integer;
colGroupN: integer;
summarizedFieldN: integer;
graphDirection: integer;
end;

670 Crystal Reports Developer’s Reference

 32-bit
type
PEGraphDataInfo = record
structSize: Word;
rowGroupN: integer;
colGroupN: integer;
summarizedFieldN: integer;
graphDirection: integer;
end;

PEGraphOptions

The PEGraphOptions structure contains information on several

options available with graphs and charts. This structure is used by
PEGetGraphOptions to retrieve the current options, and by
PESetGraphOptions to pass new options.
struct PEGraphOptions
{
WORD structSize;
double graphMaxValue,
double graphMinValue;
BOOL showDataValue,
BOOL showGridLine,
BOOL verticalBars,
BOOL showLegend;
char fontFaceName
[PE_GRAPH_TEXT_LEN];
};

Members structSize
Specifies the size of the PEGraphOptions structure. You must
initialize this member to be the size of the structure, for example:
options.structSize = PE_SIZEOF_GRAPH_OPTIONS.
graphMaxValue
Specifies the maximum value that will appear in the graph. Any
graph values above this value are not charted.
graphMinValue
Specifies the minimum value that will appear in the graph. Any
graph values below this value are not charted.

Chapter 6, Crystal Report Engine Reference 671

 showDataValue
Specifies whether or not to display the numerical value associated
with each riser on the chart. If set to TRUE (1), a value appears in the
graph for each riser.
showGridLine
Specifies whether or not to display grid lines on the graph.
verticalBars
Specifies whether to display the bars in a bar graph vertically or
horizontally.
showLegend
Specifies whether or not to display the graph legend.
fontFaceName
Specifies the font for all text and values in the entire graph.

PEGraphOptions (Other Declares)

PEGraphOptions 16-bit
(VB Type Listing) Type PEGraphOptions
structSize As Integer
GraphMaxValue As Double
GraphMinValue As Double
ShowDataValue As Integer
ShowGridLine As Integer
VerticalBars As Integer
ShowLegend As Integer
FontFaceName As String *
[PE_GRAPH_TEXT_LEN]
End Type

32-bit
Type PEGraphOptions
structSizeAs Integer
GraphMaxValueAs Double
GraphMinValueAs Double
ShowDataValueAs Integer
ShowGridLineAs Integer
VerticalBarsAs Integer
ShowLegend As Integer
FontFaceNameAs String * PE_GRAPH_TEXT_LEN
End Type

672 Crystal Reports Developer’s Reference

PEGraphOptions 16-bit
(Delphi Record type
PEGraphOptions = record
Listing) structSize: Word;
graphMaxValue: Double;
graphMinValue: Double;
showDataValue: Bool;
showGridLine: Bool;
verticalBars: Bool;
showLegend: Bool;
fontFaceName: PEGraphTextType;
end;

32-bit
type
PEGraphOptions = record
structSize: Word;
graphMaxValue: Double;
graphMinValue: Double;
showDataValue: Bool;
showGridLine: Bool;
verticalBars: Bool;
showLegend: Bool;
fontFaceName: PEGraphTextType;
end;

PEGraphTextInfo

The PEGraphTextInfo structure contains information about the title

and footnote text that appears with a graph. It is used to retrieve
current values by the PEGetGraphText function and to pass new
values by the PESetGraphText function.
struct PEGraphTextInfo
{
WORD structSize;
char graphTitlePE_GRAPH_TEXT_LEN;
char graphSubTitlePE_GRAPH_TEXT_LEN;
char graphFootNotePE_GRAPH_TEXT_LEN;
char graphGroupsTitlePE_GRAPH_TEXT_LEN;
char graphSeriesTitlePE_GRAPH_TEXT_LEN;
char graphXAxisTitlePE_GRAPH_TEXT_LEN;
char graphYAxisTitlePE_GRAPH_TEXT_LEN;
char graphZAxisTitlePE_GRAPH_TEXT_LEN;
};

Chapter 6, Crystal Report Engine Reference 673

Members structSize
Specifies the size of the PEGraphTextInfo structure. You must
initialize this member to be the size of the structure, for example:
info.structSize = PE_SIZEOF_GRAPH_TEXT_INFO
graphTitle
Specifies the main title text that will appear above your graph.
graphSubTitle
Specifies the sub title text that will appear directly under the main
title.
graphFootNote
Specifies the footnote text that will appear under your graph.
graphGroupsTitle
Specifies the title of the groups which are being graphed.
graphSeriesTitle
Specifies the title of the series which is being graphed.
graphXAxisTitle
Specifies the title text that will appear for the X axis. Not valid for Pie
graphs.
graphYAxisTitle
Specifies the title text that will appear for the Y axis. Not valid for Pie
graphs.
graphZAxisTitle
Specifies the title text that will appear for the Z axis. This value is
only valid for 3D graphs.

PEGraphTextInfo (Other Declares)

PEGraphTextInfo 16-bit
(VB Type Listing) Type PEGraphTextInfo
structSize As Integer
GraphTitle As String * [PE_GRAPH_TEXT_LEN]
GraphSubTitle As String *
[PE_GRAPH_TEXT_LEN]
GraphFootNote As String *

674 Crystal Reports Developer’s Reference

 [PE_GRAPH_TEXT_LEN]
GraphGroupsTitle As String *
[PE_GRAPH_TEXT_LEN]
GraphSeriesTitle As String *
[PE_GRAPH_TEXT_LEN]
GraphXAxisTitle As String *
[PE_GRAPH_TEXT_LEN]
GraphYAxisTitle As String *
[PE_GRAPH_TEXT_LEN]
GraphZAxisTitle As String *
[PE_GRAPH_TEXT_LEN]
End Type

32-bit
Type PEGraphTextInfo
structSizeAs Integer
GraphTitleAs String * PE_GRAPH_TEXT_LEN
GraphSubTitleAs String * PE_GRAPH_TEXT_LEN
GraphFootNoteAs String * PE_GRAPH_TEXT_LEN
GraphGroupsTitleAs String *
PE_GRAPH_TEXT_LEN
GraphSeriesTitleAs String *
PE_GRAPH_TEXT_LEN
GraphXAxisTitleAs String *
PE_GRAPH_TEXT_LEN
GraphYAxisTitleAs String *
PE_GRAPH_TEXT_LEN
GraphZAxisTitleAs String *
PE_GRAPH_TEXT_LEN
End Type

PEGraphTextInfo 16-bit
(Delphi Record type
PEGraphTextInfo = record
Listing) structSize: Word;
graphTitle: PEGraphTextType;
graphSubTitle: PEGraphTextType;
graphFootNote: PEGraphTextType;
graphGroupsTitle: PEGraphTextType;
graphSeriesTitle: PEGraphTextType;
graphXAxisTitle: PEGraphTextType;
graphYAxisTitle: PEGraphTextType;
graphZAxisTitle: PEGraphTextType;
end;

Chapter 6, Crystal Report Engine Reference 675

 32-bit
type
PEGraphTextInfo = record
structSize: Word;
graphTitle: PEGraphTextType;
graphSubTitle: PEGraphTextType;
graphFootNote: PEGraphTextType;
graphGroupsTitle: PEGraphTextType;
graphSeriesTitle: PEGraphTextType;
graphXAxisTitle: PEGraphTextType;
graphYAxisTitle: PEGraphTextType;
graphZAxisTitle: PEGraphTextType;
end;

PEJobInfo

The PEJobInfo structure retrieves print job process and display

information data that is used by the PEGetJobStatus function.
struct PEJobInfo
{
WORD structSize;
DWORD NumRecordsRead,
NumRecordsSelected,
NumRecordsPrinted;
WORD DisplayPageN,
LatestPageN,
StartPageN;
BOOL printEnded;
};

Members structSize
Specifies the size of the PEJobInfo structure. You must initialize this
member to be the size of whatever it is, for example, job.structSize =
PE_SIZEOF_JOB_INFO.
NumRecordsRead
Specifies the number of records actually processed.
NumRecordsSelected
Specifies the number of records selected for inclusion in the report
out of the total number of records read.

676 Crystal Reports Developer’s Reference

 NumRecordsPrinted
Specifies the number of pages actually printed.
DisplayPageN
Specifies the page number of the currently displayed page.
LatestPageN
Specifies the number of the last page that’s currently available. Once
the printing is complete, this value is the number of the last page.
StartPageN
Specifies the number of the starting page. The value will normally be
1, but you can specify something else using PESetPrintOptions.
printEnded
Specifies whether or not the printing process is completed. TRUE
indicates that this process is completed; FALSE indicates that is not
yet complete.

PEJobInfo (Other Declares)

PEJobInfo 16-bit
(VB Type Listing) Type PEJobInfo
StructSize As Integer
NumRecordsRead As Long
NumRecordsSelected As Long
NumRecordsPrinted As Long
DisplayPageN As Integer
LatestPageN As Integer
StartPageN As Integer
PrintEnded As Integer
End Type

32-bit
Type PEJobInfo
StructSize As Integer
NumRecordsRead As Long
NumRecordsSelected As Long
NumRecordsPrinted As Long
DisplayPageN As Integer
LatestPageN As Integer
StartPageN As Integer
PrintEnded As Long
End Type

Chapter 6, Crystal Report Engine Reference 677

PEJobInfo 16-bit
(Delphi Record type
PEJobInfo = record
Listing) structSize: Word;
NumRecordsRead: Longint;
NumRecordsSelected: Longint;
NumRecordsPrinted : Longint;
DisplayPageN: Word;
LatestPageN: Word;
StartPageN: Word;
PrintEnded: Bool;
end;

32-bit
type
PEJobInfo = record
structSize: Word;
NumRecordsRead: Longint;
NumRecordsSelected: Longint;
NumRecordsPrinted: Longint;
DisplayPageN: Word;
LatestPageN: Word;
StartPageN: Word;
PrintEnded: Bool;
end;

PELogOnInfo

The PELogOnInfo structure contains log on information that is used

by the PEGetNthTableLogOnInfo, PESetNthTableLogOnInfo,
PELogOnServer, and PELogOffServer functions. The structure is
used by the PEGetNthTableLogOnInfo function to retrieve log on
information and it is used by the PESetNthTableLogOnInfo,
PELogOnServer, and PELogOffServer functions for logging on and
off of SQL and password-protected non-SQL databases.
struct PELogOnInfo
{
WORD structSize;
char ServerName [128];
char DatabaseName [128];
char UserID [128];
char Password [128];
};

678 Crystal Reports Developer’s Reference

Members structSize
Specifies the size of the PELogOnInfo structure. You must initialize
this member to the size of whatever it is, for example, info.structSize
= PE_SIZEOF_LOGON_INFO.
ServerName
Specifies the logon name for the server used to create the report. *For
ODBC, use the data source name.
DatabaseName
Specifies the logon name for the database used to create the report. *
UserIDn
Specifies the user I.D.# necessary to log on to the server. *
Password
Specifies the password necessary to log on to the server. When
you’re using this structure to retrieve information using the
PEGetNthTableLogOnInfo function, the password parameter is
undefined.
*When you pass an empty string (“”) for this parameter, the program
uses the value that’s already set in the report. If you want to override
a value that’s already set in the report, use a non-empty string (e.g.,
"Server A"). All strings must be null-terminated.

Remarks For Netware SQL, pass the dictionary path name in ServerName and
data path name in DatabaseName.

PELogOnInfo (Other Declares)

PELogOnInfo 16-bit
(VB Type Listing) Type PELogOnInfo
structSize As Integer
ServerName As String * PE_SERVERNAME_LEN
DatabaseName As String *
PE_DATABASENAME_LEN
UserID As String * PE_USERID_LEN
Password As String * PE_PASSWORD_LEN
End Type

Chapter 6, Crystal Report Engine Reference 679

 32-bit
Type PELogOnInfo
structSize As Integer
ServerName As String * PE_SERVERNAME_LEN
DatabaseName As String *
PE_DATABASENAME_LEN
UserID As String * PE_USERID_LEN
Password As String * PE_PASSWORD_LEN
End Type

PELogOnInfo 16-bit
(Delphi Record type
PELogOnInfo = record
Listing) structSize: Word;
ServerName: PELogonServerType;
DatabaseName: PELogonDbType;
UserId: PELogonUserType;
Password: PELogonPassType;
end;

32-bit
type
PELogOnInfo = record
structSize: Word;
ServerName: PELogonServerType;
DatabaseName: PELogonDbType;
UserId: PELogonUserType;
Password: PELogonPassType;
end;

PEParameterFieldInfo

The PEParameterFieldInfo structure contains information that is

used by the PEGetNthParameterField and PESetNthParameterField
functions. The structure is used by the PEGetNthParameterField
function to retrieve current information and by the
PESetNthParameterField function to pass new information.
struct PEParameterFieldInfo
{
WORD structSize;
WORD ValueType;
WORD DefaultValueSet;

680 Crystal Reports Developer’s Reference

 WORD CurrentValueSet;
char Name [PE_PF_NAME_LEN];
char Prompt [PE_PF_PROMPT_LEN];
char DefaultValue [PE_PF_VALUE_LEN];
char CurrentValue [PE_PF_VALUE_LEN];
} ;

Members structSize
(when used with Specifies the size of the PEParameterFieldInfo structure. You must
initialize this member to the size of whatever it is, for example,
PEGetNth info.structSize = PE_SIZEOF_PARAMETER_FIELD_INFO.
ParameterField) ValueType
Specifies the data type of the parameter field. The Report Engine
supports the following data types: number, currency, Boolean, date,
and string. Use the appropriate constant from the list below.

Data Type Constant

Number PE_PF_NUMBER
Currency PE_PF_CURRENCY
Boolean PE_PF_BOOLEAN
Date PE_PF_DATE
String PE_PF_STRING
Date/Time PE_PF_DATETIME
Time PE_PF_TIME

DefaultValueSet
Indicates whether or not a default value was set for the parameter
field when the parameter field was created or modified in Crystal
Reports. The value can be either TRUE (1) if the field was given a
default value or FALSE (0) if it was not.
CurrentValueSet
If PEStartPrintJob has not been called, this parameter will equal 0.
Since the print job hasn’t been started, there is no current value set by
code or by the user.
If PEStartPrintJob has been called, and the user has entered a
parameter and said OK to the prompt, this parameter will equal 1
(TRUE) if the user enters a value at the prompt and 0 (FALSE) if the
user clicks Cancel.

Chapter 6, Crystal Report Engine Reference 681

 Name
Specifies the name of the parameter field assigned by the user when
the parameter was inserted into the report or the name that was set
from code.
Prompt
Specifies the prompting text, if any, that appears when the user runs
the report for the first time or refreshes the data. This will be either
the prompt assigned by the user when the parameter field was
inserted into the report or the prompt that was set from code.
DefaultValue
Specifies the default value assigned to the parameter field if one was
set. If the DefaultValueSet member is false, this value is meaningless.
CurrentValue
If PEStartPrintJob has not been called, this value does not apply.
There is no current value as yet set by code or by the user.
If PEStartPrintJob has been called, this will be the value entered by
the user. If the user clicked Cancel, this value is meaningless.

Members With PESetNthParameterField, there are two primary uses:

(when used with ● To set the default value, prompt, and the name on the tab using
code.
PESetNth
● To set the current value so the parameter does not prompt.
ParameterField
Settings for both alternatives are specified below:
structSize
Specifies the size of the PEParameterFieldInfo structure. You must
initialize this member to the size of whatever it is, for example,
info.structSize = PE_SIZEOF_PARAMETER_FIELD_INFO.
ValueType
Specifies the data type of the parameter field. The Report Engine
supports the following data types: number, currency, Boolean, date,
and string. Use the appropriate constant from the list below.

Data Type Constant

Number PE_PF_NUMBER
Currency PE_PF_CURRENCY
Boolean PE_PF_BOOLEAN
Date PE_PF_DATE
String PE_PF_STRING

682 Crystal Reports Developer’s Reference

 DefaultValueSet
When setting the default value from code, set this value to 1:(TRUE).
When setting the current value so the parameter does not prompt, set
this to either 1 (TRUE) or 2 (FALSE). The setting doesn’t matter in
this case.
CurrentValueSet
When setting the default value, prompt, and name on tab from code,
set this value to 0 (FALSE).
When setting the current value so the parameter does not prompt, set
this value to 1 (TRUE).
Name
When setting the name from code, set this to the name you wish to
appear on the tab of the dialog box.
When setting the current value so the parameter does not prompt, set
this to an Empty String (“”)
Prompt
When setting the prompt from code, set this to the prompt you want
the user to see.
When setting the current value so the parameter does not prompt, set
this to an Empty String (“”).
DefaultValue
When setting the default value from code, set the default value you
want the user to be prompted with.
When setting the current value so the parameter does not prompt, set
this to an Empty String (“”).
CurrentValue
When setting the default value, prompt, and name from code, set this
to an Empty String (“”).
When setting the current value so the parameter does not prompt, set
this to the value you want the parameter to use in the report.

Remarks Strings must be null terminated.

Chapter 6, Crystal Report Engine Reference 683

PEParameterFieldInfo (Other Declares)

This structure is used differently in different circumstances. Please

see the discussion in PEParameterFieldInfo.

PEParameter 16-bit
FieldInfo Type PEParameterFieldInfo
structSize As Integer
(VB type listing) ValueType As Integer
DefaultValueSet As Integer
CurrentValueSet As Integer
Name As String * PE_PF_NAME_LEN
Prompt As String * PE_PF_PROMPT_LEN
DefaultValue As String * PE_PF_VALUE_LEN
CurrentValue As String * PE_PF_VALUE_LEN
End Type

32-bit
Type PEParameterFieldInfo
structSize As Integer
ValueType As Integer
DefaultValueSet As Integer
CurrentValueSet As Integer
Name As String * PE_PF_NAME_LEN
Prompt As String * PE_PF_PROMPT_LEN
DefaultValue As String * PE_PF_VALUE_LEN
CurrentValue As String * PE_PF_VALUE_LEN
End Type

PEParameter 16-bit
FieldInfo type
PEParameterFieldInfo = record
(Delphi listing) structSize: Word;
ValueType: Word;
DefaultValueSet: Word;
CurrentValueSet: Word;
Name: PEPromptVarNameType;
Prompt: PEPromptVarTextType;
DefaultValue: PEPromptVarValueType;
CurrentValue: PEPromptVarValueType;
end;

684 Crystal Reports Developer’s Reference

 32-bit
type
PEParameterFieldInfo = record
structSize: Word;
ValueType: Word;
DefaultValueSet: Word;
CurrentValueSet: Word;
Name: PEParameterFieldNameType;
Prompt: PEParameterFieldTextType;
DefaultValue: PEParameterFieldValueType;
CurrentValue: PEParameterFieldValueType;
end;

PEParameterInfo

The PEParameterInfo structure contains information that is used by

the PEGetNthParamInfo function. The function uses the structure to
gather information about an existing stored procedure parameter.
NOTE: Use this function/structure when you are working with stored
procedure parameters, not with parameter fields.
struct PEParameterInfo
{
WORD structSize;
WORD Type;
char Name [PE_PARAMETER_NAME_LEN];
} ;

Members structSize
Specifies the size of the PEParameterInfo structure. You must
initialize this member to be the size of whatever it is, for example,
info.structSize = PE_SIZEOF_PAREMETER_INFO.
Type
Specifies the data type of the parameter. The Report Engine supports
the following data types: number, currency, Boolean, date, and
string.
Use the appropriate constant from the list below.

Data Type Constant

Number PE_PF_NUMBER
Currency PE_PF_CURRENCY

Chapter 6, Crystal Report Engine Reference 685

 Data Type Constant
Boolean PE_PF_BOOLEAN
Date PE_PF_DATE
String PE_PF_STRING
Date/Time PE_PF_DATETIME
Time PE_PF_TIME
Name
Specifies the name of the parameter in a null-terminated string.

PEParameterInfo (Other Declares)

PEParameterInfo 16-bit
(VB Type Listing) Type PEParameterInfo
structSize As Integer
Type As Integer
name As String * PE_PARAMETER_NAME_LEN
End Type

32-bit
Type PEParameterInfo
structSize As Integer
Type As Integer
Name As String * PE_PARAMETER_NAME_LEN
End Type

PEParameterInfo 16-bit
(Delphi Record type
PEParameterInfo = record
Listing) structSize: Word;
paramType: Word;
Name: PEProcParamNameType;
end;

32-bit
type
PEParameterInfo = record
structSize: Word;
paramType: Word;
Name: PEProcParamNameType;
end;

686 Crystal Reports Developer’s Reference

PEPrintFileOptions

The PEPrintFileOptions structure contains number and date

information used by the PEOutputToFile function when you select
any output file format other than Character Separated.

PEPrintFileOptions 16 -bit
(VB Type Listing) type PEPrintFileOptions
structSize As Integer
UseReportNumberFmt As Integer
UseReportDateFormat As Integer
End Type

32 -bit
type PEPrintFileOptions
structSize As Integer
UseReportNumberFmt As Integer
reserved1 As Integer
UseReportDateFormat As Integer
reserved2 As Integer
End Type

Members structSize
Specifies the size of the PEPrintFileOptions structure. You must
initialize this member to be the size of whatever it is, for example,
printfile.structSize = PE_SIZEOF_PRINT_FILE_OPTIONS.
UseReportNumberFmt
Indicates whether or not the program should save numbers in the
same format (decimal places, negatives, etc.) that you have used in
the report. Pass TRUE if you want the program to use the same
format used in the report, FALSE if you want number saved in a
format that has been optimized for the file format you have selected.
reserved1
32- bit only. A reserved member. Do not set a value.
UseReportDateFormat
Indicates whether or not the program should save dates in the same
format (MDY, DMY, etc.) that you used in the report. Pass TRUE if
you want the program to use the same format as used in the report,
FALSE if you want dates saved in a format that has been optimized
for the file format you have selected.

Chapter 6, Crystal Report Engine Reference 687

 reserved2
32- bit only. A reserved member. Do not set a value.

PEPrintOptions

The PEPrintOptions structure contains printing specifications that

are used by the PEGetPrintOptions and PESetPrintOptions
functions. The PEGetPrintOptions function uses the structure to
retrieve current options and the PESETPrintOptions functions uses it
to pass new options. These specifications are the same as those that
can be set using the Print common dialog box.
struct PEPrintOptions
{
WORD structSize;
unsigned shortstartPageN,stopPageN;
unsigned shortnReportCopies;
unsigned shortcollation;
};

Members structSize
Specifies the size of the PEPrintOptions structure. You must initialize
this member to be the size of whatever it is, for example,
options.structSize = PE_SIZEOF_PRINT_OPTIONS.
startPageN
Specifies the first page that you want to print. Page numbers are 1
origin (Page 1 = 1, Page 2 = 2, etc.). Enter 0 if you want to retain the
existing settings.
stopPageN
Specifies the last page that you want to print. Page numbers are 1
origin (Page 1 = 1, Page 2 = 2, etc.). Enter 0 if you want to retain the
existing settings.
nReportCopies
Specifies the number of copies you want to print. Copy numbers, like
page numbers, are 1 origin. Enter 0 if you want to retain the existing
settings.
collation
Indicates whether or not you want the program to collate the copies
(if you are printing multiple copies of a multiple page report).

688 Crystal Reports Developer’s Reference

 For this parameter, use one of the following constants:

Constant Action
PE_UNCOLLATED Prints multiple copies of a
multiple page report uncollated
(Page order = 1, 1, 1, 2, 2, 2, 3, 3, 3,
etc.)
PE_COLLATED Prints multiple copies of a
multiple page report collated
(Page order = 1, 2, 3, ..., 1, 2, 3, ...,
etc.)
PE_DEFAULTCOLLATION Prints multiple copies of a
multiple page report using the
collation settings as specified in
the report.

PEPrintOptions (Other Declares)

PEPrintOptions 16-bit
(VB Type Listing) Type PEPrintOptions
structSize As Integer
StartPageN As Integer
stopPageN As Integer
nReportCopies As Integer
collation As Integer
End Type

32-bit
Type PEPrintOptions
structSize As Integer
StartPageN As Integer
stopPageN As Integer
nReportCopies As Integer
collation As Integer
End Type

Chapter 6, Crystal Report Engine Reference 689

PEPrintOptions 16-bit
(Delphi Record type
PEPrintOptions = record
Listing) structSize: Word;
StartPageN: Word;
StopPageN : Word;
nReportCopies: Word;
Collation: Word;
end;

32-bit
type
PEPrintOptions = record
structSize: Word;
StartPageN: Word;
StopPageN: Word;
nReportCopies: Word;
Collation: Word;
end;

PESectionOptions

The PESectionOptions structure contains specifications for

formatting selected report sections. This information is used by the
PEGetSectionFormat and PESetSectionFormat functions. The
PEGetSectionFormat function uses the structure to retrieve current
settings and the PESetSectionFormat function uses it to pass new
settings.
struct PESectionOptions
{
WORD structSize;
short visible,
NewPageBefore,
NewPageAfter,
KeepTogether,
SuppressBlankSection,
ResetPageNAfter,
printAtBottomOfPage,
COLORREF backgroundColor
short underlaySection;
};

690 Crystal Reports Developer’s Reference

Members structSize
Specifies the size of the PESectionOptions structure. You must
initialize this member to be the size of whatever it is, for example,
options.structSize = PE_SIZEOF_SECTION_OPTIONS.
visible
Specifies whether or not the selected section is to be visible. Pass
TRUE to keep the section visible, FALSE to hide the section.
NewPageBefore
Specifies whether or not the program is to insert a page break before
the section is printed. Pass TRUE to insert a page break, FALSE not
to insert a page break.
NewPageAfter
Specifies whether or not the program is to insert a page break after
the section is printed. Pass TRUE to insert a page break, FALSE not
to insert a page break.
KeepTogether
Specifies whether or not the program is to keep all lines of the section
together, either on the current page (if there is room) or on the next
(if not). Pass TRUE to keep the lines together, FALSE to allow the
program to split section data from one page to the next if necessary.
SuppressBlankSection
Specifies whether or not the program is to eliminate blank sections
from your report. A section must be completely empty before the
program suppresses. Pass TRUE to eliminate the blank sections,
FALSE to retain them.
resetPageNAfter
Specifies whether or not the program is to reset the page number to
one (1) for the following page, after it prints a group total. Pass TRUE
to reset the page number, FALSE to retain the standard numbering.
printAtBottomOfPage
Specifies whether or not the program is to cause each group value to
print only at the bottom of a page; FALSE to have the values print in
their normal position.
backgroundColor
Specifies the RGB color value contained in the COLORREF structure.

Chapter 6, Crystal Report Engine Reference 691

 underlaySection
Indicates whether or not the specified section is to underlay the
following section(s).
1. All of the structure members except backgroundColor are Boolean
values. Use PE_UNCHANGED if you want to preserve the
existing settings.
2. Not all options are available for all sections. For example, if you
select a Page Header or page Footer Section, you can not change
NewPageBefore or NewPageAfter. The only options that are
available for all sections are visible and SuppressBlankSection.

PESectionOptions (Other Declares)

PESectionOptions 16-bit
(VB Type Listing) Type PESectionOptions
structSize As Integer
visible As Integer
NewPageBefore As Integer
NewPageAfter As Integer
KeepTogether As Integer
SuppressBlankSection As Integer
resetPageNAfter As Integer
printAtBottomOfPage As Integer
backgroundColor As Long
underlaySection As Integer
End Type

32-bit
Type PESectionOptions
structSize As Integer
Visible As Integer
NewPageBefore As Integer
NewPageAfter As Integer
KeepTogether As Integer
SuppressBlankSection As Integer
ResetPageNAfter As Integer
PrintAtBottomOfPage As Integer
backgroundColor As Long
underlaySection As Integer
End Type

692 Crystal Reports Developer’s Reference

PESectionOptions 16-bit
(Delphi Record type
PESectionOptions = record
Listing) structSize: integer;
visible: integer;
newPageBefore: integer;
newPageAfter: integer;
keepTogether: integer;
suppressBlankSection: integer;
resetPageNAfter: integer;
printAtBottomOfPage: integer;
backgroundColor: Longint;
underlaySection: integer;
end;

32-bit
type
PESectionOptions = record
structSize: Word;
visible: integer;
newPageBefore: integer;
newPageAfter: integer;
keepTogether: integer;
suppressBlankSection: integer;
resetPageNAfter: integer;
printAtBottomOfPage: integer;
backgroundColor: COLORREF;
underlaySection: integer;
end;

PESessionInfo

The PESessionInfo structure contains information about the current

Microsoft Access session. Use this structure with
PEGetNthTableSessionInfo (to retrieve current information) and
PESetNthTableSessionInfo (to pass new information).
struct PESessionInfo
{
WORD structSize;
char UserID [PE_SESS_PASSWORD_LEN];
char Password [PE_SESS_PASSWORD_LEN];
DWORD SessionHandle;
};

Chapter 6, Crystal Report Engine Reference 693

Members structSize
Specifies the size of the PESessionInfo structure. You must initialize
this member to be the size of whatever it is, for example
location.structSize = PE_SIZEOF_SESSION_INFO
UserID
Specifies the user I.D. value needed for logging onto the system.
Password
Specifies the password needed for logging onto the system.
SessionHandle
The handle to the current MS Access session.

Remarks When using this structure with PEGetNthTableSessionInfo, the

password member is not defined. You specify the password when
using the structure with PESetNthTableSessionInfo.
The SessionHandle member is likewise undefined with the
PEGetNthTableSessionInfo function. When you’re using the
PESetNthTableSessionInfo structure, if the SessionHandle value is 0,
the Report Engine uses the UserID and Password settings. In all
other cases it uses the SessionHandle value.

PESessionInfo (Other Declares)

PESessionInfo 16-bit
(VB Type Listing) Type PESessionInfo
structSize As Integer
UserID As String * PE_SESS_USERID_LEN
Password As String * PE_SESS_PASSWORD_LEN
SessionHandle As Long
End Type

32-bit
Type PESessionInfo
structSize As Integer
UserID As String * PE_SESS_USERID_LEN
Password As String * PE_SESS_PASSWORD_LEN
SessionHandle As Long
End Type

694 Crystal Reports Developer’s Reference

PESessionInfo 16-bit
(Delphi Record type
PESessionInfo = record
Listing) structSize: Word;
UserID: PESesPassType;
Password: PESesPassType;
SessionHandle: longint;
end;

32-bit
type
PESessionInfo = record
StructSize: Word;
UserID: PESesPassType;
Password: PESesPassType;
SessionHandle: DWORD;
end;

PESubreportInfo

The PESubreportInfo structure is used by the PEGetSubreportInfo

function to gather information about a specified subreport.
struct PESubreportInfo
{
WORD structSize;
char name [PE_SUBREPORT_NAME_LEN];
} ;

Members structSize
Specifies the size of the PESubreportInfo structure. You must
initialize this member to be the size of whatever it is, for example
location.structSize = PE_SIZEOF_SUBREPORT_INFO
name
Specifies the name of the subreport. This is the name assigned to the
subreport when it was first created.

Chapter 6, Crystal Report Engine Reference 695

PESubreportInfo (Other Declares)

PESubreportInfo 16-bit
(VB Type Listing) Type PESubreportInfo
structSize As Integer
Name As String * PE_SUBREPORT_NAME_LEN
End Type

32-bit
Type PESubreportInfo
structSize As Integer
Name As String * PE_SUBREPORT_NAME_LEN
End Type

PESubreportInfo 16-bit
(Delphi Record type
PESubreportInfo = record
Listing) structSize: Word;
name: PESubreportNameType;
end;

32-bit
type
PESubreportInfo = record
structSize: Word;
name: PESubreportNameType;
end;

Related Topics
Working with subreports 36

PETableLocation

The PETableLocation structure contains database location

information that is used with the PEGetNthTableLocation and
PESetNthTableLocation functions. The PEGetNthTableLocation
function uses the structure to gather current location information
and the PESetNthTableLocation function uses it to pass new location
information.

696 Crystal Reports Developer’s Reference

 struct PETableLocation
{
WORD structSize;
char Location [256];
};

Members structSize
Specifies the size of the PETableLocation structure. You must
initialize this member to be the size of whatever it is, for example
location.structSize = PE_SIZEOF_TABLE_LOCATION.
Location
Specifies the database location. This member is database dependent
and must be formatted correctly for the expected database, for
example:
● xBASE (Natively): <drive>:\<path>\<file>
● xBASE (ODBC): <datasource name>
● Paradox (Natively): <drive>:\<path>\<file>
● Paradox (ODBC): <datasource name>
● Btrieve (Natively): <drive>:\<path>\<file>
● Btrieve (ODBC): <datasource name>
● Oracle (Natively): <database>.<table>
● Oracle (ODBC): <database>.<table>
● SQL Server (Natively): <database>.<owner>.<table>
● SQL Server (ODBC): <database>.<owner>.<table>

PETableLocation (Other Declares)

PETableLocation 16-bit
(VB Type Listing) Type PETableLocation
structSize As Integer
Location As String * PE_TABLE_LOCATION_LEN
End Type

Chapter 6, Crystal Report Engine Reference 697

 32-bit
Type PETableLocation
structSize As Integer
Location As String * PE_TABLE_LOCATION_LEN
End Type

PETableLocation 16-bit
(Delphi Record type
PETableLocation = record
Listing) structSize: Word;
Location: PETableLocType;
end;

32-bit
type
PETableLocation = record
structSize: Word;
Location: PETableLocType;
end;

PETableType

The PETableType structure contains information for identifying the

type of a specified table. This information is gathered using the
PEGetNthTableType function.
struct PETableType
{
WORD structSize;
char DLLName [64];
char DescriptiveName [256];
WORD DBType;
};

Members structSize
Specifies the size of the PETableType structure. You must initialize
this member to be the size of whatever it is, for example,
TableType.structSize = PE_SIZEOF_TABLE_TYPE.
DLLName
Specifies the name of the appropriate database DLL for the table of
interest (in quotes).

698 Crystal Reports Developer’s Reference

 Select the DLL you want to use from the table below:

For this standard non-SQL

Use this DLL database
pdbbde.dll Borland Database Engine
pdbbnd.dll Bound reports
pdbdao.dll DAO data sources (Access)
pdbjet.dll Access
pdbpdx.dll Paradox
pdbxbse.dll dBASE, FoxPro, Clipper
pdctbtrv.dll Btrieve

Use this DLL For this SQL database

pdsdb22.dll DB2/2
pdsgupta.dll Gupta
pdsnetw.dll Netware
pdsodbc.dll ODBC
pdsoracl.dll Oracle
pdssyb10.dll
pdssybas.dll Sybase

DescriptiveName
Specifies the name of the table of interest (in quotes).
DBType
Specifies the type of database that contains the table of interest. Select
DB type from the table below:

Value Meaning
PE_DT_STANDARD The type for standard, non-SQL
databases.
PE_DT_SQL The type for SQL databases.

Chapter 6, Crystal Report Engine Reference 699

PETableType (Other Declares)

PETableType 16-bit
(VB Type Listing) Type PETableType
structSize As Integer
DLLName As String * PE_DLL_NAME_LEN
DescriptiveName As String *
PE_FULL_NAME_LEN
DBType As Integer
End Type

32-bit
Type PETableType
structSize As Integer
DLLName As String * PE_DLL_NAME_LEN
DescriptiveName As String *
PE_FULL_NAME_LEN
DBType As Integer
End Type

PETableType 16-bit
(Delphi Record type
PETableType = record
Listing) structSize: Word;
DLLName: PEDllNameType;
DescriptiveName: PEFullNameType;
DBType: Word;
end;

32-bit
type
PETableType = record
structSize: Word;
DLLName: PEDllNameType;
DescriptiveName: PEFullNameType;
DBType: Word;
end;

700 Crystal Reports Developer’s Reference

UXDDiskOptions

The UXDDiskOptions structure contains file name information that

is used by the PEExportOptions structure when you want to export
to a disk file.
struct UXDDiskOptions
{
WORD structSize;
char FAR *fileName;
};

Members structSize
Specifies the size of the UXDDiskOptions structure. You must
initialize this member to be the size of whatever it is, for example,
options.structSize = UXDDiskOptionsSize.
fileName
Specifies the pointer to the null-terminated string that contains the
file name under which you want your disk file saved.

UXDDiskOptions (Other Declares)

UXDDiskOptions 16-bit
(Delphi Record type
UXDDiskOptions = record
Listing) structSize: Integer;
fileName: PChar;
end;

32-bit
type
UXDDiskOptions = record
structSize: Word;
fileName: PChar;
end;

Chapter 6, Crystal Report Engine Reference 701

UXDMAPIOptions

The UXDMAPIOptions structure contains E-mail information that

is used by the PEExportOptions structure when you want to export
to a MAPI E-mail destination.
struct UXDMAPIOptions
{
WORD structSize;
char FAR *toList;
char FAR *ccList;
char FAR *subject;
char FAR *message;
WORD nRecipients;
lpMapiRecipDesc recipients;
}

Members structSize
Specifies the size of the UXDMAPIOptions structure. You must
initialize this member to be the size of whatever it is, for example,
options.structSize = UXDMAPIOptionsSize
toList
Specifies the pointer to the null-terminated string that contains the
"To" list to which you want your E-mail message directed. If you
specify "recipients" in this structure, "toList" is ignored.
ccList
Specifies the pointer to the null-terminated string that contains the
"CC" list to which you want your E-mail message copied. This string
will appear on the message. If you specify "recipients" in this
structure, "ccList" is ignored.
subject
Specifies the pointer to the null-terminated string you want to
appear as the subject line in the E-mail message.
message
Specifies the pointer to the null-terminated string you want to
appear as the body of your E-mail message.
nRecipients
Specifies the number of recipients that are to receive the E-mail
message. You must pass the value "0" if you specify "To" and "CC"
lists in this structure.

702 Crystal Reports Developer’s Reference

 recipients
Specifies the pointer to an array of structures, each of which
describes someone to whom the message is being sent or cc'd. This
member is included for those applications that are already using
Microsoft's MAPI.DLL. If you are not using MAPI.DLL in your
application, there is no advantage to using the recipients array over
the toList and ccList. You must pass the value "0" if you specify "To"
and "CC" lists in this structure. For detailed information about this
member, please refer to Microsoft's MAPI documentation.

UXDMAPIOptions (Other Declares)

UXDMAPIOptions 16-bit
(Delphi Record type
UXDMAPIOptions = record
Listing) structSize: integer;
toList: PChar;
ccList: PChar;
subject: PChar;
message: PChar;
end;

32-bit
type
UXDMAPIOptions = record
structSize: Word;
toList: PChar;
ccList: PChar;
subject: PChar;
message: PChar;
end;

UXDPostFolderOptions

The UXDPostFolderOptions structure contains information that is

used by the PEExportOptions structure when you want to export to
Microsoft Exchange.

Chapter 6, Crystal Report Engine Reference 703

 struct UXDPostFolderOptions
{
WORD structSize;
LPSTR *pszProfile;
LPSTR *pszPassword;
WORD wDestType;
LPSTR *pszFolderPath;
};

Members structSize
Specifies the size of the UXDPostFolderOptions structure. You must
initialize this member to be the size of whatever it is, for example,
options.structSize = UXDPostFolderOptionsSize.
pszProfile
Specifies the Exchange profile.
pszPassword
Specifies the Exchange password.
wDestType
Specifies the type of report to export to. Use one of the following

Constant Value Description

UXDExchFolderType 0
UXDPostDocMessage 1009 wDestType for
folder messages
UXDPostPersonalReport 1010 wDestType for
personal report
UXDPostFolderReport 1011 wDestType for
folder report

pszFolderPath
Specifies the Exchange path where you want the program to place
the exported file.

704 Crystal Reports Developer’s Reference

UXDPostFolderOptions (Other Declares)

UXDPostFolder 16-bit
Options type
UXDPostFolderOptions = record
(Delphi Record structSize: Integer;
Listing) pszProfile: PChar;
pszPassword: PChar;
wDestType: Integer;
pszFolderPath: PChar;
end;

32-bit
type
UXDPostFolderOptions = record
structSize: Word;
pszProfile: PChar;
pszPassword: PChar;
wDestType: Word;
pszFolderPath: PChar;
end;

UXDVIMOptions

The UXDVIMOptions structure contains E-mail message

information that is used by the PEExportOptions structure when you
want to export a VIM E-mail destination.
struct UXDVIMOptions
{
WORD structSize;
char FAR *toList;
char FAR *ccList;
char FAR *bccList
char FAR *subject;
char FAR *message;
};
NOTE: VIM is not supported in the 32-bit version of Crystal Reports.

Chapter 6, Crystal Report Engine Reference 705

Members structSize
Specifies the size of the UXDVIMOptions structure. You must
initialize this member to be the size of whatever it is, for example,
options.structSize = UXDVIMOptionsSize.
toList
Specifies the pointer to the null-terminated string that contains the
"To" list to which you want your E-mail message directed.
ccList
Specifies the pointer to the null-terminated string that contains the
"CC" list to which you want your E-mail message copied. This string
will appear on the message.
bccList
Specifies the pointer to the null-terminated string that contains the
"Blind CC" list to which you want your E-mail message copies. This
string will not appear on the message.
subject
Specifies the pointer to the null-terminated string you want to
appear as the subject line in the E-mail message.
message
Specifies the pointer to the null-terminated string you want to
appear as the body of your E-mail message.

UXDVIMOptions (Other Declares)

UXDVIMOptions 16-bit
(Delphi Record type
UXDVIMOptions = record
Listing) structSize: integer;
toList: PChar;
ccList: PChar;
bccList: PChar;
subject: PChar;
message: PChar;
end;

32-bit
Crystal Reports 32-bit does not export to VIM.

706 Crystal Reports Developer’s Reference

UXFCharSeparatedOptions

The UXFCharSeparatedOptions structure contains number and

date information used by the PEExportOptions structure when you
want to export in a Character Separated format and hard code
number and/or date options.
struct UXFCharSeparatedOptions
{
WORD structSize;
BOOL useReportNumberFormat;
BOOL useReportDateFormat;
char stringDelimiter;
char FAR *fieldDelimiter;
};

Members structSize
Specifies the size of the UXFCharSeparatedOptions structure. You
must initialize this member to be the size of whatever it is, for
example, options.structSize = UXFCharSeparatedOptionsSize.
useReportNumberFormat
Indicates whether or not the program should save numbers in the
same format (decimal places, negatives, etc.) that you have used in
the report. Pass TRUE if you want the program to use the same
format used in the report, FALSE if you want the number saved in a
format that has been optimized for the file format you have selected.
useReportDateFormat
Indicates whether or not the program should save dates in the same
format (MDY, DMY, etc.) that you used in the report. Pass TRUE if
you want the program to use the same format as used in the report,
FALSE if you want dates saved in a format that has been optimized
for the file format you have selected
stringDelimiter
Specifies the character you want to use to enclose Alphanumeric
field data in the character separated values format. You can use
whatever character you wish, and it must be enclosed in quotes.
fieldDelimiter
Specifies a pointer to the string you want to use to separate the fields
in the character separated values format. Your string may be up to 16
characters long and must be enclosed in quotes.

Chapter 6, Crystal Report Engine Reference 707

UXFCharSeparatedOptions (Other Declares)

UXFChar 16-bit
SeparatedOptions type
UXFCharSeparatedOptions = record
(Delphi Record structSize: integer;
Listing) useReportNumberFormat: Bool;
useReportDateFormat: Bool;
stringDelimiter: Char;
fieldDelimiter: PChar;
end;

32-bit
type
UXFCharSeparatedOptions = record
structSize: Word;
useReportNumberFormat: Bool;
useReportDateFormat: Bool;
stringDelimiter: Char;
fieldDelimiter: PChar;
end;

UXFCommaTabSeparatedOptions

The UXFCommaTabSeparatedOptions structure contains number

and date information used by the PEExportOptions structure when
you want to export in a Comma separated or Tab separated format
and hard code number and/or date options.
struct UXFCommaTabSeparatedOptions
{
WORD structSize;
BOOL useReportNumberFormat;
BOOL useReportDateFormat;
};

Members structSize
Specifies the size of the UXFCommaTabSeparatedOptions structure.
You must initialize this member to be the size of whatever it is, for
example, options.structSize =
UXFCommaTabSeparatedOptionsSize.

708 Crystal Reports Developer’s Reference

 useReportNumberFormat
Indicates whether or not the program should save numbers in the
same format (decimal places, negatives, etc.) that you have used in
the report. Pass TRUE if you want the program to use the same
format used in the report, FALSE if you want the number saved in a
format that has been optimized for the file format you have selected.
useReportDateFormat
Indicates whether or not the program should save dates in the same
format (MDY, DMY, etc.) that you used in the report. Pass TRUE if
you want the program to use the same format as used in the report,
FALSE if you want dates saved in a format that has been optimized
for the file format you have selected.

UXFCommaTabSeparatedOptions (Other Declares)

UXFCommaTab 16-bit
SeparatedOptions type
UXFCommaTabSeparatedOptions = record
(Delphi Record structSize: integer;
Listing) useReportNumberFormat: Bool;
useReportDateFormat: Bool;
end;

32-bit
type
UXFCommaTabSeparatedOptions = record
structSize: Word;
useReportNumberFormat: Bool;
useReportDateFormat: Bool;
end;

UXFDIFOptions

The UXFDIFOptions structure contains number and date

information used by the PEExportOptions structure when you want
to export in a DIF format (Data Interchange Format) and hard code
number and/or date options.

Chapter 6, Crystal Report Engine Reference 709

 struct UXDIFOptions
{
WORD structSize;
BOOL useReportNumberFormat;
BOOL useReportDateFormat;
};

Members structSize
Specifies the size of the UXFDIFOptions structure. You must
initialize this member to be the size of whatever it is, for example,
options.structSize = UXFDIFOptionsSize.
useReportNumberFormat
Indicates whether or not the program should save numbers in the
same format (decimal places, negatives, etc.) that you have used in
the report. Pass TRUE if you want the program to use the same
format used in the report, FALSE if you want the number saved in a
format that has been optimized for the file format you have selected.
useReportDateFormat
Indicates whether or not the program should save dates in the same
format (MDY, DMY, etc.) that you used in the report. Pass TRUE if
you want the program to use the same format as used in the report,
FALSE if you want dates saved in a format that has been optimized
for the file format you have selected.

UXFDIFOptions (Other Declares)

UXFDIFOptions 16-bit
(Delphi Record type
UXFCommaTabSeparatedOptions = record
Listing) structSize: integer;
useReportNumberFormat: Bool;
useReportDateFormat: Bool;
end;

32-bit
type
UXFDIFOptions = record
structSize: Word;
useReportNumberFormat: Bool;
useReportDateFormat: Bool;
end;

710 Crystal Reports Developer’s Reference

UXFHTML3Options

The UXFHTML3Options structure is used by the PEExportOptions

structure when you are exporting to HTML format.
struct UXFHTML3Options
{
WORD structSize;
char FAR *fileName;
char FAR *baseURLName;
};

Members structSize
Specifies the size of the UXFHTML3Options structure. You must
initialize this member to be the size of whatever it is, for example,
options.structSize = UXFHTML3OptionsSize.
fileName
Specifies a null terminated file name.

UXFHTML3Options (Other Declares)

UXFHTML3 16-bit
Options type
UXFHTML3Options = record
(Delphi Record structSize: Integer;
Listing) fileName: PChar;
baseURLName: PChar;
end;

32-bit
type
UXFHTML3Options = record
structSize: Word;
fileName: PChar;
baseURLName: PChar;
end;

Chapter 6, Crystal Report Engine Reference 711

UXFODBCOptions

The UXFODBCOptions structure contains information used by the

PEExportOptions structure whenever you export in ODBC format.
struct UXFODBCOptions
{
WORD structSize;
char FAR *dataSourceName;
char FAR *dataSourceUserID;
char FAR *dataSourcePassword;
char FAR *exportTableName;
};

Members structSize
Specifies the size of the UXFODBCOptions structure. You must
initialize this member to be the size of whatever it is, for example,
options.structSize = UXFODBCOptionsSize.
dataSourceName
Specifies the name of the data source that you want to export to.
dataSourceUserID
Specifies the User ID that you need to connect to the data source.
dataSourcePassword
Specifies the Password that you need to connect to the data source.
exportTableName
Specifies the name of the table you want to export to in the data
source.

UXFODBCOptions (Other Declares)

UXFODBCOptions 16-bit
(Delphi Record type
UXFODBCOptions = record
Listing) structSize: integer;
dataSourceName: PChar;
dataSourceUserID: PChar;
dataSourcePassword: PChar;
exportTableName: PChar;
end;

712 Crystal Reports Developer’s Reference

 32-bit
type
UXFODBCOptions = record
structSize: Word;
dataSourceName: PChar;
dataSourceUserID: PChar;
dataSourcePassword: PChar;
exportTableName: PChar;
end;

UXFPaginatedTextOptions

struct UXFPaginatedTextOptions
{
WORD structSize;
WORD nLinesPerPage;
};

Members structSize
Specifies the size of the UXFPaginatedTextOptions structure. You
must initialize this member to be the size of whatever it is, for
example, options.structSize = UXFPaginatedTextOptionsSize.
nLinesPerPage
Indicates the number of lines to be printed before the page break. The
default is 60 lines. When the paginated text format is used with
PEGetExportOptions, the program displays the Lines Per Page
dialog box to give the user the opportunity to specify a different
number if he or she wishes.

UXFPaginatedTextOptions (Other Declares)

UXFPaginatedText 16 bit
Options type
UXFPaginatedTextOptions = Record
(Delphi Record structSize: Integer;
Listing) nLinesPerPage: Integer;
end;

Chapter 6, Crystal Report Engine Reference 713

 32 bit
type
UXFPaginatedTextOptions = Record
structSize: Word;
nLinesPerPage: Word;
end;

UXFRecordStyleOptions

The UXFRecordStyleOptions structure contains number and date

information used by the PEExportOptions structure when you want
to export in a Record style (columns of values) format and hard code
number and/or date options.
struct UXFRecordStyleOptions
{
WORD structSize;
BOOL useReportNumberFormat;
BOOL useReportDateFormat;
};

Members structSize
Specifies the size of the UXFRecordStyleOptions structure. You must
initialize this member to be the size of whatever it is, for example,
options.structSize = UXFRecordStyleOptionsSize.
useReportNumberFormat
Indicates whether or not the program should save numbers in the
same format (decimal places, negatives, etc.) that you have used in
the report. Pass TRUE if you want the program to use the same
format used in the report, FALSE if you want the number saved in a
format that has been optimized for the file format you have selected.
useReportDateFormat
Indicates whether or not the program should save dates in the same
format (MDY, DMY, etc.) that you used in the report. Pass TRUE if
you want the program to use the same format as used in the report,
FALSE if you want dates saved in a format that has been optimized
for the file format you have selected.

714 Crystal Reports Developer’s Reference

UXFRecordStyleOptions (Other Declares)

UXFRecordStyle 16-bit
Options type
UXFRecordStyleOptions = record
(Delphi Record structSize: integer;
Listing) useReportNumberFormat: Bool;
useReportDateFormat: Bool;
end;

32-bit
type
UXFRecordStyleOptions = record
structSize: Word;
useReportNumberFormat: Bool;
useReportDateFormat: Bool;
end;

Chapter 6, Crystal Report Engine Reference 715

716 Crystal Reports Developer’s Reference
7 Creating User Defined
Functions

What you will find in this chapter...

Designing UFL Functions 718
Programming the UFL 721
Helper Modules 721
Setting Up a UFL Project 722
Function Definition 723
Function Definition Table 725
Function Templates Table 726
Function Examples Table 727
Error Table 728
InitForJob Function 729
TermForJob Function 729
UFL Function Implementation 730
Returning User Defined Errors 730
Obtaining parameter values from the parameter block 731
Picture Function - a sample UFL function 732
Module Definition (.def) File 735
UFJOB Modules 737
Multiple UFL job considerations 739
Known problems with earlier versions of UFJob.C 740

Chapter 7, Creating User Defined Functions 717

 This chapter is only supported by the Professional Edition of Crystal
Reports.
The Crystal Reports Formula Editor and formula language are
powerful tools, enabling you to do a wide variety of report-related
tasks easily and efficiently. The formula language is expandable as
well. That is, while it already includes a large selection of useful
functions, it also comes with the ability to accept new functions that
you define to meet your needs. You can add new functions to the
Crystal Reports Formula Editor by:
● writing the functions using the C programming language, and
● compiling and linking the functions into a user function DLL
called a UFL (User Function Library).
NOTE: If you are not familiar with programming Windows DLLs,
refer to the Microsoft Windows Software Development Kit. Do not
attempt to create a UFL if you do not understand Windows DLL
programming.

Designing UFL Functions

This topic is only supported by the Professional Edition of Crystal
Reports.
When designing a new function for the Crystal Reports Formula
Editor, you need to determine the following:
● the name of the function,
● the purpose of the function,
● the type of data (report data or user supplied data) the function
will require, and
● the type of data the function will return to the report.

Name of the function

The name of your new function should reflect the purpose of the
function, making it easier to recognize when it appears in the
Formula Editor's Functions list. For example, a function named
"Picture" could let you specify a template picture of how data should
appear in the report. If a field contains phone numbers, you can use
the Picture function to specify that the data appear like this:
(xxx) xxx-xxxx

718 Crystal Reports Developer’s Reference

 A resulting value from the phone number field would appear as
follows:
(415) 555-1234
Function names must start with a letter, while all remaining
characters in the name can be letters or numbers. The name can be up
to 254 characters long, and it must be unique. That is, you can not
give a function a name that has been used for another Formula Editor
function or UFL function, nor can it have a name that matches a
standard C keyword (such as if, return, switch, or while).

Purpose of the function

You may find it helpful to start simply by "fleshing out" your

function. Determine the purpose of the function and outline it on
paper. Use C code or even pseudocode to determine how the
function will perform the required operation. This step is important,
as it will form the base information for every other step in the
designing and programming of your UFL.

Function Data

UFL functions are much like any other function you might create in
C. They can accept values that are passed as parameters, and they
return a value that is printed on the report. Once you have
determined how a UFL function will perform a task, you will know
exactly what kind of data it will require to complete that operation.
The following table shows every data type that a UFL function can
accept as a parameter, along with a description of what the
parameter will look like in C.

Parameter Type C Data Type

number Double
currency Double
Boolean Short integer
string Pointer to an array of characters
range (number) Structure containing two doubles
range (currency) Structure containing two doubles
range (Boolean) Structure containing two short integers
range (date) Structure containing two long integers

Chapter 7, Creating User Defined Functions 719

 range (string) Structure containing pointers to two
elements in a character array
array (number) Pointer to a number array
array (currency) Pointer to a number array
array (integer) Pointer to an integer array
array (Boolean) Pointer to a Boolean array
array (date) Pointer to a date array
array (string) Pointer to a string array

Return Types Finally, you must determine what kind of data your function returns
to the current report in Crystal Reports. The following table lists
possible UFL return types along with a description of the C data type
used when programming the function.

Return Type C Data Type

string Pointer to a character array
number Double
date long integer
Boolean short integer
currency Double
range (date) Structure containing two long integers
range (number) Structure containing two doubles
range (currency) Structure containing two doubles
range (string) Structure containing pointers to two
elements in a character array
array (date) Pointer to a date array
array (number) Pointer to a number array
array (currency) Pointer to a number array
array (string) Pointer to a string array
array (Boolean) Pointer to a Boolean array

720 Crystal Reports Developer’s Reference

Programming the UFL
This topic is only supported by the Professional Edition of Crystal
Reports.
After sketching out your new function, deciding on its parameters
and data types, and determining the type of data the function will
return to a report, you can begin programming the UFL.
A UFL is like any other DLL with a few simple differences:
● The filename must have the "UFL" prefix for 16-bit Crystal
Reports, or with a "U2L" prefix for 32-bit Crystal Reports (e.g.,
UFLSAMP.DLL or U2LSAMP.DLL),
● it must export your User Defined Function (UDF) as a DLL
function, and
● it must export a collection of other functions required by Crystal
Reports.
You can design your UFL from scratch, but you may find the helper
modules provided with Crystal Reports useful. If you use the helper
modules provided, you will only need to create a single C code
module, a module definition (.def) file, and an application project
file. More experienced programmers may want to use these modules
simply as a starting point to design more complex UFL features.
NOTE: Although 32-bit versions of User Function Libraries have a
"U2L" prefix, they are still referred to as UFLs.

Helper Modules
This topic is only supported by the Professional Edition of Crystal
Reports.
The following files have been installed on your system in the same
directory as CRW.EXE (C:\CRW by default):

File Name Purpose

ufdll.h Defines UFL enumerated, union,
structure, and other data types.
ufuser.h Prototypes of tables and functions user
must implement.
ufmain.h Prototypes of internal UFL functions
implemented in ufmain.c.

Chapter 7, Creating User Defined Functions 721

 uffuncs.h Prototypes of functions that must be
exported by the UFL to be used by
Crystal Reports. These functions are
implemented in ufmain.c.
ufmain.c Implementation of UFL functions used
internally and used by Crystal Reports
when connecting to the UFL. This file
also contains generic LibMain and WEP
functions for Windows 3.x DLLs and a
generic DllEntryPoint function for
Win32 DLLs. (The LibMain, WEP, and
DllEntryPoint functions are defined
conditionally according to whether or
not you are building a Win32 DLL. You
do not need to make any changes to the
code here.)
ufjob.h Optional file. Contains a definition of
the JobInfo structure (see Page 737) and
prototypes of the InitForJob (see Page
729), TermForJob (see Page 729), and
FindJobInfo (see Page 738) functions
implemented in ufjob.c.
ufjob.c Optional file. Contains implementations
of the required InitForJob and
TermForJob functions. Also implements
the FindJobInfo helper function.
You do not need to work with the actual code in any of these files,
but they will have to be added to your UFL project. UFJOB.H and
UFJOB.C are optional files providing job information for the current
print job accessing the Formula Editor. For more information, see
UFJOB Modules, Page 737.

Setting Up a UFL Project

This topic is only supported by the Professional Edition of Crystal
Reports.
Begin creating your UFL by setting up a new directory on your
system to work in. Use File Manager or Windows Explorer to copy
all of the files listed in the chart under Helper Modules (see Page 721)
into your new directory. This assures that you do not inadvertently
edit or change the original files in your CRW directory.

722 Crystal Reports Developer’s Reference

 NOTE: If you will not be using the functionality provided by
UFJOB.H and UFJOB.C, you do not need to copy these files into
your working directory.
Now, open your Integrated Development Environment (IDE)
application, and use the tools there to create a new project file. Name
the new project file with a UFL prefix if your function library will be
used with Crystal Reports for Windows 3.x, or with a U2L prefix if it
will be used with Crystal Reports for Win32. For example,
UFLSAMP.MAK or U2LFUNCS.PRJ. Make sure the project is set to
build a DLL (not a Windows EXE) file.
IMPORTANT: If you are building a 32-bit version of a User Function
Library, make sure you set Struct Member Alignment for the project
to 1 byte. Crystal Reports for Win32 will not be able to use your UFL
otherwise. To find out how to change the Struct Member Alignment
setting for your project, refer to the documentation for your
development environment.
Finally, add the UFMAIN.C file to your project, and save the project
in your new working directory. Add the UFJOB.C file as well if you
are using this file. You are now ready to begin creating a new UFL
for the Crystal Reports Formula Editor.

Function Definition
This topic is only supported by the Professional Edition of Crystal
Reports.
Creating a UFL function requires that you create only one more C
code module and a module definition (.def) file in addition to the
Helper modules. (Your particular UFL Function needs may require
more modules, but the simplest method for creating a UFL requires
creating only these two.) For information on creating the module
definition file, see Module Definition File, Page 735. To begin building
your UFL, create a new C module in your IDE, and save it to your
working directory with the same name as your project file. For
example, if your project file is named UFLSAMP.MAK or
UFLFUNCS.PRJ, you would name your C module UFLSAMP.C or
UFLFUNCS.C respectively. For this demonstration, we will refer to
UFLSAMP.C. This is the "private" C module for your UFL because it
is the one section of code that must be unique to your UFL.

Chapter 7, Creating User Defined Functions 723

 The first step to programming your UFL’s private C code module is
to #include the appropriate header files:
● #include <windows.h>
● #include "ufdll.h"
● #include "ufmain.h"
● #include "ufuser.h"
You do not need to #include the UFFUNCS.H header file that you
also copied into your working directory. This file is already
#included by UFMAIN.C, and you will not be directly calling any of
the functions defined in these files (though they are necessary for
Crystal Reports when the Formula Editor accesses your UFL).
The private C code module of your UFL requires several parts:
● function definition table (see Page 725),
● function templates table (see Page 726),
● function examples table (see Page 727),
● error table (see Page 728),
● InitForJob function implementation (see Page 729),
● TermForJob function implementation (see Page 729), and
● UFL function implementation (see Page 730).
Most of these sections have specific guidelines that must be used and
that are the same for every function you add to your UFL. Your UFL
function implementation is completely designed and programmed
by you. It is the functionality that you are adding to the Crystal
Reports Formula Editor.

The "Picture" example

For the demonstration in this Help file of how to program a UFL, we

will create the Picture function. The purpose of this function is to
display string type field data using a format specified by the user. For
example, if a phone number is entered in the database table as
"4155551234", the user can create the following formula:
Picture({table.PHONENUM}, "(xxx) xxx-xxxx"
The phone number will appear in the report as:
(415) 555-1234

724 Crystal Reports Developer’s Reference

 Examples that appear in this Help file use this Picture function. To
learn how to program each section of this module, continue
browsing through the Help file using the Browse buttons (<< >>) at
the top of the Help window.

Function Definition Table

This topic is only supported by the Professional Edition of Crystal
Reports.
You must supply a definition for each function that you want to add
to Crystal Reports. Each entry in the function definition table consists
of a definition string that specifies:
● the return type,
● the function name,
● an argument list (showing the required order in which arguments
are to be entered and the data type of each argument), and
● the name of the C/C++ function that implements the call. The
definition must appear with the following format:
"returnType UDFName (arg1, arg2,...)",
CFunctionName
Here is an example:
"String Picture (String, String)", Picture
In this example:
● "String" specifies that the function is to return a string.
● "Picture" is the name that will identify the function on the
Function list in the Formula Editor.
● "(String, String)" specifies that the function is to require two
arguments, both are strings.
● “Picture” (appearing after the comma), is the actual function
name, the name you give the function when you code it.
NOTE: The UDFName and the CFunctionName do not have to be
the same. You can use something other than the function name to
identify a function on the Function list of the Formula Editor if you
wish.
All function definitions must be set up in a table with the following
heading:
UFFunctionDefStrings FunctionDefStrings [] =

Chapter 7, Creating User Defined Functions 725

 NOTE: The table must be terminated with three nulls.
Crystal Reports uses the information you supply in this table to
create parameter blocks when you call the functions.

Function definition table example

Here is a sample function definition table for the Picture function:

UFFunctionDefStrings FunctionDefStrings [] =
{
{"String Picture(String,String)",Picture},
{NULL,NULL,NULL}
};
An optional third parameter can be used when you know the
maximum length of the return value (or your code can obtain it). For
example, the definition for the Picture function might be:
{"String Picture (String, String)", Picture,
PictureRetSize},
Here, PictureRetSize specifies the maximum acceptable length of the
string returned by the Picture function.

Function Templates Table

This topic is only supported by the Professional Edition of Crystal
Reports.
You must supply a function template for each function that you
define. A function template specifies the string that Crystal Reports
is to enter in the Formula Editor’s "Formula text:" box when you
select the function from the Functions list in the Formula Editor. Each
template must contain:
● the function call,
● any syntax guides (parentheses, commas, etc.) you want to
include, and
● an exclamation point (!) character to specify where the insertion
point is to appear when the function is entered into the formula.
Here is an example:
"Picture (!, )"
In this example, the string "Picture ( , )" is to be entered into the
formula whenever you select the Picture function from the Functions
list in the Formula Editor.

726 Crystal Reports Developer’s Reference

 ● The string includes the function call "Picture" and the syntax
guides "( , )" to guide the user when entering arguments.
● The exclamation point specifies that the insertion point is to be
placed inside the parentheses, before the comma.
All function templates must be set up in a table with the following
heading:
UFFunctionTemplates FunctionTemplates [] =
NOTE: The table must be terminated with a null.
Continuing with our example, the function templates table for the
Picture function should look like this:
UFFunctionTemplates FunctionTemplates [] =
{
{"Picture (!, )"},
{NULL}
};

Function Examples Table

This topic is only supported by the Professional Edition of Crystal
Reports.
You must also supply a function example for each function. A
function example specifies the string you want to use to identify and
select the function in the Functions list in the Formula Editor. Here is
a function example for the Picture function:
"\tPicture (string, picture)"
This example specifies that the string "Picture (string, picture)" is the
listing that you want to appear in the Functions list. The characters
"\t" specify that the string is to be set in from the left one tab stop,
thus aligning it with other functions in the list.
All function examples must be set up in a table with the following
heading:
UFFunctionExamples FunctionExamples [] =
NOTE: The table must be terminated with a null.
The complete function examples table for the Picture function should
look like this:
UFFunctionExamples FunctionExamples [] =
{
{"\tPicture (string,picture)"},
{NULL}
};

Chapter 7, Creating User Defined Functions 727

Error Table
This topic is only supported by the Professional Edition of Crystal
Reports.
You must also supply an error string for each error message that you
want to make available to your functions. Each error string contains
only the text you want to display when an error is detected, and it
must be in the format:
"ErrorString"
NOTE: C compilers view the first string in the table as Error 0, the
second as Error 1, etc. Each string in the error table corresponds to
an error code that you define. For each user error code, there must
be a message string in the error table at the corresponding index,
where the first string is at index 0.
Each UFL C function must return a value of the enumerated type
UFError, defined in ufdll.h. Return UFNoError if no error occurred.
Return one of the other UFError values if there is an error. Try to
choose one of the predefined values if it fits your situation. If the
error is specific to your UFL, set the
ReturnValue.UFReturnUserError member of the parameter block to
an error code value you have defined and return UFUserError from
your function code. The Formula Editor will then call back to return
the error string that you have defined in the error table.
The Formula Editor passes a parameter block to a UFL function
rather than individual parameters. We will examine how to handle
parameter blocks under Obtaining parameter values from the
parameter block (see Page 731).
All error strings must be set up in a table with the following heading:
char *ErrorTable [] =
An error table for the Picture function should, at a minimum, look
like this:
char *ErrorTable[] =
{
"no error"
};

728 Crystal Reports Developer’s Reference

InitForJob Function
This topic is only supported by the Professional Edition of Crystal
Reports.
The InitForJob function initializes all user function UFL's with the job
ID whenever a job starts. You can handle any job initialization for
your functions here, but all that is absolutely necessary is an empty
function implementation:
void InitForJob(UFTInt32u jobID)
{
}
NOTE: See the note following TermForJob function (see Page 729).

TermForJob Function
This topic is only supported by the Professional Edition of Crystal
Reports.
The TermForJob function terminates the job ID for all user function
UFL's whenever a job finishes. You can add any job termination code
here that you like, but all that is absolutely necessary is an empty
function implementation:
void TermForJob(UFTInt32u jobID)
{
}
NOTE: Every UFL must have an implementation of InitForJob (see
Page 729) and TermForJob. These functions are called when a job
starts and ends printing, respectively. You can choose to implement
these yourself. At a minimum, you must provide empty functions.
Crystal Reports provides helper modules (UFJOB.C and UFJOB.H)
which implement these functions and maintain a doubly linked list
of JobInfo structures, one for each active job. The JobInfo structure
(declared in UFJOB.H) holds the ID# of the job and contains a void
pointer where you can store any data that you allocate. The files also
implement a FindJobInfo function (see Page 738) which you can use
to retrieve the job information for any open job. We will examine
these files and their implementation of InitForJob and TermForJob
under UFJOB Modules (see Page 737).

Chapter 7, Creating User Defined Functions 729

UFL Function Implementation
This topic is only supported by the Professional Edition of Crystal
Reports.
As the final step to creating a UFL function (see The Function
Definition, Page 723), you must add code for the operation of the
function you have designed. Your function must be programmed for
the specific needs of your UFL. In this section, we will examine the
basics of how to obtain the parameters from the parameter block and
use the values of those parameters in the implementation of the UFL
function.
You begin by coding your function as follows:
ExternC UFError FAR _export PASCAL FunctionName
(UFParamBlock *ParamBlock)
{
// Your function’s code
}
First, notice that the function is exported because a UFL is simply a
DLL being accessed by Crystal Reports. Second, the function returns
an error code of the enumerated type UFError. In the error trapping
sections of your function, you can return a UFError value, such as
UFNotEnoughParameters, or you can return UFUserError and
define your own errors in the error table. Finally, the function accepts
a parameter block of type UFParamBlock from Crystal Reports
rather than individual parameters. You will need to retrieve the
individual parameters from that parameter block to work with the
data values passed by the Formula Editor.
NOTE: ExternC is defined in UFDLL.H and is equivalent to: extern
"C".

Returning User Defined Errors

This topic is only supported by the Professional Edition of Crystal
Reports.
The UFError enumerated type provides several errors that are
common to many types of functions. If appropriate, have your UFL
function return one of these predefined types. If no error occurs, you
can return UFNoError.

730 Crystal Reports Developer’s Reference

 If your function can cause an error that is not predefined, however,
you can establish a user-defined error. You do this by:
● adding an error string to the error table,
● passing the appropriate error index to the
ReturnValue.UFReturnUserError member of the parameter
block, and
● returning UFUserError from your UFL function implementation.
A user-defined error string in the error table might look like this:
char *ErrorTable[] =
{
"My User-defined Error"
};
This error string is assigned an error index by Crystal Reports. The
first error is 0, the second is 1, etc. If an error occurs in your function,
you assign the appropriate index value to the
ReturnValue.UFReturnUserError member of the parameter block.
For example:
ParamBlock->ReturnValue.UFReturnUserError = 0;
Once you specify a user-defined error, you can return the UFError
value UFUserError from your function. When the Formula Editor
finds the error in a formula entered in the Formula text box (when
the Check or Accept button is clicked), it will use the error index
specified to report the appropriate string listed in the error table.

Obtaining parameter values from the parameter

block
This topic is only supported by the Professional Edition of Crystal
Reports.
Since Crystal Reports passes the values for a Formula Editor
function’s parameters in a parameter block rather than individually,
you must separate the values from the parameter block before they
can be evaluated. For the Picture function (see Page 732), we expect
the parameter block to contain two parameters, both of type String,
as defined in the function definition table.

Chapter 7, Creating User Defined Functions 731

 To obtain the values of the individual parameters, we begin by
defining pointers to two structures of type UFParamListElement
(defined in UFDLL.H):
UFParamListElement*FirstParam,
*SecondParam;
Next, we call the GetParam function (defined in UFMAIN.C) for
each UFParamListElement to obtain a pointer to each parameter
from the parameter block:
FirstParam = GetParam (ParamBlock, 1);
SecondParam = GetParam (ParamBlock, 2);
The actual value is stored in the Parameter member of the
UFParamListElement according to the type of data it contains. The
Parameter member is a UFParamUnion type (a union data type
holding a value according to the type of data expected). Since both of
our parameters are of type String, we can obtain the actual parameter
value for each UFParamListElement by using the following notation:
FirstParam->Parameter.ParamString
SecondParam->Parameter.ParamString
If, on the other hand, the second parameter contained a numeric
value, we could use this notation:
SecondParam->Parameter.ParamNumber
Study the UFParamUnion union definition in the UFDLL.H file for a
complete list of all possible parameter types and how to obtain a
value from them.

Picture Function - a sample UFL function

This topic is only supported by the Professional Edition of Crystal
Reports.
Here is a complete commented private C code module implementing
the Picture function. Use this as a guide for how to create your own
functions in UFLs:
/********************************
** UFLSAMP.C
**
** Private C code module
** implementing the Picture UDF.
********************************/

#include <Windows.h>
#include "UFDll.h"

732 Crystal Reports Developer’s Reference

 #include "UFMain.h"
#include "UFUser.h"

#define PicturePlaceholder 'x'

/* UDF PROTOTYPE */
ExternC UFError FAR _export PASCAL Picture
(UFParamBlock * ParamBlock);

/*****
* This array gives CRYSTAL the types for the
* parameters to our UDF, the return
* type, and the name. It also passes the
* address of the actual function code.
*****/

UFFunctionDefStrings FunctionDefStrings [] =
{
{"String Picture (String, String)",
Picture},
{NULL, NULL, NULL}
};

/*****
* The following is the template CRYSTAL
* REPORTS will insert into the Formula Editor
* "Formula text:" when this function is
* selected.
*****/

UFFunctionTemplates FunctionTemplates [] =
{
{"Picture (!, )"},
{NULL}
};

/*****
* The following is an example of the format
* for this function. This text will appear
* in the Functions list box of the Formula
* Editor.
*****/

UFFunctionExamples FunctionExamples [] =
{
{"\tPicture (string, picture)"},

Chapter 7, Creating User Defined Functions 733

 {NULL}
};

/*****
* This array contains ASCII string
* representations of the errors which
* could occur.
*****/

char *ErrorTable [] =
{
"no error"
};

/* Called for on initialization */

void InitForJob (UFTInt32u jobID)
{
}

/* Called on termination */
void TermForJob (UFTInt32u jobID)
{
}

/*****
* This function is used by the Picture UDF to
* copy the contents of a source string and a
* format string into a destination string.
*****/

static void copyUsingPicture(char *dest,

const char *source, const char *picture)
{
while (*picture != '\0')
{
If (tolower (*picture) ==
PicturePlaceholder)
If (*source != '\0')
*dest++ = *source++;
Else
; // do not insert anything
Else
*dest++ = *picture;
picture++;
}

734 Crystal Reports Developer’s Reference

 // copy the rest of the source
lstrcpy (dest, source);
}

/*****
* This is our User Defined Function
*****/

ExternC UFError FAR _export PASCAL Picture

(UFParamBlock * ParamBlock)
{
UFParamListElement*FirstParam,*SecondParam;
FirstParam = GetParam (ParamBlock, 1);
SecondParam = GetParam (ParamBlock, 2);

If (FirstParam == NULL || SecondParam ==

NULL)
return UFNotEnoughParameters;
copyUsingPicture(ParamBlock-
ReturnValue.ReturnString,
FirstParam-Parameter.ParamString,
SecondParam-Parameter.ParamString);
return UFNoError;
}

Module Definition (.def) File

This topic is only supported by the Professional Edition of Crystal
Reports.
The last element of your UFL is the module definition (.def) file. This
is just like any module definition file you would create for a DLL, but
you must make sure to explicitly export not only your UFL function,
but also the specialized UFL functions defined in UFMAIN.C that
Crystal Reports expects to find. The following is an example of a
module definition file for the UFL that exports our Picture function
(see Page 732):
Library UFLSAMP
Description’User Function Library for Crystal
Reports’
ExeType Windows
HeapSize 1024
Code Moveable Discardable Preload
Data Moveable Preload
Segments _TEXT Preload

Chapter 7, Creating User Defined Functions 735

 Exports
WEP
UFINITIALIZE
UFTERMINATE
UFGETVERSION
UFSTARTJOB
UFENDJOB
UFGETFUNCTIONDEFSTRINGS
UFGETFUNCTIONEXAMPLES
UFGETFUNCTIONTEMPLATES
UFERRORRECOVERY
PICTURE
Notice that the only function exported that you actually coded is the
Picture UFL. The rest of the exported functions have been defined for
you in UFMAIN.C. Every UFL must export these 9 UF* functions. In
addition to these functions, every UFL that you create must be
exported.
NOTE: If you are creating a 32-bit UFL, do not export the WEP
procedure function. WEP is specific to 16-bit Windows. If you are
creating a 16-bit UFL, however, the WEP function must be exported
here.
NOTE: If you are creating a 32-bit UFL, you will only need to include
the LIBRARY, DESCRIPTION, and EXPORTS sections of the .def file.
Any other sections included will be ignored by 32-bit Windows.
When you have finished coding the module definition file, save it to
your working directory and add it to the list of files in your project
file.
Finally, compile and link the ufl* or u2l* project file. Resolve any
errors that occur, and recompile if necessary. Once you have your
DLL (ufl*.dll or u2l*.dll), place it in the directory that holds
CRW.EXE. From that point on, when you open the Formula Editor,
your user defined function(s) will appear in the "Additional
Functions" section at the bottom of the Functions list of the Formula
Editor. Enter each function in one or more formulas, and test and
modify it until it works the way you want.
NOTE: For additional information, review UFLSAMP1.C and
UFLSAMP2.C (sample files that were installed in the Crystal Reports
directory, \CRW by default).

736 Crystal Reports Developer’s Reference

UFJOB Modules
This topic is only supported by the Professional Edition of Crystal
Reports.
Two optional modules, UFJOB.H and UFJOB.C have been provided
with Crystal Reports. These files provide an implementation of the
InitForJob (see Page 729) and TermForJob (see Page 729) functions
that allow you to obtain an ID number that is specific to the current
print job in Crystal Reports. At the same time, these modules
establish a JobInfo structure for the current job where you can store
information regarding the job. If your UFL, for example, must
evaluate all values in a field before printing a result, it can tally data
in the JobInfo structure until it has a result. Data can even be passed
between functions using the JobInfo structure.
Use the JobInfo structure whenever you want to create UFL
functions that summarize or group report data. For example,
statistical functions that evaluate the median, mean, or range of
values in a field can store data in the JobInfo structure.
The UFLSAMP2.C file, included with Crystal Reports, demonstrate
UFLs that group data according to the Top N values. (Crystal
Reports can do this automatically for you, but the functions in
UFLSAMP2.C will help you understand how to use the functions
and the JobInfo structure in the UFJOB modules.)
If you decide to use the UFJOB modules in your own UFL, you must
do the following:
● add UFJOB.C to your UFL project file,
● #include UFJOB.H in your private C code module that
implements your UFL functions, and
● replace your own implementations of the InitForJob and
TermForJob functions with implementations of the InitJob and
TermJob functions.

UFJOB.C

This module contains implementations of the InitForJob (see Page

729) and TermForJob (see Page 729) functions that provide a JobInfo
structure for the current job in Crystal Reports. These replace any
versions of these functions that you coded in your private C module
containing your UFL definitions. They also call the InitJob and
TermJob functions respectively. You will implement these functions
in your private C code module.

Chapter 7, Creating User Defined Functions 737

 In addition, this file also defines the FindJobInfo function. Use this
function in your own code whenever you need to obtain a pointer to
the JobInfo structure for the current job. This function requires only
the job ID number, which is stored in the JobId member of the
parameter block. The following code demonstrates how to call this
function:
struct JobInfo *jobInfo;
jobInfo = FindJobInfo (ParamBlock->JobId);

UFJOB.H

This module prototypes the InitForJob, TermForJob, and

FindJobInfo functions that appear in UFJOB.C. It also prototypes the
InitJob and TermJob functions that you must implement yourself.
Most importantly, this file defines the JobInfo structure:
struct JobInfo
{
UFTInt32u jobId;
struct JobInfo FAR *prev;
struct JobInfo FAR *next;

void FAR *data;

};
The data member of this structure allows you to store a pointer to
any kind of data you wish. This means you can store information for
the current job that allows you to evaluate several field values before
printing a result or store data from one function to be used by
another function.

Implementing InitJob and TermJob

If you previously implemented the InitForJob and TermForJob

functions in the private C code module with your UFL function
definitions, delete those functions now since they are being replaced
by the functions in UFJOB.C. Now, in your private C module, define
the InitJob and TermJob functions which InitForJob and TermForJob
call. You can use these functions to add job initialization or job
termination code to your UFL, but they can also remain blank.

738 Crystal Reports Developer’s Reference

 Following are examples of how you might implement these
functions for your own UFL:
void InitJob (struct JobInfo *jobInfo)
{
}
void TermJob (struct JobInfo *jobInfo)
{
If (jobInfo->data != 0)
free (jobInfo->data);
}
Once you have done all this, you can make full use of the JobInfo
structure with your own UFL function code.

Multiple UFL job considerations

Certain problems can occur when a 16-bit UFL has multiple client
reports open simultaneously. It has a loop that searches a list of job
structures looking for the current job:
while (cursor != 0)
if (cursor->jobId == jobId)
break;
If the current job isn't the first one in the list, however, this is an
infinite loop since 'cursor' is never changed. We fixed this problem a
long time ago:
while (cursor != 0)
{
if (cursor->jobId == jobId)
break;
cursor = cursor->next;
}
Here's why this bug hasn't been much of a problem before 5.0: To a
UFL, a job exists from the moment when record reading starts to the
moment when the last page has been formatted. The UFL will only
have more than one job if a second report is printed while the first
one is also printing, which is not very common.
In 5.0, UFL jobs exist much longer because of print engine changes.
The user may never preview the last page of the report, so a UFL job,
once created, is kept open until either the preview is closed or the
data is refreshed. This change makes it very easy to have more than
one UFL job at a time.

Chapter 7, Creating User Defined Functions 739

Known problems with earlier versions of UFJob.C
Early versions of UFJob.C, a file used for creating UFL functions, can
cause a UFL to go into an infinite loop under certain conditions,
forcing a user to reboot his or her system. Problems can arise when
using 16-bit UFL functions to handle multiple client reports
simultaneously. The problem was fixed several years ago but it may
recur with the current version of Crystal Reports if you are still using
an early version of UFJob.C.
If you are experiencing the problem, you can correct it in one of two
ways:
● Open your UFL project in your C or C++ development
environment. Replace the UFJob.C module in your project with
the current UFJob.C module distributed with Crystal Reports 5.0.
(A comment appears at the beginning of the module code
showing a date of 13Mar., 1993.) Finally, recompile your UFL
project.
● Open your UFL project in your C/C++ development
environment and edit the code in UFJob.C. Replace the following
code:
while (cursor !=0)
if (cursor->jobId==jobId)
break;

with this code

while (cursor !=0)
{
if (cursor->jobId==jobId)
break;
cursor = cursor->next;
}

740 Crystal Reports Developer’s Reference

I N D E X
A COLORREF ..............................619 GetNSortFields .......... 266, 377
Connect Property................55 , 135 GetNTables ............... 255, 367
Access Notes Sparse Array
CopiesToPrinter Property....57 , 136 GetNthFormula ......... 285, 398
Properties ............................ 208 Correct syntax ............................41 GetNthGroupSortField309, 425
Action Property .................. 55 , 135
creating GetNthParam ............ 291, 404
ActiveX Control............................ 8 custom print link to Report GetNthParameterField ....... 316
adding to project ................... 9
Engine ................................21 GetNthParamInfo .............. 311
changing properties ....... 10, 11 interface for Report Engine .....4 GetNthSortField......... 266, 378
using ................................... 10
reports for Report Engine........4 GetNthTableLocation 257, 369
adding custom control to project.. 6 CRPEExportOptions ..........218, 330 GetNthTableLogOn-
Adding Report Engine to
CRPEGraphDataInfo .........225, 337 Info .......................... 259, 370
application .............................. 4 CRPEGraphOptions ..........230, 341 GetNthTableSession-
adding the ActiveX Control to
CRPEGraphTextInfo..........228, 339 Info .......................... 256, 368
project .................................... 9 CRPEJob GetNthTableType ...... 255, 367
adding VCL to project ................ 11
Cancel .......................247, 359 GetPrintDate ............. 292, 405
Also correct syntax..................... 41 CheckFormula ...........285, 398 GetPrintOptions ........ 293, 406
API
CheckGroupSelection- GetReportTitle ........... 271, 383
Report Engine ...................... 15 Formula....................286, 399 GetSectionCode ................ 313
applications
CheckSelection- GetSectionFormat...... 297, 412
Report Engine ...................... 35 Formula....................286, 399 GetSelectedPrinter..... 296, 411
Close .........................247, 359 GetSelectionFormula . 261, 373
B CloseWindow ............254, 366 GetSQLQuery............ 270, 382
before using the Report Engine..... 3 CRPEJob.....................246, 358 GetWindowHandle ........... 254
DeleteNthGroupSort- HasSavedData ................... 313
C Field .........................270, 382 IsJobFinished ............. 249, 360
C DeleteNthSortField ....268, 380 NextWindow-
Report Engine API................ 16 DiscardSavedData..............311 Magnification........... 252, 364
sample REAPI code.............. 34 EnableProgressDialog.........315 OpenSubreportJob............. 319
changing properties for ActiveX ExportPrintWindow....253, 365 OutputToPrinter ........ 280, 393
Control............................ 10, 11 ExportTo ....................282, 395 OutputToWindow ..... 279, 392
changing properties in the VCL .. 13 GetErrorCode .............283, 396 PrintControlsShowing 284, 397
changing properties on the GetErrorText ..............283, 396 PrintWindow ............. 252, 364
properties list .......................... 7 GetExportOptions ......282, 395 SelectPrinter .............. 281, 394
CLASS CRPEExportOptions ...... 329 GetFormula................260, 372 SetDialogParentWindow ... 314
CLASS CRPEGraphDataInfo ..... 336 GetGraphData ...........302, 418 SetFont ...................... 276, 389
CLASS CRPEGraphOptions ...... 340 GetGraphOptions ......307, 422 SetFormula ................ 261, 372
CLASS CRPEGraphTextInfo ...... 338 GetGraphText ............305, 420 SetGraphData............ 304, 419
CLASS CRPEJob........................ 343 GetGraphType ...........299, 414 SetGraphOptions....... 308, 423
class CRPEJob GetGroupCondition ...287, 400 SetGraphText............. 306, 421
public CObject.................. 237 GetGroupSelection- SetGraphType............ 301, 416
CLASS CRPEJobInfo.................. 324 Formula....................262, 374 SetGroupCondition.... 264, 375
CLASS CRPEngine .................... 342 GetJobHandle ............249, 361 SetGroupSelection-
class CRPEngine GetJobStatus ..............248, 359 Formula ................... 263, 375
public CObject.................. 236 GetLineHeight ...................409 SetLineHeight .................... 388
CLASS CRPEPrintOptions ......... 327 GetMargins ................294, 407 SetMargins................. 274, 386
CLASS CRPESectionOptions..... 333 GetMinimumSection- SetMinimumSection-
CLASS CRPESessionInfo ........... 326 Height ......................295, 408 Height...................... 275, 387
CLASS CRPETableLocation....... 327 GetNDetailCopies......293, 406 SetNDetailCopies ...... 274, 386
CLASS CRPETableType ............ 325 GetNFormulas ...........284, 397 SetNthGroupSortField 269, 381
Class Library GetNGroups ..............287, 400 SetNthParam ............. 291, 404
Report Engine ...................... 13 GetNGroupSortFields.268, 380 SetNthParameterField ........ 317
classes GetNLinesInSection ...........410 SetNthSortField.......... 267, 379
REC Library ................... 13, 14 GetNPages .........................314 SetNthTableLocation . 258, 370
Clear Method ........................... 200 GetNParameterFields .........316 SetNthTableLogOn-
CloseWindow Method ............. 201 GetNParams ..............290, 403 Info .......................... 259, 371
coding a custom print link.......... 21 GetNSections .....................312

Index-1
 SetNthTableSession- Crystal NewEra Class Library developers
Info .......................... 257, 368 Overview............................ 322 what you should know ..........3
SetPrintDate............... 272, 384 Crystal Report Engine development
SetPrintOptions.......... 273, 385 adding to application ............ 4 Report Engine API................ 15
SetReportTitle ............ 272, 384 coding a custom print link... 21 DEVMODE ..............................619
SetSectionFormat ....... 298, 413 custom print link ................. 21 DEVMODE (Delphi Record
SetSelectionFormula .. 262, 374 declarations ........................ 16 Listing) ................................642
SetSQLQuery............. 271, 383 distributing applications ...... 35 DEVMODE (VB Type Listing) ...636
ShowFirstPage ........... 250, 361 error handling ..................... 30 DialogParentHandle
ShowLastPage............ 250, 362 introduction to ...................... 2 Property ........................ 60 , 140
ShowNextPage .......... 249, 361 PEPrintReport ...................... 17 DiscardSavedData Property 61 , 141
ShowNthPage ....................310 print only link ..................... 17 distributing Report Engine
ShowPreviousPage..... 250, 362 sample custom print link ..... 25 applications........................... 35
ShowPrintControls ..... 251, 363 structures ............................ 35
Start ...................................247 using ................................4, 16 E
StartJob ..............................358 Crystal Reports Engine Class Library EMailCCList Property ......... 62 , 141
TestNthTabl- Reference............................ 209 EMailMessage Property ...... 62 , 142
eConnectivity........... 254, 366 Crystal VCL................................ 11 EMailSubject Property ........ 63 , 142
ZoomPreviewWindow251, 363 adding to project ................. 11 EMailToList Property .......... 64 , 143
CRPEJobInfo .............................212 changing properties............. 13 EMailVIMBCCList Property. 64 , 143
CRPELogOnInfo ...............323, 210 using ................................... 12 Embedded quotes in Visual Basic
CRPEngine ...............................245 Crystal VCL Overview ............. 133 calls to the Report Engine ...... 41
CanClose .............. 245, 356 custom control............................. 5 Enabled Property......................144
Close .................... 238, 350 adding to project ................... 6 Encoding..................................429
CRPEngine ............ 237, 349 changing properties............7, 8 Error Table ...............................728
GetEngine ..................... 239 using ..................................... 7 errors in custom print link .......... 30
GetEngineStatus .... 240, 351 custom print link........................ 21 ExchangeFolder Property............ 65
GetErrorCode........ 245, 357 coding................................. 21 ExchangePassword Property....... 66
GetErrorText ......... 246, 357 errors .................................. 30 ExchangeProfile Property ........... 66
GetNPrintJobs ....... 245, 356 sample ................................ 25 Execute Property ......................144
GetVersion............ 239, 350 ExportPrintWindow Method .....201
LogOffServer......... 243, 354 D
LogOnServer......... 242, 353 DataFiles Property ..............57 , 137 F
LogOnSQLServerWith- DataFilesLocation Property ...... 138 features
PrivateInfo .......... 243, 355 dBASE for Windows Report Engine ........................2
Open .................... 238, 349 Report Engine API ............... 16 Focused Method ......................202
OpenJob ............... 240, 351 sample REAPI code ............. 34 Formulas Property .............. 67 , 145
PrintReport............ 241, 352 DCU.......................................... 11 Function Data ..........................719
CRPEParameterFieldInfo...........233 adding to project ................. 11 Function Definition ..................723
CRPEParameterInfo ..................235 changing properties............. 13 Function Definition Table ........725
CRPEPrintOptions ............ 216, 328 using ................................... 12 Function definition table
CRPESectionOptions ........ 223, 334 declarations example ..............................726
CRPESessionInfo............... 214, 326 REAPI .................................. 16 Function Examples Table .........727
CRPESubreportInfo ...................236 Decoding................................. 429 Function Templates Table ........726
CRPETableLocation .......... 215, 327 Delphi
CRPETableType................ 213, 325 adding VCL to project ......... 11 G
Crystal ActiveX Control ................8 changing VCL properties ..... 13
Crystal ActiveX Control Methods GraphData Property ................... 68
Report Engine API ............... 16 GraphOptions Property ...... 70 , 146
Index...................................129 sample REAPI code ............. 34
Crystal ActiveX Control Properties GraphText Property............ 72 , 148
using the Crystal VCL .......... 12
Index.....................................47 GraphType Property........... 73 , 149
Delphi VCL................................ 11
Crystal Custom Control ................5 GroupCondition Property... 74 , 151
Designing UFL Functions......... 718
adding to project ...................6 GroupSelectionFormula
Destination Property ...........59 , 138
changing properties ........... 7, 8 Property ........................ 78 , 152
DetailCopies Property.........60 , 139
using......................................7 GroupSortFields Property ... 76 , 153

Index-2
H P PEClosePrintJob (dBASE for
Windows Syntax) ................ 440
Hard-coded nulls in Visual Basic PageCount Method...........130, 202
PEClosePrintJob (Delphi
structures .............................. 44 PageFirst Method......................130 Syntax) ................................ 440
Helper Modules ....................... 721 PageLast Method ......................130
PEClosePrintJob (VB Syntax)..... 439
PageNext Method.....................131 PECloseSubreport..................... 440
I PagePrevious Method ...............131
PECloseSubreport (dBASE for
Identifying string issues in Visual PageShow Method....................131 Windows Syntax) ................ 441
Basic links to the Report PageZoom Method ...................132
PECloseSubreport (Delphi
Engine................................... 43 ParameterFields Property ......83, 84 Syntax) ................................ 441
Implementing InitJob and Passing dates/date ranges in Visual
PECloseSubreport (VB Syntax) .. 441
TermJob .............................. 738 Basic using the Report Engine PECloseWindow ...................... 441
InitForJob Function................... 729 API calls ................................42
PECloseWindow (dBASE for
interface Password Property ..............85 , 159 Windows Syntax) ................ 442
creating for Report Engine ..... 4 PECancelPrintJob......................431
PECloseWindow (Delphi
PECancelPrintJob (dBASE for Syntax) ................................ 442
K Windows Syntax).................432
PECloseWindow (VB Syntax) ... 442
Known problems with earlier PECancelPrintJob (Delphi PEDeleteNth GroupSortField
Syntax).................................432
versions of UFJob.C............. 740 (dBASE for Windows
PECancelPrintJob (VB Syntax) ...432 Syntax) ............................... 444
L PECanCloseEngine....................433
PEDeleteNth GroupSortField
PECanCloseEngine (dBASE for (Delphi Syntax) ................... 444
LastErrorNumber Property .. 79 , 155 Windows Syntax).................433
LastErrorString Property ...... 80 , 155 PEDeleteNth GroupSortField (VB
PECanCloseEngine (Delphi Syntax) ................................ 444
Library Syntax).................................433
Report Engine Class ............. 13 PEDeleteNthGroupSortField..... 443
PECanCloseEngine (VB Syntax).433 PEDeleteNthSort Field (dBASE for
PECharSepFileOptions..............660
M PECheckFormula ......................434
Windows Syntax) ................ 446
PEDeleteNthSort Field (Delphi
MarginBottom Property ...... 80 , 156 PECheckFormula (dBASE for
Syntax) ................................ 446
MarginLeft Property............ 81 , 157 Windows Syntax).................435 PEDeleteNthSort Field (VB
MarginRight Property ......... 82 , 157 PECheckFormula (Delphi
Syntax) ................................ 445
MarginTop Property ........... 82 , 158 Syntax).................................435 PEDeleteNthSortField............... 444
MDIChild Property................... 158 PECheckFormula (VB Syntax) ...434
PEDiscardSaved Data (dBASE for
Members (when used with PECheckGroup SelectionFormula Windows Syntax) ................ 447
PEGetNthParameterField) .... 681 (dBASE for Windows
PEDiscardSaved Data (Delphi
Members (when used with Syntax).................................436 Syntax) ................................ 447
PESetNthParameterField ...... 682 PECheckGroup SelectionFormula
PEDiscardSaved Data (VB
Module Definition (.def) File .... 735 (Delphi Syntax) ....................436 Syntax) ................................ 447
Multiple UFL job PECheckGroup SelectionFormula
PEDiscardSavedData................ 446
considerations..................... 739 (VB Syntax) ..........................436 PEEnableProgressDialog........... 447
PECheckGroupSelection-
O PEEnableProgressDialog (Delphi
Formula ...............................435 Syntax) ................................ 448
Obtaining parameter values from PECheckSelection Formula (dBASE
PEEnableProgressDialog (VB
the parameter block ............ 731 for Windows Syntax)............438 Syntax) ................................ 448
OCX............................................. 8 PECheckSelection Formula (Delphi
PEExportOptions ...................... 662
adding to project ................... 9 Syntax).................................437 PEExportOptions (Delphi Record
changing properties ....... 10, 11 PECheckSelection Formula (VB
Listing) ................................ 668
using ................................... 10 Syntax).................................437 PEExportOptions (VB Type
OLE control.................................. 8 PECheckSelectionFormula ........436
Listing) ................................ 667
adding to project ................... 9 PECloseEngine..........................438 PEExportPrint Window (dBASE for
changing properties ....... 10, 11 PECloseEngine (dBASE for
Windows Syntax) ................ 450
using ................................... 10 Windows Syntax).................439
PEExportPrint Window (Delphi
OnExecute Event...................... 206 PECloseEngine (Delphi Syntax) .439
Syntax) ................................ 450
OnLoadDataFiles Event............ 207 PECloseEngine (VB Syntax) .......438
PEExportPrint Window (VB
PEClosePrintJob ........................439
Syntax) ................................ 450
PEExportPrintWindow.............. 449

Index-3
PEExportTo...............................451 PEGetMargins (Delphi Syntax) . 474 PEGetNSubreportsInSection (VB
PEExportTo (Delphi Syntax) ......451 PEGetMargins (VB Syntax) ....... 474 Syntax) ................................487
PEExportTo (VB Syntax) ............451 PEGetMinimum SectionHeight PEGetNTables ..........................488
PEGetErrorCode .......................452 (Delphi Syntax) ................... 476 PEGetNTables (dBASE for Windows
PEGetErrorCode (dBASE for PEGetMinimum SectionHeight (VB Syntax) ................................489
Windows Syntax) ................453 Syntax)................................ 475 PEGetNTables (Delphi Syntax) .489
PEGetErrorCode (Delphi PEGetMinimumSectionHeight . 474 PEGetNTables (VB Syntax) .......489
Syntax) ................................453 PEGetNDetail Copies (Delphi PEGetNth ParameterField (Delphi
PEGetErrorCode (VB Syntax).....452 Syntax)................................ 477 Syntax) ................................497
PEGetErrorText .........................453 PEGetNDetail Copies (VB PEGetNth ParameterField (VB
PEGetErrorText (Delphi Syntax) 454 Syntax)................................ 477 Syntax) ................................497
PEGetErrorText (VB Syntax) ......454 PEGetNDetailCopies................ 476 PEGetNth ParamInfo (Delphi
PEGetExport Options (Delphi PEGetNFormulas ..................... 477 Syntax) ................................498
Syntax) ................................456 PEGetNFormulas (dBASE for PEGetNth Subreport InSection (VB
PEGetExport Options (VB Windows Syntax) ................ 478 Syntax) ................................502
Syntax) ................................455 PEGetNFormulas (Delphi PEGetNth SubreportIn Section
PEGetExportOptions.................455 Syntax)................................ 478 (Delphi Syntax)....................502
PEGetFormula ..........................456 PEGetNFormulas (VB Syntax)... 478 PEGetNthFormula ....................489
PEGetFormula (Delphi Syntax) .457 PEGetNGroups ........................ 478 PEGetNthFormula (Delphi
PEGetFormula (VB Syntax) .......457 PEGetNGroups (dBASE for Syntax) ................................491
PEGetGraph Options (Delphi Windows Syntax) ................ 479 PEGetNthFormula (VB Syntax) .491
Syntax) ................................461 PEGetNGroups (Delphi Syntax) 479 PEGetNthGroup SortField (Delphi
PEGetGraph Options (VB PEGetNGroups (VB Syntax) ..... 479 Syntax) ................................493
Syntax) ................................460 PEGetNGroupSortFields........... 479 PEGetNthGroup SortField (VB
PEGetGraphData......................458 PEGetNGroupSortFields (dBASE for Syntax) ................................493
PEGetGraphData (Delphi Windows Syntax) ................ 481 PEGetNthGroupSortField .........492
Syntax) ................................459 PEGetNGroupSortFields (Delphi PEGetNthParam .......................494
PEGetGraphData (VB Syntax) ...459 Syntax)................................ 480 PEGetNthParam (Delphi
PEGetGraphOptions.................459 PEGetNGroupSortFields (VB Syntax) ................................495
PEGetGraphText.......................461 Syntax)................................ 480 PEGetNthParam (VB Syntax) ....495
PEGetGraphText (Delphi PEGetNPages........................... 481 PEGetNthParam Info (VB
Syntax) ................................462 PEGetNPages (Delphi Syntax) .. 482 Syntax) ................................498
PEGetGraphText (VB Syntax)....462 PEGetNPages (VB Syntax) ........ 481 PEGetNthParameterField..........496
PEGetGraphType......................463 PEGetNParameterFields ........... 482 PEGetNthParamInfo .................497
PEGetGraphType (Delphi PEGetNParameterFields (Delphi PEGetNthSortField ...................499
Syntax) ................................465 Syntax)................................ 483 PEGetNthSortField(Delphi
PEGetGraphType (VB Syntax)...464 PEGetNParameterFields (VB Syntax) ................................500
PEGetGroup Condition (Delphi Syntax)................................ 482 PEGetNthSortField(VB Syntax)..500
Syntax) ................................467 PEGetNParams ........................ 483 PEGetNthSubreportInSection....501
PEGetGroup Condition (VB PEGetNParams (dBASE for PEGetNthTable Location (Delphi
Syntax) ................................467 Windows Syntax) ................ 484 Syntax) ................................504
PEGetGroup SelectionFormula PEGetNParams (Delphi Syntax) 484 PEGetNthTable Location (VB
(Delphi Syntax)....................469 PEGetNParams (VB Syntax)...... 484 Syntax) ................................503
PEGetGroup SelectionFormula (VB PEGetNSections....................... 484 PEGetNthTable LogOnInfo (Delphi
Syntax) ................................469 PEGetNSections (Delphi Syntax) ................................505
PEGetGroupCondition..............465 Syntax)................................ 485 PEGetNthTable LogOnInfo (VB
PEGetGroupSelectionFormula ..468 PEGetNSections (VB Syntax) .... 485 Syntax) ................................505
PEGetHandle String (Delphi PEGetNSortFields..................... 485 PEGetNthTable SessionInfo (Delphi
Syntax) ................................471 PEGetNSortFields (dBASE for Syntax) ................................507
PEGetHandle String (VB Windows Syntax) ................ 487 PEGetNthTable SessionInfo (VB
Syntax) ................................470 PEGetNSortFields (Delphi Syntax) ................................506
PEGetHandleString...................469 Syntax)................................ 486 PEGetNthTable Type (Delphi
PEGetJobStatus .........................471 PEGetNSortFields (VB Syntax).. 486 Syntax) ................................508
PEGetJobStatus (Delphi Syntax) 472 PEGetNSubreportsInSection..... 487 PEGetNthTable Type (VB
PEGetJobStatus (VB Syntax) ......472 PEGetNSubreportsInSection Syntax) ................................508
PEGetMargins...........................473 (Delphi Syntax) ................... 488 PEGetNthTableLocation ...........502

Index-4
PEGetNthTableLogOnInfo........ 504 PEGraphDataInfo (Delphi Record PEOpenEngine ......................... 536
PEGetNthTableSessionInfo ....... 505 Listing).................................670 PEOpenEngine (dBASE for
PEGetNthTableType................. 507 PEGraphDataInfo (VB Type Windows Syntax) ................ 537
PEGetPrintDate ........................ 509 Listing).................................670 PEOpenEngine (Delphi Syntax) 537
PEGetPrintDate (Delphi Syntax)510 PEGraphOptions.......................671 PEOpenEngine (VB Syntax) ...... 537
PEGetPrintDate (VB Syntax) ..... 510 PEGraphOptions (Delphi Record PEOpenPrintJob ....................... 537
PEGetPrintOptions ................... 510 Listing).................................673 PEOpenPrintJob (dBASE for
PEGetPrintOptions(Delphi PEGraphOptions (VB Type Windows Syntax) ................ 539
Syntax) ................................ 512 Listing).................................672 PEOpenPrintJob (Delphi
PEGetPrintOptions(VB Syntax) . 511 PEGraphTextInfo ......................673 Syntax) ................................ 539
PEGetReportTitle...................... 512 PEGraphTextInfo (Delphi Record PEOpenPrintJob (VB Syntax) .... 538
PEGetReportTitle (Delphi Listing).................................675 PEOpenSubreport .................... 539
Syntax) ................................ 513 PEGraphTextInfo (VB Type PEOpenSubreport (Delphi
PEGetReportTitle (VB Syntax) ... 513 Listing).................................674 Syntax) ................................ 540
PEGetSection Format (Delphi PEHasSavedData ......................526 PEOpenSubreport (VB Syntax).. 540
Syntax) ................................ 516 PEHasSavedData (Delphi PEOutputTo Printer (dBASE for
PEGetSection Format (VB Syntax).................................528 Windows Syntax) ................ 543
Syntax) ................................ 516 PEHasSavedData (VB Syntax) ...527 PEOutputTo Printer (Delphi
PEGetSectionCode ................... 513 PEIsPrintJob Finished (dBASE for Syntax) ................................ 543
PEGetSectionCode(Delphi Windows Syntax).................529 PEOutputTo Printer (VB Syntax)543
Syntax) ................................ 514 PEIsPrintJob Finished (Delphi PEOutputTo Window (dBASE for
PEGetSectionCode(VB Syntax) . 514 Syntax).................................529 Windows Syntax) ................ 548
PEGetSectionFormat................. 515 PEIsPrintJob Finished (VB PEOutputTo Window (Delphi
PEGetSelected Printer (Delphi Syntax).................................529 Syntax) ................................ 547
Syntax) ................................ 518 PEIsPrintJobFinished .................528 PEOutputTo Window (VB
PEGetSelected Printer (VB PEJobInfo..................................676 Syntax) ................................ 547
Syntax) ................................ 518 PEJobInfo (Delphi Record PEOutputToPrinter ................... 541
PEGetSelectedPrinter................ 516 Listing).................................678 PEOutputToWindow................ 543
PEGetSelection Formula (Delphi PEJobInfo (VB Type Listing).......677 PEParameter FieldInfo (Delphi
Syntax) ................................ 520 PELogOffServer.........................529 listing) ................................. 684
PEGetSelection Formula (VB PELogOffServer (Delphi Syntax)531 PEParameter FieldInfo (VB type
Syntax) ................................ 520 PELogOffServer (VB Syntax)......530 listing) ................................. 684
PEGetSelectionFormula............ 519 PELogOnInfo ............................678 PEParameterFieldInfo ............... 680
PEGetSQLQuery ...................... 520 PELogOnInfo (Delphi Record PEParameterInfo....................... 685
PEGetSQLQuery (Delphi Listing).................................680 PEParameterInfo (Delphi Record
Syntax) ................................ 522 PELogOnInfo (VB Type Listing) .679 Listing) ................................ 686
PEGetSQLQuery (VB Syntax).... 521 PELogOnServer.........................531 PEParameterInfo (VB Type
PEGetSubreport Info (Delphi PELogOnServer (Delphi Syntax)533 Listing) ................................ 686
Syntax) ................................ 523 PELogOnServer (VB Syntax)......532 PEPrintControls Showing (Delphi
PEGetSubreport Info (VB PELogOnSQL Syntax) ................................ 549
Syntax) ................................ 523 ServerWithPrivateInfo (Delphi PEPrintControls Showing (VB
PEGetSubreportInfo.................. 522 Syntax).................................535 Syntax) ................................ 549
PEGetVersion ........................... 524 PELogOnSQL PEPrintControlsShowing........... 548
PEGetVersion (dBASE for Windows ServerWithPrivateInfo (VB PEPrintFileOptions ................... 687
Syntax) ................................ 525 Syntax).................................534 PEPrintFileOptions(VB Type
PEGetVersion (Delphi Syntax) .. 525 PELogOnSQLServerWithPrivate- Listing) ................................ 687
PEGetVersion (VB Syntax) ........ 524 Info......................................533 PEPrintOptions......................... 688
PEGetWindow Handle (dBASE for PENextPrint WindowMagnification PEPrintOptions (Delphi Record
Windows Syntax) ................ 526 (dBASE for Windows Listing) ................................ 690
PEGetWindow Handle (Delphi Syntax).................................536 PEPrintOptions (VB Type
Syntax) ................................ 526 PENextPrint WindowMagnification Listing) ................................ 689
PEGetWindow Handle (VB (Delphi Syntax) ....................536 PEPrintReport..................... 17, 549
Syntax) ................................ 526 PENextPrint WindowMagnification PEPrintReport (dBASE for Windows
PEGetWindowHandle .............. 525 (VB Syntax) ..........................536 Syntax) ................................ 552
PEGraphDataInfo ..................... 668 PENextPrintWindow- PEPrintReport (Delphi Syntax) .. 551
Magnification ......................535 PEPrintReport (VB Syntax) ........ 551

Index-5
PEPrintWindow ........................552 PESetGroup SelectionFormula PESetNthTable LogOnInfo (Delphi
PEPrintWindow (dBASE for (dBASE for Windows Syntax) ................................593
Windows Syntax) ................553 Syntax)................................ 576 PESetNthTable SessionInfo (Delphi
PEPrintWindow (Delphi PESetGroup SelectionFormula Syntax) ................................594
Syntax) ................................553 (Delphi Syntax) ................... 576 PESetNthTable SessionInfo (VB
PEPrintWindow (VB Syntax) .....553 PESetGroup SelectionFormula (VB Syntax) ................................594
PESectionOptions..................... 690 Syntax)................................ 576 PESetNthTableLocation ............589
PESectionOptions (Delphi Record PESetGroupCondition .............. 571 PESetNthTableLogOnInfo .........591
Listing) ................................693 PESetGroupSelectionFormula .. 575 PESetNthTableSessionInfo ........593
PESectionOptions (VB Type PESetMargins ........................... 576 PESetPrintDate .........................595
Listing) ...............................692 PESetMargins (dBASE for Windows PESetPrintDate (dBASE for
PESelectPrinter .........................554 Syntax)................................ 578 Windows Syntax) ................596
PESelectPrinter (Delphi Syntax) 556 PESetMargins (Delphi Syntax) .. 578 PESetPrintDate (Delphi Syntax) 596
PESelectPrinter (VB Syntax) ......555 PESetMargins (VB Syntax) ........ 578 PESetPrintDate (VB Syntax) ......596
PESessionInfo ...........................693 PESetMinimum SectionHeight PESetPrintOptions ....................597
PESessionInfo (Delphi Record (dBASE for Windows PESetPrintOptions (Delphi
Listing) ................................695 Syntax)................................ 580 Syntax) ................................598
PESessionInfo (VB Type Listing) 694 PESetMinimum SectionHeight PESetPrintOptions (VB Syntax) .597
PESetDialogParentWindow ......556 (Delphi Syntax) ................... 580 PESetReportTitle.......................598
PESetDialogParentWindow PESetMinimum SectionHeight (VB PESetReportTitle (dBASE for
(Delphi Syntax)....................557 Syntax)................................ 579 Windows Syntax) ................599
PESetDialogParentWindow (VB PESetMinimumSectionHeight .. 579 PESetReportTitle (Delphi
Syntax) ................................557 PESetNDetail Copies (dBASE for Syntax) ................................599
PESetFont .................................557 Windows Syntax) ................ 581 PESetReportTitle (VB Syntax) ....599
PESetFont (dBASE for Windows PESetNDetail Copies (Delphi PESetSection Format (Delphi
Syntax) ................................562 Syntax)................................ 581 Syntax) ................................601
PESetFont (Delphi Syntax) ........562 PESetNDetail Copies (VB PESetSection Format (VB
PESetFont (VB Syntax) ..............561 Syntax)................................ 581 Syntax) ................................601
PESetFormula ...........................563 PESetNDetailCopies................. 580 PESetSection FormatFormula (VB
PESetFormula (dBASE for Windows PESetNth ParameterField (Delphi Syntax) ................................604
Syntax) ................................564 Syntax)................................ 587 PESetSectionFormat..................600
PESetFormula (Delphi Syntax) ..564 PESetNth ParameterField (VB PESetSectionFormatFormula.....601
PESetFormula (VB Syntax) ........564 Syntax)................................ 586 PESetSelection Formula (dBASE for
PESetGraph Options (Delphi PESetNthGroup SortField (dBASE Windows Syntax) ................606
Syntax) ................................567 for Windows Syntax)........... 584 PESetSelection Formula (Delphi
PESetGraph Options (VB PESetNthGroup SortField (Delphi Syntax) ........................ 604, 606
Syntax) ...............................567 Syntax)................................ 583 PESetSelection Formula (VB
PESetGraphData.......................564 PESetNthGroup SortField (VB Syntax) ................................605
PESetGraphData (Delphi Syntax)................................ 583 PESetSelectionFormula.............604
Syntax) ................................566 PESetNthGroupSortField .......... 582 PESetSQLQuery .......................606
PESetGraphData (VB Syntax) ....565 PESetNthParam........................ 584 PESetSQLQuery (dBASE for
PESetGraphOptions..................566 PESetNthParam (dBASE for Windows Syntax) ................608
PESetGraphText........................568 Windows Syntax) ................ 586 PESetSQLQuery (Delphi
PESetGraphText (Delphi PESetNthParam (Delphi Syntax)585 Syntax) ................................607
Syntax) ................................569 PESetNthParam (VB Syntax) ..... 585 PESetSQLQuery (VB Syntax).....607
PESetGraphText (VB Syntax).....569 PESetNthParameterField .......... 586 PEShow Functions....................608
PESetGraphType.......................569 PESetNthSortField .................... 587 PEShow Functions (dBASE for
PESetGraphType (Delphi PESetNthSortField (dBASE for Windows Syntax) ................610
Syntax) ................................571 Windows Syntax) ................ 589 PEShow Functions (Delphi
PESetGraphType (VB Syntax)....570 PESetNthSortField (Delphi Syntax) ................................609
PESetGroup Condition (dBASE for Syntax)................................ 589 PEShow Functions (VB Syntax) .609
Windows Syntax) ................575 PESetNthSortField (VB Syntax) . 588 PEShowNthPage.......................610
PESetGroup Condition (Delphi PESetNthTable Location (Delphi PEShowNthPage (Delphi
Syntax) ................................574 Syntax)................................ 590 Syntax) ................................611
PESetGroup Condition (VB PESetNthTable Location (VB PEShowNthPage (VB Syntax)....611
Syntax) ................................574 Syntax)................................ 590

Index-6
PEShowPrint Controls (dBASE for PrintFileCharSepQuote before using in your
Windows Syntax) ................ 613 Property.........................91 , 168 application........................... 3
PEShowPrint Controls (Delphi PrintFileCharSepSeparator creating interface for.............. 4
Syntax) ................................ 613 Property.........................91 , 169 creating reports for ................ 4
PEShowPrint Controls (VB PrintFileLinesPerPage Property ...92 distributing applications ...... 35
Syntax) ................................ 613 PrintFileName Property ......93 , 170 features.................................. 2
PEShowPrintControls................ 612 PrintFileODBCPassword.............93 introduction to....................... 2
PEStartPrintJob ......................... 613 PrintFileODBCSource.................94 using ..................................... 4
PEStartPrintJob (dBASE for PrintFileODBCTable...................95 Report Engine API
Windows Syntax) ................ 615 PrintFileODBCUser ....................95 coding a custom print link ... 21
PEStartPrintJob (Delphi Syntax). 614 PrintFileType Property ........96 , 170 custom print link ................. 21
PEStartPrintJob (VB Syntax)....... 614 PrintFileUseRptDateFmt declarations......................... 16
PESubreportInfo ....................... 695 Property.........................98 , 173 error handling...................... 30
PESubreportInfo (Delphi Record PrintFileUseRptNumberFmt PEPrintReport ...................... 17
Listing) ................................ 696 Property.........................99 , 173 print-only link...................... 17
PESubreportInfo (VB Type PrintMonth Property .........101, 174 REC Library ......................... 14
Listing) ................................ 696 print-only link.............................17 sample code ........................ 34
PETableLocation ...................... 696 PrintReport Method ..................100 sample custom print link ..... 25
PETableLocation (Delphi Record PrintWindow Method ...............202 structures............................. 35
Listing) ................................ 698 PrintYear Property ............101, 175 using ................................... 16
PETableLocation (VB Type programming Report Engine Class Library........ 13
Listing) ................................ 697 Report Engine API ................15 ReportDisplayPage
PETableType ............................ 698 programming a custom print link21 Property ...................... 105, 177
PETableType (Delphi Record Programming the UFL...............721 ReportFileName Property......... 105
Listing) ................................ 700 ProgressDialog Property ...102, 175 ReportLatestPage Property 106, 178
PETableType (VB Type Listing) . 700 properties ReportName Property .............. 178
PETestNthTable Connectivity changing ................................7 ReportPrinterSetup Property ..... 179
(dBASE for Windows changing for ActiveX reports
Syntax) ................................ 617 Control .........................10, 11 creating for Report Engine ..... 4
PETestNthTable Connectivity changing VCL ......................13 ReportSource Property ............. 107
(Delphi Syntax) ................... 616 properties list ReportStartPage Property.. 107, 180
PETestNthTable Connectivity (VB changing properties on ..........7 ReportTitle Property ................. 180
Syntax) ................................ 616 Purpose of the function.............719 ReportWindowHandle Method 203
PETestNthTableConnectivity .... 615 Resetting Array Properties ........ 207
PEZoomPreview Window (dBASE R Resetting Sort Array Properties . 208
for Windows Syntax) ........... 618 REAPI .........................................15 Resetting TCrpe String
PEZoomPreview Window (Delphi coding a custom print link ...21 Properties............................ 208
Syntax) ................................ 618 custom print link ..................21 Retrieving report data with Visual
PEZoomPreview Window (VB declarations .........................16 Basic ..................................... 44
Syntax) ................................ 618 error handling ......................30 Return Types............................ 720
PEZoomPreviewWindow ......... 617 PEPrintReport .......................17 Returning User Defined Errors.. 730
Picture Function - a sample UFL print only link ......................17 runtime
function .............................. 732 REC Library ..........................14 changing custom control
PrintControls Property .............. 166 sample code ........................34 properties............................. 8
PrintDay Property............... 90 , 167 sample custom print link ......25 changing VCL properties ..... 13
PrintEnded Property ................. 168 structures .............................35 runtime properties
PrinterCollation Property.... 85 , 159 using ....................................16 ActiveX Control ................... 11
PrinterCopies Property ....... 86 , 160 REC Library ................................13
PrinterDriver Property ........ 87 , 160 RecordsPrinted Property ...103, 176 S
PrinterMode Property ............... 161 RecordsRead Property ......103, 176 sample code for Report Engine
PrinterName Property......... 87 , 163 RecordsSelected Property .104, 177 API........................................ 34
PrinterPort Property............ 88 , 164 Report Engine sample custom print link ............ 25
PrinterSelect Method................ 132 adding to application .............4 Section Map............................. 430
PrinterStartPage Property.... 89 , 165 API.......................................15 SectionFont Property................ 181
PrinterStopPage Property.... 89 , 166 SectionFormat Property.... 109, 182

Index-7
SectionLineHeight using the Report Engine API....... 16 Visual dBASE
Property ...................... 111, 184 using the VCL ............................ 12 Report Engine API................ 16
SectionMinHeight UXDDiskOptions..................... 701 sample REAPI code.............. 34
Property ...................... 112, 185 UXDDiskOptions (Delphi Record
SelectionFormula Property113, 186 Listing) ................................ 701 W
SessionHandle Property............114 UXDMAPIOptions ................... 702 Where to open/close the Report
SetFocus Method......................203 UXDMAPIOptions(Delphi Record Engine using Visual Basic API
setting properties at runtime .........8 Listing) ................................ 703 calls ...................................... 40
Setting Up a UFL Project ..........722 UXDPostFolder Options (Delphi WindowBorderStyle
ShowFirstPage Method .............204 Record Listing) .................... 705 Property ...................... 120, 192
ShowLastPage Method .............204 UXDPostFolderOptions ........... 703 WindowControlBox
ShowNextPage Method ............205 UXDVIMOptions ..................... 705 Property ...................... 121, 192
ShowPage Method ...................205 UXDVIMOptions (Delphi Record WindowControls......................121
ShowPreviousPage Method ......206 Listing) ................................ 706 WindowControls Property 121, 193
SortFields Property ........... 115, 187 UXFChar SeparatedOptions (Delphi WindowHeight Property .. 122, 193
SQLQuery Property .......... 117, 189 Record Listing) .................... 708 WindowLeft Property ....... 123, 194
Status Property ................. 118, 190 UXFCharSeparatedOptions ...... 707 WindowMaxButton
StoredProcParam Property 118, 190 UXFCommaTab SeparatedOptions Property ...................... 123, 195
structure CRPEExportOptions ...217 (Delphi Record Listing) ....... 709 WindowMinButton
structure CRPEGraphDataInfo ..225 UXFCommaTabSeparated- Property ...................... 124, 195
structure CRPEGraphOptions ...229 Options............................... 708 WindowParentHandle
structure CRPEGraphTextInfo ...227 UXFDIFOptions ....................... 709 Property ...................... 125, 196
structure CRPEJobInfo...............211 UXFDIFOptions (Delphi Record WindowState Property ..... 126, 196
structure CRPELogOnInfo .........210 Listing) ................................ 710 WindowTitle Property ...... 127, 197
structure CRPEParameterField- UXFHTML3 Options (Delphi WindowTop Property....... 127, 198
Info .....................................231 Record Listing) .................... 711 WindowWidth Property ... 128, 198
structure CRPEParameterInfo ....234 UXFHTML3Options................. 711 Working with section codes .....428
structure CRPEPrintOptions ......215 UXFODBCOptions .................. 712 Wrong syntax ............................. 41
structure CRPESectionOptions..222 UXFODBCOptions(Delphi Record
structure CRPESessionInfo ........213 Listing) ................................ 712 Z
structure CRPESubreportInfo.....235 UXFPaginatedTextOptions....... 713
ZoomMagnification Method.....199
structure CRPETableLocation....214 UXFPaginatedTextOptions (Delphi
ZoomPreviewWindow Property200
structure CRPETableType .........212 Record Listing) .................... 713
structures UXFRecordStyle Options (Delphi
Report Engine API................35 Record Listing) .................... 715
UXFRecordStyleOptions .......... 714
T
TCrpe Component....................134 V
TCrpePrinterSetup Class ...........134 VBX ............................................. 5
TermForJob Function................729 adding to project ................... 6
changing properties............7, 8
U using ..................................... 7
UFJOB Modules .......................737 VCL ........................................... 11
UFJOB.C ..................................737 adding to project ................. 11
UFJOB.H..................................738 changing properties............. 13
UFL Function Implementation ..730 using ................................... 12
user defined types ...................... 35 Visual Basic
User Function Libraries - An Report Engine API ............... 16
Overview ............................717 sample REAPI code ............. 34
user interface Visual Component Library ......... 11
creating for Report Engine......4 adding to project ................. 11
UserName Property.......... 119, 191 changing properties............. 13
using the ActiveX Control...........10 using ................................... 12
Using the Crystal Report Engine ...4 Visual Component Library (VCL) 11
using the custom control ..............7

Index-8