< Previous | Next >

Modifying a record

To modify the contents of a record, you first retrieve the record by calling the GetEntity method and then calling the EditEntity method of the Session object.

About this task

The EditEntity method performs the specified action on a record and makes the record available for editing. The Entity object you specify in the entity parameter must have been previously obtained by calling GetEntityByDbId or GetEntity, or by running a query.

The syntax for EditEntity: 
$session->EditEntity(entity, edit_action_name);
  • session - The Session object that represents the current database-access session.
  • entity - The Entity object corresponding to the record that is to be edited.
  • edit_action_name - A String containing the name of the action to initiate for editing (for example, modify or resolve).

    You can get the list of legal values for the edit_action_name parameter, call the GetActionDefNames method of the appropriate EntityDef object.

For example: 
# Build Session object...

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

After calling the EditEntity method, you can call the methods of the Entity object to modify the fields of the corresponding record. You can also get additional information about the type of data in the fields or about the record as a whole, or change the behavior of a field for the duration of the current action.

Here are some of the methods you can use when editing records and field values:
  • Modify field values: SetFieldValue, AddFieldValue, DeleteFieldValue
  • Add /Delete Attachments: AddAttachmentFieldValue, DeleteAttachmentFieldValue
  • Get status of groups of fields: GetInvalidFieldValues, GetFieldsUpdatedThisSetValue/Group/Action
  • Get status of individual field from its FieldInfo: GetValidationStatus, GetMessageText

The SetFieldValue method places the specified value in the named field. If the field can be changed, this method sets its new value, regardless of whether that value is valid, and returns the empty String.

To determine whether a field contains a valid value, obtain the FieldInfo object for that field and call the ValidityChangedThisSetValue method of the FieldInfo object to validate the field. If the field cannot be changed, the returned String indicates why the field cannot be changed. Typical values include "no such field", "record is not being edited", and "field is read-only". If the field can have multiple values instead of just one, use the AddFieldValue method to add each new value. It is still legal to use SetFieldValue; however, using SetFieldValue on a field that already contains a list of values replaces the entire list with the single new value. You can call this method only if the Entity object is editable.

The syntax for SetFieldValue: 
$entity->SetFieldValue(field_name, new_value);
  • entity - An Entity object representing a user database record.
  • field_name - A String containing a valid field name of this Entity object.
  • new_value - A String containing the new value.
If changes to the field are permitted, this method returns an empty String; otherwise, this method returns a String containing an explanation of the error.

To edit an existing record, follow these steps:

Procedure

  1. Get the Entity object you want to edit by using the methods of the Session object. You can use methods of the Session object to have a query find records that match criteria you define, and then work with the records in the query's result set.
  2. To make an existing Entity object editable, call the EditEntity method of the Session object.
  3. Use methods of the Entity object to modify data in the record.
  4. When you are done editing the record, validate it and commit your changes to the database by calling the Entity object's Validate and Commit methods, respectively.

Example

The following example lists all the defect records in a Rational® ClearQuest® user database, and modifies one of the records. The program:
  • Lists all the defect records in the SAMPL database, and selects id, Headline, and State as display fields.
  • Modifies the Description field of the defect record SAMPL00000012 to be "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);
< Previous | Next >