基于 Rational ClearQuest API 的脚本开发技巧

基于 Rational ClearQuest API 的脚本开发技巧

2008-03-07 作者：王秉坤,张涛 来源：IBM

本文内容包括：

本文主要介绍如何利用 Rational ClearQuest API 从代码层次上实现 Rational ClearQuest 的相关功能，并通过相关的例子帮助读者掌握基于 Rational ClearQuest API 的脚本开发方式和技巧。

Rational ClearQuest 是重要的变更管理工具，Rational ClearQuest 更能让客户根据自己的具体需求，灵活的设计变更管理流程。除此之外，Rational ClearQuest 还提供了一套编程接口，即 Rational ClearQuest API，让用户和开发人员可以根据需要通过编程来实现 Rational ClearQuest 的相关功能，同时还可以通过编程来实现模式中 Hook 脚本的开发和定制，从而使整个 Rational ClearQuest 产品的功能更加灵活和强大。本文就全面介绍了基于 Rational ClearQuest API 的脚本开发技巧，以便读者了解如何通过编程来实现 Rational ClearQuest 相关功能，以及如何实现模式中 Hook 脚本的开发和定制的过程和注意事项。

在 Rational ClearQuest 中有两个非常重要的概念，一个是模式库，一个是用户数据库，其中用户数据库需要与某个模式的某个版本相关联，如图１所示。模式存放在模式库中，用户的数据存放在用户数据库中。用户可以通过 Rational ClearQuest 客户端访问模式库和用户数据库。Rational ClearQuest API 为用户和开发人员提供了一套可编程接口，从代码层面上实现 Rational ClearQuest 的相关功能，访问和操作模式库及用户数据库中的相应数据。

　

一般来说，用户使用 Rational ClearQuest 访问和操作数据库的过程，如图２所示，用户可以通过 ClearQuest 客户端，调用 ClearQuest Core 中的代码，而后 ClearQuest Core 通过 ODBC 建立与数据库之间的连接。而 Rational ClearQuest API 可以在用户和 ClearQuest Core 之间建立起桥梁，用户通过 API 调用 ClearQuest Core 中的相应模块，进而通过 ODBC 访问数据库。

Rational ClearQuest API 提供了基于 VBScript 和 Perl 脚本的两种接口，Rational ClearQuest API 的文档中也分别提供了关于两种接口的说明。对于 Linux 和 Unix 平台，我们可以调用基于 Perl 的 API，对于 Windows 平台，我们可以调用基于 VBScript 或 Perl 的 API。

Rational ClearQuest API 有两种调用方式，分别是：

1. 在 ClearQuest hook 或脚本中调用
2. 在外部应用程序中调用

通过对 Rational ClearQuest API 的调用，用户和开发人员将可以从代码层面上实现以下功能：

1. 登陆用户数据库或者模式库
2. 浏览，编辑或创建新的数据记录
3. 创建查询，运行已有的查询并且得到查询的结果
4. 生成图和报表
5. 浏览和更新用户、组、数据库信息

在 Rational ClearQuest API 中定义了很多对象和常量，为了便于区分，针对不同的编程语言，它们的定义遵循一定的命名规范。

基于 VBScript 的 Rational ClearQuest API 中对象及常量的命名规范如表 1 所示：

表 1 基于 VBScript 的 Rational ClearQuest API 中对象及常量的命名规范

前缀	描述	举例
OAd	对象的前缀	OAdEntity OAdSession
AD	常量的前缀	AD_BUTTON_CLICK AD_ORACLE

基于 Perl 的 Rational ClearQuest API 中对象及常量的命名规范如表 2 所示：

表 2 基于 Perl 的 Rational ClearQuest API 中对象及常量的命名规范

前缀	描述	举例
CQ	对象的前缀	CQEntity CQSession
$CQPerlExt::CQ	常量的前缀	$CQPerlExt::CQ_BUTTON_CLICK $CQPerlExt::CQ_ORACLE

另外，在 Rational ClearQuest API 的命名规范中，英文复数的对象名通常指一组以单数对象名命名的对象，比如 Schemas 就是一个包含多个 Schema 对象的集合。还有，名称后包含 Def 三个字母的对象一般用于定义以其前缀命名的对象，比如 EntityDef 就定义和描述了 Entity 对象的结构。了解了这些，会帮助我们更好地阅读，理解和使用 Rational ClearQuest API。

