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

基于 Rational ClearQuest API 的脚本开发技巧本文主要介绍如何利用 Rational ClearQuest API 从代码层次上实现 Rational ClearQuest 的相关功能，并通过相关的例子帮助读者掌握基于 Rational ClearQuest API 的脚本开发方式和技巧。Rational ClearQuest 简介Rational ClearQuest 是重要的变更管理工具，Rational ClearQuest 更能让客户根据自己的具体需求，灵活的设计变更管理流程。除此之外，Rational ClearQuest 还提供了一套编程接口，即 Rational ClearQuest API，让用户和开发人员可以根据需要通过编程来实现 Rational ClearQuest 的相关功能，同时还可以通过编程来实现模式中 Hook 脚本的开发和定制，从而使整个 Rational ClearQuest 产品的功能更加灵活和强大。本文就全面介绍了基于 Rational ClearQuest API 的脚本开发技巧，以便读者了解如何通过编程来实现 Rational ClearQuest 相关功能，以及如何实现模式中 Hook 脚本的开发和定制的过程和注意事项。Rational ClearQuest API 简介在 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 访问数据库。图 用 ClearQuest 访问数据库示意图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 中对象及常量的命名规范在 Rational ClearQuest API 中定义了很多对象和常量，为了便于区分，针对不同的编程语言，它们的定义遵循一定的命名规范。 基于 VBScript 的 Rational ClearQuest API 中对象及常量的命名规范如表 1 所示：表 1 基于 VBScript 的 Rational ClearQuest API 中对象及常量的命名规范前缀 描述 举例 OAd 对象的前缀 OAdEntityOAdSession AD常量的前缀 AD_BUTTON_CLICKAD_ORACLE 基于 Perl 的 Rational ClearQuest API 中对象及常量的命名规范如表 2 所示：表 2 基于 Perl 的 Rational ClearQuest API 中对象及常量的命名规范前缀 描述 举例 CQ 对象的前缀 CQEntityCQSession $CQPerlExt:CQ 常量的前缀 $CQPerlExt:CQ_BUTTON_CLICK$CQPerlExt:CQ_ORACLE 另外，在 Rational ClearQuest API 的命名规范中，英文复数的对象名通常指一组以单数对象名命名的对象，比如 Schemas 就是一个包含多个 Schema 对象的集合。还有，名称后包含 Def 三个字母的对象一般用于定义以其前缀命名的对象，比如 EntityDef 就定义和描述了 Entity 对象的结构。了解了这些，会帮助我们更好地阅读，理解和使用 Rational ClearQuest API。Rational ClearQuest API 中的对象，方法及其调用方式Entity 对象和 EntityDef 对象在 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 对象中包含的这些信息是只读的。Session 对象及 Session 变量在 Rational ClearQuest API 中，定义了 Session 对象，用户可以通过 Session 对象访问 ClearQuest 用户数据库、创建查询、对数据记录进行操作。图 3 显示出了 Session 对象与 Entity 对象的关系，通过 Session 对象，用户可以登陆用户数据库，每一个 Entity 对象对应了某种数据类型在用户数据库中的一条数据记录。图 3 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 myValuemyValue = Hello WorldcuSession 为 Session 对象if(curSession.HasValue(“Hello”)获得 Session 变量 Hello 的值Dim newValuenewValue = curSession.NameValue(Hello)else创建变量 Hello, 并将 myValue 的值赋给 Session 变量curSession.NameValue Hello, myValuePerl 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 访问用户数据库使用 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 = GetSessionPerl 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, )NextPerl example:my $Databases;$Databases = $curSession-GetAccessibleDatabases(MASTR, admin, ); my $count = $Databases-Count();for(my $i=0;$iItem($i); my $dbName = $db-GetDatabaseName();my $curSession-UserLogon( Mike, 1qaz2wsx, $dbName, ); 在 ClearQuest 的 Hook 中，则无需进行上述这些数据库登入操作，因为用户数据库的授权登入是由 ClearQuest 客户端来控制的。了解了使用 Rational ClearQuest API 访问用户数据库的步骤后，我们有必要对如何使用 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).GetValuePerl 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 生成图在介绍调用 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.GetWorkSpaceSet ChartDef = WorkSpace.GetChartDef Personal Queries/Sample_Chart创建结果集Set Result = curSession.BuildResultSet(ChartDef)Result.SetMaxRowsInMemory(1000)Result.Execute创建 ChartMgr 对象Set chartMgr = WorkSpace.GetChartMgrchartMgr.SetResultSet Result生成图chartMgr.MakeJPEG C: Chart.jpgPerl 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 生成报表在 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_reportreportMgr.SetHTMLFileName C:Report.html生成报表reportMgr.ExecuteReportPerl example:# 创建 WorkSpace 对象my $WorkSpace = $curSession-GetWorkSpace();# 创建 ReportMgr 对象my $reportMgr = $WorkSpace-GetReportMgr (Personal Queries/Sample_report );$reportMgr-SetHTMLFileName(C:Report.html);# 生成报表$reportMgr-ExecuteReport();调用 Rational ClearQuest API 创建，修改和删除数据记录在用户数据库中创建，修改和删除数据记录主要通过调用 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.Validateif Status = “” then 提交数据记录 DefectEntity.Commitelse DefectEntiry.RevertEnd ifPerl 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.Validateif Status = “” then 提交数据记录 DefectEntity.Commitelse DefectEntiry.RevertEnd ifPerl 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”);调用 Rational ClearQuest API 访问模式库和访问用户数据库类似，访问模式库，首先需要建立 AdminSession 对象，再调用该对象的 Logon 方法访问模式库，其中，AdminSession 对象允许用户创建和模式库相关的 Session 对象。调用 Logon 成功后，可以使用 AdminSession 对象的其他方法进行下列的操作：1. 创建数据库 2. 删除数据库 3. 创建用户 4. 创建组 5. 5查询模式、用户数据库、用户和组信息 AdminSession 对象的层级结构如图 4 所示。AdminSession 对象的属性中包含四个对象，分别是 Schemas 对象，Databases 对象，Groups 对象和 Users 对象。根据前面讲的命名规范，我们会比较容易理解下面的层级结构图。其中，SchemaRevs 对象包含某一个 Schema 对象所对应模式 ( 即 Schema) 的所有版本，SchemaRev 对象包含其中某一版本的相关信息。图 4 AdminSession 对象的层级结构图表 5 列出了上述几个比较重要的对象及其描述表 5 AdminSession 相关对象及描述对象 描述 Database 可以存储用户数据库的信息，包括数据库名称、登陆用户名、密码、数据库的类型等 User 可以存储模式库的用户信息，包括用户名、密码、对不同数据库的权限等 Group 可以存储组信息，包括组名、组所包含的用户名、组权限所应用的数据库等 Schema 可以存储模式信息，包括模式名称及该模式相应的各个版本信息 SchemaRev 可以存储某一模式的特定版本信息及该版本的描述 用 Rational ClearQuest API 创建用户数据库，分以下几步完成：1. 创建 AdminSession 对象 2. 登陆模式库 3. 创建用户数据库 4. 配置用户数据库参数 下面的例子就是通过代码实现了这一过程： VBScript example:Dim adminSessionDim myDbDim mySchemaDim mySchemaRev创建 AdminSession 对象Set adminSession = CreateObject(ClearQuest.AdminSession)登陆模式库adminSession.Logon Mike, 1qaz2wsx, Schema_Repository_Name获取模式版本信息Set mySchema = adminSession.Schemas.Item(2)Set