< Previous | Next >

Retrieving a record

To view the contents of a record, you retrieve the record by calling the GetEntity method of the Session object.

About this task

The GetEntity method returns the specified record. When requesting a state-based record type, the display_name parameter must contain the visible ID of the record (for example, DEF00013323). For stateless record types, this parameter must contain the value of the record's unique key field.

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.

The syntax for GetEntity: 
$session->GetEntity(entity_def_name, display_name);
  • session - The Session object that represents the current database-access session.
  • entity_def_name - A String that identifies the name of the record type to which the record belongs.
  • display_name - A String that identifies the display name of the record. The display name should be either the visible ID for request entities or the unique key fields for aux entities. Return value Returns an Entity Object corresponding to the requested record.
For example: 
# Build Session object...
$sessionObj->UserLogon("admin","","SAMPL","");
#Get record DEF00013323 
$record1 = $sessionObj->GetEntity( "defect", "DEF00013323" );
You should also check to validate that the Entity exists or that it is returned correctly. You can use the EntityExists or EntityVisible methods of the Session object before calling GetEntity to validate that the Entity exists and can be viewed. You can also test the return value of the GetEntity method to validate that you have the Entity object before calling additional methods on it. You can test for not null like this:
$record1 = $sessionobj->GetEntity("defect", "DEF00013323");
die "Error getting Defect DEF00013323" unless $record1;

To view the contents of a record, follow these steps:

Procedure

  1. Use the GetEntity method to acquire the record. Validate that the Entity object is returned.
  2. Use methods of the returned Entity object to access the record's fields.
    After you acquire an Entity object, you can call its methods to perform the following tasks:
    • Examine the values and status of a field: GetFieldValue, GetValue

      The GetFieldValue(fieldname) method returns a FieldInfo object, which represents a field and is not a field value. The FieldInfo object contains the value and status of the value. You can use these methods of the FieldInfo object to get the actual values: GetType, GetRequiredness, GetValueStatus, GetValue

    • Validate and commit the record: Validate, Commit
    • Determine which fields must be filled in by the user: GetFieldRequiredness
    • Determine the acceptable values for each field, and which fields have incorrect values: GetFieldType, GetInvalidFieldValues
    • Determine which fields have been updated: GetFieldsUpdatedThisAction, GetFieldsUpdatedThisGroup, GetFieldsUpdatedThisSetValue
    • Find other data records that are considered duplicates of this one: GetDuplicates
    • Find the original data record, if this one is a duplicate: GetFieldOriginalValueEntities
    To get a list of record types by name, use the following methods of the Session object:
    • All record types: GetEntityDefNames
    • Record types that have states: GetReqEntityDefNames
    • Record types that are stateless: GetAuxEntityDefNames
    • Record types that belong to a record type family: GetQueryEntityDefNames Record types you can use to create a new record: GetSubmitEntityDefNames
    To get the EntityDef object associated with a particular record type, use the GetEntityDef method.
    You can use the following methods to get details of a record:
    • Get Field Properties:

      Entity->GetFieldNames, Entity->GetFieldChoiceType(fieldName), Entity->GetFieldMaxLength(fieldName), Entity->GetFieldChoiceList(fieldName), Entity->GetFieldType(fieldName), Entity->GetFieldRequiredness(fieldName)

    • Get special fields: Entity->GetAttachmentFields, Entity->GetHistoryFields
    • Get Attachments:

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

    • Get History: HistoryField->GetDisplayNameHeader, HistoryField->GetHistories, History->GetValue
    • Get Legal Actions for current State of the Record: Entity->GetLegalActionDefNames

Results

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.)

Examples

This sections includes two examples:
  • Retrieving data about a field in a record
  • Retrieving data about a record type

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);
To illustrate that you can manipulate metadata, the following example prints the following EntityDef information:
  • The name of the EntityDef
  • The names and types of each field and action it contains
  • The names of each state it contains
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);
< Previous | Next >