BuildFilter

Description

Adds a comparison operand to the node.

The operand created by this method consists of a field name, a comparison operator, and a value. When the query is run, the value in the field is compared to the specified value using the given comparison operator. The comparison yields a Boolean value, which the node uses in its own Boolean comparison.

The value argument is a VBScript Variant or Perl reference to an array of strings to allow you to specify an array of values when appropriate. For example, if you wanted to find the defects submitted between December 1 and December 15, 2007, you could construct the following filter:

@dateRange = ("2007-12-01", "2007-12-15");
$node->BuildFilter("submit_date", $CQPerlExt::CQ_COMP_OP_BETWEEN, \@dateRange);

The BuildFilter method requires a third argument for all comparison operators, including OP_IS_NULL and OP_IS_NOT_NULL. For example,

$operator->BuildFilter("customer_priority", $CQPerlExt::CQ_COMP_OP_IS_NOT_NULL, [""]);
$operator->BuildFilter("customer_priority", $CQPerlExt::CQ_COMP_OP_IS_NULL, [""]);

See also the example given for the BuildFilterOperator method of the QueryDef object.

Query expressions are not limited to being binary trees; you can call this method as many times as you want for a given QueryFilterNode object.

To obtain valid values for the field_name argument, call the GetFieldDefNames method of the EntityDef object upon which the query was based.

Syntax

VBScript

node.BuildFilter field_name, comparison_operator, value

Perl

$node->BuildFilter(field_name, comparison_operator, value);

Identifier

Description

node

A QueryFilterNode object, representing one node in the query expression.

field_name

A String containing the name of a valid field in the EntityDef Object on which the current QueryDef Object is based.

comparison_operator

A Long whose value is one of the CompOp enumeration constants.

value

The value you want to find in the specified field.

For VBScript, specify the value as a Variant array.

For Perl, specify the value as a reference to a string or an array of strings.

Return value

None.

Examples

VBScript

Dim dateRange
ReDim dateRange(1) ' This sets up a two element array
dateRange(0) = "2007-12-01" 
dateRange(1) = "2007-12-15" 
node.BuildFilter "submit_date", AD_COMP_OP_BETWEEN, dateRange

Perl

#Example1
@dateRange = ("2007-12-01", "2007-12-15"); 
$node->BuildFilter("submit_date", $CQPerlExt::CQ_COMP_OP_BETWEEN, \@dateRange); 

#Example2
@owner = ("jsmith");
@state = ("closed");
$queryDef = $CQsession->BuildQuery("defect");
@dbfields = ("ID","State","Headline");
foreach $field (@dbfields) {
   $queryDef->BuildField($field);
   }
$operator=$queryDef->BuildFilterOperator($CQPerlExt::CQ_BOOL_OP_AND);
$operator->BuildFilter("Owner", $CQPerlExt::CQ_COMP_OP_EQ,\@owner);
$operator->BuildFilter("State", $CQPerlExt::CQ_COMP_OP_NOT_IN, \@state);