< Anterior | Siguiente >

Recuperación de un registro

Para ver el contenido de un registro, recupere el registro llamando al método GetEntity del objeto Session.
El método GetEntity devuelve el registro especificado. Cuando se solicita un tipo de registro basado en estado, el parámetro display_name debe contener el ID visible del registro (por ejemplo, DEF00013323). Para tipos de registro sin estado, este parámetro debe contener el valor del campo de clave exclusiva del registro.

A cada nuevo registro se le asigna una serie de ID visible compuesta por el nombre de base de datos lógica y un número secuencial exclusivo. Por ejemplo, el décimo registro de la base de datos BUGID puede tener el ID visible BUGID00000010. Si no conoce el ID del registro, puede utilizar el método BuildQuery del objeto Session para crear una consulta y buscar los registros que coincidan con un conjunto de criterios deseado.

Para solicitar un registro utilizando su ID de base de datos en lugar del ID visible, utilice el método GetEntityByDbId. Un identificador de base de datos (DBID) de Rational ClearQuest es un valor entero que se utiliza para identificar de modo exclusivo un objeto en una base de datos de Rational ClearQuest. Los DBID son exclusivos de una clase de registros, exclusivos dentro de los registros con estado y exclusivos dentro de los registros sin estado.

Sintaxis para GetEntity:
$session->GetEntity(entity_def_name, display_name); 
  • session: el objeto Session que representa la sesión de acceso a la base de datos actual.
  • entity_def_name: un valor String que identifica el nombre del tipo de registro al que pertenece el registro.
  • display_name: un valor String que identifica el nombre de visualización del registro. El nombre de visualización debe ser el ID visible para entidades de solicitud, o bien, los campos de clave exclusiva para una entidad aux. El valor de retorno de un objeto Entity correspondiente al registro solicitado.
Por ejemplo:
# Build Session object...
$sessionObj->UserLogon("admin","","SAMPL","");
#Get record DEF00013323 
$record1 = $sessionObj->GetEntity( "defect", "DEF00013323" ); 
También debe comprobar si se debe validar que el objeto Entity exista o que se devuelva correctamente. Puede utilizar los métodos EntityExists o EntityVisible del objeto Session antes de llamar a GetEntity para validar que el objeto Entity exista y pueda verse. También puede probar el valor de retorno del método GetEntity para validar que tenga el objeto Entity antes de llamar a métodos adicionales. Puede probar si no es nulo del modo siguiente:
$record1 = $sessionobj->GetEntity("defect", "DEF00013323");
die "Error getting Defect DEF00013323" unless $record1;

Para ver el contenido de un registro, siga los pasos que se indican a continuación:

  1. Utilice el método GetEntity para obtener el registro. Valide que se devuelva el objeto Entity.
  2. Utilice métodos del objeto Entity devuelto para acceder a los campos del registro.
    Después de obtener un objeto Entity, puede llamar a sus métodos para ejecutar las tareas siguientes:
    • Examinar los valores y estado de un campo: GetFieldValue, GetValue

      El método GetFieldValue(nombre_campo) devuelve un objeto FieldInfo, que representa un campo y no es un valor de campo. El objeto FieldInfo contiene el valor y estado del valor. Puede utilizar estos métodos del objeto FieldInfo para obtener los valores reales: GetType, GetRequiredness, GetValueStatus, GetValue

    • Validar y confirmar el registro: Validate, Commit
    • Determinar los campos que debe rellenar el usuario: GetFieldRequiredness
    • Determinar los valores aceptables para cada campo, y los campos que tienen valores incorrectos: GetFieldType, GetInvalidFieldValues
    • Determinar los campos que se han actualizado: GetFieldsUpdatedThisAction, GetFieldsUpdatedThisGroup, GetFieldsUpdatedThisSetValue
    • Buscar otros registros de datos que se consideren duplicados de este: GetDuplicates
    • Encontrar el registro de datos original, si este es un duplicado: GetFieldOriginalValueEntities
    Para obtener una lista de tipos de registro por nombre, utilice los métodos del objeto Session siguientes:
    • Todos los tipos de registro: GetEntityDefNames
    • Tipos de registro que tienen estados: GetReqEntityDefNames
    • Tipos de registro que no tienen estados: GetAuxEntityDefNames
    • Tipos de registro que pertenecen a una familia de tipos de registro: GetQueryEntityDefNames Tipos de registro que puede utilizar para crear un registro nuevo: GetSubmitEntityDefNames
    Para obtener el objeto EntityDef asociado a un tipo de registro concreto, utilice el método GetEntityDef.
    Puede utilizar los métodos siguientes para obtener detalles de un registro:
    • Obtener propiedades de campo:

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

    • Obtener campos especiales: Entity->GetAttachmentFields, Entity->GetHistoryFields
    • Obtener adjuntos:

      AttachmentField->GetDisplayNameHeader, AttachmentField->GetAttachments, Attachment->GetDisplayName, Attachment->GetDescription, Attachment->GetFileSize Attachment->GetFileName, Attachment->Load(nombre-archivo-temp)

    • Get History: HistoryField->GetDisplayNameHeader, HistoryField->GetHistories, History->GetValue
    • Obtener acciones legales para el estado actual del registro: Entity->GetLegalActionDefNames

Los objetos Entity que se encuentran utilizando estas técnicas son de sólo lectura (para editar un objeto Entity, debe llamar al método EditEntity del objeto Session, que se describe en la próxima lección de esta guía de aprendizaje).

Ejemplos

Esta sección incluye dos ejemplos:
  • Recuperación de datos de un campo de un registro
  • Recuperación de datos de un tipo de registro

Una de las llamada de API más comunes es al objeto FieldInfo. Por ejemplo, el objeto FieldInfo tiene el método GetValue que le permite obtener el valor de un campo de un registro. La subrutina de aplicación externa siguiente imprime la información almacenada en un 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 ilustrar que se pueden manipular metadatos, el ejemplo siguiente imprime la siguiente información de EntityDef:
  • El nombre del EntityDef
  • Los nombres y los tipos de cada registro y acción que contiene
  • Los nombres de cada estado que contiene
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) { 
      #  tipo de registro con estado 
      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 | Siguiente >

Comentarios