Making expressions for ad hoc parameters

The value of an ad hoc parameter can be a single value or an expression. Expressions use special characters called operators to select a group or range of values. For example, a greater than sign (>) specifies matching a value that is greater than the value that follows the symbol, as in >10. In this example, the greater than sign is the operator and 10 is the value.

There are two types of ad hoc parameters available, Dynamic Filters and Query by Example (QBE). Dynamic Filters requests users to build simple expressions using a single operator. Query by Example (QBE) syntax requests users to select one or more operators to build simple and complex expressions.

Examples of using expressions in an ad hoc parameter:

A single value, such as 10.

A relational expression, such as >10.

A range of values, such as 10–20.2

A list of values, expressions, or ranges, separated by pipe signs, such as 10|20–30|>50. Some locales also accept a comma as a list separator.

A group of values, such as (abc|xyz), that a Boolean expression can combine, such as (abc|xyz)&bbb.

Dynamic filters are used in BIRT design and document files. QBE ad hoc parameters are used in BIRT spreadsheet files.

Using a dynamic filter operator

When an Actuate file prompts the user to select from a list of operators, the user selects one of the operators and supplies a value for the operator to use. This expression is used to select data to display in the document.

Figure 3-4 shows an example of using dynamic filter operators.

Figure 3-4

Using dynamic filters

Dynamic filters are available in BIRT design and document files. Table 3-1 lists the operators that are available in Actuate files. Developers select which operators are presented to users of the file.

Table 3-1

Dynamic filter operators

Operator	Usage
Between	Find data that is between two specific values
Equal to	Find data equal to a specific value
Greater than	Find data greater than the specific value
Greater than or equal to	Find data greater than or equal to the specific value
In	Find data that matches any of the selected values
Is false	Find data that equals zero
Is not null	Find data that does not have a null value
Is null	Find data that has a null value
Is true	Find data that does not equal zero
Less than	Find data less than the specific value
Less than or equal	Find data less than or equal to the specific value
Like	Find data matching the value’s string pattern
Match	Find data matching the value’s string expression
No Condition	Find all values for this parameter
Not between	Find data that is not between two specific values
Not equal to	Find data not equal to a specific value
Not in	Find data that does not match any of the selected values
Not like	Find data not matching the value’s string pattern
Not match	Find data not matching the value’s string expression

The Like operator supports the following special characters:

% matches zero or more characters. For example, %ace% matches any value that contains the string ace, such as Ace Corporation, Facebook, Kennedy Space Center, and MySpace.

_ matches exactly one character. For example, t_n matches tan, ten, tin, and ton. It does not match teen or tn.

The Match operator is case sensitive and supports special metacharacters that can be combined to form text patterns called regular expressions. Metacharacters can be combined to form complex matches. For example, using ^H.*(Gifts|Collectables)$ to search through a list of company names matches all companies whose name starts with the letter H, has one or more letters after H and includes the word Gifts or Collectables at the end of the name.

If you need to match on a metacharacter itself, a backslash (\) followed by the metacharacter causes the search to interpret the metacharacter as a normal character. For example, if $ is part of the data to be found, it must be entered as \$ because $ is a metacharacter.

Table 3-2 lists the metacharacters that can be used to form regular expressions with the Match operator.

Table 3-2

Regular expression metacharacters

Metacharacter	Usage
.	Matches any single character.
*	Matches the previous character zero or more times. For example po* matches Liverpool and Leipzig.
!	Matches everything not equal to the search expression.
( )	Matches all characters in the set between the parentheses.
|	Matches if any one of multiple conditions is true.
[]	Matches any character in the set between the brackets
[^ ]	Matches any character not in the set between the brackets.
+	Matches the previous character one or more times. For example, po+ matches Singapore and Liverpool but not Leipzig.
?	Matches the previous character zero or one times. For example, po? matches Singapore and Leipzig.
x{y}	Matches the previous character exactly y times. For example, o{2} matches Liverpool but not Lyon.
^	Matches the start of the string. For example ^A matches Australia but does not match Los Angeles.
$	Matches the end of the string. For example n$ matches Lyon.
\	Used with a metacharacter to make it a literal character. For example, to search for a string containing the $ sign, search for \$.
\A	Matches the start of a string.
\b	Matches the edge of a word, beginning or end.
\B	Matches any place inside a word, but not the edge of a word.
\d	Matches any decimal digit.
\D	Matches any non digit character.
\s	Matches a space.
\S	Matches a non space.
\w	Matches a word that is made of letters, numbers or an underscore.
\W	Matches a non word.
\Z	Matches the end of a string.

Table 3-3 provides examples of dynamic filter expressions.

Table 3-3

Example results for dynamic filter expressions

Operator	Values	Matches	Does not match
Between	'A' 'D'	'Barcelona' 'Dublin'	'Zurich' 'Seattle'
Greater than	'Oslo'	'Oulu' 'Paris'	'Oslo' 'NYC'
In	'Lyon' 'New York'	'Lyon' 'New York'	'London' 'New Haven'
Is False		'0'	'11'
Like	'A%'	'Amsterdam' 'Auckland'	'Zurich'
Like	'B___'	'Bern'	'Berlin' 'Boston'
Like	'Be%n'	'Berlin' 'Bern'	'Bergamo'
Like	'%& Co%n'	'Handji Gifts& Co' 'Models & Co.'	'Boards & Toys Co' 'Cruz & Sons Co.'
Match	'ity'	'City' 'Makati City'	'Nantes' 'Paris'
Match	'ern'	'Stavern' 'Bern'	'Liverpool' 'Bergen'
Match	'(ern)|(New)'	'Bern' 'Newark' 'New Bedford'	'Glendale' 'Cunewalde'
Match	'A'	'Allentown' 'Los Angeles'	'Nantes' 'Paris'
Match	'.A'	'Los Angeles'	'Allentown'
Match	'[A-C]'	'Burbank' 'Los Angeles' 'NYC'	'Frankfurt' 'Singapore'
Match	'es.'	'Manchester'	'Nantes'
Match	L[^o]s	'Lisboa'	'Los Angeles'

Using Query by Example operators

Users build a QBE expression by combining operators and values, for example >10 is a QBE expression defining a value greater than ten. QBE expressions are available with BIRT Spreadsheet and e.Report files. Table 3-4 lists the operators that can be used to form ad hoc parameter expressions.

Table 3-4

QBE operators used in ad hoc parameters

Name	Operator	Usage
Ampersand	&	Match if two or more conditions are true
Backslash	\	Used with an operator to make it a literal character
Brackets	[]	Matches any character in the set between the brackets
Caret	^	Matches everything not in the bracket set
Comma	,	Combines search terms and expressions
Exclamation	!	Matches everything not equal to the search expression
Greater than	>	Matches everything greater than the value that follows the operator
Greater than or equal to	>=	Matches everything greater than the value that follows the operator
Hyphen	-	Separates upper and lower limits of the search range
Less than	<	Matches everything less than the value that follows the operator
Less than or equal to	<=	Matches everything less than or equal to the value that follows the operator
Number sign	#	Matches any single ASCII numeric character [0–9]
Parenthesis	( )	Matches all characters in the set between the parenthesis
Percent sign	%	Matches any character, group of characters, or no character
Pipe sign	|	Matches if any one of multiple conditions is true
Single quotation mark	'	Converts an operator character in a string into a literal character
Underscore	_	Matches any single character

Copyright Actuate Corporation 2012