Using the Crystal Report Engine API in Delphi

All versions of Delphi can make direct calls to the functions in the Crystal Report Engine API. The Delphi unit file CRPE.PAS (CRPE32.PAS for 32-bit systems) includes complete declarations for all Report Engine API functions and records. When you need to add the Report Engine API to your own Delphi unit, simply add the Crystal Report Engine API unit to your project and refer to the unit in your uses clause. For example:

Uses

crpe32;

The implementation section of the Crystal Report Engine API unit contains all of the Crystal Report Engine API functions defined as external and as part of the CRPE or CRPE32 DLL.

The Using the Crystal Report Engine, Page 66, includes Delphi declarations for all Report Engine API functions and records. In addition, the Developer’s online Help includes Delphi sample code using many of the functions and records defined in CRPE.PAS. Search for Report Engine Functions - Sample Code in Delphi in the Developer’s online Help.

NOTE: Many functions and records are defined differently for 16-bit and 32-bit systems. When referring to declarations in reference sections, make sure you are using the correct version of the function or record for the operating system environment you are working in.

Crystal Report Engine API

The following topics are discussed in this section:

Declarations for the Crystal Report Engine API (REAPI), Page 70

Using the Crystal Report Engine API, Page 70

The Print-Only Link, Page 71

¾PEPrintReport Arguments, Page 71

¾Example code for a Print-Only Link, Page 73 The Custom-Print Link, Page 74

¾Coding a Custom-Print Link, Page 75

¾Custom-Print Link Step 1: Open the Crystal Report Engine, Page 75

¾Custom-Print Link Step 2: Open a print job, Page 76

¾Custom-Print Link Step 3: Set the output destination, Page 76

¾Custom-Print Link Step 4: Start the print job, Page 77

¾Custom-Print Link Step 5: Close the print job, Page 77

¾Custom-Print Link Step 6: Close the Crystal Report Engine, Page 77

¾A Sample Custom-Print Link, Page 78

¾Code Evaluation, Page 80

Crystal Report Engine

68

Working with Parameter Values and Ranges, Page 83

Working with section codes, Page 84

¾Overview, Page 84

¾Encoding, Page 84

¾Decoding, Page 86

¾Section Map, Page 87

¾Section Codes in Visual Basic, Page 88

Crystal Report Engine API variable length strings, Page 89

¾Sample Code, Page 90

¾Code Evaluation, Page 91

Crystal Report Engine API structures, Page 92

Working with subreports, Page 93

Changing report formats, Page 94

The Crystal Report Engine API (REAPI) is the most direct method of adding the Crystal Report Engine to your application project. The Crystal Report Engine itself is a Dynamic Link Library (DLL), and, therefore, exports its functionality in the form of DLL functions. These functions make up the Crystal Report Engine API.

The Crystal Report Engine DLL, CRPE.DLL (16-bit) or CRPE32.DLL (32-bit), was installed in your \WINDOWS\SYSTEM directory when you installed Seagate Crystal Reports. This assures that the DLL is available to any application on your system that uses the Crystal Report Engine.

NOTE: For complete information on distributing Crystal Report Engine and other runtime DLLs with your application, refer to the Runtime File Requirements online Help.

The process for loading a DLL and calling DLL functions is a well documented aspect of the Windows API. If you are not familiar with working with DLLs, please refer to Windows API documentation before attempting to use the Crystal Report Engine API. You may also want to consider one of the other methods described in this section for adding the Crystal Report Engine to your application.

The rest of this section assumes an understanding of DLLs and how to use them in a Windows application. It also assumes a basic understanding of the C language. The examples here are written in C, and do not cover the LoadLibrary, GetProcAddress, or FreeLibrary calls.

Many Windows development environments support direct calls to DLL functions, Visual Basic, Visual dBASE, and Delphi, for example. Refer to the documentation for your development environment for complete instructions on using a DLL. Your documentation may also cover instructions on how to translate C function calls to the language you use. Study your documentation, then review the steps described here for using the Crystal Report Engine in an application via the Crystal REAPI.

Crystal Report Engine

69

Declarations for the Crystal Report Engine API (REAPI)

Seagate Crystal Reports provides several source code files that declare the functions in the Crystal REAPI for several popular development languages. These files were installed in the Seagate Crystal Reports directory (\CRW by default) and are ready to be immediately added to your project. The following Crystal REAPI declaration files are available:

●CRPE.H declares all Crystal Report Engine API functions for C/C++.

●GLOBAL.BAS and GLOBAL32.BAS declare all Crystal Report Engine API functions for Visual Basic. For more information on using the Crystal Report Engine API with Visual Basic, see Using the Crystal Report Engine API in Visual Basic, Page 104.

●CRPEDB.H declares several Crystal Report Engine functions for Visual dBASE. Because of limits in the dBASE language, not all Crystal Report Engine functions are available to dBASE programmers. Refer to the individual function in Developer’s online Help for information on dBASE availability.

