Crystal Reports

 

This tutorial shows you how to use Crystal Reports 4.6, which is the version of Crystal Reports that shipped with Visual Studio / Visual Basic 6.0. Crystal Reports provides a relatively easy way to incorporate reporting into your application. The basis of a report is a database query.

 

 It should be pointed out that this version of Crystal Reports is quite old, and that this version and the past versions of Crystal Reports that have shipped with VB are generally "watered down" versions that do not have all the bells and whistles of the standalone product that is sold by Seagate Software.  Furthermore, CR 4.6 will not work with MS-Access databases higher than Access 97. That said, what you learn about designing reports with CR 4.6 will help when working with later versions. Regarding the MS-Access issue, later versions of Access (2000, 2002, etc.) can read and save in Access 97 format.

 

Installing Crystal Reports 4.6

Crystal Reports 4.6 is bundled with Visual Studio/Visual Basic 6.0, but it is not installed automatically. To install it manually, locate the CRYSREPT folder on your installation CD – for Visual Studio 6.0, the path is COMMON\TOOLS\VB\CRYSREPT on the third CD. In that folder, double-click the file CRYSTL32.EXE. You will be asked if you want to install Crystal Reports. Respond Yes. It will then tell you where it is going to install CR; you can override the location if desired. Following that, CR will be installed, and a few moments later you should get a message indicating that installation was successful.

 

The Sample Database

The sample database used for this tutorial (as well as others to follow) is an Access 97 format database named EMPLOYEE.MDB.

 

EMPLOYEE.MDB contains three tables: EmpMast, DeptMast, and JobMast.  The tables are structured as follows:

 

EmpMast table:

 

Field Name

DataType

Comments

EmpNbr

AutoNumber

Primary Key. Uniquely identifies each employee in the database.

EmpFirst

Text (50)

Employee's first name

EmpLast

Text (50)

Employee's last name

DeptNbr

Number (Long Integer)

Foreign Key to PK of DeptMast table.  Identifies which department the employee works in.

JobNbr

Number (Long Integer)

Foreign Key to PK of JobMast table. Identifies the employee's job.

HireDate

Date/Time

Date the employee was hired

HrlyRate

Number (Single)

Employee's hourly rate

SchedHrs

Number (Single)

The number of hours per week the employee is scheduled to work.

 

DeptMast table:

 

Field Name

DataType

Comments

DeptNbr

Number (Long Integer)

Primary Key; uniquely identifies each department in the database.

DeptName

Text (50)

The name of the department.

Location

Text (50)

The department's location (could be a building, suite number, floor, etc.)

 

JobMast table: 

 

Field Name

DataType

Comments

JobNbr

AutoNumber

Primary Key; uniquely identifies each job in the database.

JobTitle

Text (50)

The job title (description).

MinRate

Number (Single)

The minimum hourly rate that somebody working in this position is usually paid.

AvgRate

Number (Single)

The average hourly rate that somebody working in this position is usually paid.

MaxRate

Number (Single)

The maximum hourly rate that somebody working in this position is usually paid.

 

Designing the Reports

 

Two reports will be developed from this database: "Annual Salary Expenses by Department" and "Annual Salary Expenses by Job".

 

For the Annual Salary Expenses by Department report, you want to show various fields from the employee database tables grouped and subtotaled by department.  You also want to show a grand total at the end of the report. A sketch of the design might look something like the following:

 

 

                              Annual Salary Expenses by Department                       

 

                                      JOB                   WKLY    HRLY

            EMP #  EMP NAME     #   JOB TITLE  HIRE DATE  HOURS   RATE   ANN SALARY

            -----  --------        ---   ---------  ---------  -----   ----   ----------

 

DEPT XXXX XXXXXXXXXXXXXXXX

 

              XXX  XXXXXXXXXXXXXXX XXX  XXXXXXXXXX XX/XX/XX    XX.XX   XX.XX $XXX,XXX.XX

              XXX  XXXXXXXXXXXXXXX XXX  XXXXXXXXXX XX/XX/XX    XX.XX   XX.XX $XXX,XXX.XX

     

                                  DEPT XXXX XXXXXXXXXXXXXXXXXXXXXXXX TOTALS: $XXX,XXX.XX

 

                              .

                              .

                              .

 

                                                      GRAND TOTALS: $XXX,XXX.XX  

 

 

The design of the Annual Salary Expenses by Job report is similar, except that you want to show various fields from the employee database tables grouped and subtotaled by job.  You might sketch the design as follows:

 

 

                              Annual Salary Expenses by Job                  

 

                                      DEPT                        WKLY    HRLY

            EMP #  EMP NAME     #   DEPT NAME  HIRE DATE  HOURS   RATE   ANN SALARY

            -----  --------        ---   ---------  ---------  -----   ----   ----------

 

JOB XXX XXXXXXXXXXXXXXXX

 

              XXX  XXXXXXXXXXXXXXX XXXX  XXXXXXXXXX XX/XX/XX    XX.XX   XX.XX $XXX,XXX.XX

              XXX  XXXXXXXXXXXXXXX XXXX  XXXXXXXXXX XX/XX/XX    XX.XX   XX.XX $XXX,XXX.XX

     

                                  JOB XXX XXXXXXXXXXXXXXXXXXXXXXXX TOTALS:    $XXX,XXX.XX

 

                              .

                              .

                        .

 

                                                      GRAND TOTALS: $XXX,XXX.XX  

 

 

This tutorial will start off by showing the step-by-step process for designing the first report, "Annual Salary Expenses by Department".  Once that is done, it will be a simple matter to copy that report and modify it to create the Annual Salary Expenses by Job report.

 

With the report designs in mind, open Crystal Reports (Report Designer) from the VB Add-Ins menu:

 

 

A registration form appears. Click the Cancel button.

 

 

From the Crystal Reports File menu, select New:

 

 

The Create New Report dialog box appears. Click the Standard button.

 

 

The Create Report Expert dialog box appears with the Step 1: Tables tab open.  Click the Data File button:

 

 

The Choose Database File dialog box appears. Navigate to the directory where your database file resides, then click the name of the database file so that it appears under "File Name:".  Click the Add button, then click the Done button.

 

 

The 2: Links tab then appears, showing you a diagram similar to that of Access' Relationships diagram.

 

 

 

Move on by clicking the 3: Fields tab.

 

The "3: Fields" tab initially looks like this:

 

 

Using the "Add ->" button, select the desired fields from the "Database Fields" listbox so that they appear in the "Report Fields" listbox.  Select the fields based on the initial design.  For fields that are involved in a primary key – foreign key relationship, only select one of those fields from either table (for example, select the DeptNbr field from either the DeptMast table OR the EmpMast table, but not both). 

 

Select the following Database Fields:

Select DeptNbr and DeptName from the DeptMast table.

Select EmpNbr From the EmpMast table.

Skip down to the JobMast table and select the JobNbr and JobTitle.

Jump back up to the EmpMast table and select the HireDate, HrlyRate, and SchedHrs.

 

Your screen should look like this:

 

 

Still sticking with Tab 3, you can specify column headings by selecting each of the Report Fields in turn, and giving them a heading by typing the desired text in the "Column Heading:" textbox (by default, the column heading is the same as the field name).

 

Specify the column headings as follows:

 

Report Field

Column Heading

DeptMast.DeptNbr

Dept #

DeptMast.DeptName

Dept  Name

EmpMast.EmpNbr

Emp #

JobMast.JobNbr

Job #

JobMast.JobTitle

Job Title

EmpMast.HireDate

Hire Date

EmpMast.HrlyRate

Hrly Rate

EmpMast.SchedHrs

Wkly Hours

 

We're still not done with Tab 3.  We need two computed columns, one for the employee name (which will be a concatenation of the EmpLast and EmpFirst fields) and one for the annual salary (which will be the employee's hourly rate multiplied by their weekly hours multiplied by 52).

 

Click the Formula button.  The "New Formula" dialog box appears.  Type EmpName in the textbox and click OK

 

 

The "Edit Formula" dialog box appears. In the "Formula text" area, type:

 

TrimRight ({EmpMast.EmpLast}) + ", " + TrimRight ({EmpMast.EmpFirst})

 

Your screen should look like this:

 

 

Note: Crystal Reports has its own formula syntax, which differs from the syntax of VB and Access expressions.  You can scroll the "Fields", "Functions", and "Operators" listboxes above the Formula text entry area to see what's available.  Also, instead of typing everything directly into the text entry area, you can double-click on a listbox selection and the text of that selection will appear in the Formula text box.

 

Click the Check button.  If you entered the formula correctly, the message "No errors found" will pop up.  Passing that, click the Accept button.

 

