Managing records (entities) that are stateless and stateful

Your schema has stateless records, such as the Project, and stated records, such as Defect, which move from state to state. The Rational® ClearQuest® API enables you to get and set field values for both kinds of records.

The example shown in this section is an external application example that contains two subroutines: No_state for stateless records, and Has_state for records that have states. The example does the following:

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

The code invokes some external routines that are not shown here:

• DumpFields, which prints out an entity's fields to the standard output
• ValidateAndCommit, which calls the Entity object's Validate and Commit methods.

VBScript

' subroutine for stateless records

Sub No_state(session) ' the Session Object
   Dim entity ' the Entity Object
   Dim failure ' a String 

   StdOut "Test for stateless entities is starting" 
   StdOut "submit a stateless entity" 
   Set entity = session.BuildEntity("project")

   ' ignore failure
   failure = entity.SetFieldValue("name", "initial project name") 

   DumpFields entity 
   ValidateAndCommit entity 
   Set entity = Nothing 

   StdOut "Reload, show values before modification" 
   Set entity = session.GetEntity("project", "initial project name")
   DumpFields entity 

   StdOut "Modify, then show new values" 
   session.EditEntity entity, "modify" 

   ' ignore the failure
   failure = entity.SetFieldValue("name", "modified project name") 
   DumpFields entity 

   StdOut "revert, then show restored values" 
   entity.Revert 
   DumpFields entity 

   StdOut "Modify again, and commit" 
   session.EditEntity entity, "modify" 

   ' ignore failure 
   failure = entity.SetFieldValue("name", "final project name") 
   ValidateAndCommit entity 
   Set entity = Nothing 

   StdOut "Reload, and show final result" 
   Set entity = session.GetEntity("project", "final project name")
   DumpFields entity 
   Set entity = Nothing 

   StdOut "Test for stateless entities is done" 
End Sub 


' subroutine for stateful records
Sub Has_states(session) ' the Session object
   Dim entity ' the Entity object that is stateful 

  ' failure message from functions that return strings 
   Dim failure 
   Dim failures ' an iterator containing list of failure reasons 
   Dim id ' Rational
                    ClearQuest defect database ID 

   StdOut "Test for stateful entities is starting" 
   StdOut "submit a stateful entity" 
   Set 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 "XXStdout" For Append As #1 
   Print #1, "Entity id is"; id; Chr(10); 
   Close #1 

   DumpFields entity 
   ValidateAndCommit entity 
   Set entity = Nothing 

   StdOut "Reload, show values before modification" 
   Set entity = session.GetEntityByDbId("defect", id) 
   DumpFields entity 

   StdOut "Modify then show new values" 
   session.EditEntity entity, "modify" 

   ' ignore failure
   failure = entity.SetFieldValue("headline", "man bites tree!") 
   DumpFields entity 

   StdOut "revert, then show restored values" 
   entity.Revert 
   DumpFields entity 

   StdOut "Modify again and commit" 
   session.EditEntity entity, "modify" 

   ' ignore failure 
   failure = entity.SetFieldValue("headline", "tree bites man!")
   ValidateAndCommit entity 
   Set entity = Nothing 

   StdOut "Reload and show before changing state" 
   Set entity = session.GetEntityByDbId("defect", id) 
   DumpFields entity 

   StdOut "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 

   StdOut "revert then show restored values" 
   entity.Revert 
   DumpFields entity 

   StdOut "Change to new state again then commit" 
   session.EditEntity entity, "close" 
   failure = entity.SetFieldValue("description", _ 
      "man of steel, tree of maple") ' ignore failure 
   ValidateAndCommit entity 
   Set entity = Nothing 

   StdOut "Reload, show final values" 
   Set entity = session.GetEntityByDbId("defect", id) 
   DumpFields entity 
   Set entity = Nothing 

   StdOut "Test of stateful entities is done" 
End Sub 

REM Start of Global Script StdOut

sub StdOut(Msg)

   msgbox Msg

end sub

REM End of Global Script StdOut 

Perl

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);

   $entity->Validate();

   $entity->Commit();


    $entity = "";


    print "Reload, show values before modification";

    $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");

      $entity->Validate();

      $entity->Commit();

    $entity = "";


    print "Reload, and show final result";

    $entity = $session->GetEntity("project", "final project name");

    DumpFields($entity);

    $entity = "";


    print "Test for stateless entities is done";

} 

Perl

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);

      $entity->Validate();

      $entity->Commit();

    $entity = "";


    print "Reload, show values before modification";

    $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!");

      $entity->Validate();

      $entity->Commit();


    $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

      $entity->Validate();

      $entity->Commit();


    $entity = "";


    print "Reload, show final values";

    $entity = $session->GetEntityByDbId("defect", $id);

    DumpFields($entity);

    $entity = "";


    print "Test of stateful entities is done";

}