在 Rational ClearQuest Common Schema 中，每一个数据类型，对应了用户数据库中的一张表，表中的每一条记录对应了一条属于该数据类型的数据。在 Rational ClearQuest API 中，定义了 Entity 对象，Rational ClearQuest 用户数据库表中的每一条记录可以对应为一个 Entity 对象。一条数据记录的所有信息都可以存储在一个 Entity 对象中，通过 Entity 对象的方法可以得到一条记录的每一数据项的值。通过创建 Entity 对象，用户可以在代码层次对数据记录进行一系列的操作。

Entity 对象具备两个属性，一个是 AttachmentFields，用来记录该条记录的附件，一个是 HistoryFields，用来记录该条记录的历史日志，它们都是只读的，无法通过程序进行修改。

Entity 对象的一些常用方法如表 3 所示：

表 3 Entity 对象的常用方法及描述

方法	描述
AddAttachmentFieldValue	为数据记录添加附件及描述
AddFieldValue	为某数据记录添加值
Commit	提交数据记录
GetActionName	获得操作名称
GetDbId	获得该数据记录的 DBID
GetFieldChoiceList	获得某数据项的选项单
GetFieldType	获得某数据项的类型
GetFieldValue	获得某数据项的值
Revert	忽略对数据记录做出的改动
SetFieldChoiceList	设定某数据项的选项单
SetFieldRequirenessForCurrentAction	设定某数据项的行为，可以是 Mandatory，Optional 或 Read-only
SetFieldValue	设定某数据项的值
Validate	验证该数据记录是否合法可以提交

由于每种数据类型的数据项、数据项的行为、状态、状态跳转、操作、Hook 都不相同，因此 Entity 对象有不同的结构，它的结构就是由 EntityDef 对象来定义和描述的。EntityDef 对象中包含的这些信息是只读的。

在 Rational ClearQuest API 中，定义了 Session 对象，用户可以通过 Session 对象访问 ClearQuest 用户数据库、创建查询、对数据记录进行操作。

图 3 显示出了 Session 对象与 Entity 对象的关系，通过 Session 对象，用户可以登陆用户数据库，每一个 Entity 对象对应了某种数据类型在用户数据库中的一条数据记录。

Session 对象的一些常用方法如表 4 所示：

表 4 Session 对象的常用方法及描述

方法	描述
BuildEntity	创建数据记录
BuildQuery	创建查询
BuildSQLQuery	创建基于 SQL 语句的查询
DeleteEntity	删除数据记录
EditEntity	编辑数据记录
EntityExists	判断某条数据记录是否存在
GetEntity	获得指定数据类型的数据记录
GetSessionDatabase	获得当前 Session 访问的数据库名称
OutputDebugString	输出调试信息
UserLogon	以特定的用户名和密码登陆用户数据库

Session 变量作用于整个 Session 周期中，对于整个登陆 Session 来说，Session 变量是全局变量。当创建 Session 变量之后，可以通过当前 Session 对象访问 Session 变量，当 Session 结束时，Session 变量会自动被释放。在程序中，使用 HasValue 方法可以判断当前 Session 是否定义了某个 Session 变量。下面的代码就是一个关于如何创建 Session 变量的例子。

                VBScript example:
Dim myValue
myValue = "Hello World"
‘cuSession 为 Session 对象
if(curSession.HasValue(“Hello”))
{
‘获得 Session 变量 Hello 的值
Dim newValue
newValue = curSession.NameValue("Hello")
}
else
{
‘创建变量 Hello, 并将 myValue 的值赋给 Session 变量
curSession.NameValue "Hello", myValue
}

Perl example:
my $myValue = "Hello World";
#$curSession 为 Session 对象
if($curSession->HasValue(“Hello”))
{
# 获得 Session 变量 Hello 的值
my $newValue = $curSession->GetNameValue("Hello");
}
else
{
# 创建变量 Hello, 并将 myValue 的值赋给 Session 变量
$curSession->SetNameValue("Hello", $myValue);
}

使用 Rational ClearQuest API 访问用户数据库的基本调用顺序分为以下四步：

