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 2 types of ad hoc parameters available to Information Console users; Dynamic Filters and Query by Example (QBE). Dynamic Filters requests users to build expressions using a single operator. Query by Example (QBE) syntax requests users to select one or more operators to also build complex expressions.

Examples of using expressions in an ad hoc parameter:

n	A single value, such as 10.

n	A relational expression, such as >10.

n	A range of values, such as 10–20.2

n	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.

n	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 and e.Report files.

Using a dynamic filter operator

Dynamic filters appear in BIRT design and document files. When dynamic filters exist in an Actuate file, Information Console prompts the user to select from a list of operators and supply a value. The developer decides which operators are available in an Actuate file.

Dynamic filters support multiple values and complex string expressions, depending on the operator. Data matching this expression displays in the output document of the file job.

Figure 4-23 shows an example of using dynamic filter operators to make an ad hoc expression.

Figure 4-23  Using dynamic filters

Table 4-3 lists the operators that are available in Actuate files. Developers select which operators are available to users of the file.

Table 4-3  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:

n	% 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.

n	_ 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 combine to form text patterns called regular expressions. 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, 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 4-4 lists the metacharacters available to form regular expressions with the Match operator.

Table 4-4  Regular expression metacharacters used with Match

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 a $ sign, use \$.
\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 4-5 provides examples of dynamic filter expressions.

Table 4-5  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' or 'Boston'
Like	'Be%n'	'Berlin' or 'Bern'	'Bergamo'
Like	'%& Co%n'	'Handji Gifts& Co' 'Models & Co.'	'Boards & Toys Co' 'Cruz & Sons Co.'
Match	'es.'	'Manchester'	'Nantes'
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	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 4-6 lists the operators available to form ad hoc parameter expressions.

Table 4-6  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

(c) Copyright Actuate Corporation 2011