< 上一课 | 下一课 >

检索记录

要查看记录的内容,请调用 Session 对象的 GetEntity 方法来检索记录。
GetEntity 方法返回指定的记录。 请求基于状态的记录类型时,display_name 参数必须包含该记录的可视标识(例如,DEF00013323)。 对于无状态记录类型,该参数必须包含此记录的唯一键字段的值。

每条新记录会分配到一个可视标识字符串,该字符串由逻辑数据库名称和唯一序号组成。例如,BUGID 数据库中的第十条记录具有可视标识 BUGID00000010。如果您不知道记录的标识,那么可以使用 Session 对象的 BuildQuery 方法来创建查询,搜索符合一组期望的条件的记录。

要使用数据库标识而非可视标识来请求记录,请使用 GetEntityByDbId 方法。Rational ClearQuest 数据库标识(DBID)是用于唯一标识 Rational ClearQuest 数据库中对象的整数值。 DBID 对于一类记录、有状态记录以及无状态记录都是唯一的。

GetEntity 的语法如下:
$session->GetEntity(entity_def_name, display_name); 
  • session - 一个 Session 对象,表示当前的数据库访问会话。
  • entity_def_name - 一个字符串,用于标识该记录所属记录类型的名称。
  • display_name - 一个字符串,用于标识记录的显示名称。显示名称应当是请求实体的可视标识,或是辅助实体的唯一键字段。返回值返回对应于所请求记录的 Entity 对象。
例如:
# Build Session object...
$sessionObj->UserLogon("admin","","SAMPL","");
#Get record DEF00013323 
$record1 = $sessionObj->GetEntity( "defect", "DEF00013323" ); 
您还应当进行检查,以验证该 Entity 是否存在,或返回是否正确。您可以在调用 GetEntity 之前使用 Session 对象的 EntityExists 或 EntityVisible 方法来验证该 Entity 是否存在以及是否可以查看。您还可以在针对 Entity 对象调用其他方法之前测试 GetEntity 方法的返回值,以验证是否具有该对象。您可以如下所示测试非空条件:
$record1 = $sessionobj->GetEntity("defect", "DEF00013323");
die "Error getting Defect DEF00013323" unless $record1;

要查看记录的内容,请执行以下步骤:

  1. 使用 GetEntity 方法获取记录。 验证是否返回 Entity 对象。
  2. 使用已返回 Entity 对象的方法来访问记录的字段。
    获取 Entity 对象后,您可以调用该对象的各种方法来执行以下任务:
    • 检查字段的值和状态:GetFieldValue 和 GetValue

      GetFieldValue(fieldname) 方法返回表示字段而非字段值的 FieldInfo 对象。FieldInfo 对象包含值及其状态。您可以使用 FieldInfo 对象的以下方法来获取实际值:GetType、GetRequiredness、GetValueStatus 和 GetValue

    • 验证并落实记录:Validate 和 Commit
    • 确定用户必须填充哪些字段:GetFieldRequiredness
    • 确定每个字段的可接受值,以及哪些字段具有不正确的值:GetFieldType 和 GetInvalidFieldValues
    • 确定哪些字段已更新:GetFieldsUpdatedThisAction、GetFieldsUpdatedThisGroup 和 GetFieldsUpdatedThisSetValue
    • 查找被视为与该记录重复的其他数据记录:GetDuplicates
    • 当存在重复记录时,查找原始数据记录:GetFieldOriginalValueEntities
    要按名称获取记录类型的列表,请使用 Session 对象的以下方法:
    • 所有记录类型:GetEntityDefNames
    • 有状态的记录类型:GetReqEntityDefNames
    • 无状态的记录类型:GetAuxEntityDefNames
    • 属于某个记录类型系列的记录类型:GetQueryEntityDefNames 您可以用于创建新记录的记录类型:GetSubmitEntityDefNames
    要获取与特定记录类型关联的 EntityDef 对象,请使用 GetEntityDef 方法。
    您可以使用以下方法来获取记录的详细信息:
    • 获取字段属性:

      Entity->GetFieldNames、Entity->GetFieldChoiceType(fieldname)、Entity->GetFieldMaxLength(fieldname)、Entity->GetFieldChoiceList(fieldname)、Entity->GetFieldType(fieldname) 和 Entity->GetFieldRequiredness(fieldname)

    • 获取特定字段:>GetAttachmentFields 和 Entity->GetHistoryFields
    • 获取附件:

      AttachmentField->GetDisplayNameHeader、AttachmentField->GetAttachments、Attachment->GetDisplayName、Attachment->GetDescription、Attachment->GetFileSize、Attachment->GetFileName 和 Attachment->Load(temp-file-name)

    • 获取历史记录:HistoryField->GetDisplayNameHeader、HistoryField->GetHistories 和 History->GetValue
    • 获取针对记录当前状态的合法操作:Entity->GetLegalActionDefNames

使用以上技术找到的 Entity 对象是只读的。 (要编辑 Entity 对象,您必须调用 Session 对象的 EditEntity 方法,这在本教程的下一课中介绍。)

示例

本部分包含两个示例:
  • 检索有关记录中某个字段的数据
  • 检索有关某个记录类型的数据

