Each new record is assigned a visible ID string composed of the logical database name and a unique, sequential number. For example, the tenth record in the BUGID database can have the visible ID BUGID00000010. If you do not know the ID of the record, you can use the Session object's BuildQuery method to create a query and search for records that match a desired set of criteria.
To request a record using its database ID instead of its visible ID, use the GetEntityByDbId method. A Rational ClearQuest database identifier (DBID) is an integer value used to uniquely identify an object within a Rational ClearQuest database. DBIDs are unique to a class of records, and unique within the stateful records, and unique within the stateless records.
$session->GetEntity(entity_def_name, display_name);
# Build Session object...
$sessionObj->UserLogon("admin","","SAMPL","");
#Get record DEF00013323
$record1 = $sessionObj->GetEntity( "defect", "DEF00013323" );
$record1 = $sessionobj->GetEntity("defect", "DEF00013323");
die "Error getting Defect DEF00013323" unless $record1;
To view the contents of a record, follow these steps:
Entity objects found using these techniques are read-only. (To edit an Entity object, you must call the Session object's EditEntity method, which is described in the next lesson of this tutorial.)
One of the most common API calls is to the FieldInfo object. For example, the FieldInfo object has the GetValue method that enables you to get the value of a field in a record. The following external application subroutine prints out the information stored in a FieldInfo object.
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);
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);