< 前へ | 次へ >

レコードの取り出し

レコードの内容を表示するには、Session オブジェクト の GetEntity メソッドを呼び出してレコードを取り出します。

GetEntity メソッドは、指定されたレコードを戻します。状態ありレコード タイプを要求する場合、display_name パラメータにはレコードの表示 ID (例えば、DEF00013323) が含まれている必要があります。状態なしレコード タイプの場合、このパラメータには、レコードの一意なキー フィールドの値が含まれている必要があります。

各新規レコード には、1 つの表示可能な ID 文字列が割り当てられます。これは、論理データベース名と固有 の順序番号から構成されます。例えば、BUGID データベースの 10 番目のレコードは、表示 ID が BUGID00000010 となります。レコードの ID が不明な場合は、Session オブジェクトの BuildQuery メソッドを使用して、必要な条件セットに一致するレコードのクエリーと検索を作成します。

表示 ID の代わりにデータベース ID を使用してレコードを要求するには、GetEntityByDbId メソッドを使用します。Rational ClearQuest データベース ID (DBID) は、 Rational ClearQuest データベース内のオブジェクトを一意的に識別するために使用される整数値です。 DBID は、 ある 1 つのクラスのレコードで固有で、状態ありレコード内で固有で、 状態なしレコード内で固有です。

GetEntity の構文は次のとおりです。
$session->GetEntity(entity_def_name, display_name); 
  • session - 現在のデータベース アクセス セッションを表す Session オブジェクト。
  • entity_def_name - レコードが属するレコード タイプの名前を識別する String。
  • display_name - レコードの表示名を識別する String。表示名は、依頼エンティティの表示 ID かまたは aux エンティティの一意なキー フィールドです。戻り値は、依頼 されたレコードに対応する Entity オブジェクトです。
以下に例を示します。
# Build Session object...
$sessionObj->UserLogon("admin","","SAMPL","");
#Get record DEF00013323 
$record1 = $sessionObj->GetEntity( "defect", "DEF00013323" ); 
Entity が存在すること、または正しく戻されたことの 検証も行う必要があります。GetEntity を呼び出す前に、Session オブジェクトの EntityExists メソッドまたは EntityVisible メソッドを 使用して、Entity が存在し、表示可能であることを検証することができます。また、GetEntity メソッドの 戻り値をテストして、Entity オブジェクトに追加のメソッドを呼び出す前に Entity オブジェクトがあることを検証することもできます。次のようにして、NULL でないことを テストできます。
$record1 = $sessionobj->GetEntity("defect", "DEF00013323");
die "Error getting Defect DEF00013323" unless $record1;

レコードの内容を表示するには、次のステップに従います。

  1. GetEntity メソッドを使用して、レコードを取得します。 Entity オブジェクトが戻されたことを確認します。
  2. 戻された Entity オブジェクトのメソッドを使用して、レコードのフィールドにアクセスします。
    Entity オブジェクトを取得したら、そのオブジェクトのメソッドを呼び出して次のようなタスクを実行できます。
    • フィールドの値と状態を調べる: GetFieldValue、GetValue

      GetFieldValue(fieldname) メソッド は、フィールド値ではなくフィールドを表す FieldInfo オブジェクト を戻します。FieldInfo オブジェクトには、値および値の状態 が含まれています。FieldInfo オブジェクトの次のメソッドを使用して、 実際の値を取得できます: GetType、GetRequiredness、GetValueStatus、GetValue

    • レコードの検証とコミット: Validate、Commit
    • ユーザーによって表示されるフィールドの判別: GetFieldRequiredness
    • 各フィールドごとの許容値の判別と、不正値のあるフィールドの判別: GetFieldType、GetInvalidFieldValues
    • 更新されたフィールドの判別: GetFieldsUpdatedThisAction、 GetFieldsUpdatedThisGroup、GetFieldsUpdatedThisSetValue
    • このレコードの重複と思われるほかのデータ レコードの検索: GetDuplicates
    • オリジナル データ レコードの検索 (このレコードが重複の場合): GetFieldOriginalValueEntities
    レコード タイプのリストを名前順に取得するには、Session オブジェクトの次のメソッドを使用します。
    • すべてのレコード タイプ: GetEntityDefNames
    • 状態ありのレコード タイプ: GetReqEntityDefNames
    • 状態なしのレコード タイプ: GetAuxEntityDefNames
    • レコード タイプ ファミリーに属しているレコード タイプ: GetQueryEntityDefNames 新規レコードの作成に使用できるレコード タイプ: GetSubmitEntityDefNames
    個々のレコード タイプに関連付けられた EntityDef オブジェクトを取得するには、GetEntityDef メソッドを使用します。
    次のメソッドを使用して、レコードの詳細を 取得できます。
    • フィールドのプロパティの取得:

      Entity->GetFieldNames, Entity->GetFieldChoiceType(fieldName), Entity->GetFieldMaxLength(fieldName), Entity->GetFieldChoiceList(fieldName), Entity->GetFieldType(fieldName), Entity->GetFieldRequiredness(fieldName)

    • 特殊フィールドの取得: Entity->GetAttachmentFields, Entity->GetHistoryFields
    • 添付の取得:

      AttachmentField->GetDisplayNameHeader, AttachmentField->GetAttachments, Attachment->GetDisplayName, Attachment->GetDescription, Attachment->GetFileSize Attachment->GetFileName, Attachment->Load(temp-file-name)

    • 履歴の取得: HistoryField->GetDisplayNameHeader, HistoryField->GetHistories, History->GetValue
    • レコードの現在の状態に対する正当なアクションの取得: Entity->GetLegalActionDefNames

