Dataset parameters and report parameters

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.

Getting input from the user

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:

  1. Create a new report and call it Employee-Chapter6.rpDesign.
  2. Create a new data source from the Classic Cars Sample Database.
  3. Create a new SQL Statement dataset called dsetEmployeeInfo based of the Classic Cars Data Source.
    Getting input from the user
  4. Use the following SQL statement as the query. We need to make sure to keep the question mark in the query, as it indicates to BIRT that a dataset parameter needs to be created and used in its place:
    select
*
from
Employees
Where EmployeeNumber = ?
  5. When we click Finish, we will be brought to the dataset editor screen. Click on the Parameters branch in the tree view on the left-hand side.
    Getting input from the user
  6. We can notice that there is a dataset parameter, 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.
  7. We should notice that at the top of the screen there is a red X with a comment about a default value. This is because if we do not have a default value in the parameter, BIRT will not have any sort of value in the parameter for report development. Therefore, we need to assign a default value. Select param_1 and click the Edit button.
  8. Change the name to 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.
    Getting input from the user
  9. Now if we select Preview Results, we can see one employee record. Click OK.
    Getting input from the user

    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.

  10. From the Data Explorer, go to Report Parameters, right-click on it, and choose New Parameter option from the list.
    Getting input from the user
  11. On the next screen, enter the properties for the Report Parameter. Here we can set the Report Parameter to be required for report execution. There are several options such as:
    • Hidden: This makes sure that the user will not see it in the parameter dialog, although we can still pass values when calling the report with a URL
    • Is Required: This makes a value in the parameter mandatory
    • Do Not Echo: This is useful for sensitive information.

      Use the following values and check the Is Required checkbox.

    Field

    Value

    Name

    rprmEmployeeID

    Prompt Text

    Enter Employee ID

    Data Type

    Integer

    Display Type

    Text Box

    Getting input from the user
  12. The Default value textbox is left blank for the user to fill it. Normally if we filled this in, on the first report run, this value would populate the parameter dialog presented to the user. Click OK.
  13. At this point, there is no binding between the dataset and the Report Parameter. To create the binding, start off by double-clicking on dsetEmployeeInfo in the Data Explorer to open the Edit Data Set dialog.
  14. Go to the Parameters category. Double-click on dsprmEmploeeID, or select it and click on Edit button.
  15. There are two different ways by which we can bind the parameter to the dataset at this point. The easiest way is to select 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.
  16. Once you are finished, click OK.

    Here we see the old fashion way, using an Expression to link to the value of the Data Set Parameter to the Report Parameter.

    Getting input from the user
  17. Under the Data Explorer, right-click on dsetEmployeeInfo and choose Insert into Layout, or drag-and-drop the dsetEmployeeInfo onto the Report Designers Layout pane.
  18. Preview the report.

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.

Getting input from the user

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.

Creating parameter binding the easy way

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.

  1. Under the Data Explorer or the Outline tab, expand the Report Parameters branch, select 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.
    Creating parameter binding the easy way
  2. Open up the dsetEmployeeInfo dataset from either the Data Set Explorer or the Outline tab.
  3. Under Parameters, select dsprmEmployeeID, and click the Remove button.
    Creating parameter binding the easy way
  4. Click the New button to create a new Data Set Parameter. At this point, we are basically at Step 6 from the first exercise. We have a new Data Set Parameter with no linking to any sort of values and no default value.
  5. From the New Parameter dialog, use the same information as did before.
    • Name: dsprmEmployeeID
    • Data Type: Integer
    • Direction: Input
    Creating parameter binding the easy way
  6. Click the fX button next to the Linked to Report Parameter textbox. This will bring up the Edit dialog for the Report Parameter, with most of the relevant information filled in. Set the Name value to dsprmEmplyoyeeID, fill in the prompt with what the reader should see when they run the report, and set the Default value to 1002.
Creating parameter binding the easy way

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.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset