Showing changes to an Entity (record) object
The following example illustrates how to use the Rational® ClearQuest® API to get information about field values before and after the user has updated a record. This example is structured as a global hook that can be called from any other hook, such as from the ACTION_COMMIT hook.
VBScript
REM Start of Global Script ShowOldNewValues
REM TODO -- put your script code here
Sub ShowOldNewValues (actionname, hookname)
Dim fieldnames
Dim FN
Dim OldFV
Dim FieldValueStatus
Dim FieldInfo
Dim i
Dim NewFV
Dim FieldType
Dim is_short
M = "'" & actionname & "' action's " & hookname & " script (VB" & _
"version):" & VBCrLf & VBCrLf
' Get a list of the fields in this record type...
fieldnames = GetFieldNames
' Loop through the fields, showing name, type, old/new value...
if IsArray(fieldnames) Then
i = LBound(fieldnames)
Do While i <= UBound(fieldnames)
FN = fieldnames(i)
M = M & FN & ":"
' Get the field's original value...
set FieldInfo = GetFieldOriginalValue(FN)
FieldValueStatus = FieldInfo.GetValueStatus()
If FieldValueStatus = AD_HAS_NO_VALUE Then
OldFV = "<no value>"
ElseIf FieldValueStatus = AD_VALUE_NOT_AVAILABLE Then
OldFV = "<value not available>"
ElseIf FieldValueStatus = AD_HAS_VALUE Then
OldFV = FieldInfo.GetValue()
Else
OldFV = "<Invalid value status: " & FieldValueStatus & ">"
End If
' Get the current value (it may have been updated during
' this action)...
set FieldInfo = GetFieldValue(FN)
FieldValueStatus = FieldInfo.GetValueStatus()
If FieldValueStatus = AD_HAS_NO_VALUE Then
NewFV = "<no value>"
ElseIf FieldValueStatus = AD_VALUE_NOT_AVAILABLE Then
NewFV = "<value not available>"
ElseIf FieldValueStatus = AD_HAS_VALUE Then
NewFV = FieldInfo.GetValue()
Else
NewFV = "<Invalid value status: " & FieldValueStatus & ">"
End If
' Get and reformat the field's type...
FieldType = FieldInfo.GetType()
is_short = 1
If FieldType = AD_SHORT_STRING Then
FieldType = "Short String"
ElseIf FieldType = AD_MULTILINE_STRING Then
FieldType = "Multiline String"
is_short = 0
ElseIf FieldType = AD_INT Then
FieldType = "Integer"
ElseIf FieldType = AD_DATE_TIME Then
FieldType = "Date time"
ElseIf FieldType = AD_REFERENCE Then
FieldType = "Reference"
ElseIf FieldType = AD_REFERENCE_LIST Then
FieldType = "Reference List"
is_short = 0
ElseIf FieldType = AD_ATTACHMENT_LIST Then
FieldType = "Attachment List"
is_short = 0
ElseIf FieldType = AD_ID Then
FieldType = "ID"
ElseIf FieldType = AD_STATE Then
FieldType = "State"
ElseIf FieldType = AD_JOURNAL Then
FieldType = "Journal"
is_short = 0
ElseIf FieldType = AD_DBID Then
FieldType = "DBID"
ElseIf FieldType = AD_STATETYPE Then
FieldType = "STATETYPE"
ElseIf FieldType = AD_RECORDTYPE Then
FieldType = "RECORDTYPE"
Else
FieldType = "<UNKNOWN TYPE: " & FieldType & ">"
is_short = 0
End IF
M = M & " Type=" & FieldType & "."
' Display the results. For the purposes of this example,
' the following values are shown:
' 1. Identify whether the field's value has changed or
' not during the current action and indicate that in
' the output.
' 2. For single-line fields (integer, short_string, etc.)
' show the field's value.
' 3. For single-line fields whose values have changed
' during the current action, show the old and the new
' values.
If OldFV = NewFV Then
M = M & " Value is unchanged."
If is_short = 1 Then
M = M & " Value='" & OldFV & "'"
End If
Else
M = M & " Value has changed."
If is_short = 1 Then
M = M & " Old value='" & OldFV & "' New value='" & _
NewFV & "'"
End If
End If
M = M & VBCrLf
i = i + 1
Loop
Else
M = M & "fieldnames is not an array" & VBCrLf
End If
' At this point you could write this information to a file,
' present it in a message box, or write it to the debug window
' using the session.OutputDebugString() method. Here, is used
' the Windows 'MsgBox' API to present the results to the user
' in a message box (note this only works for the first 1024
' characters of "M" due to limitations in the Windows MsgBox
' API...)
MsgBox M
End Sub
REM End of Global Script ShowOldNewValues Perl
# Start of Global Script ShowOldNewValues
# ShowOldNewValues: Show field values in the current
# record, drawing attention to fields whose values have changed
# during the current action.
sub ShowOldNewValues {
# $actionname as string
# $hookname as string
my($actionname, $hookname) = @_;
my($M) = "'".$actionname."' action's ".$hookname." script (Perl
version):\n\n";
# Get a list of the fields in this record type
# (NOTE: GetFieldNames() returns a *REFERENCE* to an array)...
my($FieldNamesRef) = $entity->GetFieldNames();
# Loop through the fields, showing name, type, old/new value...
foreach $FN (@$FieldNamesRef) {
$M .= $FN . ":"; # Show the field name...
# Get the field's original value...
$FieldInfo = $entity->GetFieldOriginalValue($FN);
$FieldValueStatus = $FieldInfo->GetValueStatus();
if ($FieldValueStatus == $CQPerlExt::CQ_HAS_NO_VALUE) {
$OldFV = "<no value>";
} elsif ($FieldValueStatus ==
$CQPerlExt::CQ_VALUE_NOT_AVAILABLE) {
$OldFV = "<value not available>";
} elsif ($FieldValueStatus == $CQPerlExt::CQ_HAS_VALUE) {
$OldFV = $FieldInfo->GetValue();
} else {
$OldFV = "<Invalid value status:
" . $FieldValueStatus . ">";
}
# Get the current value (may have been updated during this
# action)...
$FieldInfo = $entity->GetFieldValue($FN);
$FieldValueStatus = $FieldInfo->GetValueStatus();
if ($FieldValueStatus == $CQPerlExt::CQ_HAS_NO_VALUE) {
$NewFV = "<no value>";
} elsif ($FieldValueStatus ==
$CQPerlExt::CQ_VALUE_NOT_AVAILABLE) {
$NewFV = "<value not available>";
} elsif ($FieldValueStatus == $CQPerlExt::CQ_HAS_VALUE) {
$NewFV = $FieldInfo->GetValue();
} else {
$NewFV = "<Invalid value status:
" . $FieldValueStatus . ">";
}
# Get and reformat the field's type...
$FieldType = $FieldInfo->GetType();
$is_short = 1;
if ($FieldType == $CQPerlExt::CQ_SHORT_STRING) {
$FieldType = "Short String";
} elsif ($FieldType == $CQPerlExt::CQ_MULTILINE_STRING) {
$FieldType = "Multiline String";
$is_short = 0;
} elsif ($FieldType == $CQPerlExt::CQ_INT) {
$FieldType = "Integer";
} elsif ($FieldType == $CQPerlExt::CQ_DATE_TIME) {
$FieldType = "Date Time";
} elsif ($FieldType == $CQPerlExt::CQ_REFERENCE) {
$FieldType = "Reference";
} elsif ($FieldType == $CQPerlExt::CQ_REFERENCE_LIST) {
$FieldType = "Reference List";
$is_short = 0;
} elsif ($FieldType == $CQPerlExt::CQ_ATTACHMENT_LIST) {
$FieldType = "Attachment List";
$is_short = 0;
} elsif ($FieldType == $CQPerlExt::CQ_ID) {
$FieldType = "ID";
} elsif ($FieldType == $CQPerlExt::CQ_STATE) {
$FieldType = "State";
} elsif ($FieldType == $CQPerlExt::CQ_JOURNAL) {
$FieldType = "Journal";
$is_short = 0;
} elsif ($FieldType == $CQPerlExt::CQ_DBID) {
$FieldType = "DBID";
} elsif ($FieldType == $CQPerlExt::CQ_STATETYPE) {
$FieldType = "STATETYPE";
} elsif ($FieldType == $CQPerlExt::CQ_RECORDTYPE) {
$FieldType = "RECORDTYPE";
} else {
$FieldType = "<UNKNOWN TYPE: " . $FieldType . ">";
$is_short = 0;
}
$M .= " Type=" . $FieldType . ".";
# Display the results. For the purposes of this example, we
# show values as follows:
# 1. Identify whether the field's value has changed or not
# during the current action and indicate that in the
# output.
# 2. For single-line fields (integer, short_string, etc.)
# show the field's value.
# 3. For single-line fields whose values have changed during
# the current action, show the old and the new values.
if ($OldFV eq $NewFV) {
$M .= " Value is unchanged.";
if ($is_short) {
$M .= " Value='".$OldFV."'";
}
} else {
$M .= " Value has changed.";
if ($is_short) {
$M .= " Old value='".$OldFV."' New
value='".$NewFV."'";
}
}
$M .= "\n";
}
$M .= "\n'".$actionname."' action's notification script
(Perl version) exiting.\n";
# At this point you could write this information to a file,
# present it in a message box, or write it to the debug window
# using $session->OutputDebugString().
# Here is called a subroutine 'DBGOUT' which writes the message
# out to a file and invokes 'Notepad' on it...
DBGOUT($M);
}
# End of Global Script ShowOldNewValues
# Start of Global Script DBGOUT
sub DBGOUT {
my($Msg) = shift;
my($FN) = $ENV{'TEMP'}.'\STDOUT.txt';
open(DBG, ">>$FN") || die "Failed to open $FN";
print DBG ($Msg);
close(DBG);
system("notepad $FN");
system("del $FN");
}
# End of Global Script DBGOUT