1. 启动 ClearQuest Session
2. 登入用户数据库
3. 操作 ClearQuest 用户数据库中的数据记录
4. 结束 ClearQuest Session

在 Rational ClearQuest 的 hook 中，Session 对象会自动被创建，因此这里主要讨论如何在外部应用程序中创建 Session 对象。

下面的代码是如何在外部应用程序中创建 Session 对象的例子：

                VBScript example:
Set curSession = CreateObject(“CLEARQUEST.SESSION”)

Perl example:
my $curSession = CQSession::Build();
# 释放 Session 对象
CQSession::Unbuild($curSession);

下面的代码是如何在 Hook 中获得 Session 对象的例子：

                VBScript example:
Set currentSession = GetSession

Perl example:
my $curSession = $entity->GetSession();

在操作用户数据库的数据之前，需要使用 ClearQuest 授权的用户名密码登入数据库，一般来说这个操作包括以下几步：

1. 通过 Session 对象调用方法 GetAccessibleDatabases 获得和模式库相关联的用户数据库列表，这个方法返回的是 DatabaseDesc 对象列表，其中每个对象包含一个用户数据库的信息
2. 通过调用 DatabaseDesc 对象的方法可以得到相应用户数据库的信息，比如数据库名称，与其相关联的模式库等
3. 通过 Session 对象调用方法 UserLogon，以用户数据库名称，相关联的模式库，ClearQuest 用户名和密码为参数，就可以登入用户数据库建立查询对数据进行操作了

下面的例子就是通过代码实现了这一过程：

                VBScript example:
Set Databases = curSession.GetAccessibleDatabases(“MASTER”, “admin”, “”)
for each db in Databases 
Set dbName = db.GetDatabaseName 
curSession.UserLogon("Mike", "1qaz2wsx", dbName, AD_PRIVATE_SESSION, "")
Next

Perl example:
my $Databases;
$Databases = $curSession->GetAccessibleDatabases("MASTR", "admin", ""); 
my $count = $Databases->Count();
for(my $i=0;$i<$count;$i++)
{ 
my $db = $databases->Item($i); 
my $dbName = $db->GetDatabaseName();
my $curSession->UserLogon( "Mike", "1qaz2wsx", $dbName, "" ); 
} 

在 ClearQuest 的 Hook 中，则无需进行上述这些数据库登入操作，因为用户数据库的授权登入是由 ClearQuest 客户端来控制的。

了解了使用 Rational ClearQuest API 访问用户数据库的步骤后，我们有必要对如何使用 Rational ClearQuest API 操作用户数据库中的数据进行详细介绍。下面将分别介绍如何调用 Rational ClearQuest API 建立查询、生成图表的方法。

下面的代码分别是使用 Session 对象的 BuildQuery 方法和 BuildSQLQuery 方法建立查询的过程：

                VBScript example:
'使用 BuildQuery 方法建立查询
'建立针对数据类型“defect”的查询
Set Query = curSession.BuildQuery ("defect")
Query.BuildField("id")
Query.BuildField("headline")

'建立查询的结果集
Set Result = curSession.BuildResultSet (Query)

'运行查询，查询结果会返回到结果集中
Result.Execute


'使用 BuildSQLQuery 方法建立查询
'创建 SQL 语句
Set sqlQuery = “Select * from Defect”

'建立查询的结果集
Set Result = curSession.BuildSQLQuery(sqlQuery)

'运行查询，查询结果会返回到结果集中
Result.Execute

'根据结果集的查询结果对数据进行操作
while (Result.MoveNext == AD_SUCCESS)
{
Set Id = Result.GetColumnValue(1)

'获取关于“defect”数据类型的数据记录
DefectEntity = curSession.GetEntity "Defect" Id

'获取相应数据项的值
 Set Head = DefectEntity.GetFieldValue("Headline").GetValue
 Set State= DefectEntity.GetFieldValue("State").GetValue
}


Perl example:
# 使用 BuildQuery 方法建立查询
# 建立针对数据类型“defect”的查询
my $Query = $curSession -> BuildQuery ("defect");
$Query -> BuildField ("id");
$Query -> BuildField ("headline");

# 建立查询的结果集
my $Result = $CurSession -> BuildResultSet ($Query);

