Using report parameters

Whatever you decide to use the parameters for, they represent the best way communication channel between the report engine and the execution environment (which is your application).

A parameter can have a default value which is defined by means of the default expression property. This expression is evaluated by JasperReports only when a value for the parameter has not been provided by the user at run time.

To manage the parameters, use the report inspector. From here is possible to add and remove parameters.

To modify a parameter, select it in the report inspector and use the property sheet.

Built-in parameters

All reports contain a set of built-in parameters, parameters available by default that contain some run time information. Some the most important are the REPORT_CONNECTION, which holds the JDBC connection used to run the SQL query of the report (if the report is filled using a JDBC connection), the REPORT_DATA_SOURCE which contains, if available, the data source used to fill the report, the REPORT_LOCALE which contains the Locale used to fill the report and so on.

Some built-in parameters are specific of some query languages, in example when using the Hibernate query language, the reports automatically includes the parameter HIBERNATE_SESSION that holds the Hibernate session used to run the HQL query.

The built-in parameters can not be modified or deleted.

To hide the built-in parameters from the report inspector, click the filter icon at the bottom of the report inspector.

Using parameters in an SQL query

Parameters can be used in SQL queries to filter records in a where condition or to add/replace pieces of raw SQL or even to pass the entire SQL string to execute.

In the first case the parameters are used as standard SQL parameters, in example:

SELECT * FROM ORDERS WHERE ORDER_ID = $P{my_order_id}

In this example my_order_id is a parameter that contains the ID of the order to read. This parameter can be passed to the report from the application that is running it to select only a specific order. Please note that the parameter here is a real SQL parameter, meaning that the query will be executed using a prepared statement like:

SELECT * FROM ORDERS WHERE ORDER_ID = ?

and the value of the parameter my_order_id will then passed to the statement. Let's consider this query:

SELECT * FROM ORDERS ORDER BY $P!{my_order_field}

In this case my_order_field can not be treated as an SQL parameter. JasperReports will consider this parameter like a kind of place holder (note the special syntax $P!{}) which will be replaced with the text value of the parameter (which in this case may be for instance "ORDERDATE DESC"). With the same logic, a query can be fully passed using a parameter. The query string would look like:

$P!{my_query}

The number of parameters in a query is arbitrary. When passing a value using the $P!{} syntax, the value of the parameter is taken as is, the user is responsible of the correctness of the passed value (SQL escaping is not performed by JasperReports in this case).

When using a parameter in a query, to allow iReport to execute the query to retrieve the available fields, a default value must be set for the parameter.

Parameters prompt

If a parameter is set to be used as a prompt, when a report is executed, iReport asks for the value of the parameter. Here is a simple example.

Create a report with a parameter called MESSAGE of type String set to be used as a prompt (the property Use as a prompt must be checked).

Drag the parameter from the report inspector inside the title band. iReport creates a textfield to display the parameter value.

Run the report using an empty data source by clicking the preview button. The parameter prompt dialog will appear asking for a value for the MESSAGE parameter.

Set a value for the parameter (i.e. Hello World!). The message will be printed in the title band.

iReport provides input dialogs for parameters of type String, Date, Time, Number and Collection.

See Also

• Built-in Parameters for Logged In User
• How to use built in parameter (LoggedInUser) in report and scriptlet
• Creating additional built-in parameters