The formula will then appear in the Database Fields listbox (as "@EmpName").  With @EmpName highlighted, click the "Add->" button to add it to the Report Fields list.  In the Report Fields list, drag and drop "@EmpName" so that it appears under "EmpMast.EmpNbr". Give @EmpName a column heading of "Employee Name".


 

Now we must create the annual salary formula.  To do so, follow these steps:

·         Make sure anything OTHER than @EmpName is selected in the Database Fields listbox.

·         Click the Formula button.

·         In the "New Formula" dialog box, type "AnnSal" and click OK.

·         In the "Edit Formula" dialog box, type

{EmpMast.HrlyRate} * {EmpMast.SchedHrs} * 52

      click Check, then Accept.

·         Use the "Add->" button to bring @AnnSal over from the Database Fields list to the Report Fields list.

·         In the Report Fields listbox, drag and drop the @AnnSal formula so that it is the last field in the list.

·         Give @AnnSal a column heading of "Ann Salary".

 

Click  the 4: Sort tab.  Select DeptMast.DeptNbr from the "Report Fields" list and click the "Add->" button. DeptMast.DeptNbr then appears in the "Group Fields" list.  Repeat this process for @EmpName.  Your screen should look like this:

 

 

Click the 5: Total tab.  Within this Total tab, an inner tabbed dialog appears, with one tab for each field selected in the sort.  On the "DeptMast.DeptNbr" tab, remove all items except "@AnnSal" from the Total Fields list, as shown below.  What we are saying is that we want to print a subtotal for the annual salary every time there is a change, or break, in the department number.

 

 

