Generating UCM Baseline Reports

So far, all the examples have made use of Base ClearCase labels. If you are using UCM, the examples are still relevant for any fully labeled UCM baselines you have created. This is possible because fully labeled UCM baselines are also exposed as Base ClearCase labels. However, you can use a number of additional capabilities to report on UCM baselines that display information not only about element versions but also about the UCM activities that have been worked on.

Using the ClearCase Command Line

A number of additional cleartool commands that are available solely for UCM can help you with your reporting. For example, to display information about a specific baseline, you can use the cleartool lsbl command:

>cleartool lsbl -l RATLBANK_01_INT@\RationalProjects baseline "RATLBANK_01_INT"  11-Jan-06.20:56:58 by alex   stream: RatlBank_Int@\RationalProjects   owner: alex   group: ccase_users   component: RationalBank@\RationalProjects   label status: Fully Labeled   change sets:     RBPRO00000030@\RationalProjects     RBPRO00000031@\RationalProjects     RBPRO00000032@\RationalProjects     RBPRO00000038@\RationalProjects   promotion level: INITIAL   depends on:

In this example, a wealth of information is displayed about the particular baseline, including when it was created, by whom, and what type of baseline it is: fully labeled or incremental. Of more interest is the section on change sets. This is the collection of UCM activities that have contributed to this baseline's content; in this case, they refer to ClearQuest records. To find out more about the exact set of element versions in each of these activities, you can use the cleartool lsactivity command:

>cleartool lsactivity -l RBPRO00000038@\RationalProjects activity "RBPRO00000038"  02-Jan-06.17:01:39 by alex   "Created automatically as a result of 'Work On' action in    ClearQuest"   owner: alex   group: ccase_users   stream: RatlBank_Int@\RationalProjects   title: Implement transfer result page   change set versions: C:\Views\RatlBank_bld\RatlBank\WebContent\WEB-INF\faces-config.xml@@\main\RatlBank_Int\6 C:\Views\RatlBank_bld\RatlBank\JavaSource\pagecode\TransferResult.java@@\main\RatlBank_Int\2 C:\Views\RatlBank_bld\RatlBank\WebContent\transferResult.jsp@@\main\RatlBank_Int\3

Note that to retrieve change set versions, the command needs to have been executed from within a view.

As you can see, this gives you all the information you need about any activity, including the element versions captured by its change set. Unfortunately, though, to find out this information, two commands were required. What is needed is a way to script this process so that for each activity within a baseline, the change set versions can be found. Again, Perl can be used to automate this process.

Using Perl

In Listing 8.1, a batch file was created to work out the difference between two Base ClearCase labels. UCM uses the cleartool diffbl command to achieve this. Here's an example:

[View full width]
>cleartool diffbl -act -ver RATLBANK_01_INT@\RationalProjects RATLBANK_02_INT@\ RationalProjects -> RBPRO00000033 "Java Server Faces Refactoring" C:\Views\RatlBank_bld\RatlBank\WebContent\WEB-INF\faces-config.xml@@\main\RatlBank_Int\6 ... -> RBPRO00000038 "Implement transfer result page " C:\Views\RatlBank_V1_bld\RationalBank\WebContent\transferResult.jsp@@\main\RatlBank_Int\2  ...

In this example the baselines RATLBANK_01_INT and RATLBANK_02_INT are compared, and the list of activities (via the -act option) and activity versions (via the -ver option) are displayed.

If you want to compare a baseline with its immediate predecessor (which can be useful for reporting on regular builds), you can specify just a single baseline and the -pred option. Listing 8.3 shows how you can report on what has changed between two baselines using Perl.

Listing 8.3. Perl diffbl_report.pl File

[View full width]

