< Anterior | Próximo >

Recuperando um registro

Para visualizar os conteúdos de um registro, você recupera o registro chamando o método GetEntity do objeto Session.
O método GetEntity retorna o registro especificado. Ao solicitar um tipo de registro baseado em estado, o parâmetro display_name deve conter o ID visível do registro (por exemplo, DEF00013323). Para tipos de registro stateless, esse parâmetro deve conter o valor do campo da chave exclusiva do registro.

A cada novo registro é designado uma cadeia de ID visível composta do nome do banco de dados lógico e um número sequencial exclusivo. Por exemplo, o décimo registro no banco de dados BUGID pode ter o ID visível ID BUGID00000010. Se você não sabe o ID do registro, você pode usar o método BuildQuery do objeto Session para criar uma consulta e procurar registros que correspondam a um conjunto desejado de critérios.

Para solicitar um registro usando o ID do banco de dados em vez do ID visível, use o método GetEntityByDbId. Um identificador de banco de dados do Rational ClearQuest (DBID) é um valor inteiro usado para identificar exclusivamente um objeto dentro do banco de dados do Rational ClearQuest. Os DBIDs são exclusivos para uma classe de registro e exclusivos dentre os registros stateful e exclusivo dentre os registros stateless.

Sintaxe para o GetEntity:
$session->GetEntity(entity_def_name, display_name); 
  • session - O objeto Session que representa a sessão atual de acesso ao banco de dados.
  • entity_def_name - Uma Cadeia que identifica o nome do tipo de registro ao qual o registro pertence.
  • display_name - Uma Cadeia que identifica o nome de exibição do registro. O nome de exibição deve ser o ID visível para entidades de pedido ou campos de chave exclusiva para entidades aux. O valor Return Retorna um Objeto Entity que corresponde ao registro solicitado.
Exemplo:
# Build Session
object...
$sessionObj->UserLogon("admin","","SAMPL","");
#Get record DEF00013323
$record1 = $sessionObj->GetEntity( "defect", "DEF00013323" ); 
Você deve também verificar de forma a validar se aquele Entity existe ou se foi retornado corretamente. Você pode usar os métodos EntityExists ou EntityVisible do objeto Session antes de chamar o GetEntity para validar se aquele Entity existe e pode ser visualizado. Você pode também testar o valor de retorno do método GetEntity para validar se possui o objeto Entity antes de chamar métodos adicionais nele. Você pode testar para não nulo da seguinte maneira:
$record1 =
$sessionobj->GetEntity("defect", "DEF00013323");
die "Error getting Defect DEF00013323" unless $record1;

Para visualizar o conteúdo de um registro, siga estas etapas:

  1. Use o método GetEntity para adquirir o registro. Valide se o objeto Entity foi retornado.
  2. Use os métodos do objeto Entity retornado para acessar os campos do registro.
    Depois de adquirir um objeto Entity, você pode chamar seu método para executar as tarefas a seguir:
    • Examinar os valores e o status de um campo: GetFieldValue, GetValue

      O método GetFieldValue(fieldname) retorna um objeto FieldInfo, que representa um campo e não um valor de campo. O objeto FieldInfo contém o valor e status do valor. Você pode usar esses métodos do objeto FieldInfo para obter os valores reais: GetType, GetRequiredness, GetValueStatus, GetValue

    • Validar e confirmar o registro: Validate, Commit
    • Determinar os campos que devem ser preenchidos pelo usuário: GetFieldRequiredness
    • Determinar os valores aceitáveis para cada campo e quais campos possuem valores incorretos: GetFieldType, GetInvalidFieldValues
    • Determinar quais campos foram atualizados: GetFieldsUpdatedThisAction, GetFieldsUpdatedThisGroup, GetFieldsUpdatedThisSetValue
    • Localizar outros registros de dados que são considerados duplicatas desse registro: GetDuplicates
    • Localizar o registro original de dados, se esse for uma duplicata: GetFieldOriginalValueEntities
    Para obter uma lista dos tipos de registro por nome, use os seguintes métodos do objeto Session:
    • Todos os tipos de registro: GetEntityDefNames
    • Tipos de registro que têm estado: GetReqEntityDefNames
    • Tipos de registro que são stateless: GetAuxEntityDefNames
    • Tipos de registro que pertencem a uma família de ripo de registro: GetQueryEntityDefNames Tipos de registro que podem ser usados para criar um novo registro: GetSubmitEntityDefNames
    Para obter o objeto EntityDef associado a um tipo de registro particular, use o método GetEntityDef.
    É possível usar os seguintes métodos para obter detalhes de um registro:
    • Obter Propriedades do Campo:

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

    • Obter campos especiais: Entity->GetAttachmentFields, Entity->GetHistoryFields
    • Obter Anexos:

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

    • Obter Histórico: HistoryField->GetDisplayNameHeader, HistoryField->GetHistories, History->GetValue
    • Obter Ações Válidas para o Estado atual do Registro: Entity->GetLegalActionDefNames

Objetos Entity encontrados usando essas técnicas são somente leitura. (Para editar um objeto Entity, você deve chamar o método EditEntity do objeto Session, que está descrito na próxima lição deste tutorial.)

Exemplos

Esta seção inclui dois exemplos:
  • Recuperando dados sobre um campo em um registro
  • Recuperando dados sobre um tipo de registro

Uma das chamadas da API mais comuns é a para o objeto FieldInfo. Por exemplo, o objeto FieldInfo possui o método GetValue que permite que você obtenha o valor de um campo em um registro. A sub-rotina do aplicativo externo a seguir imprimi as informações armazenadas em um objeto 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);
Para mostrar que você pode manipular metadados, o exemplo a seguir imprime as seguintes informações do EntityDef:
  • O nome do EntityDef
  • Os nomes e tipos de cada campo e a ação que ele contém
  • Os nome de cada estado que ele contém
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); 
< Anterior | Próximo >

Feedback