Using the Crystal Report Engine API in Visual Basic

This section provides additional information for developers working in Visual Basic. Several features of the Crystal Report Engine must be handled differently in Visual Basic than in other development environments. In addition, some of the topics here are designed to simply assist Visual Basic programmers in the design of applications using the Crystal Report Engine.

The following topics are discussed in this section.

When to Open/Close the Crystal Report Engine, Page 104

Embedded Quotes in Visual Basic Calls to the Crystal Report Engine, Page 104

Passing Dates/Date Ranges in Visual Basic using the Crystal Report Engine API Calls, Page 105

Identifying String Issues in Visual Basic Links to the Crystal Report Engine, Page 106

Hard-coded Nulls in Visual Basic User Defined Types, Page 107

Visual Basic Wrapper DLL, Page 107

When to Open/Close the Crystal Report Engine

In a Visual Basic application, you can either open the Crystal Report Engine when you open your application or when you open a form. As a general rule, it is always best to open the Crystal Report Engine when you open the application and close it when you close the application. Here is why:

●When you open and close a form, the Crystal Report Engine opens every time you open the form and closes every time you close the form. If you print a report, close the form, and later decide to print a report again, the application has to reopen the Crystal Report Engine when you open the form, creating a time delay while running your application.

●When you open and close the application, the Crystal Report Engine opens as you start the application, and stays open as long as the application is open. Once the Crystal Report Engine is open, you can print a report as often as you wish without the need to reopen the Crystal Report Engine every time you print.

Embedded Quotes in Visual Basic Calls to the Crystal Report Engine

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

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

Incorrect 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'

This is the correct syntax for use in a Seagate Crystal Reports record selection formula. This is the syntax you would use if you were entering a selection formula directly into Seagate Crystal Reports.

VBNameVariable$ = “John” Recselct$ = “{file.Lastname} = “ (+ “'” + VBNameVariable + “'”

This code also results in the string:

{file.LASTNAME} = 'John'

Again, the correct syntax.

Passing Dates/Date Ranges in Visual Basic using the Crystal Report Engine API Calls

You may want to pass date or date range information from your Visual Basic application to the Crystal Report Engine for use in formulas, selection formulas, etc. Here is an example showing a way to do it successfully:

1Start by opening a print job and assigning the print job handle to a variable.

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

2Create variables that hold the year, month, and day for both the start and end of the range.

StartYear$ = 1992 StartMonth$ = 01 StartDay$ = 01 EndYear$ = 1993 EndMonth$ = 12 EndDay$ = 31

3Now 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 StrtSelect$ and EndSelect$ variables.

Recselct$ = StrtSelect$ + “ AND “ + EndSelect$

4Once your formula is built, set the record selection formula for the report.

RetCode% = PESetSelectionFormula

(JobHandle%, RecSelect$)

5Finally, print the report.

RetCode% = PEStartPrintJob (JobHandle, 1)

RetCode% = PEClosePrintJob (JobHandle, 1)

6Modify this code to fit your needs.

Identifying String Issues in Visual Basic Links to the Crystal Report Engine

When passing a string to the Crystal Report Engine as part of the Custom-Print Link, you may think that you are passing one thing when the program, in fact, is passing something entirely different. This can happen easily, for example, when you are passing a concatenated string that you have built using variables. A small syntax error (with embedded quotes, for example) can lead to an error message and a failed call. A simple debugging procedure follows.

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 Seagate Crystal Reports expects for

astring.

●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 Seagate 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 Nulls in Visual Basic User Defined Types

When you assign a string to a user defined type in Visual Basic, it is necessary to hard-code a null immediately after the string. For example:

myStruct.stringField = “Hello” + CHR$(0)

Visual Basic Wrapper DLL

Some of the features of the Crystal Report Engine API are not directly available to Visual Basic programmers, due to restrictions in the Visual Basic language, while others present technological issues that are better handled differently from what was originally designed in the Report Engine API. To avoid problems calling functions in the API, you may want to consider using the Crystal ActiveX Controls, Page 108, or the Crystal Report Engine Automation Server, Page 111. However, if you prefer to work with the API, Seagate Crystal Reports includes the Visual Basic Wrapper DLL, CRWRAP16.DLL (16-bit) and CRWRAP32.DLL (32-bit).

The Visual Basic Wrapper DLL has been designed specifically for programming in the Visual Basic environment and can be used to build Crystal Report Engine applications in Visual Basic 4.0 or later. The CRWRAP.BAS module, installed by default in the \Seagate Software\Crystal Reports directory, redefines many of the functions and structures defined in GLOBAL.BAS. When working with the Crystal Report Engine API, add both modules to your Visual Basic project.

The functions and structures defined in the Visual Basic Wrapper DLL provide an interface for handling export formats, parameter fields, SQL server and ODBC logon information, graphs, printing, and more. For complete information on each of the structures and functions included, search for Visual Basic Wrapper for the Crystal Report Engine in the Developer’s online Help. In most cases, each function or structure has a corresponding function or structure in the original Crystal Report Engine API with a similar name. When working in Visual Basic though, you must use the functions and structures provided by the Visual Basic Wrapper DLL.