# 运行查询，查询结果会返回到结果集中
$Result -> Execute();


# 使用 BuildSQLQuery 方法建立查询
# 创建 SQL 语句
my $sqlQuery = “Select * from Defect”;

# 建立查询的结果集
my $Result = $curSession->BuildSQLQuery($sqlQuery);

# 运行查询，查询结果会返回到结果集中
$Result->Execute();

# 根据结果集的查询结果对数据进行操作
while ($Result->MoveNext() == $CQPerlExt::CQ_SUCCESS)
{
my $Id = $Result->GetColumnValue(1);

# 获取关于“defect”数据类型的数据记录
my $DefectEntity = $curSession->GetEntity("Defect", $Id);

# 获取相应数据项的值
 my $Head = $DefectEntity->GetFieldValue("Headline")->GetValue();
 my $State= $DefectEntity->GetFieldValue("State")->GetValue();
}

在介绍调用 Rational ClearQuest API 生成图表之前，有必要对 API 中定义的 WorkSpace 对象作一个介绍，Rational ClearQuest 的 WorkSpace 包含查询，图表存储的目录层次关系。WorkSpace 对象主要就是用来储存这些信息，在代码中我们可以通过调用 Session 对象的 GetWorkSpace 方法得到 WorkSpace 对象。

在 Rational ClearQuest API 中，定义了 ChartMgr 对象，该对象提供了创建图的接口。值得注意的是，ChartMgr 对象只支持 Windows 系统下的绘图。

在 Windows 系统下调用 Rational ClearQuest API 生成图可以分为以下几个步骤：

1. 通过调用 Session 对象的 GetWorkSpace 方法得到 WorkSpace 对象
2. 调用 WorkSpace 对象的 GetCharMgr 方法得到 ChartMgr 对象
3. 创建查询的结果集，用 Execute 方法得到查询结果
4. 调用 ChartMgr 对象的 SetResultSet 方法设定图中包含的数据
5. 调用 ChartMgr 对象的 MakeJPEG 或 MakePNG 方法生成图，并存储于指定的文件路径中

下面的代码是调用 Rational ClearQuest API 生成图的例子：

                VBScript example:
'创建 WorkSpace 对象
Set WorkSpace = curSession.GetWorkSpace
Set ChartDef = WorkSpace.GetChartDef "Personal Queries/Sample_Chart"

'创建结果集
Set Result = curSession.BuildResultSet(ChartDef)
Result.SetMaxRowsInMemory(1000)
Result.Execute

'创建 ChartMgr 对象
Set chartMgr = WorkSpace.GetChartMgr
chartMgr.SetResultSet Result

'生成图
chartMgr.MakeJPEG "C:\\ Chart.jpg"

Perl example:
# 创建 WorkSpace 对象
my $WorkSpace = $curSession->GetWorkSpace();
my $ChartDef = $WorkSpace->GetChartDef("Personal Queries/Sample_Chart");

# 创建结果集
my $Result = $curSession->BuildResultSet($ChartDef);
$Result->SetMaxRowsInMemory(1000);
$Result->Execute();

# 创建 ChartMgr 对象
my $chartMgr = $WorkSpace->GetChartMgr();
$chartMgr->SetResultSet($Result);

# 生成图
$chartMgr->MakeJPEG("C:\\ Chart.jpg");

在 Rational ClearQuest API 中，定义了 ReportMgr 对象，该对象提供了创建报表的接口。值得注意的是，ReportMgr 对象也只支持 Windows 系统下报表的创建。

在 Windows 系统下调用 Rational ClearQuest API 生成报表可以分为以下几个步骤：

1. 通过调用 Session 对象的 GetWorkSpace 方法得到 WorkSpace 对象
2. 调用 WorkSpace 对象的 GetReportMgr 方法得到 ReportMgr 对象
3. 调用 ReportMgr 对象的 SetHTMLFileName 方法设定报表文件存储路径
4. 调用 ReportMgr 对象的 ExecuteReport 方法生成报表

下面的代码是调用 Rational ClearQuest API 生成报表的例子：

                VBScript example:
'创建 WorkSpace 对象
Set WorkSpace = curSession.GetWorkSpace

