< Vorherige Lektion | Nächste Lektion >

Datensatz abrufen

Wenn Sie den Inhalt eines Datensatzes anzeigen möchten, rufen Sie den Datensatz ab, indem Sie die Methode GetEntity des Sitzungsobjekts aufrufen.
Die Methode GetEntity gibt den angegebenen Datensatz zurück. Wenn Sie einen statusabhängigen Satztyp anfordern, muss der Parameter Anzeigename die sichtbare ID des Datensatzes enthalten (z. B. DEF00013323). Für statusunabhängige Satztypen muss dieser Parameter den Wert des Felds für den eindeutigen Schlüssel des Datensatzes enthalten.

Jedem neuen Datensatz wird eine sichtbare ID-Zeichenfolge zugeordnet, die sich zusammensetzt aus dem Namen der logischen Datenbank und einer eindeutigen fortlaufenden Zahl. Der zehnte Datensatz in der Datenbank BUGID könnte beispielsweise die sichtbare ID "BUGID00000010" haben. Wenn Sie die ID des Datensatzes nicht kennen, können Sie mit der Methode BuildQuery des Sitzungsobjekts eine Abfrage erstellen und nach Datensätzen suchen, die mit den gewünschten Kriterien übereinstimmen.

Verwenden Sie die Methode GetEntityByDbId, um einen Datensatz über seine Datenbank-ID und nicht seine sichtbare ID anzufordern. Eine Rational-ClearQuest-Datenbankkennung (DBID) ist ein ganzzahliger Wert, mit dem ein Objekt in einer Rational-ClearQuest-Datenbank eindeutig identifiziert wird. DBIDs sind im Kontext einer Datensatzklasse, im Kontext der statusabhängigen Datensätze und im Kontext der statusunabhängigen Datensätze eindeutig.

Die Syntax für GetEntity lautet wie folgt:
$session->GetEntity(Name_der_Entitätsdefinition, Anzeigename); 
  • session - Das Sitzungsobjekt, das die aktuelle Sitzung für den Datenbankzugriff repräsentiert.
  • Name_der_Entitätsdefinition - Eine Zeichenfolge, die den Namen des Satztyp angibt, zu dem der Datensatz gehört.
  • Anzeigename - Eine Zeichenfolge, die den Anzeigenamen des Datensatzes angibt. Der Anzeigename sollte bei Anforderungsentitäten der sichtbaren ID oder bei Hilfsentitäten dem Feld für den eindeutigen Schlüssel entsprechen. Der Rückgabewert gibt ein Entitätsobjekt zurück, das dem angeforderten Datensatz entspricht.
Beispiel:
# Sitzungsobjekt erstellen...
$sessionObj->UserLogon("admin","","SAMPL","");
#Datensatz DEF00013323 abrufen
$record1 = $sessionObj->GetEntity( "defect", "DEF00013323" ); 
Sie müssen auch prüfen, ob die Entität vorhanden ist bzw. richtig zürückgegeben wurde. Sie können die Methode "EntityExists" oder "EntityVisible" des Sitzungsobjekts verwenden, bevor Sie "GetEntity" aufrufen, um zu prüfen, ob die Entität vorhanden ist und angezeigt werden kann. Sie können auch den Rückgabewert der Methode "GetEntity" testen, um sicherzustellen, dass Sie das Entitätsobjekt haben, bevor Sie weitere Methoden für das Objekt aufrufen. Sie können wie folgt testen, ob die Bedingung "Is not null" vorliegt:
$record1 = $sessionobj->GetEntity("defect", "DEF00013323");
die "Error getting Defect DEF00013323" unless $record1;

