In BIRT, there is a very important distinction between dataset parameters and report parameters. This distinction can be confusing at first, which is why I want to discuss it now. The difference is one of scope and function. A report parameter has a global scope and can be used in a number of different ways in reports. Report Parameters are user facing variables that prompt the user for input. If you have ever worked with a traditional reporting language, think of report parameters as a global variable, combined with a standard input statement that will fill that variable with a value.
Dataset parameters, on the other hand, are limited in scope to within the dataset that they are declared in. Dataset parameters work more like bind variables in a relational database management system, or a prepared query in a data aware programming model, such as ADO or JDBC. Dataset Parameters are typically linked to Report Parameters to retrieve their values, but that is not always the case. They can be bound to a number of different sources.
This becomes an important concept, especially when working with JDBC datasets. With other types of datasets, Report Parameters will get linked to Filters typically and not to datasets parameters. In the Web Services example from the preceding chapter, we saw that it is possible to use placeholders and dataset parameters with dataset types other than JDBC, but this is mostly used with JDBC SQL datasets and bound parameters. This is something to keep in mind when working in BIRT as the term parameter is used with both Report Parameters and Data Set Parameters, and gets even more confusing when taking into consideration that later versions of BIRT allow users to create Report Parameters directly from the Data Set Parameter dialog. The difference will become clear throughout the chapter.
Let's take a look at an example. In the following exercise, we are going to build a very simple query that will let us retrieve all employees that have a particular Employee ID. The user will be prompted to enter an ID number and the report will return the information relevant to that user. Let's work on getting input from the user:
Employee-Chapter6.rpDesign
. dsetEmployeeInfo
based of the Classic Cars Data Source.select * from Employees Where EmployeeNumber = ?
param_1
, created automatically for us. It has already been assigned automatically, the type of the database, so we don't need to change anything. This is a dataset parameter. This parameter is for only within this dataset and its value gets assigned to the ? in the query. param_1
and click the Edit button. dsprmEmployeeID
, click on the drop down next to Default Value, and set the option to Constant and the default value to 1002. We will notice the drop down that says Linked to Report Parameter. Ignore this for now, we will come back to it later. Click OK.So, we have created a dataset with a parameter and assigned it a default value for us to work with. But we don't have a way to get user input and put that user input into the Data Set Parameter. Don't worry, as we will next create a Report Parameter and will bind it to the dataset for use in our report.
Use the following values and check the Is Required checkbox.
Field |
Value |
---|---|
Name |
|
Prompt Text |
Enter Employee ID |
Data Type |
|
Display Type |
Text Box |
dsetEmployeeInfo
in the Data Explorer to open the Edit Data Set dialog. dsprmEmploeeID
, or select it and click on Edit button. rprmEmployeeID
from the Linked to Report Paramter drop-down box. If we do this now, the default value will blank out. We will now be linked to the report parameter, and the dataset parameter will take on its default value or any value the user enters in the dialog box.Here we see the old fashion way, using an Expression to link to the value of the Data Set Parameter to the Report Parameter.
dsetEmployeeInfo
and choose Insert into Layout
, or drag-and-drop the dsetEmployeeInfo
onto the Report Designers Layout pane.The first time we preview the report with a Report Parameter, the BIRT Designer will bring up a dialog box asking us to enter the Employee ID. If we put in nothing and click OK, we will get prompted that a required parameter is not filled in as rprmEmployeeID
was set to required
. Enter 1002 for the Employee ID to see the results of report.
We can change the parameters to see other results after running the preview report by clicking on the Show Report Parameters button in the Preview pane. The example that we just saw demonstrates that there is a distinct difference between Report Parameters and Data Set Parameters. This will become an important distinction later when we start to use Report Parameters in ways that affect the layout and logic of a report that are separate from data.
The example in the previous section was a good introduction to using parameters with data. In older versions of BIRT, it was the only way to create the binding between dataset parameters and report parameters. However, there are some tedious steps involved that cause some confusion. Creating parameters as in the previous example, we either need to know what our report parameters are going to be before we put our queries and build them before we create our dataset, or we would need to go back as in steps 13-15 in the previous example. That seems a little counter-intuitive to typical report design. Fortunately there is an easier way to create datasets, report parameters, and bind them in one simple procedure. We might remember the button next to the Linked To Report Parameter textbox to which I said we would come back to. In the following example, we will revisit the process of creating a dataset parameter to show how much easier it is to do the linking of Report Parameters and Data Set Parameters in later versions of BIRT. In the next exercise, we will go through the same steps as the previous exercise, except now we are going to use the quick method. Because we are going to use the same query as used earlier, we might want to go ahead and copy the existing one to the clipboard.
rprmEmployeeID
, and delete it. We can do this by right-clicking and choosing Delete, going up to the Edit menu item and choosing Delete, or just pressing the Delete key on the keyboard. dsetEmployeeInfo
dataset from either the Data Set Explorer or the Outline tab. dsprmEmployeeID
, and click the Remove button.dsprmEmployeeID
Integer
Input
dsprmEmplyoyeeID
, fill in the prompt with what the reader should see when they run the report, and set the Default value to 1002.Now, when we click OK and go back to the Data Set Edit Dialog, we click on Preview. We will see the default value from the link Report Parameter is automatically filtered down to our dataset. Use of this method is preferred as it automatically creates that binding for us and takes out the additional steps of creating the Report Parameter separately from Data Set Parameters.