'创建 ReportMgr 对象
Set reportMgr = WorkSpace.GetReportMgr "Personal Queries/Sample_report"
reportMgr.SetHTMLFileName "C:\\Report.html"

'生成报表
reportMgr.ExecuteReport

Perl example:
# 创建 WorkSpace 对象
my $WorkSpace = $curSession->GetWorkSpace();

# 创建 ReportMgr 对象
my $reportMgr = $WorkSpace->GetReportMgr ("Personal Queries/Sample_report" );
$reportMgr->SetHTMLFileName("C:\\Report.html");

# 生成报表
$reportMgr->ExecuteReport();

在用户数据库中创建，修改和删除数据记录主要通过调用 Entity 对象的相应方法来实现。

下面的代码是调用 Rational ClearQuest API 创建数据记录的例子：

                VBScript example:
'创建基于”Defect”数据类型的 Entity 对象
set DefectEntity = curSession.BuildEntity(“Defect”) 
DefectEntity.SetFieldValue “Headline”“MyDefect”
DefectEntity.SetFieldValue “Severity”“1-Critical”
Set Status = DefectEntity.Validate
if Status = “” then
 '提交数据记录
 DefectEntity.Commit
else
 DefectEntiry.Revert
End if

Perl example:
# 创建基于”Defect”数据类型的 Entity 对象
my $DefectEntity = $curSession->BuildEntity(“Defect”);
$DefectEntity->SetFieldValue(“Headline”, “MyDefect”);
$DefectEntity->SetFieldValue(“Severity”, “1-Critical”);
 my $Status = $DefectEntity->Validate();
 if($Status eq “”) 
{
 # 提交数据记录
$DefectEntity->Commit();
}
else
{
 # 打印错误信息
 print $Status;
 $DefectEntity->Revert();
}

下面的代码是调用 Rational ClearQuest API 修改数据记录的例子：

                VBScript example:
'得到 id 为“BUGDB00000001”的数据记录
Set DefectEntity = curSession.GetEntity(“Defect”, “BUGDB00000001”)

'设定修改数据记录的操作
curSession.EditEntity DefectEntity “Modify”
DefectEntity.SetFieldValue “Headline”“MyDefect”
DefectEntity.SetFieldValue “Severity”“1-Critical”
Set Status = DefectEntity.Validate
if Status = “” then
 '提交数据记录
 DefectEntity.Commit
else
 DefectEntiry.Revert
End if

Perl example:
# 得到 id 为“BUGDB00000001”的数据记录
my $DefectEntity = $curSession->GetEntity(“Defect”, “BUGDB00000001”);

# 设定修改数据记录的操作
$curSession->EditEntity($DefectEntity ,“Modify”);
$DefectEntity->SetFieldValue(“Headline”, “MyDefect”);
$DefectEntity->SetFieldValue(“Severity”, “1-Critical”);
 my $Status = $DefectEntity->Validate();
 if($Status eq “”) 
{
 # 提交数据记录
$DefectEntity->Commit();
}
else
{
 # 打印错误信息
 print $Status;
 $DefectEntity->Revert();
}

下面的代码是调用 Rational ClearQuest API 删除数据记录的例子：

                VBScript example:
'得到 id 为“BUGDB00000001”的数据记录
Set DefectEntity = curSession.GetEntity(“Defect”, “BUGDB00000001”)
'删除数据记录
curSession.DeleteEntity DefectEntity “Delete”

Perl example:
# 得到 id 为“BUGDB00000001”的数据记录
my $DefectEntity = $curSession->GetEntity(“Defect”, “BUGDB00000001”);
# 删除数据记录
$curSession->DeleteEntity($DefectEntity ,“Delete”);

和访问用户数据库类似，访问模式库，首先需要建立 AdminSession 对象，再调用该对象的 Logon 方法访问模式库，其中，AdminSession 对象允许用户创建和模式库相关的 Session 对象。

调用 Logon 成功后，可以使用 AdminSession 对象的其他方法进行下列的操作：

1. 创建数据库
2. 删除数据库
3. 创建用户
4. 创建组
5. 5．查询模式、用户数据库、用户和组信息

