Creating a new record

To create a new record, you use the BuildEntity method of the Session object.

About this task

The BuildEntity method creates a new Entity object with a unique ID for the given user database and initiates a submit action for the record. During the submit action, the record is available for editing the default values in the Entity object.

If you create an Entity object using BuildEntity and have not yet committed it to the database, the object is available for editing.

The BuildEntity method creates a new record of the specified type and begins a submit action, which enables you to begin editing the record's contents. (You do not need to call EditEntity to make the record editable.) You can assign values to the new record's fields using the SetFieldValue method of the returned Entity object. When you are done updating the record, use the Validate and Commit methods of the Entity object to validate and commit any changes you made to the record, respectively. The name you specify in the entitydef_name parameter must also correspond to an appropriate record type in the schema. To obtain a list of legal names for entitydef_name, use the GetSubmitEntityDefNames method.

The syntax for BuildEntity:

$session->BuildEntity(entity_def_name);

session - The Session object that represents the current database-access session.
entity_def_name - A String containing the name of the EntityDef object to use as a template when creating the record.

The return value is a new Entity object that is built using the named EntityDef object as a template.

For example:

# Build Session object...

# Create a new "defect" record 
$entityobj = $sessionobj->BuildEntity("defect");

After calling the BuildEntity method, you can call the methods of the Entity object to set the field values in the record as described in the previous lesson of this tutorial.

To create a new record:

Procedure

Determine what record types you can create by calling the GetSubmitEntityDefNames method of the Session object.
Call the BuildEntity method of the Session object.
Use methods of the Entity object to set values for fields in the record.
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 illustrates how to work with both stateful and stateless records types.

Your schema has stateless records, such as the Project, and stateful records which move from state to state, such as Defect. The Rational® ClearQuest® API enables you to get and set field values for both kinds of records. The following example contains two subroutines: No_state for stateless records, and Has_state for records that have states.

The code example:

Uses the Session's BuildEntity method to create an Entity Object.
Set the values in one or more fields.
Validates and commits the entity.
Retrieves and modifies the entity.
Reverts the entity.

The code in these two subroutines calls two external routines that are not shown here - DumpFields, which prints out an entity's fields to the standard output, and myValidateCommit, which first validates the changes and commits the change following validation success or reverts on validation failure. Here is the code that could be used for myValidateCommit:

 sub myValidateCommit( $entity ){
  $status = $entity->Validate;
  if ( $status ) {
    $entity->Revert;
    # for simplicity, we die on any error, you should do what makes sense in your
    # application if recovery is possible.
    die "Error validating: $status \n";
  }
  else {
    $entity->Commit;
  }
 }

sub No_state { 
   my($session) = @_; 
   my($entity); 
   my($failure); 
   print "Test for stateless entities is starting"; 
   print "submit a stateless entity"; 
   $entity = $session->BuildEntity("project"); 
   # ignore failure $failure = $entity->SetFieldValue("name", "initial project name");
   DumpFields($entity); 
   myValidateCommit( $entity ); 
   $entity = ""; 
   print "Reload, show values before modification"; 
   # Note that the Entity->Reload method can be used to force a refresh of the entity from the database.
   $entity = $session->GetEntity("project", "initial project name"); 
   DumpFields($entity); 
   print "Modify, then show new values"; 
   $session->EditEntity($entity, "modify"); 

   # ignore the failure 
   $failure = $entity->SetFieldValue("name", "modified project name"); 
   DumpFields($entity); 

   print "revert, then show restored values"; 
   $entity->Revert(); 
   DumpFields($entity); 

   print "Modify again, and commit"; 

   $session->EditEntity($entity, "modify"); 

   # ignore failure 
   $failure = $entity->SetFieldValue("name", "final project name"); 
   myValidateCommit( $entity ); 
   $entity = ""; 
   print "Reload, and show final result"; 
   $entity = $session->GetEntity("project", "final project name"); 
   DumpFields($entity); 
   $entity = ""; 
   print "Test for stateless entities is done"; 
}

The following is an example of testing for stateful entities:

sub Has_states {
 my($session) = @_;
 my($entity);
 # the entity that is stateful
 # failure message from functions that return strings 
 my($failure);
 my($id);
 # Rational
ClearQuest defect database ID 
 print "Test for stateful entities is starting";
 print "submit a stateful entity";
 $entity = $session->BuildEntity("defect");
 # ignore failures
 $failure = $entity->SetFieldValue("headline", "man bites dog!");
 $failure = $entity->SetFieldValue("project", "final project name");
 $failure = $entity->SetFieldValue("submit_date", "03/18/2000 10:09:08");
 $id = $entity->GetDbId();
 open(FILE, ">>XXStdout");
 print FILE, "Entity id is", $id, "\n";
 close FILE;
 DumpFields($entity);
 myValidateCommit( $entity ); 

 $entity = "";
 print "Reload, show values before modification";
 # Note that the Entity->Reload method can be used to force a refresh of the entity from the database.
 $entity = $session->GetEntityByDbId("defect", $id);
 DumpFields($entity);
 print "Modify then show new values";
 $session->EditEntity($entity, "modify"); 

 # ignore failure
$failure = $entity->SetFieldValue("headline", "man bites tree!");
 DumpFields($entity);
 print "revert, then show restored values";
 $entity->Revert();
 DumpFields($entity);
 print "Modify again and commit";
 $session->EditEntity($entity, "modify");
 # ignore failure
 $failure = $entity->SetFieldValue("headline", "tree bites man!");
 myValidateCommit( $entity ); 
 $entity = "";
 print "Reload and show before changing state";
 $entity = $session->GetEntityByDbId("defect", $id);
 DumpFields($entity);
 print "Change to new state, then show new values";
 $session->EditEntity($entity, "close");
 $failure = $entity->SetFieldValue("description", "looked like an oak tree");
 # ignore failure
 DumpFields($entity);
 print "revert then show restored values";
 $entity->Revert();
 DumpFields($entity);
 print "Change to new state again then commit";
 $session->EditEntity($entity, "close");
 $failure = $entity->SetFieldValue("description", "man of steel, tree of maple");
 # ignore failure
 myValidateCommit( $entity ); 

 $entity = "";
 print "Reload, show final values";
 $entity = $session->GetEntityByDbId("defect", $id);
 DumpFields($entity);
 $entity = "";
 print "Test of stateful entities is done";
 }

< Previous | Next >