Still in the "5: Total" tab, click the "@EmpName" tab and remove all items from the Total Fields list, as shown below. (We don't want to print subtotals after every employee name.)

 

 

We don't need to do anything in tab 6, so click the 7: Style tab.  For the title, type "Annual Salary Expenses by Department".

 

 

Click the Preview Report button.  At this time, the "Create Report Expert" is finished and you can't go back to it, but you can make any desired changes in the Crystal Reports interface.  Following is the screen that is initially displayed after you click the Preview Report button from Step 7 of the Expert:

 

 

On the Crystal Reports toolbar, click the Zoom button, so you can see what the Expert did for you (it gives you a start, but it needs some work):

 

 

Click the Design tab:

 

 

Perform the following steps to fix up the report:

 

·         Go to the File menu, select Printer Setup, and change the Orientation to Landscape.

 

·         In the Page header area, click the title ("Annual Salary Expenses by Department") to select it.  Resize the title so that it spans the width of the entire report. Go to the format bar and click the center button to center the title.

 

·         From the Insert menu, select Text Field.  In the dialog box that appears, type Run Date: and click the Accept button.  At that point, your mouse pointer will also have box representing the text field you just entered.  Drag this box to the line where the date is.  Use your mouse to arrange the items so that they look like this:

 

 

 

·         Still in the Page Header area, remove the column headings for Dept # and Dept Name.  (Do this by selecting each item with the mouse and pressing the Delete key.)

 

·         In the first area labeled #1: DeptNbr – A (the one above Details), select the item there and delete it.

 

·         In the Details area, select the DeptNbr and DeptName fields, and drag them with the mouse to the first #1: DeptNbr  -A area.

 

·         Once in the new area, select these two fields and click the Bold button. Insert a text field in this area (using the same technique as you did with "Run Date:") with the text "Department:".  Make this text field bold as well.  Arrange the fields so that they look like the following (you can resize a field by selecting it and dragging on the handles, just like resizing a control on a VB form):

 

 

·         Note that the default format for the department number contains a comma.  We don't want that.  Right click the department number, and select Change Format … from the context menu.  The Format Number dialog appears, as shown below.  Clear the "Thousands Separator" checkbox and click OK.  (Note: You can also add or remove comma formatting by selecting the field and clicking the comma button on the formatting toolbar.)

 

 

·         Remove the commas from the formats for the employee number and the job number.  Resize the fields on the detail line and resize their corresponding column headings so that the column headings can be fully read and the field data is lined up beneath them. Use the screen shot below as a guide:

 

 

·         In the second area labeled #1: DeptNbr – A (the one below Details), you will see a text item (denoted by X's) on the far left of the line.  Delete that text item.  In the same area, toward the right-hand side of the line, you will see a numeric item (denoted by "55.56").  This is the department subtotal.  Resize this item to make it larger, and move it to the right so that it lines up with the detail annual salary field, as shown below:

 

 

·         Insert a text field with the text "Subtotal for Department" to the left of the subtotal (not to the immediate left, because we are going to insert another field between these two).  Click the Bold button to make it bold.

 

·         On the Insert menu, select Database Field … The "Insert Database Field" dialog box comes up (shown below).  From it, select DeptNbr and drag the DeptNbr field to the subtotal line, between the text "Subtotal for Department" and the numeric subtotal.

 

 

·         The second area labeled #1: DeptNbr – A should now look like this:

 

 

·         In the area of the report labeled Grand Total, delete all fields except the first one (a text item with the text "Grand Total") and the last one (a numeric item that is the grand total of the annual salaries).  Resize and line up the remaining two items so that the report looks like the following:

·          


·         In the Page Footer area of the report, there is a field for the page number. With your mouse, move this field up to the right-hand side of the page heading area.  Add a text field that says "Page:" and place it adjacent to the page number, as in the following screen-shot:

 

 

That's just about it.  Click the Preview tab to check out the finished product.

 

Due to the fact this was set up to print in landscape orientation, a few screen shots are presented to show the final report.  Below is the left-hand side of the report:

 

 

Scrolling to the right, we see the following:

 

 

 


Scrolling down, we see the following:

 

 

At this point, if you want to do any further tweaking, you can click the Design tab and do so.  You can also print the report at this time.  Before exiting Crystal Reports, save the report in the same directory as your VB project, under the name SALDEPT.RPT (Crystal Reports automatically appends the .RPT extension).

 

The real objective is to be able to print the report from the VB program.  The how-to for that is coming up shortly, but first, there is another report to create.  The second report is similar to this one, except that it will be sorted and subtotaled by job, not department.  Fortunately, this second report does not have to be built from scratch. We can modify the first report to create the second report.

 

To create the second report, follow these steps:

 

1.         Copy the SALDEPT.RPT file and name the new file SALJOB.RPT.

 

2.         Double-click SALJOB.RPT to open it in Crystal Reports.

 

3.         Dismiss the registration screen by clicking Cancel.

 

4.         Click the Design tab.

 

5.         From the Report menu, select Report Title ...  The Edit Report Title dialog box appears. Change the title to Annual Salary Expenses by Job and click the Accept button.

 

6.         From the Report menu, select Change Group Expert.  The Edit Group Section dialog box appears.  There should only be one item in the listbox, reading Group #1: DeptMast.DeptNbr – A.  Select that item and click OK. Another Edit Group Section dialog box appears.  The first combo box should have "DeptMast.DeptNbr" selected.  Click the drop down arrow and select JobMast.JobNbr and click OK.

 

7.         In the Page header area, right-click the title, select Edit Text Field, change the word "Department" to "Job" and click Accept.

 

8.         The next objective is to switch the department fields in the first #1: JobNbr – A area with the job fields in the Details area.  To do this, perform the following steps:

            a.         Move the job number and job title fields from the Details line to an open area of the #1: JobNbr – A line.

b          Move the department number and department name fields from the first  #1: JobNbr – A line to the space formerly occupied by the job fields in the Details line.  Resize the department name field so that it fits.

c.         In  the first  #1: JobNbr – A line, edit the text of the "Department:" text field so that it says "Job:".  Move the job number and job title fields close to the "Job:" text field and make these two items bold.

d.         In the Details line, remove the bold formatting from the department number and department name fields.

e.         Back in the Page header area, change the text of the "Job #" and "Job Title" column headings to "Dept #" and "Dept Name", respectively.

f.          Make cosmetic adjustments as necessary.

 

9.         In the second  #1: JobNbr – A area, delete the department number field. Replace it with the job number field.  To do this, go to the Insert menu, select Database field, and select JobNbr. Resize the JobNbr field so that its small enough to fit where the department number used to be.  Remove the commas from the formatting and make it bold.  Edit the text field "Subtotal for Department", changing the word "Department" to "Job".  Make cosmetic adjustments as necessary.

 

10.        That's just about it.  Click the Preview tab to view the fruits of your labor.  If you wish, go back and make any adjustments you deem necessary and print out the report.  When you are done, save the report and exit Crystal Reports.

 

How to Print a Crystal Report from a VB Program

 

First, you must add the Crystal Report control to your VB toolbox.  To do so, go to Project à Components and check Crystal Report Control 4.6 from the Components dialog box, as shown below:

 

 

The Crystal Reports control will then appear in the VB toolbox (it is circled in the screen shot below):

 

 

The form used in the demo application associated with this topic, named frmCRDemo, is shown below. The form contains two sets of option button control arrays (each contain two option buttons indexed 0 and 1). The first option button control array, named optReport, appears in the frame labelled "Select Report"; the second option button control array, named optDestination, appears in the frame labelled "Select Destination". The Crystal Report control was renamed rptAnnSalExp.  No other properties of the Crystal Report control were set at design-time; all necessary properties are set in code at run-time.  Only one Crystal Report control is necessary to print any number of reports off of a form. The Crystal Report control is not visible at run-time.  Finally, there are two command buttons on the form; the OK button and the Exit button. The OK button runs the report based on the options selected by the user in the frames above; the Exit button ends the application.

 

 

 

 

Following is the code for both the frmCRDemo form and a standard module called modCommon.  The Crystal Reports-related code will be explained following the code listings.

 

Code for frmDemo:

 

Option Explicit

 

'------------------------------------------------------------------------

Private Sub Form_Load()

'------------------------------------------------------------------------

    CenterForm Me

   

End Sub

 

'------------------------------------------------------------------------

Private Sub cmdOK_Click()

'------------------------------------------------------------------------

 

    On Error GoTo cmdOK_Click_Error

   

    Dim strReportName           As String

    Dim intReportDestination    As Integer

    

    If optReport(0).Value = True Then

        strReportName = "SALDEPT.RPT"

    Else

        strReportName = "SALJOB.RPT"

    End If

   

    If optDestination(0).Value = True Then

        intReportDestination = crptToWindow

    Else

        intReportDestination = crptToPrinter

    End If

   

    With rptAnnSalExp

        .ReportFileName = GetAppPath() & strReportName

        .DataFiles(0) = GetAppPath() & "EMPLOYEE.MDB"

        .Destination = intReportDestination

        .Action = 1                ' 1 = "Run the Report"

    End With

   

    Exit Sub

 

cmdOK_Click_Error:

 

    MsgBox "The following error has occurred:" & vbNewLine _

         & Err.Number & " - " & Err.Description, _

           vbCritical, _

           "cmdOK_Click"

 

End Sub

 

'------------------------------------------------------------------------

Private Sub cmdExit_Click()

'------------------------------------------------------------------------

    Unload Me

End Sub

 

 

Code for modCommon:

 

Option Explicit

 

'------------------------------------------------------------------------

Public Sub CenterForm(pobjForm As Form)

'------------------------------------------------------------------------

 

    With pobjForm

        .Top = (Screen.Height - .Height) / 2

        .Left = (Screen.Width - .Width) / 2

    End With

 

End Sub

 

'------------------------------------------------------------------------

Public Function GetAppPath() As String

'------------------------------------------------------------------------

 

    GetAppPath = IIf(Right$(App.Path, 1) = "\", App.Path, App.Path & "\")

 

End Function

 

Note that in the cmdOK_Click event procedure, the variable strReportName is set to "SALDEPT.RPT" or "SALJOB.RPT", depending on which optReport button was clicked.  The variable intDestination is set to either crptToWindow or crptToPrinter, both built-in Crystal Reports constants, depending on which optDestination button was clicked (if you choose to send the report to a window, a "print preview" type screen appears allowing the user to view the report on screen; if you choose to send the report to the printer, it will be sent directly to the default printer with no preview).

 

 The sample app references the following properties of the Crystal Report control:

 

·         ReportFileName refers to the name of the report definition that you saved in Crystal Reports.  Alternatively, this property can also be set at design-time.

 

·         DataFiles is a Crystal Reports property array specifying the database file(s) to be used as the basis for the report.  The file you specify here will override the database file used when the report was created in Crystal Reports.  Although different MDB files can be used (at Crystal Reports design-time vs. VB run-time), they still must contain the same table and/or query names, with the same structure, that were used to build the report.

 

·         Destination refers to where you want to direct the output of the report.  In code, you can use a predefined constant (like crptToPrinter) or its numeric equivalent as used in the sample code.  This property can also be set at design-time.  The sample app uses either crptToWindow (numeric value of 0) or crptToPrinter (numeric value of 1).

 

·         Action is the property that triggers the running of the report.  It must be set to 1 to run.

 

Download the project files for the sample application here.