Query varaiables are used to modify queries at runtime. E.g. If you want to select all invoices with a minimum value, but you want to use a different mimimum value each time, then you can use a variable for the minimum value.

Each time a report with one or more variables is run, ReportWeaver will first pop up a dialog, that asks the user for the variable(s). If the report is run through the api, the the variables can also be preset through the api.

Variables are referenced in the query with a prefixed '$' sign. E.g. a variable with the name minOrderValue is refernced by the expression $minOrderValue.

Variables are typed and must be defined using the Query Variable Manager. The Query Variable Manager is started from the tools menu. It will also pop up if you reference a variable in a query or formula, that is not yet defined. Please note that variables are case sensitive:

Press ok to close the Query Variable Manager. Then you can use the defined variables in all your templates.

  1. The variables list shows all variables defined in the template set. Select the variable that you want to edit here. The properties of the selected variable will be shown on the right.
  2. Use the add button to add a new variable.
  3. Use the delete button to remove an obsolete variable.
    Note: Deleting a variable, that is still used in query will cause a syntax error when the query is executed.
  4. The Basic settings page allows you to set the properties that are common to all variables. These are the name, the propmt text and the type.
  5. The Values page of the variable allows you to set type specific properties. These are explained in detail below.
  6. Use the name field to change the name of the selected variable.
    Note:The name must conform to the syntax of a programming language identifier. I.e. it must start with a letter which is followed by letters, digits or underscores. A name must not contain blanks or puntuation. The length of a name is arbitrary, and all characters are significant. Names are case sensitive.
  7. The prompt text will be displayed in the dialog when the user is asked for the value.
  8. The type of the variable. The type determines which values are allowed and which input method will be used.
String
Allows the user to enter an arbitrary String. A mask can be set for the string, that constrains the allowed values.

The mask character indicate a character class, that the character at the position has to conform to. The folowing character classes are defined:

#
This mask character allow any digit or number punctuation to be entered (.,-+)
@
This mask allows any digit.
H
This allows any hexadecimal character "123456789abcdef"
A
This allows any letter but not digits or punctuation.
^
This allows letters, digits and dollar signs or underscores. "$_"
U
This allows letters, that will be automatically converted to uppercase.
L
This allows letters, that will be automatically converted to lowe case.
int
A integer value represented by a 64 bit long. On the values page you can enter a default value and a minimum and a maximum.
float
A floating point number represented by a 64 bit double.
Pick String
Allows the user to pick a value from a list of predefined Strings. You can edit the list on the Values page.
Enum
Allows the user to select a value from a list of named integers. I.e. the user selects a string, and the system uses the coresponding integer in the query. You can edit the list on the Values page.
Java Date
Allows the user to pick a date, that will be returned as an Java Date object.
Posix Date
Allows the user to pick a date, that will be returned as a Posix (Unix/Windows) date number. A Posix date is represented by the number of seconds since 1970.
Pick Field
Queries a collection in the database and presents a list of field values to the user. The user can pick one value which will be returned. Use theValues page to configure the query.
Pick Object
Queries a collection in the database and presents a list of objects to the user. The user can pick one object which will be returned. Use the Values page to configure the query.
Selection
Queries a collection in the database and presents a list of objects to the user. The user can pick several objects which will be returned. Use theValues page to configure the query. The value of this variable type can be used with the in operator. (e.g. customer.manager in $selectedmanagers)

Note:The difference is between a picked field and a picked object may not be immediately clear. Both look the same when presented to the user, because the object list can also just show the designated fields. However for the object pick, not the field but the containing object will be returned.

Configuring Pick String Variables

  1. The list of strings, with the editor border about the string currently in work.
  2. Press add to add a new string.
  3. Prese deöete to delete the selected string.

Note:You cannot define the ordering of the strings. It will always be sorted alphabetically.

Configuring Enum Variables

  1. The list of strings and numbers, with the current entry selected for editing.
  2. The names of the entries. These will be shown to the user.
  3. The mapped numbers. These will be returned in the variable.
  4. Press add to add a new string.
  5. Prese deöete to delete the selected string.

Note:You cannot define the ordering of the strings. It will always be sorted alphabetically.

Configuring Date Variables

Java and Posix date variables are configured and selectd in the same way. Only their internal representation differs.

  1. Here the current default date value is displayed, and can be edited directly.
  2. Click the arrow button to pop up the date picker. (as shown)
  3. The year. Select with the spinner buttons or type the desired year. Press tab to update the calendar.
  4. The month. Select with the spinner buttons or type the desired month. Press tab to update the calendar.
  5. The currently selected day. Click on any other day that you desire.
  6. The time. Type a new time by entering values for the hour, the minute and the seconds. Please use 24h notation.
  7. Cancel button closes the pp up and keeps the previously set date/time.
  8. Ok Button: Click to close the pop up and to use the selected date/time.

Configuring Pick Field/Object Variables

  1. The root that is used as the entry point into the database.
  2. The collection which is reachable from the root that will be queried.
  3. The field to display for the object. (If the Variable picks a field then this is also the source for the value.)
  4. A filter to preselect elements from the collection.
  5. Press one of the edit buttons to pop up an editor for the coresponding value.

Configuring Selection Variables

  1. The root that is used as the entry point into the database.
  2. The collection which is reachable from the root that will be queried.
  3. The field to display for the object. (If the Variable picks a field then this is also the source for the value.)
  4. A filter to preselect elements from the collection.
  5. The initial selection presented to the user can either be empty (user selects values) or has all elements (User deselects).
  6. This specifies wheter the returned variable contains a collection of objects or a collection of strings.
  7. Press one of the edit buttons to pop up an editor for the coresponding value.