AdminSession 对象的层级结构如图 4 所示。AdminSession 对象的属性中包含四个对象，分别是 Schemas 对象，Databases 对象，Groups 对象和 Users 对象。根据前面讲的命名规范，我们会比较容易理解下面的层级结构图。其中，SchemaRevs 对象包含某一个 Schema 对象所对应模式 ( 即 Schema) 的所有版本，SchemaRev 对象包含其中某一版本的相关信息。

表 5 列出了上述几个比较重要的对象及其描述

表 5 AdminSession 相关对象及描述

对象	描述
Database	可以存储用户数据库的信息，包括数据库名称、登陆用户名、密码、数据库的类型等
User	可以存储模式库的用户信息，包括用户名、密码、对不同数据库的权限等
Group	可以存储组信息，包括组名、组所包含的用户名、组权限所应用的数据库等
Schema	可以存储模式信息，包括模式名称及该模式相应的各个版本信息
SchemaRev	可以存储某一模式的特定版本信息及该版本的描述

用 Rational ClearQuest API 创建用户数据库，分以下几步完成：

1. 创建 AdminSession 对象
2. 登陆模式库
3. 创建用户数据库
4. 配置用户数据库参数

下面的例子就是通过代码实现了这一过程：

                VBScript example:
Dim adminSession
Dim myDb
Dim mySchema
Dim mySchemaRev

'创建 AdminSession 对象
Set adminSession = CreateObject("ClearQuest.AdminSession")

'登陆模式库
adminSession.Logon "Mike", 1qaz2wsx"", "Schema_Repository_Name"

'获取模式版本信息
Set mySchema = adminSession.Schemas.Item(2)
Set mySchemaRev = mySchema.SchemaRevs.Item(0)

'创建用户数据库
Set myDb = adminSession.CreateDatabase(“UDB")

'配置数据库参数
With myDb
.RWLogin = "db2inst1"
.RWPassword = "db2inst1"
.Description = "creating database using API"
.vendor = 4 '或 AD_DB2
.DatabaseName = "TESTDB"
.SetInitialSchemaRev mySchemaRev
.TimeoutInterval = 120
.CheckTimeoutInterval = 5

'提交数据库参数变更，如果配置参数不正确则返回错误信息
.ApplyPropertyChanges
End With

Perl example:
my $adminSession;
my $myDb;
my $mySchema;
my $mySchemaRev;
my $mySchemaList;
my $mySchemaRevList;

# 创建 AdminSession 对象
$adminSession= CQAdminSession::Build();

# 登陆模式库
$adminSession->Logon( "Mike", 1qaz2wsx"", "Schema_Repository_Name");

# 获取模式版本信息
$mySchemaList = $adminSession->GetSchemas();
$mySchema =$mySchemaList ->Item(2);
$mySchemaRevList = $mySchema->GetSchemaRevs();
$mySchemaRev = $mySchemaRevList->Item(0);

# 创建用户数据库
$myDb = $adminSession->CreateDatabase(“UDB");

# 配置数据库参数
$myDb->SetRWLogin( "db2inst1");
$myDb->SetRWPassword("db2inst1");
$myDb->SetDescription( "creating database using API”);
$myDb->SetVendor(4); # 或 AD_DB2
$myDb->SetDatabaseName("TESTDB");
$myDb->SetInitialSchemaRev($mySchemaRev);
$myDb->SetTimeoutInterval(120);
$myDb->SetCheckTimeoutInterval(5);

# 提交数据库参数变更，如果配置参数不正确则返回错误信息
$myDb->ApplyPropertyChanges(0);
CQAdminSession::Unbuild($adminSession);

本文介绍了 Rational ClearQuest API 中的对象、常量命名规范，并针对比较重要的几个对象及其方法进行了介绍，最后介绍了如何使用 Rational ClearQuest API 访问操作用户数据库和模式库。使用好 Rational ClearQuest API 不仅可以帮助用户和开发人员方便地在外部应用程序中实现 Rational ClearQuest 的相关功能，而且可以帮助用户和开发人员进行模式中 Hook 脚本的开发和定制。

Rational ClearQuest API 参考文档

1. IBM Rational ClearQuest and Rational ClearQuest MultiSite Installation and Upgrade Guide
2. Rational ClearQuestAPI Reference
3. "Learning Perl", Schwartz, Phoenix & foy