All'interno di un hook VBScript, IBM® Rational ClearQuest fornisce un oggetto Entity implicito che rappresenta il record di dati corrente. Se un hook VBScript richiama un metodo Entity senza fornire un identificativo principale, IBM Rational ClearQuest utilizza automaticamente tale questo oggetto Entity implicito. Inoltre, le funzioni hook Rational ClearQuest definiscono una variabile "entità" esplicita, da utilizzare se si desidera specificare l'oggetto al quale si fa riferimento. Il nome della variabile entità è uguale al nome del tipo di record. Se si sta accedendo all'API dall'esterno di una funzione hook, o se si sta accedendo ad un oggetto Entity diverso da quello implicito, è necessario specificare esplicitamente l'altro oggetto Entity. (Inoltre, se si sta utilizzando Perl, è necessario fornire sempre una variabile esplicita il cui nome è "entità". Consultare GetSession per i dettagli.)
I seguenti esempi mostrano due modi per richiamare lo stesso metodo in una funzione hook VBScript. Nel secondo esempio, il valore, defect, rappresenta l'oggetto entità corrente (tipo di record).
fieldvalue = GetFieldValue("fieldname").GetValue()
fieldvalue = defect.GetFieldValue("fieldname").GetValue()
L'oggetto Session fornisce due metodi per ottenere un'entità: BuildEntity (per creare un nuovo record) o GetEntity (per un record esistente). Quando viene inoltrato un nuovo record, BuildEntity ottiene automaticamente l'entità. Per ottenere un record esistente, si trasmette al metodo GetEntity l'unico identificativo del record e il nome del tipo di record.
L'oggetto Entity viene identificato utilizzando il nome di visualizzazione del tipo di record corrispondente. Per tipi di record stateless, i singoli record vengono identificati utilizzando il contenuto dell'unico campo chiave del tipo di record. Per tipi di record basati sullo stato, i record vengono identificati utilizzando l'ID visibile del record. IBM Rational ClearQuest assegna ad ogni nuovo record una stringa ID visibile composta dal nome del database logico e un numero consecutivo univoco. Ad esempio, il decimo record nel database "BUGID" può disporre dell'ID visibile "BUGID00000010".
Il seguente esempio di VBScript proviene da una funzione hook che ha effettuato l'accesso a due oggetti entità: l'oggetto implicito e un oggetto duplicato. L'oggetto duplicato corrisponde al record il quale ID è "BUGID00000031".
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()
Come mostrato nell'esempio precedente, per accedere ad un oggetto Entity diverso da quello implicito da una funzione hook VBScript, è necessario acquisire prima tale oggetto Entity. Dall'esterno di una funzione hook, è necessario sempre acquisire l'oggetto Entity che si intende gestire.