my $debug = 0; my $CLEARTOOL_CMD = "cleartool"; '$CLEARTOOL_CMD pwv' or die "Error: can't find cleartool command: $!\n"; my $blid = $ARGV[0]; if ($blid eq "") {     die("Error: invalid baseline specification.\n"); } print "CLEARCASE BASELINE REPORT\n\n"; # print information on the baseline print cleartool_exec("lsbl -fmt \"Baseline: %n \\n created: %Sd \\n by: %u \\n status:  %[locked]p \\n level: %[plevel]p \\n\" $blid"); # print information on the baselines activities and versions print "\n\nACTIVITIES CHANGED BETWEEN $blid AND ITS PREDECESSOR:\n\n"; # get list of changed/new activities my @activities = cleartool_exec("diffbl -pred -act $blid"); foreach $act (@activities) {     # tidy up activity name     chomp($act);     $act =~ s{-> }{}g; $act =~ s{>> }{}g;     # set activity id and title     ($act_id, $act_title) = split / "/, $act;     $act_title =~ s{\"}{}g;     # get the type of the activity     my $act_type = cleartool_exec("describe -fmt\"%[crm_record_type]p\"activity:$act_id");     # get the change set for the activity     my @versions = split /, /, cleartool_exec("lsactivity -fmt\"%[versions]Cp\" $act_id");     $act =~ s{@.*}{}g; # remove Project VOB postfix     print "$act_id - $act_title ($act_type)\n";     foreach $ver (@versions) {         print "\t$ver\n";     }     print "\n"; } sub cleartool_exec {     print "[DEBUG] Executing cleartool @_\n" if $debug;     return '$CLEARTOOL_CMD @_' or die("Error failed to execute cleartool@_: $!\n"); } exit(0);

In this example, information about the UCM baselines is displayed first. To work out the activities and versions, the baseline passed to the script is compared to its immediate predecessor using the cleartool diffbl -pred command. For each activity, its change set, in terms of element versions, is retrieved using the cleartool lsactivity -fmt command. If you executed this script, you would see output similar to the following:

>ratlperl diffbl_report.pl RATLBANK_01_INT@\RationalProjects CLEARCASE BASELINE REPORT Baseline: RATLBANK_01_INT  created: 11-Jan-06  by: alex  status: locked  level: INITIAL ACTIVITIES CHANGED BETWEEN RATLBANK_01_INT AND ITS PREDECESSOR: RBPRO00000033 - Java Server Faces Refactoring (EnhancementRequest)     C:\Views\RatlBank_bld\RatlBank\WebContent\WEB-INF\faces-config.xml@@\main\RatlBank_Int\6     ... RBPRO00000038 - Implement transfer result page (Defect)     C:\Views\RatlBank_V1_bld\RationalBank\WebContent\transferResult.jsp@@\main\RatlBank_Int\2 ...

Notice how the display of information is more readable and that additional information is displayed about the baseline (such as its status and promotion level) and the activities (such as their type).

ClearCase Perl Module (CtCmd)

ClearCase::CtCmd is a Perl extension module that takes cleartool-like arguments. It gives your Perl scripts direct access to ClearCase commands and allows for better error handling and control. The core of this module is essentially a single exec function (that can be used in different contexts, performing either a single or multiple operations). This function takes a string or array containing the command to execute and returns a three-element Perl array:

[View full width]
use ClearCase::CtCmd; my $inst = ClearCase::CtCmd->new(); my $pvob="\@\\RationalProjects"; # describe a baseline ($status, $output, $err) = $inst->exec(lsbl, -fmt, "Name: %n,  Created: %Sd\n", "RATLBANK_01_INT".$pvob); print $output; # try an invalid baseline ($status, $output, $err) = $inst->exec(lsbl, -fmt, "Name: %n,  Created: %Sd\n", "NO_SUCH_BASELINE".$pvob); die $err if $inst->status();

The array that is returned contains a status bit (with a value of 0 on success or 1 on failure), a scalar string corresponding to stdout, and any error message corresponding to stderr.

The main advantages of CtCmd are that it allows easier parsing of the return data from the cleartool command line, allowing the script author to work at a higher level, and that it keeps an "open" cleartool session. Therefore, if you execute multiple cleartool commands in your script, you should find that using this module works faster than calling the commands individually yourself.

The main disadvantage of CtCmd is that it does not ship with ClearCase, so you have to download the module and recompile your Perl installation to use it. This is not a trivial exercise, especially on Windows. I recommend that you attempt this only if you have gained some Perl experience. The module and its documentation are available at http://search.cpan.org/~ratl/CtCmd-1.04/CtCmd.pm.