Führen Sie die folgenden Schritte aus, um den Inhalt eines Datensatzes anzuzeigen:

  1. Verwenden Sie die Methode GetEntity, um den Datensatz abzurufen. Vergewissern Sie sich, dass das Entitätsobjekt zurückgegeben wird.
  2. Verwenden Sie die Methoden des zurückgegebenen Entitätsobjekts, um auf die Felder des Datensatzes zuzugreifen.
    Nach Abruf eines Entitätsobjekts können Sie die zugehörigen Methoden aufrufen, um beispielsweise die folgenden Tasks auszuführen:
    • Prüfen Sie die Werte und den Status eines Felds: GetFieldValue, GetValue

      Die Methode GetFieldValue(Feldname) gibt ein FieldInfo-Objekt zurück, das ein Feld darstellt und kein definierter Feldwert ist. Das FieldInfo-Objekt enthält den Wert und den Status des Werts. Sie können die folgenden Methoden des FieldInfo-Objekts verwenden, um die tatsächlichen Werte abzurufen: GetType, GetRequiredness, GetValueStatus, GetValue.

    • Den Datensatz validieren und festschreiben: Validate, Commit
    • Feststellen, welche Felder vom Benutzer ausgefüllt werden müssen: GetFieldRequiredness
    • Feststellen, welche Werte für die einzelnen Felder akzeptabel sind und welche Felder falsche Werte haben: GetFieldType, GetInvalidFieldValues
    • Feststellen, welche Felder aktualisiert wurden: GetFieldsUpdatedThisAction, GetFieldsUpdatedThisGroup, GetFieldsUpdatedThisSetValue
    • Datensätze suchen, die als Duplikate des aktuellen Datensatzes gelten: GetDuplicates
    • Den ursprünglichen Datensatz suchen, wenn der aktuelle Datensatz ein Duplikat ist: GetFieldOriginalValueEntities
    Verwenden Sie zum Abrufen einer Liste der Satztypen nach Namen die folgenden Methoden des Sitzungsobjekts:
    • Alle Satztypen: GetEntityDefNames
    • Statusabhängige Satztypen: GetReqEntityDefNames
    • Statusunabhängige Satztypen: GetAuxEntityDefNames
    • Satztypen, die zu einer Satztypfamilie gehören: GetQueryEntityDefNames Satztypen, mit denen Sie einen neuen Datensatz erstellen können: GetSubmitEntityDefNames
    Verwenden Sie die Methode "GetEntityDef", um das einem bestimmten Satztyp zugeordnete EntityDef-Objekt abzurufen.
    Sie können die folgenden Methoden verwenden, um Details eines Datensatzes abzurufen:
    • Feldeigenschaften:

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

    • Sonderfelder abrufen: Entity->GetAttachmentFields, Entity->GetHistoryFields
    • Anhänge abrufen:

      AttachmentField->GetDisplayNameHeader, AttachmentField->GetAttachments, Attachment->GetDisplayName, Attachment->GetDescription, Attachment->GetFileSize Attachment->GetFileName, Attachment->Load(Name_der_temporären_Datei)

    • Historie abrufen: HistoryField->GetDisplayNameHeader, HistoryField->GetHistories, History->GetValue
    • Gültige Aktionen für den aktuellen Status des Datensatzes abrufen: Entity->GetLegalActionDefNames

Entitätsobjekte, die mit diesen Verfahren ermittelt werden, sind schreibgeschützt. (Zum Bearbeiten eines Entitätsobjekts müssen Sie die Methode EditEntity des Sitzungsobjekts aufrufen, die in der nächsten Lektion dieses Lernprogramms beschrieben wird.)

Beispiele

Dieser Abschnitt enthält zwei Beispiele:
  • Daten zu einem Feld in einem Datensatz abrufen
  • Daten zu einem Satztyp abrufen

Das FieldInfo-Objekt wird von der API am häufigsten aufgerufen. Beispielsweise hat das FieldInfo-Objekt die Methode GetValue, mit der Sie den Wert eines Felds in einem Datensatz abrufen können. Die folgende externe Anwendungssubroutine gibt die Informationen, die in einem FieldInfo-Objekt gespeichert sind, aus.

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);
Um zu veranschaulichen, dass Sie Metadaten bearbeiten können, gibt das folgende Beispiel diese EntityDef-Informationen aus:
  • den Namen der EntityDef-Objekts
  • die Namen und Typen aller Felder und darin enthaltenen Aktionen
  • die Namen aller enthaltenen Status
use strict; 
use CQPerlExt; 
my $sessionObj = CQSession::Build(); 
$sessionObj->UserLogon("admin", "", "SAMPL", ""); 
my $entityDefNames = $sessionObj->GetEntityDefNames(); 

# Durch Satztypen navigieren
foreach my $edef_name (@$entityDefNames) 
   { 
     my $entityDefObj = $sessionObj->GetEntityDef($edef_name);
     print_edef($entityDefObj); 
   }
 
sub print_edef { 
   my($edef)=@_; 
   # Der Parameter ist ein EntityDef-Objekt.
   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) { 
      # festgestellter Satztyp
      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); 
< Vorherige Lektion | Nächste Lektion >

Feedback