< Indietro | Avanti >

Richiamo di un record

Per visualizzare il contenuto di un record, richiamare il record utilizzando il metodo GetEntity dell'oggetto Session.
Il metodo GetEntity restituisce il record specificato. Quando viene richiesto un tipo di record basato sullo stato, il parametro display_name deve contenere l'ID visibile del record (ad esempio, DEF00013323). Per i tipi di record stateless, questo parametro deve contenere il valore del campo della chiave univoca del record.

A ciascun nuovo record viene assegnata una stringa ID visibile composta dal nome del database logico e un numero sequenziale univoco. Ad esempio, il decimo record nel database BUGID può disporre dell'ID visibile BUGID00000010. Se non si conosce l'ID del record, è possibile utilizzare il metodo BuildQuery dell'oggetto Session per creare una query e ricercare i record che corrispondono a una serie di criteri desiderati.

Per richiedere un record utilizzando il relativo ID database invece del relativo ID visibile, utilizzare il metodo GetEntityByDbId. Un DBID (Database Identifier/identificativo database) Rational ClearQuest è un numero intero utilizzato per identificare in modo univoco un oggetto in un database Rational ClearQuest. I DBID sono univoci per una classe di record, univoci all'interno dei record stateful ed univoci all'interno dei record stateless.

La sintassi per GetEntity è la seguente:
$session->GetEntity(entity_def_name, display_name); 
  • session - L'oggetto Session che rappresenta la sessione di accesso al database corrente.
  • entity_def_name - Una stringa che identifica il nome del tipo di record al quale il record appartiene.
  • display_name - Una stringa che identifica il nome di visualizzazione del record. Il nome di visualizzazione deve essere l'ID visibile per le entità di richiesta oppure i campi della chiave univoca per le entità ausiliarie. Il valore restituito è un oggetto Entity corrispondente al record richiesto.
Ad esempio:
# Creare l'oggetto Session...
$sessionObj->UserLogon("admin","","SAMPL","");
#Chiamare il record DEF00013323 
$record1 = $sessionObj->GetEntity( "defect", "DEF00013323" ); 
È anche necessario verificare per confermare che l'oggetto Entity esista o che sia stato restituito correttamente. Utilizzare i metodi EntityExists o EntityVisible dell'oggetto Session prima di chiamare GetEntity, per confermare che l'oggetto Entity esista e possa essere visualizzato. È anche possibile verificare il valore di restituzione del metodo GetEntity per confermare di avere l'oggetto Entity prima di chiamare altri metodi su esso. È possibile verificare che l'oggetto non sia null nel seguente modo:
$record1 = $sessionobj->GetEntity("defect", "DEF00013323");
die "Error getting Defect DEF00013323" unless $record1;

Per visualizzare il contenuto di un record, effettuare quanto segue:

  1. Utilizzare il metodo GetEntity per acquisire il record. Confermare che l'oggetto Entity sia stato restituito.
  2. Utilizzare i metodi dell'oggetto Entity restituito per accedere ai campi del record.
    Dopo aver acquisito un oggetto Entity, è possibile richiamare i relativi metodi per eseguire attività come quelle che seguono:
    • Esaminare i valori e lo stato di un campo: GetFieldValue, GetValue

      Il metodo GetFieldValue(nomecampo) restituisce un oggetto FieldInfo, che rappresenta un campo e non è un valore campo. L'oggetto FieldInfo contiene il valore e lo stato del valore. È possibile utilizzare questo metodo dell'oggetto FieldInfo per richiamare i valori reali: GetType, GetRequiredness, GetValueStatus, GetValue

    • Convalidare e eseguire il commit del record: Validate, Commit
    • Determinare quali campi devono essere compilati dall'utente: GetFieldRequiredness
    • Determinare i valori accettabili per ogni campo e quali campi hanno valori non corretti: GetFieldType, GetInvalidFieldValues
    • Determinare quali campi sono stati aggiornati: GetFieldsUpdatedThisAction, GetFieldsUpdatedThisGroup, GetFieldsUpdatedThisSetValue
    • Trovare altri record di dati considerati duplicati di questo: GetDuplicates
    • Trovare il record di dati originale, se questo è un duplicato: GetFieldOriginalValueEntities
    Per ottenere un elenco di tipi di record per nome, utilizzare i seguenti metodi dell'oggetto Session:
    • Tutti i tipi di record: GetEntityDefNames
    • Tipi di record che dispongono degli stati: GetReqEntityDefNames
    • Tipi di record che non dispongono degli stati: GetAuxEntityDefNames
    • Tipi di record che appartengono ad una famiglia di tipi di record: GetQueryEntityDefNames Tipi di record che è possibile utilizzare per creare un nuovo record: GetSubmitEntityDefNames
    Per ottenere l'oggetto EntityDef associato ad un particolare tipo di record, utilizzare il metodo GetEntityDef.
    È possibile utilizzare i seguenti metodi per ottenere i dettagli di un record:
    • Ottenere le proprietà di un campo:

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

    • Ottenere campi speciali: Entity->GetAttachmentFields, Entity->GetHistoryFields
    • Ottenere allegati:

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

    • Ottenere la cronologia: HistoryField->GetDisplayNameHeader, HistoryField->GetHistories, History->GetValue
    • Ottenere azioni valide per lo stato corrente del record: Entity->GetLegalActionDefNames

Gli oggetti entità trovati utilizzando queste tecniche sono di sola lettura. (Per modificare un oggetto Entity, è necessario richiamare il metodo EditEntity dell'oggetto Session, come descritto nella successiva lezione di questa esercitazione.)

Esempi

Questa sezione include due esempi:
  • Come richiamare i dati su un campo in un record
  • Come richiamare i dati su un tipo di record

Una delle più comuni chiamate API viene effettuata verso l'oggetto FieldInfo. Ad esempio, l'oggetto FieldInfo dispone del metodo GetValue che consente di acquisire il valore di un campo in un record. La seguente routine secondaria dell'applicazione esterna stampa le informazioni memorizzate in un oggetto 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);
Per mostrare come sia possibile manipolare metadati, questo esempio stampa le seguenti informazioni su EntityDef:
  • Il nome di EntityDef
  • Per ogni campo, nome, tipo e azione contenuta
  • Nomi degli stati contenuti
use strict; 
use CQPerlExt; 
my $sessionObj = CQSession::Build(); 
$sessionObj->UserLogon("admin","","SAMPL",""); 
my $entityDefNames = $sessionObj->GetEntityDefNames(); 

# Spostarsi sui tipi di record 
foreach my $edef_name (@$entityDefNames) 
   { 
     my $entityDefObj = $sessionObj->GetEntityDef($edef_name);
     print_edef($entityDefObj); 
   }
 
sub print_edef { 
   my($edef)=@_; 
   # Il parametro è un oggetto EntityDef. 
   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) { 
      # tipo record con stato 
      print "\nEntityDef is a REQ entity def"; 
      print "\nStateDefs:"; 
      $names = $edef->GetStateDefNames; 
      foreach $name (@$names) { 
         print " " , $name; 
         } 
      }
else { 
      # tipo record stateless 
      print "\nEntityDef is an AUX entity def"; 
      } 
   print "\n\n"; 
   } 
CQSession::Unbuild($sessionObj); 
< Indietro | Avanti >

Feedback