< Anterior | Próximo >

Modificando um Registro

Para modificar os conteúdos de um registro, você recupera primeiro o registro chamando o método GetEntity e, em seguida, EditEntity do objeto Session.

O método EditEntity executa a ação especificada em um registro e torna o registro disponível para edição. O objeto Entity especificado por você no parâmetro da entidade deve ter sido obtido previamente chamando o GetEntityByDbId ou GetEntity, ou pela execução de uma consulta.

A sintaxe para EditEntity:
$session->EditEntity(entity, edit_action_name); 
  • session - O objeto Session que representa a sessão atual de acesso ao banco de dados.
  • entity - O objeto Entity correspondente ao registro que será editado.
  • edit_action_name - Uma Cadeia que contém o nome da ação para iniciar a edição (por exemplo, modify ou resolve).

    Você pode obter a lista dos valores permitidos para o parâmetro edit_action_name, chamando o método GetActionDefNames do objeto EntityDef adequado.

Exemplo:
# Build Session object...

# Edit the record whose ID is "BUGDB00000010" using the "modify" action
$objtoedit = $sessionobj->GetEntity("defect", "BUGDB00000010");
$sessionobj->EditEntity($objtoedit,"modify"); 

Depois de chamar o método EditEntity, você pode chamar os métodos do objeto Entity para modificar os campos do registro correspondente. Você pode também obter informações adicionais sobre o tipo de dados nos campos ou sobre o registro como um todo ou alterar o comportamento de um campo para a duração da ação atual.

Abaixo estão alguns dos métodos que podem ser usados durante a edição de registros e valores de campo:
  • Modificar valores de campo: SetFieldValue, AddFieldValue, DeleteFieldValue
  • Incluir /Excluir Anexos: AddAttachmentFieldValue, DeleteAttachmentFieldValue
  • Obter status dos grupos dos campos: GetInvalidFieldValues, GetFieldsUpdatedThisSetValue/Group/Action
  • Obter status do campo individual a partir do FieldInfo: GetValidationStatus, GetMessageText

O método SetFieldValue posiciona o valor especificado no campo nomeado. Se o campo pode ser alterado, esse método configura seu novo valor, independente de o valor ser válido e retorna a Cadeia vazia.

Para determinar se um campo contém um valor válido, obtenha o objeto FieldInfo para aquele campo e chame o método ValidityChangedThisSetValue do objeto FieldInfo para validar o campo. Se o campo não pode ser alterado, a Cadeia retornada indica por que o campo não pode ser alterado. Os valores típicos incluem "no such field", "record is not being edited" e "field is read-only". Se o campo pode ter múltiplos valores em vez de apenas um, use o método AddFieldValue para incluir cada novo valor. Ainda é permitido usar SetFieldValue; no entanto, usar SetFieldValue em um valor que já contém uma lista de valores substitui a lista inteira com o novo valor único. Você pode chamar esse método somente se o objeto Entity for editável.

Sintaxe para o SetFieldValue:
$entity->SetFieldValue(field_name, new_value); 
  • entity - Um objeto Entity que representa um registro de banco de dados do usuário.
  • field_name - Uma cadeia que contém um nome de campo válido desse objeto Entity.
  • new_value - Uma Cadeia que contém o novo valor.
Se as alterações no campo são permitidas, esse método retorna uma Cadeia vazia, do contrário, retorna uma Cadeia que contém uma explicação do erro.

Para editar um registro existente, siga estas etapas:

  1. Obtenha o objeto Entity que deseja edita usando os métodos do objeto Session. É possível usar os métodos do objeto Session para realizar uma consulta que localize registros que correspondam aos critérios definidos e, em seguida, trabalhar com os registros no conjunto de resultados da consulta.
  2. Para tornar um objeto Entity editável, chame o método EditEntity do objeto Session.
  3. Use os métodos do objeto Entity para modificar os dados no registro.
  4. Quando tiver terminado a edição do registro, valide e confirme suas alterações no banco de dados chamando os métodos Validate e Commit, do objeto respectivamente.

Exemplo

O exemplo seguinte lista todos os registros de defeito no banco de dados do usuário do Rational ClearQuest e modifica um dos registros. O programa:
  • Lista todos os registros de defeito no banco de dados SAMPL e seleciona id, Headline, e State como campos de exibição.
  • Modifica o campo Description do registro de defeito SAMPL00000012 para "This defect has been modified."
use CQPerlExt; 
#Getting the session
my $session = CQSession::Build();
CQSession::UserLogon ($session, "admin", "", "SAMPL", "Lab3");

my $querydef = $session->BuildQuery ("defect");
$querydef->BuildField ("id");
$querydef->BuildField ("headline");
my $resultset = $session->BuildResultSet ($querydef);
$resultset->Execute();
while (($resultset->MoveNext()) == 1) {
   $id = $resultset->GetColumnValue(1);
   $rec = $session->GetEntity("Defect", $id);
   $head = $rec->GetFieldValue("Headline")->GetValue();
   $state= $rec->GetFieldValue("State")->GetValue();
   print "$id, $head, $state. \n";
      if ($id eq "SAMPL00000012") {
         $session->EditEntity($rec, "Modify");
         $rec->SetFieldValue("description", "This defect has been modified."); 
         $status = $rec->Validate();
         if ( $status ){
            $rec->Revert;
            die "Validation Error: $status \n"
          } else {
               # Only commit the changes if the validation is first successful.
               $rec->Commit();
             }
      }
 } 
CQSession::Unbuild($session); 
< Anterior | Próximo >

Feedback