In einem VBScript-Hook stellt IBM® Rational ClearQuest ein implizites Entity-Objekt bereit, das den aktuellen Datensatz darstellt. Wenn der VBScript-Hook eine Methode des Entity-Objekts aufruft, ohne eine vorangestellte ID anzugeben, verwendet IBM Rational ClearQuest automatisch dieses implizite Entity-Objekt. Darüber hinaus definieren Rational ClearQuest-Hooks eine explizite Entitätsvariable ("Entity"), die Sie zum Angeben des Objekts verwenden können, auf das Sie sich beziehen. Der Name der Entitätsvariablen entspricht dem Namen des Satztyps. Wenn Sie außerhalb eines Hooks auf die API zugreifen, oder wenn Sie auf ein Entity-Objekt zugreifen, das nicht das implizite Entity-Objekt ist, müssen Sie das andere Entity-Objekt explizit angeben. (Bei Verwendung von Perl müssen Sie immer eine explizite Variable angeben, deren Name "Entity" lautet. Details hierzu finden Sie im Abschnitt GetSession.)
In den folgenden Beispielen werden zwei Möglichkeiten aufgezeigt, um eine Methode in einem VBScript-Hook aufzurufen. Im zweiten Beispiel stellt der Wert defect das aktuelle Entity-Objekt (Satztyp) dar.
fieldvalue = GetFieldValue("fieldname").GetValue()
oder
fieldvalue = defect.GetFieldValue("fieldname").GetValue()
Das Session-Objekt stellt zwei Methoden zum Abrufen einer Entität zur Verfügung: BuildEntity (zur Erstellung eines neuen Datensatzes) oder GetEntity (für einen vorhandenen Datensatz). Wenn Sie einen neuen Datensatz übergeben, ruft BuildEntity die Entität automatisch ab. Zum Abrufen eines vorhandenen Datensatzes übergeben Sie der Methode GetEntity die eindeutige Kennung des Datensatzes und den Namen des Satztyps.
Entity-Objekte werden über den Anzeigenamen des entsprechenden Satztyps identifiziert. Bei statusunabhängigen Satztypen werden einzelne Satztypen mit dem Inhalt des eindeutigen Schlüsselfelds des Satztyps identifiziert. Bei statusabhängigen Satztypen werden Datensätze mit der sichtbaren Datensatz-ID identifiziert. IBM Rational ClearQuest ordnet jedem neuen Datensatz eine sichtbare ID zu, die aus dem logischen Datenbanknamen und einer eindeutigen, fortlaufenden Nummer besteht. Der zehnte Datensatz in der Datenbank "BUGID" könnte beispielsweise die sichtbare ID "BUGID00000010" haben.
Das folgende VBScript-Beispiel bezieht sich auf einen Hook, der auf zwei Entity-Objekte zugreift: auf das implizite Objekt und ein dupliziertes Objekt. Das duplizierte Objekt entspricht dem Datensatz, dessen ID "BUGID00000031" lautet.
set sessionObj = GetSession
' Call a method of the implicit Entity object.
set fieldvalue = GetFieldValue("fieldname")
' VBScript assumes the current entity implicitly.
' The fieldname must be valid or IBM
Rational ClearQuest returns an error.
value = fieldvalue.GetValue()
' Call the same method for the duplicate object, by explicitly acquiring
' the other entity, which is of the defect record type.
set otherEntity = sessionObj.GetEntity("defect", "BUGID00000031")
set fieldvalue2 = otherEntity.GetFieldValue("fieldname")
value = fieldvalue2.GetValue()
Wie im obigen Beispiel gezeigt muss für den Zugriff auf ein Entity-Objekt, das nicht das implizite Entity-Objekt eines VBScript-Hooks ist, dieses Entity-Objekt zuerst abgerufen werden. Außerhalb eines Hooks müssen Sie das Entity-Objekt, mit dem Sie arbeiten möchten, stets abrufen.