您可以使用查询过滤器定义查询的搜索条件,这些过滤器基于对用户数据库中每条记录的字段的比较。该查询将在 ResultSet 对象中返回数据库中与搜索条件匹配的所有记录。
每次比较都是 QueryFilterNode 对象的一个实例,由过滤器实施。过滤器允许您将一个字段与单一值或某个范围内的多个值进行比较。为过滤器选择的运算符确定要执行的比较类型。
要获取有效运算符的列表,请参阅 CompOp 常量枚举类型。要创建过滤器的分层树,请使用布尔运算符将它们连接在一起,并可以将某些过滤器嵌套在另一些过滤器中。
每个过滤器包含单一条件,或使用 AND 或 OR 运算符连接在一起的一组条件。在构建自己的过滤器时,您可以嵌套多组更为复杂的过滤器,以创建一组复杂的搜索逻辑。
以下是设计查询时常用的一些对象以及处理查询的方法:
- QueryDef 对象:
- BuildQuery(记录类型)- 针对指定记录类型的新查询
- BuildField(指定要显示的字段)。
- BuildFilterOperator 方法需要枚举常量 - BoolOpConstant(And/Or)。
- Session 对象:
- BuildResultSet 方法(从查询检索到的数据的占位符)。
- ResultSet 对象:
- BuildResultSet 方法(从查询检索到的数据的占位符)。
- Execute 方法(运行查询并检索产生的数据)。
- MoveNext 方法(将游标移至数据集中的下一条记录)。
- GetColumnLabel 方法(已获取的字段标签文本)- 例如,“Headline”、“id”以及“State”
- GetColumnValue 方法(获取特定于字段的数据)- 例如,“SAMPL00000014”、“This is my headline”以及“Submitted”
- QueryFilterNode 对象:
- BuildFilter(过滤器参数)需要 CompOpConstant 枚举常量(如 EQ、NEQ、GT、GTE、LT 以及 LTE)形式的比较运算符(如 In、Equal、Less Than、Greater Than 以及 Is Null)和要比较的值(如 State EQ Submitted),以及一个 Perl 字符串数组,该数组包含要与指定字段中的值进行比较的值。
- BuildFilterOperator 方法需要枚举常量 - BoolOpConstant
设计查询时,您可以使用以上列出的方法,如下所示:
- 使用 BuildQueryDef 方法来构建 QueryDef 对象:$QueryDef
= $Session->BuildQueryDef(entity-def-name)
- 使用 BuildField 方法添加要选择的字段:$QueryDef->BuildField(field-name)
- 将查询过滤器构建为 And/Or 树。And/Or 节点是 QueryFilterNode 对象。使用 BuildFilterOperator 方法构造树的顶级节点:$QueryFilterNode =
$QueryDef->BuildFilterOperator(bool)
- 使用以下方法,将 And/Or 比较节点添加为 QueryFilterNode 对象的子代:QueryFilterNode = $QueryFilterNode->BuildFilter(field,CompOp,value) 和 $QueryFilterNode->BuildFilterOperator(bool) 例如,要针对表达式 priority = 1 and (component = gui or owner = joe) 进行过滤:
$and_node = $querydef->BuildFilterOperator(And);
$and_node->BuildFilter("priority",eq,1);
$or_node = $and_node->BuildFilterOperator(Or);
# The third argument of the BuildFilter method must be a reference to an array:
# Here we first build the array @comp, then pass
# the reference \@comp into the BuildFilter method.
@comp = ("gui");
$or_node->BuildFilter("component", $CQPerlExt::CQ_COMP_OP_EQ, \@comp);
@name = ("Joe");
$or_node->BuildFilter("owner", $CQPerlExt::CQ_COMP_OP_EQ, \@name);
# Another way to pass the array reference for simple values is using anonymous arrays. For example:
$or_node->BuildFilter("owner", $CQPerlExt::CQ_COMP_OP_EQ, ["Joe"]);
示例
以下示例包含一些查询过滤器,扩展了前一主题中的示例:
use CQPerlExt;
#Start a Rational ClearQuest session
$SessionObj = CQSession::Build();
$dbsetname = "CQMS.SAMPL.HOME";
#Refresh list of accessible databases
$databases = $SessionObj->GetAccessibleDatabases("MASTR", "", $dbsetname);
#Log into a database
$SessionObj->UserLogon("admin","","SAMPL",$dbsetname);
#Create a Query
$querydef = $SessionObj->BuildQuery("defect");
$querydef->BuildField("id");
$querydef->BuildField("headline");
$querydef->BuildField("owner.login_name");
$querydef->BuildField("submit_date");
#Create the queryfilternode object:
# where (state is not Closed AND (id = 1 OR id = 2))
$where = $querydef->BuildFilterOperator($CQPerlExt::CQ_BOOL_OP_AND);
# All filter values passed in as a reference to an array.
@states = ("closed");
$where->BuildFilter("state", $CQPerlExt::CQ_COMP_OP_NEQ, \@states);
# Another way to pass the array reference for simple values is using an anonymous array, like this:
# $where->BuildFilter("state", $CQPerlExt::CQ_COMP_OP_EQ, ["closed"]);
$subor = $where->BuildFilterOperator($CQPerlExt::CQ_BOOL_OP_OR);
@id1 = ("SAMPL00000001");
$subor->BuildFilter("id", $CQPerlExt::CQ_COMP_OP_EQ, \@id1);
@id2 = ("SAMPL00000002");
$subor->BuildFilter("id", $CQPerlExt::CQ_COMP_OP_EQ, \@id2);
$resultset = $SessionObj->BuildResultSet($querydef);
$ct = $resultset->ExecuteAndCountRecords();
for ($i = 0; $i < $ct; $i++) {
$resultset->MoveNext();
print $resultset->GetColumnValue(1);
print " ";
print $resultset->GetColumnValue(2);
print " ";
print $resultset->GetColumnValue(3);
print " ";
print $resultset->GetColumnValue(4);
print "\n";
}
CQSession::Unbuild($SessionObj);