< Précédent | Suivant >

Récupération d'un enregistrement

Pour afficher le contenu d'un enregistrement, récupérez l'enregistrement en appelant la méthode GetEntity de l'objet Session.
La méthode GetEntity renvoie l'enregistrement spécifié. En cas de demande d'un type d'enregistrement basé sur un état, le paramètre nom_affichage doit contenir l'ID visible de l'enregistrement (par exemple, DEF00013323). Pour les types d'enregistrement sans état, ce paramètre doit contenir la valeur de la zone de clé unique de l'enregistrement.

Chaque nouvel enregistrement dispose d'une chaîne d'ID visible, composée du nom de base de données logique et d'un nombre de séquence unique. Par exemple, le dixième enregistrement de la base de données BUGID peut comporter l'ID visible BUGID00000010. Si vous ignorez l'ID de l'enregistrement, vous pouvez utiliser la méthode BuildQuery de l'objet Session afin de créer une requête et rechercher des enregistrements correspondant à un ensemble de critères donné.

Pour effectuer une requête sur un enregistrement à l'aide de son ID base de données au lieu de son ID visible, utilisez la méthode GetEntityByDbId. Un identificateur de base de données Rational ClearQuest (ID base de données) est un entier utilisé pour identifier de façon unique un objet au sein d'une base de données Rational ClearQuest. Les IDBD sont propres à chaque classe d'enregistrements, uniques au sein des enregistrements avec état et uniques au sein des enregistrements sans état.

La syntaxe pour GetEntity est :
$session->GetEntity(nom_déf_entité, nom_affichage); 
  • session - Objet Session qui représente la session d'accès à la base de données en cours.
  • nom_déf_entité - Chaîne qui identifie le nom du type d'enregistrement auquel appartient l'enregistrement.
  • nom_affichage - Chaîne qui identifie le nom d'affichage de l'enregistrement. Le nom d'affichage doit être l'ID visible pour les entités des demandes ou les zones de clés uniques pour les entités auxiliaires. La valeur de retour renvoie un objet Entity correspondant à l'enregistrement demandé.
For example:
# Build Session object...
$sessionObj->UserLogon("admin","","SAMPL","");
#Get record DEF00013323 
$record1 = $sessionObj->GetEntity( "defect", "DEF00013323" ); 
Vous devez également vérifier que l'objet Entity existe ou qu'il a été correctement renvoyé. Vous pouvez utiliser les méthodes EntityExists ou EntityVisible de l'objet Session avant d'appeler GetEntity afin de vérifier que l'objet Entity existe et qu'il peut être affiché. Vous pouvez également tester la valeur de retour de la méthode GetEntity pour vérifier que vous possédez l'objet Entity avant d'appeler des méthodes supplémentaires pour ce dernier. Vous pouvez tester les valeurs non nulles, par exemple :
$record1 = $sessionobj->GetEntity("defect", "DEF00013323");
die "Error getting Defect DEF00013323" unless $record1;

Pour afficher le contenu d'un enregistrement, procédez comme suit :

  1. Utilisez la méthode GetEntity pour acquérir l'enregistrement. Vérifiez que l'objet Entity est renvoyé.
  2. Utilisez les méthodes de l'objet Entity renvoyé pour accéder aux zones de l'enregistrement.
    Lorsque vous avez acquis un objet Entity, vous pouvez appeler ses méthodes pour effectuer les tâches suivantes :
    • Examiner les valeurs et l'état d'une zone : GetFieldValue, GetValue

      La méthode GetFieldValue(nomzone) renvoie un objet FieldInfo, représentant une zone mais pas une valeur de zone. L'objet FieldInfo contient la valeur et l'état de la valeur. Vous pouvez utiliser les méthodes de l'objet FieldInfo pour obtenir les valeurs réelles : GetType, GetRequiredness, GetValueStatus, GetValue

    • Valider l'enregistrement : Validate, Commit
    • Déterminer les zones que l'utilisateur doit remplir : GetFieldRequiredness
    • Déterminer les valeurs acceptables pour chaque zone, ainsi que les zones ayant des valeurs incorrectes : GetFieldType, GetInvalidFieldValues
    • Déterminer les zones qui ont été mises à jour : GetFieldsUpdatedThisAction, GetFieldsUpdatedThisGroup, GetFieldsUpdatedThisSetValue
    • Rechercher d'autres enregistrements de données considérés comme doublons d'un enregistrement spécifié : GetDuplicates
    • Rechercher l'enregistrement de données original, si un enregistrement spécifique est un doublon : GetFieldOriginalValueEntities
    Pour obtenir la liste des types d'enregistrement par nom, utilisez les méthodes suivantes de l'objet Session :
    • Tous les types d'enregistrement : GetEntityDefNames
    • Les types d'enregistrement avec état : GetReqEntityDefNames
    • Les types d'enregistrement sans état : GetAuxEntityDefNames
    • Les types d'enregistrement appartenant à une famille de type d'enregistrement : GetQueryEntityDefNames Les types d'enregistrement que vous pouvez utiliser pour créer un enregistrement : GetSubmitEntityDefNames
    Pour obtenir l'objet EntityDef associé à un type d'enregistrement particulier, utilisez la méthode GetEntityDef.
    Vous pouvez utiliser les méthodes suivantes pour obtenir des détails sur un enregistrement :
    • Obtenir les propriétés d'une zone :

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

    • Obtenir des zones spécifiques : Entity->GetAttachmentFields, Entity->GetHistoryFields
    • Obtenir des pièces jointes :

      AttachmentField->GetDisplayNameHeader, AttachmentField->GetAttachments, Attachment->GetDisplayName, Attachment->GetDescription, Attachment->GetFileSize Attachment->GetFileName, Attachment->Load(nom-fichier-temp)

    • Obtenir un historique : HistoryField->GetDisplayNameHeader, HistoryField->GetHistories, History->GetValue
    • Obtenir les actions admises pour l'état actuel de l'enregistrement : Entity->GetLegalActionDefNames

Les objets Entity trouvés à l'aide de ces techniques sont en lecture seule. (Pour modifier un objet Entity, vous devez appeler la méthode EditEntity de l'objet Session, décrite dans la leçon suivante de ce tutoriel.)

Exemples

Ces sections incluent deux exemples :
  • Récupération des données sur la zone d'un enregistrement
  • Récupération des données sur le type d'un enregistrement

Les appels de l'API les plus courants correspondent à l'objet FieldInfo. Par exemple, l'objet FieldInfo contient la méthode GetValue, qui vous permet d'obtenir la valeur d'une zone dans un enregistrement. La sous-routine de l'application externe suivante fournit les informations stockées dans un objet 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);
Pour illustrer la manipulation des métadonnées, l'exemple suivant fournit les informations EntityDef suivantes :
  • Le nom de l'objet EntityDef
  • Le nom et le type de chaque zone et action qu'il contient
  • Le nom de chaque état qu'il contient
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); 
< Précédent | Suivant >

Commentaire