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:
The code invokes some external routines that are not shown here:
' 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
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";
}
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";
}