Overview Contents This document provides information about parameter fields in Crystal Reports (CR) version 7.x. Definition of terms, architecture, usage and features are discussed. This document should be consulted in addition to the Crystal Reports 7 User s Guide, which ships with the product and outlines exactly how to use parameter fields. WHAT IS A PARAMETER FIELD?...2 ARCHITECTURE...2 HOW IT WORKS...2 TIPS, TRICKS AND LIMITATIONS...2 Using parameters to specify groups or sorts... 3 NEW FEATURES OF PARAMETER FIELDS IN CRYSTAL REPORTS 7...4 To create a pick list of values:...5 To select multiple values:...5 To select a range of values:...5 CONTACTING CRYSTAL DECISIONS FOR TECHNICAL SUPPORT...5 6/25/2002 4:45 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 1
What is a parameter field? Architecture How it works Tips, tricks and limitations A parameter field is a field that prompts you to specify a value each time you refresh the data in a report. You supply the value and the program runs the report using that value. By using parameter fields in formulas, selection formulas, and in the report itself, you can create a report that you can modify whenever your needs change. For example, suppose you have a database that contains information about the sales of products across the United States. You could create a report that displays all the customers in a particular region by hard-coding the value in the record selection formula: {Customer.Region} = CA This works fine provided you always want to run your report using California records. To view other regions, you have to edit the formula and hard-code your changes. However, by entering the region as a parameter, you can specify a different region each time you refresh the report. A parameter field must be of the same data type as the field against which it is being compared. For example, if a {Customer Name} field of type String is being used in a report that limits record selections to a particular Customer Name, then the parameter field created for this purpose must also be of type String. Once a parameter field has been created, it can then be used as a variable in record selections or in formulas. In fact, formulas and record selection formulas can contain multiple parameter fields. In these cases, you are prompted for each parameter before the data is refreshed. A parameter first prompts the user for some information. This information is then compared against the records stored in the relevant database field, through a record selection formula or a formula field. To be prompted with a parameter, it must be included somewhere in the report in a record or group selection, in a formula, or simply as a field on the report. A parameter field does not have to be placed in a report in order to be used in a record or group selection formula. You can create the parameter and then enter it into your formula as you would any other field. Crystal Reports supports parameter fields in the following data types: String, Number, Currency, Boolean, Date, Time and DateTime. 6/25/2002 4:45 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 2
Crystal Reports Functions may also be used with parameter fields. For example, you can use the ToText() function on a Number type parameter field in order to return a String. Parameter field prompting text can be up to two lines long with approximately 40-50 characters per line (depending on character width, up to the 255-character limit). The program performs automatic wordwrap on prompts more than one line long. Using parameters to specify groups or sorts Step 1: Creating a parameter field 1. On the Insert menu, select Parameter Field. 2. Select New. 3. Type a name for your parameter, For example, GroupingParam. 4. Type the prompting text you require. For example, Type Customer to group by customer name, or Region to group by region. 5. From the Value type drop-down list box, select String. 6. Select the Discrete value(s) option button. 7. Click OK. You will see your parameter field, prefixed with a?, on the Parameter tab of the Insert Fields dialog box. It is not necessary to insert your parameter field into the report as it will be referenced later in a formula. 8. Click Close to return to your report. Step 2: Creating a formula field 1. On the Insert menu, select Formula Field. 2. Select New. 3. Type a name for your formula. For example, Group. The Formula Editor dialog box appears. 4. Enter the elements of your formula. Ensure that the first line of the formula reads: WhileReadingRecords; as it is only possible to perform Grouping or Sorting on formulas that are evaluated WhileReadingRecords. 5. Enter the remaining criteria for your formula. You can enter the parameter field and database fields directly into your formula by selecting them from the leftmost box of the Formula Editor and double clicking. @Group WhileReadingRecords; If {?GroupingParam} = Customer then {Customer.Name} Else if {?GroupingParam} = Region then {Customer.Region} 6/25/2002 4:45 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 3
1. To check your formula for errors, click the Check button on the Formula Editor toolbar. 2. Click OK, and then close the Formula Editor. You will see your formula field on the Formula tab of the Insert Fields dialog box. It is not necessary to insert your parameter field into the report as it will be referenced later in a formula. 3. Click Close to return to your report. Step 3: Adding a group 1. From the Insert menu, select Group. The Insert Group dialog box appears. 2. The upper-most dropdown list shows all of the report fields that you can select as your grouping field. Scroll down the list until your find your formula field this will be shown prefixed with a @, for example, @Group. Select your formula from the list. 3. Click OK to close the dialog box and return to your report. Now, each time the report is refreshed, you will be prompted to enter a grouping field. If you type Customer then the report will be grouped on the {Customer.Name} field; if you type Region then the report will be grouped by the {Customer.Region} field. This formula could also be used for sorting a report. Simply insert it into your report as a Sort field: 1. From the Report menu, select Sort Records 2. In the Report Fields box, highlight the formula field you want to use for your Sort field. 3. Click the Add button to add the formula to the Sort Fields box, and then click OK. Refer to the Crystal Reports User s Guide Version 7 for further information about Groups and Sort fields. New features of parameter fields in Crystal Reports 7 The ability to change the parameter prompt order without deleting and recreating each parameter, as was necessary in previous versions. The ability to create pick lists. The ability to create range-limited parameters. Selecting the Allow Multiple Values option (Edit Parameter Field dialog box) allows you to pick multiple values from a pick list. Clearing this option allows you to pick only one value from the pick list. Selecting the Discreet Values option allows singular values only. The Default Values list box is populated with values that will appear in the parameter field pick list. The Edit Mask option is used to limit user input into the parameter field text box. (Please refer to your CR User s Guide for a list of Edit Mask characters.) 6/25/2002 4:45 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 4
The Length Limit and Range Limited options allow you to limit the minimum or maximum value that can be entered depending upon the type of parameter you are creating. To create a pick list of values: 1. Create a new parameter field. 2. Click the Select default values button. You can add values by typing something directly into the Select or Enter a Value to Add box, and then clicking the Add button, or by browsing to choose a table and then a field. 3. After selecting the field, the Select or Enter a Value to Add list box will populate with the records from the field selected. Now you can click each on each value and add them separately, or add them all to the pick list. When running the report you will be prompted to enter a parameter and will now be able to select a value from the pick list. To select multiple values: Selecting the Allow multiple values option will enable you to select multiple fields from the pick list when refreshing your report. To select a range of values: Selecting the Range values option allows you to select a range for a parameter field. For example, a date range. Contacting Crystal Decisions for Technical Support We recommend that you refer to the product documentation and that you visit our Technical Support web site for more resources. Self-serve Support: http://support.crystaldecisions.com/ Email Support: http://support.crystaldecisions.com/support/answers.asp Telephone Support: http://www.crystaldecisions.com/contact/support.asp 6/25/2002 4:45 PM Copyright 2001 Crystal Decisions, Inc. All Rights Reserved. Page 5