新規レコードを作成するには、Session オブジェクトの BuildEntity メソッドを使用します。
BuildEntity メソッドは、指定されたユーザー データベース用に固有の ID を付けた新規の Entity オブジェクトを作成し、レコードに対して登録アクションを開始します。登録アクション中、レコードは、Entity オブジェクトのデフォルト値の編集が可能です。
BuildEntity を使用して Entity オブジェクトを作成済みで、まだデータベースにコミットしていなかった場合、そのオブジェクトは編集可能になっています。
BuildEntity メソッドは、 指定されたタイプの新規レコードを作成し、登録アクションを開始します。これによって、レコード内容の編集を開始できる ようになります。(レコードを編集可能にするために、EditEntity を呼び出す必要はありません。) 新規レコードのフィールドに値を割り当てるには、戻された Entity オブジェクトの SetFieldValue メソッドを使用します。レコードの更新を行った場合は、レコードに行った変更について、Entity オブジェクトの Validate を使用して検証し、Commit メソッドを使用してコミットします。entitydef_name パラメータに指定する名前が、スキーマ内の該当するレコード タイプに対応している必要もあります。 entitydef_name の正当な名前のリストを取得するには、GetSubmitEntityDefNames メソッドを使用します。
$session->BuildEntity(entity_def_name);
# Build Session object...
# Create a new "defect" record
$entityobj = $sessionobj->BuildEntity("defect");
BuildEntity メソッドを呼び出した後は、 このチュートリアルの前のレッスンで説明されているように、Entity オブジェクトのメソッドを呼び出して、レコードのフィールド値を設定する ことができます。
新規レコードを作成する手順は、 次のとおりです。
以下の例は、 状態ありと状態なしの両方のレコード タイプを処理する方法を示しています。
スキーマには、 状態なしレコード (プロジェクトなど) と、ある状態から別の状態に移動する状態ありレコード (障害など) が あります。Rational ClearQuest API を使用すると、両種類のレコードのフィールド値を取得および設定できます。以下の例 には 2 つのサブルーチンが含まれています。状態なしレコード用の No_state と、 状態ありレコード用の Has_state です。
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";
}
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";
}