これらの方法を使用して見つかった Entity オブジェクトは、読み取り専用です。(Entity オブジェクト を編集するには、Session オブジェクトの EditEntity メソッドを 呼び出す必要があります。それは、このチュートリアルの次のレッスンで説明されます。)

ここでは、2 つの例を示します。
  • レコード内のフィールドに関するデータの取得
  • レコード タイプに関するデータの取得

最も一般的な API 呼び出しの 1 つは、FieldInfo オブジェクトに対する呼び出しです。例えば、FieldInfo オブジェクトには、レコード内のフィールドの値を取得できる GetValue メソッドがあります。次の外部アプリケーションサブルーチンは、FieldInfo オブジェクトに格納されている情報を印刷します。

use CQPerlExt; 
$CQsession = CQSession::Build(); 
$CQsession->UserLogon("admin", "", "perl", ""); 
$record = $CQsession->GetEntity("Defect", "perl00000001"); 
$fieldInfo = $record->GetFieldValue("id"); 
$temp = $fieldInfo->GetValueStatus(); 
if ($temp == $CQPerlExt::CQ_VALUE_NOT_AVAILABLE) { 
   $status = "VALUE_NOT_AVAILABLE"; 
} elsif ($temp == $CQPerlExt::CQ_HAS_VALUE) { 
   $status = "HAS_VALUE"; 
   $value = "'" . $fieldinfo->GetValue() . "'"; 
} elsif ($temp == $CQPerlExt::CQ_HAS_NO_VALUE) { 
   $status = "NO_VALUE";
} else { 
   $status = "<invalid value status: "& temp & ">"; 
} 
   $temp = $fieldInfo->GetValidationStatus(); 
if ($temp == $CQPerlExt::CQ_KNOWN_INVALID) { 
   $validity = "INVALID";
 } elsif ($temp == $CQPerlExt::CQ_KNOWN_VALID) { 
   $validity = "VALID"; 
} elsif ($temp == $CQPerlExt::CQ_NEEDS_VALIDATION) { 
   $validity = "NEEDS_VALIDATION"; 
} else { $validity = "<invalid validation status: " & temp & ">"; 
} 
$valuechange = ""; 
if ($fieldInfo->ValueChangedThisSetValue()) { 
   $valuechange = $valuechange . " setval=Y"; 
} else { 
   $valuechange = $valuechange . " setval=N"; 
} 
if ($fieldInfo->ValueChangedThisGroup()) { 
   $valuechange = $valuechange . " group=Y"; 
} else { 
$valuechange = $valuechange . " group=N"; 
} 
if ($fieldInfo->ValueChangedThisAction()) {
 $valuechange = $valuechange . " action=Y"; 
} else { 
   $valuechange = $valuechange . " action=N";
} 
$validchange = ""; 
if ($fieldInfo->ValidityChangedThisSetValue()) { 
   $validchange = $validchange . " setval=Y"; 
} else { 
   $validchange = $validchange . " setval=N"; 
} 
if ($fieldInfo->ValidityChangedThisGroup()) { 
   $validchange = $validchange . " group=Y"; 
} else { 
   $validchange = $validchange . " group=N"; 
} 
if ($fieldInfo->ValidityChangedThisAction()) { 
   $validchange = $validchange . " action=Y"; 
} else { 
   $validchange = $validchange . " action=N"; 
}
print "FieldInfo for field = ", $fieldInfo->GetName(), "¥n";
print "Field's value       = ", $value, "¥n";
print "Value status        = ", $status, "¥n";
print "Value change        = ", $valuechange, "¥n";
print "Validity            = ", $validity, "¥n";
print "Validity change     = ", $validchange, "¥n";
print "Error = ", $fieldInfo->GetMessageText(), "'"; 
CQSession::Unbuild($CQsession);
メタデータを操作できることを示すために、 以下の例は次の EntityDef 情報を印刷します。
  • EntityDef の名前
  • 各フィールドの名前とタイプ、およびそこに含まれるアクション
  • 含まれる各状態の名前
use strict; 
use CQPerlExt; 
my $sessionObj = CQSession::Build(); 
$sessionObj->UserLogon("admin", "", "SAMPL", ""); 
my $entityDefNames = $sessionObj->GetEntityDefNames(); 

# Iterate over the record types 
foreach my $edef_name (@$entityDefNames) 
   { 
     my $entityDefObj = $sessionObj->GetEntityDef($edef_name);
     print_edef($entityDefObj); 
   }
 
sub print_edef { 
   my($edef)=@_; 
   # The parameter is an EntityDef object. 
   my($names, $name); 
   print "Dumping EntityDef ", $edef->GetName; print "\nFieldDefs:"; 
   $names = $edef->GetFieldDefNames; 
   foreach $name (@$names) { 
      print " " , $name , " type=" , $edef->GetFieldDefType($name);
      } 
   print "¥nActionDefs: ";
   $names = $edef->GetActionDefNames; 
   foreach $name (@$names) { 
      print " " , $name , " type=" , $edef->GetActionDefType($name);
      } 
   if ($edef->GetType == $CQPerlExt::CQ_REQ_ENTITY) { 
      # stated record type 
      print "¥nEntityDef is a REQ entity def";
      print "¥nStateDefs:";
      $names = $edef->GetStateDefNames; 
      foreach $name (@$names) { 
         print " " , $name; 
         } 
      }
else { 
      # stateless record type 
      print "¥nEntityDef is an AUX entity def";
      } 
   print "¥n¥n";
   } 
CQSession::Unbuild($sessionObj); 

フィードバック
< 前へ | 次へ >