●CRPE.PAS and CRPE32.PAS declare all Crystal Report Engine API functions for Delphi. For more information on using the Crystal Report Engine API with Delphi, see Using the Crystal Report Engine API in Delphi, Page 68.

NOTE: Functions can be declared on an individual basis, but unless you will only be using a few of the Crystal Report Engine functions in your code, it is easiest to simply copy one of the previously mentioned code files into your project directory and add it to your project.

Using the Crystal Report Engine API

The Crystal REAPI provides two options for processing and producing reports from within an application:

1.The Print-Only Link, Page 71

2.The Custom-Print Link, Page 74

The Print-Only Link is the fastest, easiest method for producing a report with the Crystal REAPI. A Print-Only Link, however, provides a very limited functionality. It allows a report to be printed on a default printer or previewed in a window on-screen. It does not allow you to customize a report in any way before printing it, though.

A Custom-Print Link, on the other hand, provides all the report processing power of Seagate Crystal Reports itself. By coding a Custom-Print Link into your application, you can change record selection, record sorting, group creation, group selecting, group sorting, exporting to disk files, e-mail, Exchange and Lotus Notes folders, ODBC data sources, selecting specific printers for printing, logging on to SQL servers and ODBC data sources, editing formulas, formatting report sections, and much more. A Custom-Print Link is, however, a more complex process to code than a Print-Only Link.

The first time you use the Crystal REAPI in your application project, you may want to start by coding a simple Print-Only Link to produce basic reporting functionality. As your project develops and you become more familiar with the Crystal REAPI, you can expand the reporting functionality with a Custom-Print Link.

Crystal Report Engine

70

The Print-Only Link

A Print-Only Link is performed using the PEPrintReport function. The PEPrintReport function provides basic report printing functionality and demonstrates basic techniques for calling Crystal Report Engine functions from your application.

PEPrintReport enables your application to print a report, to select the output device, either a default printer or a preview window, and to specify the size and location of the preview window if the report is printed to a window. This function does not enable you to customize the report (select the records to print, set the sort order, etc.) at print time. You can set those parameters at report design time (using the Seagate Crystal Reports Design Tab), but you can not change them at print time through a Print-Only Link.

If the report is sent to a preview window, you should also use the PEOpenEngine and PECloseEngine functions with your Print-Only Link. PEOpenEngine and PECloseEngine allow you to control how long the preview window remains open. The window will remain open until the PECloseEngine function is called or the user clicks Close in the window. If PEOpenEngine and PECloseEngine are not used, and the report is sent to a preview window, the window will automatically close as soon as the report finishes processing.

NOTE: You may also want to get in the habit of using PEOpenEngine and PECloseEngine in all Print-Only Links, as they are required steps to coding a Custom-Print Link. If your code includes these functions when you design a Print-Only Link, advancing the application to use a Custom-Print Link in the future will be much easier.

PEPrintReport Arguments

PEPrintReport is declared in CRPE.H as follows:

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);
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 toDefaultPrinter is set to TRUE (1), the report is sent to a printer. The
		toWindow argument should be set to FALSE.
toWindow		If toWindow is set to TRUE (1), the report is sent to a preview window. The
		toDefaultPrinter argument should be set to FALSE.

Crystal Report Engine

71

Parameter	Description
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 current screen coordinates, at which you want the left edge of
	the preview window to appear if the report is being printed to a window.
	Current screen coordinate measurements can be set within your application.
top	The position, in current screen coordinates, at which you want the top edge of
	the preview window to appear if the report is being printed to a window.
	Current screen coordinate measurements can be set within your application.
width	The width of your preview window, in current screen coordinates, if the
	report is being printed to a window. Current screen coordinate
	measurements can be set within your application.
height	The height of your preview window, in current screen coordinates, if the
	report is being printed to a window. Current screen coordinate
	measurements can be set within your application.
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.

When designing a Print-Only Link using PEPrintReport, keep the following points in mind:

●If toDefaultPrinter = True, and if you have specified a printer in the report using the Printer 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.

●If toDefaultPrinter = 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).

●If parentWindow is null, Seagate 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, Seagate 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.

Crystal Report Engine

72

●If parentWindow is the handle of some other window, Seagate 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.

●You can use the Windows constant CW_USEDEFAULT (-32768) as the value of left, top, width, and height to indicate a default position for the preview window.

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, Seagate 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 maximize and minimize buttons.

Example code for a Print-Only Link

The first step in accessing the Crystal 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 Crystal 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.

Finally, once you are finished with the Crystal Report Engine, close it by calling PECloseEngine. If you have several print jobs, do not close the Crystal Report Engine until all print jobs are finished. Opening and closing the Crystal 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;

Crystal Report Engine

73