最常见的 API 调用之一是 FieldInfo 对象。 例如,FieldInfo 对象具有 GetValue 方法,使您可以获取记录中某个字段的值。以下外部应用程序子例程会打印出存储在 FieldInfo 对象中的信息。

use CQPerlExt; 
$CQsession = CQSession::Build(); 
$CQsession->UserLogon("admin", "", "perl", ""); 
$record = $CQsession->GetEntity("Defect", "perl00000001"); 
$fieldInfo = $record->GetFieldValue("id"); 
$temp = $fieldInfo->GetValueStatus(); 
if ($temp == $CQPerlExt::CQ_VALUE_NOT_AVAILABLE) { 
   $status = "VALUE_NOT_AVAILABLE"; 
} elsif ($temp == $CQPerlExt::CQ_HAS_VALUE) { 
   $status = "HAS_VALUE"; 
   $value = "'" . $fieldinfo->GetValue() . "'"; 
} elsif ($temp == $CQPerlExt::CQ_HAS_NO_VALUE) { 
   $status = "NO_VALUE";
} else { 
   $status = "<invalid value status: "& temp & ">"; 
} 
   $temp = $fieldInfo->GetValidationStatus(); 
if ($temp == $CQPerlExt::CQ_KNOWN_INVALID) { 
   $validity = "INVALID";
 } elsif ($temp == $CQPerlExt::CQ_KNOWN_VALID) { 
   $validity = "VALID"; 
} elsif ($temp == $CQPerlExt::CQ_NEEDS_VALIDATION) { 
   $validity = "NEEDS_VALIDATION"; 
} else { $validity = "<invalid validation status: " & temp & ">"; 
} 
$valuechange = ""; 
if ($fieldInfo->ValueChangedThisSetValue()) { 
   $valuechange = $valuechange . " setval=Y"; 
} else { 
   $valuechange = $valuechange . " setval=N"; 
} 
if ($fieldInfo->ValueChangedThisGroup()) { 
   $valuechange = $valuechange . " group=Y"; 
} else { 
$valuechange = $valuechange . " group=N"; 
} 
if ($fieldInfo->ValueChangedThisAction()) {
 $valuechange = $valuechange . " action=Y"; 
} else { 
   $valuechange = $valuechange . " action=N";
} 
$validchange = ""; 
if ($fieldInfo->ValidityChangedThisSetValue()) { 
   $validchange = $validchange . " setval=Y"; 
} else { 
   $validchange = $validchange . " setval=N"; 
} 
if ($fieldInfo->ValidityChangedThisGroup()) { 
   $validchange = $validchange . " group=Y"; 
} else { 
   $validchange = $validchange . " group=N"; 
} 
if ($fieldInfo->ValidityChangedThisAction()) { 
   $validchange = $validchange . " action=Y"; 
} else { 
   $validchange = $validchange . " action=N"; 
}
print "FieldInfo for field = ", $fieldInfo->GetName(), "\n"; 
print "Field's value = ", $value, "\n";
print "Value status = ", $status, "\n"; 
print "Value change = ", $valuechange, "\n"; 
print "Validity = ", $validity, "\n"; 
print "Validity change = ", $validchange, "\n"; 
print "Error = ", $fieldInfo->GetMessageText(), "'"; 
CQSession::Unbuild($CQsession);
为证明您可以操作元数据,以下示例会打印以下 EntityDef 信息:
  • EntityDef 的名称
  • 所包含的每个字段和操作的名称和类型
  • 所包含的每种状态的名称
use strict; 
use CQPerlExt; 
my $sessionObj = CQSession::Build(); 
$sessionObj->UserLogon("admin", "", "SAMPL", ""); 
my $entityDefNames = $sessionObj->GetEntityDefNames(); 

# Iterate over the record types 
foreach my $edef_name (@$entityDefNames) 
   { 
     my $entityDefObj = $sessionObj->GetEntityDef($edef_name);
     print_edef($entityDefObj); 
   }
 
sub print_edef { 
   my($edef)=@_; 
   # The parameter is an EntityDef object. 
   my($names, $name); 
   print "Dumping EntityDef ", $edef->GetName; print "\nFieldDefs:"; 
   $names = $edef->GetFieldDefNames; 
   foreach $name (@$names) { 
      print " " , $name , " type=" , $edef->GetFieldDefType($name);
      } 
   print "\nActionDefs: "; 
   $names = $edef->GetActionDefNames; 
   foreach $name (@$names) { 
      print " " , $name , " type=" , $edef->GetActionDefType($name);
      } 
   if ($edef->GetType == $CQPerlExt::CQ_REQ_ENTITY) { 
      # stated record type 
      print "\nEntityDef is a REQ entity def"; 
      print "\nStateDefs:"; 
      $names = $edef->GetStateDefNames; 
      foreach $name (@$names) { 
         print " " , $name; 
         } 
      }
else { 
      # stateless record type 
      print "\nEntityDef is an AUX entity def"; 
      } 
   print "\n\n"; 
   } 
CQSession::Unbuild($sessionObj); 
< 上一课 | 下一课 >

反馈