C.4 Report Programming Examples

All report procedures supplied with ClearCase Reports are written in ccperl. The programming examples presented in this section are modifications of these report procedures. Report procedures can be written in many other scripts and programming languages; report procedures that use other programming languages are available from the ClearCase Customer Web site at http://www.rational.com/support/downloadcenter/addins/clearcase/contrib/index.jsp in the T0046 package. The following programming examples are presented in this section:

• Example 1: Adding a new column to the report for Versions_byDate.prl.

• Example 2: Changing the directory organization and report description, modifying the version path to a use different field name, and adding an element type column to report output for Elements_with_New_Versions_Since_Date.prl.

• Example 3: Changing the report description, parameter types, and report output for Elements_Created_by_User.prl.

• Example 4: Changing the order of commands and adding a command to the shortcut menu for Element_with_Labels.prl.

• Example 5: Adding a user-defined command to the shortcut menu for Element_with_Branches.prl.

In the source code listings that accompany each example, the string ### customization change marks the changes to the original report that accomplish the task.

Example 1: Adding a Column to Report Output

The Versions by Date report lists all versions that exist for the pathname that the user specified. This report includes the following columns:

• Version Path

• Version Creation Time

The change to this report adds a column that lists the user name associated with each version. The report procedure is located in ccase-home-dir\Reports\Scripts\Elements\Versions_by_Date.prl

Processing Logic

The processing logic of Versions_by_Date.prl is as follows:

1. The LOOKIN parameter, which is the sole parameter for this function, is received in a string of this form:

LOOKIN = "<path1> [<path2> ...]"

This parameter specifies the list of paths with which the cleartool find command is to be invoked.

2. The routine, when invoked, extracts the paths from the LOOKIN string and passes them to the check_lookin() routine (located in common_script.prl).

3. check_lookin() then puts the paths into the global variable $ctfind_paths, enclosing each path in double quotes; it also performs simple validations on the paths received.

4. The report procedure calls cleartool lshistory, passing $ctfind_paths as the paths parameter, and with a -fmt parameter to return the necessary information.

5. The report procedure executes a print statement with parameters (that is, the items to print) of the same number and order as the list passed during interface specification processing. The Report Builder has the information required to set up the column headings; the report procedure must conform to this specification to print its output.

Interface Specification

This is the existing interface specification for Versions_by_Date.prl:

if (/^-i/) {
print "description : 'Versions by Date'\n";
print "id : 2018\n";
print "helpfile :\n";
print "parameters : ";
print "LOOKIN ";
print "\n";
print_version_rightclick();
print "fields : ";
print "\"Version Path\"(version_xpn, rightclick, sort 2) ";
print "\"Version Creation Time\"(cctime) ";
print "\"Version Creation Time\"(time_t, sort 1, hidden) ";
print "\n";
exit(0);
}

Changes Required

To add an additional column of report output:

1. Add a properly coded print statement to the interface specification that the Report Builder can pass to the Report Viewer.

2. Add a %Fu; to the -fmt parameter in the cleartool lshist call, to get this information from ClearCase.

3. Properly extract the user information into some variable after the cleartool lshist call returns its output, so that it can be printed.

4. Print the user variable in the same order as it appeared in the interface specification so that it appears under the correct column heading.

Modified Report Procedure

Here is the modified version of Versions_by_Date.prl. This report procedure is example1.prl in the T0046 package, which is available at http://www.rational.com/support/downloadcenter/addins/clearcase/contrib/index.jsp.

$start_dir = $0; $start_dir =~ s/\\scripts\\.*/\\scripts/;
$common_dir = $start_dir;
$common_dir =~ s/(.*)\\scripts/$1\\script_tools/;

$cc = ""; if ($cc) {;};
$ct = ""; if ($ct) {;};
$debug = ""; if ($debug) {;};
$skip_path_checks = ""; if ($skip_path_checks) {;};
$CLEARCASE_XN_SFX = ""; if ($CLEARCASE_XN_SFX) {;};
$ctfind_paths = ""; if ($ctfind_paths) {;};
$skip_path_checks = "yes"; if ($skip_path_checks) {;};
$debug = "no"; if ($debug) {;};

sub do_exit {
$err = join(" ", @_);
if ("$err" != "") {
print STDERR "$err\n";
}
sleep(2);
if ("$err" != "") {
exit(1);
} else {
exit(0);
}
}

open(INCLUDE, "<$common_dir\\common_script.prl") or do_exit("error opening include file '$common_dir\\common.prl'");
$buf = "";
while(<INCLUDE>) {
$buf = $buf . $_;
}
close(INCLUDE);
eval $buf || do_exit("error on eval of include file '$common_dir\\common.prl'");

my $args = $ARGV[0];
$args =~ s/%/ /g;
@args = split(";", $args);
$required_args = 0;
foreach(@args) {

s/^[ ]+//;
s/[ ]+$//;
validate_arg_length($_);
if (/^-i/) {
print "description : 'Versions by Date'\n";
print "id : 2018\n";
print "helpfile :\n";
print "parameters : ";
print "LOOKIN ";
print "\n";
print_version_rightclick();
print "fields : ";
print "\"Version Path\"(version_xpn, rightclick, sort 2) ";
print "\"Version Creation Time\"(cctime) ";
print "\"Version Creation Time\"(time_t, sort 1, hidden) ";
### customization change *** added following line
print "\"User'(user) ";
print "\n";
exit(0);
}
if (/^LOOKIN[ ]*=[ ]*('.*')/) {
check_lookin($1);
$required_args++;
next;
}
print STDERR "unrecognized argument: $_\n";
print STDERR " ccperl $0 -i\n";
print STDERR " for script's interface.\n";
do_exit("\n");
}
if ($required_args != 1) {
print STDERR "usage: not all required arguments specified.\n";
print STDERR " ccperl $0 -i\n";
print STDERR " for script's interface.\n";
do_exit("\n");
}
$ENV{"d;"} = "d;";
open(CTHIST, "cleartool lshist -fmt '%d;%e;%n\\n' -recurse -nco $ctfind_paths |");
while(<CTHIST>) {
chomp;
if (/create directory version/ || /create version/) {
($date, $event, $xpn) = split /;/, $_, 3;
if ($date) {;}
if ($event) {;}
if ($xpn) {;}
$timet = time_to_ticks($date);
### customization change *** added following line
$user = `cleartool desc -fmt '%Fu' '$xpn'`;
### customization change *** added ";$user" to following line
print "$xpn;$date;$timet;$user\n";
}
}
do_exit();

Example 2: Changing Report Directory Organization, Report Description, and Report Output

The Elements with New Versions Since Date report lists all new versions for the pathname and since the date and time specified by the user. This report includes the following columns:

• Element Path

• Version Path

• Version Creation Time

The changes to the report procedure do the following:

• Display in the Report Builder tree pane a new directory named ccase-home-dir\Reports\Scripts\Elements\New_Versions directory.

• Display a new report description: Types of Elements with New Versions Since Date.

• Display the version path information in the version_xpn field in a different format.

• Add a column in the report output to display a new column for Element Type.

The report procedure is located in ccase-home-dir\Reports\Scripts\Elements\Elements_with_New_Versions_Since_Date.prl.

Processing Logic

The processing logic of Elements_with_New_Versions_Since_Date.prl is as follows:

1. When the Report Builder processes the interface specification, the report procedure yields two parameters:

LOOKIN

CCTIME

The mechanics of the LOOKIN parameter are described in Example 1: Adding a Column to Report Output. When the report procedure receives CCTIME, it is a string of this form:

CCTIME = "time"

This parameter specifies the times that the cleartool find command uses.

2. When the report procedure is invoked by the Report Viewer using a fully qualified command line, it extracts the values from the CCTIME string and passes them to the chooser_time_to_cctime() subroutine (located in common.prl). This routine converts the string to the correct format (for passing to cleartool) and returns it.

3. The report procedure opens a pipe from a cleartool find -print command, with the converted cctime value passed in as a created_since(<cctime>) string. created_since is a query_language(1) predicate, which is frequently used in conjunction with the find command.

4. As the values from the cleartool find are returned, the report procedure calls cleartool describe on the output to get the version-creation time. The routine calls the time_to_ticks() routine (in common.prl) to get the time equivalent in ticks.

5. The report procedure gets the path and version ID from the cleartool find output, splitting it on the value of the $CLEARCASE_XN_SFX extended naming symbol for the host. Finally, the report procedure prints the information in the same order as defined in the interface specification.

Interface Specification

This is the existing interface specification for Elements_with_New_Versions_Since_Date.prl:

if (/^-i/) {
print "description : 'Elements with New Versions Since Date'\n";
print "id : 2017\n";
print "helpfile :\n";
print "parameters : ";
print "LOOKIN CCTIME";
print "\n";
print_element_rightclick();
print "fields : ";
print "\"Element Path\"(element_pn, sort 2, rightclick) ";
print "\"Version Path\"(version_pn) ";
print "\"Version Creation Time\"(cctime) ";
print "\"Version Creation Time\"(time_t, hidden, sort 1) ";
print "\n";
exit(0);
}

Changes Required

To change the directory organization and report description, to modify the version path to use a different field name, and to add an element type column to the report output:

1. Create a new folder, New_Versions, and move the report procedure there.

2. Add a properly coded print statement to the interface specification that does the following:

• Specifies how to display the report description information in the Report Builder

• Specifies how to display the report in the Report Viewer

3. Add additional processing to the cleartool find output as required to get the desired information for element type.

4. Properly extract the new information for element type into a variable.

5. Print the new information in the proper position so that it appears under the correct column heading.

Modified Report Procedure

Here is the modified version of Elements_with_New_Versions_Since_Date.prl. This report procedure is example2.prl in the T0046 package, which is available at http://www.rational.com/support/downloadcenter/addins/clearcase/contrib/index.jsp.

$start_dir = $0; $start_dir =~ s/\\scripts\\.*/\\scripts/;
$common_dir = $start_dir;
$common_dir =~ s/(.*)\\scripts/$1\\script_tools/;

$cc = ""; if ($cc) {;};
$ct = ""; if ($ct) {;};
$debug = ""; if ($debug) {;};
$skip_path_checks = ""; if ($skip_path_checks) {;};
$CLEARCASE_XN_SFX = ""; if ($CLEARCASE_XN_SFX) {;};
$ctfind_paths = ""; if ($ctfind_paths) {;};
$skip_path_checks = "yes"; if ($skip_path_checks) {;};
$debug = "no"; if ($debug) {;};

sub do_exit {
$err = join(" ", @_);
if ("$err" != "") {
print STDERR "$err\n";
}
sleep(2);
if ("$err" != "") {
exit(1);
} else {
exit(0);
}
}
open(INCLUDE, "<$common_dir\\common_script.prl") or do_exit("error opening include file '$common_dir\\common.prl'");
$buf = "";
while(<INCLUDE>) {
$buf = $buf . $_;
}
close(INCLUDE);
eval $buf || do_exit("error on eval of include file '$common_dir\\common.prl'");

my $args = $ARGV[0];
$args =~ s/%/ /g;
@args = split(";", $args);
my $cctime = "";
$required_args = 0;
foreach(@args) {

s/^[ ]+//;
s/[ ]+$//;
validate_arg_length($_);
if (/^-i/) {
### customization change *** changed following line
print "description : 'Types of Elements with New Versions Since
Date'\n";
print "id : 2017\n";
print "helpfile :\n";
print "parameters : ";
print "LOOKIN CCTIME";
print "\n";
print_element_rightclick();
print "fields : ";
print "\"Element Path\"(element_pn, sort 2, rightclick) ";
### customization change *** changed following line
print "\"Version Path\"(version_xpn) ";
print "\"Version Creation Time\"(cctime) ";
print "\"Version Creation Time\"(time_t, hidden, sort 1) ";
### customization change *** added following line
print "\"Element Type\"(eltype) ";
print "\n";
exit(0);
}
if (/^LOOKIN[ ]*=[ ]*('.*')/) {
check_lookin($1);
$required_args++;
next;
}
if (/^CCTIME[ ]*=[ ]*'*([^']*)'*/) {
$cctime = chooser_time_to_cctime($1);
$required_args++;
next;
}
print STDERR "unrecognized argument: $_\n";
print STDERR " ccperl $0 -i\n";
print STDERR " for script's interface.\n";
do_exit("\n");
}
if ($required_args != 2) {
print STDERR "usage: not all required arguments specified.\n";
print STDERR " ccperl $0 -i\n";
print STDERR " for script's interface.\n";
do_exit("\n");
}
open(CTFIND, "cleartool find $ctfind_paths -version 'created_since($cctime)' -print |");
while(<CTFIND>) {
chomp;
if (/CHECKEDOUT/) {next;}
$vertime = `cleartool desc -fmt '%d' '$_'`;
### customization change *** added following line
$eltype = `cleartool desc -fmt '%[type]p' '$_'`;
$vertime_t = time_to_ticks($vertime);
($path, $verid) = split $CLEARCASE_XN_SFX, $_, 2;
### customization change *** changed following line
print "$_;$verid;$vertime;$vertime_t;$eltype\n";
#print "$path;$verid;$vertime;$vertime_t\n";
}
do_exit();

Example 3: Changing Report Description, Parameter Types, and Report Output

The Elements Created by User report lists all elements created by the user-defined user name. This report includes the following columns:

• Element Path

• Creating User

The changes to this report do the following:

• Display a new report description: Elements with Group.

• Remove the existing user parameter and add a new parameters for group.

• Compare the group associated with an element with the group specified in a user-defined group parameter.

• Add a column in the report output for Group and Yes/No. The Yes/No column will reflect the result of the comparing whether the group associated with each element is the same as the value of the user-defined group parameter.

The script is located in ccase-home-dir\Reports\Scripts\Elements\Elements_Created_by_User.prl.

Processing Logic

The processing logic of Elements_Created_by_User.prl is as follows:

1. When the Report Builder processes the interface specification, the report procedure yields two parameters:

LOOKIN

USER

The mechanics of the LOOKIN parameter are described in Example 1: Adding a Column to Report Output. The report procedure receives USER as a string of this form:

USER= "user-name"

This parameter specifies the user name that the cleartool subcommand uses.

2. The USER string is extracted and stored as $ccuser. It is then passed to the created_by($ccuser).

3. The created_by ($ccuser) query language primitive filters the paths specified to cleartool find and returns only those that match the predicate, in this case, those created by the user by setting a parameter value for USER.

4. The user variable is printed in the same order specified in the interface specification so that it appears under the correct column heading.

Interface Specification

This is the existing interface specification for Elements_Created_by_User.prl:

if (/^-i/) {
print "description : 'Elements Created by User'\n";
print "id : 2016\n";
print "helpfile :\n";
print "parameters : ";
print "LOOKIN USER";
print "\n";
print_element_rightclick();
print "fields : ";
print "\"Element Path\"(element_xpn, sort 2, rightclick) ";
print "\"Creating User\"(user, sort 1) ";
print "\n";
exit(0);
}

Changes Required

To remove the user parameter, to add parameters for group and date/time, and to adjust the report output for group and date/time information:

1. Change the interface specification of the report procedure to correspond to required interface changes.

2. Change the logic in the report procedure to handle data requests for group information; add a %Gu; to the -fmt parameter in the cleartool describe call, to get group information from ClearCase.

3. Properly extract the group information into a variable after the cleartool describe call returns its output, so that it can be printed.

4. Determine whether the element's group is the same group parameter value entered by the user and print the result of this comparison as a column heading.

5. Print the group variables in the order specified in the interface specification so that they appear under the correct column heading.

Modified Report Procedure

Here is the modified version of Elements_Created_by_User.prl. This report procedure is example3.prl in the T0046 package, which is available at http://www.rational.com/support/downloadcenter/addins/clearcase/contrib/index.jsp.

$start_dir = $0; $start_dir =~ s/\\scripts\\.*/\\scripts/;
$common_dir = $start_dir;
$common_dir =~ s/(.*)\\scripts/$1\\script_tools/;

$cc = ""; if ($cc) {;};
$ct = ""; if ($ct) {;};
$debug = ""; if ($debug) {;};
$skip_path_checks = ""; if ($skip_path_checks) {;};
$CLEARCASE_XN_SFX = ""; if ($CLEARCASE_XN_SFX) {;};
$ctfind_paths = ""; if ($ctfind_paths) {;};
$skip_path_checks = "yes"; if ($skip_path_checks) {;};
$debug = "no"; if ($debug) {;};

sub do_exit {
$err = join(" ", @_);
if ("$err" != "") {
print STDERR "$err\n";
}
sleep(2);
if ("$err" != "") {
exit(1);
} else {
exit(0);
}
}
open(INCLUDE, "<$common_dir\\common_script.prl") or do_exit("error opening include file '$common_dir\\common.prl'");
$buf = "";
while(<INCLUDE>) {
$buf = $buf . $_;
}
close(INCLUDE);
eval $buf || do_exit("error on eval of include file '$common_dir\\common.prl'");

my $args = $ARGV[0];
$args =~ s/%/ /g;
@args = split(";", $args);
my $ccuser = "";
$required_args = 0;
foreach(@args) {

s/^[ ]+//;
s/[ ]+$//;
validate_arg_length($_);
if (/^-i/) {
### customization change *** changed following line
print "description : 'Elements With Group'\n";
print "id : 2016\n";
print "helpfile :\n";
print "parameters : ";
### customization change *** changed following line
print "LOOKIN GROUP";
print "\n";
print_element_rightclick();
print "fields : ";
print "\"Element Path\"(element_xpn, sort 2, rightclick) ";
### customization change *** added following 2 lines
print "\"Element's Group\"(group, sort 1) ";
print "\"Same\"(yes_no) ";
### customization change *** deleted following line
#print "\"Creating User\"(user, sort 1) ";
print "\n";
exit(0);
}
if (/^LOOKIN[ ]*=[ ]*('.*')/) {
check_lookin($1);
$required_args++;
next;
}
### customization change *** deleted following 2 lines
#if (/^USER[ ]*=[\t ]*\"*([^\"]*)\"*/) {
#$ccuser = $1;
### customization change *** added following 2 lines
if (/^GROUP[ ]*=[\t ]*\"*([^\"]*)\"*/) {
$ccgroup = $1;
$required_args++;
### customization change *** deleted following line
#validate_user($ccuser);
next;
}
print STDERR "unrecognized argument: $_\n";
print STDERR " ccperl $0 -i\n";
print STDERR " for script's interface.\n";
do_exit("\n");
}
if ($required_args != 2) {
print STDERR "usage: not all required arguments specified.\n";
print STDERR " ccperl $0 -i\n";
print STDERR " for script's interface.\n";
do_exit("\n");
}
### customization change *** deleted following 3 lines
#if ($ccuser =~ /[ ]+/) {
# do_clearprompt("cleartool find does not allow spaces in user names;
# cannot proceed.");
#}

### customization change *** changed following line
open(CTFIND, "cleartool find $ctfind_paths -nxname -print |");
while(<CTFIND>) {
chomp;
### customization change *** added following 6 lines
$grp = `cleartool desc -fmt '%Gu' '$_'`;
if ($grp eq $ccgroup) {
$same = "yes";
} else {
$same = "no";
}
### customization change *** changed following line
print "$_;$grp;$same\n";
#print "$_;$ccuser;\n";
}
do_exit();

Example 4: Changing the Shortcut Menu for the Right-Click Handling Mechanism

The Elements with Labels report lists all elements with labels for a user-defined pathname. This report includes one column:

• Element Path

The change to this report adds the Compare with Previous Version command to the shortcut menu. Currently, these commands appear on the shortcut menu:

• Properties of Element

• Version Tree

• History

The report procedure is located in ccase-home-dir\Reports\Scripts\Elements\Labels\Elements_with_Labels.prl.

Interface Specification

This is the existing interface specification for Elements_with_Labels.prl:

if (/^-i/) {
print "description : ";
print "'Elements with Labels'";
print "\n";
print "id : 2003\n";
print "helpfile :\n";
print "parameters : ";
print "LOOKIN ";
print "LABEL ";
print "\n";
print_element_rightclick();
print "fields : ";
print "\"Element Path\"(element_pn, rightclick, sort 1)";
print "\n";
exit(0);
}

Note the call to print_element_rightclick() in the middle of the interface specification. The code for this routine is located in\script_tools\common.prl:

sub print_element_rightclick {
print "rightclick : ";
print "Properties_of_Element(single) ";
print "sep ";
print "Version_Tree(single) ";
print "History(single) ";
print "\n";
}

Changes Required

A convention used in the report procedures is to put the same commands on shortcut menus for all reports that use the same primary sort field. For example, all the reports whose primary sort key is element or element_xpn display the same set of commands.

To make an additional command available for all reports whose primary sort key is element or element_xpn, modify the routines stored in \script_rightclick and then edit the associated routine in \script_tools\common.prl.

To change the report procedure, copy the contents of sub print_element_rightclick (located in \script_tools\common.prl) and paste it into the appropriate part of the interface specification. Then, add a declaration to display the new command.

Modified Report Procedure

Here is the modified version of Elements_with_Labels.prl. This report procedure is example4.prl in the T0046 package, which is available at http://www.rational.com/support/downloadcenter/addins/clearcase/contrib/index.jsp.

$start_dir = $0; $start_dir =~ s/\\scripts\\.*/\\scripts/;
$common_dir = $start_dir;
$common_dir =~ s/(.*)\\scripts/$1\\script_tools/;

$cc = ""; if ($cc) {;};
$ct = ""; if ($ct) {;};
$debug = ""; if ($debug) {;};
$skip_path_checks = ""; if ($skip_path_checks) {;};
$CLEARCASE_XN_SFX = ""; if ($CLEARCASE_XN_SFX) {;};
$ctfind_paths = ""; if ($ctfind_paths) {;};
$skip_path_checks = "yes"; if ($skip_path_checks) {;};
$debug = "no"; if ($debug) {;};

sub do_exit {
$err = join(" ", @_);
if ("$err" != "") {
print STDERR "$err\n";
}
sleep(2);
if ("$err" != "") {
exit(1);
} else {
exit(0);
}
}
open(INCLUDE, "<$common_dir\\common_script.prl") or do_exit("error opening include file '$common_dir\\common.prl'");
$buf = "";
while(<INCLUDE>) {
$buf = $buf . $_;
}
close(INCLUDE);
eval $buf || do_exit("error on eval of include file '$common_dir\\common.prl'");

my $args = $ARGV[0];
$args =~ s/%/ /g;
@args = split(";", $args);
my $cclabel = "";
$required_args = 0;
foreach(@args) {
s/^[ ]+//;
s/[ ]+$//;
validate_arg_length($_);
if (/^-i/) {
print "description : ";
print "'Elements with Labels'";
print "\n";
print "id : 2003\n";
print "helpfile :\n";
print "parameters : ";
print "LOOKIN ";
print "LABEL ";
print "\n";
### customization change *** deleted following line
#print_element_rightclick();
### customization change *** added following 7 lines
print "rightclick : ";
print "Properties_of_Element(single) ";
print "sep ";
print "Compare_with_Previous_Version(single) ";
print "Version_Tree(single) ";
print "History(single) ";
print "\n";
print "fields : ";
print "\"Element Path\"(element_pn, rightclick, sort 1)";
print "\n";
exit(0);
}
if (/^LOOKIN[ ]*=[ ]*('.*')/) {
#print "paths are $1\n";
check_lookin($1);
$required_args++;
next;
}
if (/^LABEL[ ]*=[ ]*'*([^']*)'*/) {
$cclabel = $1;
#print "label is $cclabel\n";
$required_args++;
next;
}
print STDERR "unrecognized argument: $_\n";
print STDERR " ccperl $0 -i\n";
print STDERR " for script's interface.\n";
do_exit("\n");
}
if ($required_args != 2) {
print STDERR "usage: not all required arguments specified.\n";
print STDERR " ccperl $0 -i\n";
print STDERR " for script's interface.\n";
do_exit("\n");

}
open(CTFIND, "cleartool find $ctfind_paths -element 'lbtype_sub($cclabel)' -print |");
while(<CTFIND>) {
chomp;
($path, $rest) = split $CLEARCASE_XN_SFX, $_, 2;
if ($rest) {;}
print "$path;\n";
}
do_exit();

Example 5: Adding a New Command to the Report Viewer Shortcut Menu

The Elements with Branches report lists all elements associated with a branch and pathname that the user provides. This report includes the following columns:

• Element Path

• Branch

The report procedure is located in ccase-home-dir\Reports\Scripts\Elements\Branches\Elements_with_Branches.prl.

The change to this report adds the Merge Manager command to the shortcut menu. This command is not supplied with ClearCase Reports, so the work required to included it is different from that in Example 4: Changing the Shortcut Menu for the Right-Click Handling Mechanism.

These commands currently appear on the shortcut menu:

• Properties of Element

• Version Tree

• History

Interface Specification

This is the existing interface specification for Elements_with_Branches.prl:

if (/^-i/) {
print "description : 'Elements with Branches'\n";
print "id : 2013\n";
print "helpfile :\n";
print "parameters : ";
print "LOOKIN BRANCH";
print "\n";
print_element_rightclick();
print "fields : ";
print "\"Element Path\"(element_xpn, sort 1, rightclick) ";
print "\"Branch\"(branch) ";
print "\n";
exit(0);
}

Changes Required

Making this modification requires a new script for the new command functions.

You must place this script in the \scripts_rightclick directory. (The script can be written in any of the supported programming languages.) The script must be coded to receive a stream on input from STDIN from a field that is designated by a rightclick modifier in the interface specification of the report procedure. For example, to create my_rc.prl, which starts clearmrgman.exe (Merge Manager), you must place my_rc.prl in \scripts_rightclick.

Modified Report Procedure

Here is the modified version of Elements_with_Branches.prl. This report procedure is example5.prl in the T0046 package, which is available at http://www.rational.com/support/downloadcenter/addins/clearcase/contrib/index.jsp.

$start_dir = $0; $start_dir =~ s/\\scripts\\.*/\\scripts/;
$common_dir = $start_dir;
$common_dir =~ s/(.*)\\scripts/$1\\script_tools/;

$cc = ""; if ($cc) {;};
$ct = ""; if ($ct) {;};
$debug = ""; if ($debug) {;};
$skip_path_checks = ""; if ($skip_path_checks) {;};
$CLEARCASE_XN_SFX = ""; if ($CLEARCASE_XN_SFX) {;};
$ctfind_paths = ""; if ($ctfind_paths) {;};
$skip_path_checks = "yes"; if ($skip_path_checks) {;};
$debug = "no"; if ($debug) {;};

sub do_exit {
$err = join(" ", @_);
if ("$err" != "") {
print STDERR "$err\n";
}
sleep(2);
if ("$err" != "") {
exit(1);
} else {
exit(0);
}
}
open(INCLUDE, "<$common_dir\\common_script.prl") or do_exit("error opening include file '$common_dir\\common.prl'");
$buf = "";
while(<INCLUDE>) {
$buf = $buf . $_;
}
close(INCLUDE);
eval $buf || do_exit("error on eval of include file '$common_dir\\common.prl'");

my $args = $ARGV[0];
$args =~ s/%/ /g;
@args = split(";", $args);
my $ccbranch = "";
$required_args = 0;
foreach(@args) {
s/^[ ]+//;
s/[ ]+$//;
validate_arg_length($_);
if (/^-i/) {
print "description : 'Elements with Branches'\n";
print "id : 2013\n";
print "helpfile :\n";
print "parameters : ";
print "LOOKIN BRANCH";
print "\n";
### customization change *** deleted following line
#print_element_rightclick();
### customization change *** added following 8 lines
print "rightclick : ";
print "my_rc(single) ";
print "Properties_of_Element(single) ";
print "sep ";
print "Compare_with_Previous_Version(single) ";
print "Version_Tree(single) ";
print "History(single) ";
print "\n";
print "fields : ";
print "\"Element Path\"(element_xpn, sort 1, rightclick) ";
print "\"Branch\"(branch) ";
print "\n";
exit(0);
}

if (/^LOOKIN[ ]*=[ ]*('.*')/) {
#print "paths are $1\n";
check_lookin($1);
$required_args++;
next;
}
if (/^BRANCH[ ]*=[ ]*'*([^']*)'*/) {
$ccbranch = $1;
$required_args++;
next;
}
print STDERR "unrecognized argument: $_\n";
print STDERR " ccperl $0 -i\n";
print STDERR " for script's interface.\n";
do_exit("\n");
}
if ($required_args != 2) {
print STDERR "usage: not all required arguments specified.\n";
print STDERR " ccperl $0 -i\n";
print STDERR " for script's interface.\n";
do_exit("\n");
}
open(CTFIND, "cleartool find $ctfind_paths -nxname -branch 'brtype($ccbranch)' -print |");
while(<CTFIND>) {
chomp;
print "$_;$ccbranch;\n";
}
do_exit();

Here is the new command of my_rc.prl that has been created to support a new shortcut menu command for starting Merge Manager. This report procedure is available in the T0046 package, which is available at http://www.rational.com/support/downloadcenter/addins/clearcase/contrib/index.jsp.

# these are all set by set_record_vars in common_rightclick.prl
#
$CLEARCASE_PN = "", $CLEARCASE_XN_SFX = "", $CLEARCASE_ID_STR = "",
$CLEARCASE_XPN = "";
$CLEARCASE_BRANCH_PATH = "", $CLEARCASE_VERSION_NUMBER = "";
$ELEMENT_RESULTS = "", $BRANCH_RESULTS = "", $VERSION_RESULTS = "";
$results = "";

$debug = "no";

$start_dir = $0; $start_dir =~
s/\\scripts_rightclick\\.*/\\scripts_rightclick/;
$common_dir = $start_dir;
$common_dir =~ s/(.*)\\scripts_rightclick/$1\\script_tools/;

open(INCLUDE, "<$common_dir\\common_rightclick.prl") or do_exit("error opening include file '$common_dir\\common_rightclick.prl'");
$buf = "";
while(<INCLUDE>) {
$buf = $buf . $_;
}
close(INCLUDE);
eval $buf || do_exit("error on eval of include file '$common_dir\\common_rightclick.prl'");

if ($CLEARCASE_PN) {;}
if ($CLEARCASE_XN_SFX) {;}
if ($CLEARCASE_ID_STR) {;}
if ($CLEARCASE_XPN) {;}
if ($CLEARCASE_BRANCH_PATH) {;}
if ($CLEARCASE_VERSION_NUMBER) {;}
if ($ELEMENT_RESULTS) {;}
if ($BRANCH_RESULTS) {;}
if ($VERSION_RESULTS) {;}
if ($debug) {;}

$first = "yes";

while(<STDIN>) {
chomp;
set_record_vars($_);
########################################################################
# things to be done a record at a time are done here
if ($first eq "yes") {
$first = "no";
open(COMMAND, "clearmrgman |");
while(<COMMAND>) {;}
close(COMMAND);
}
########################################################################
}
# things to be done with the result set as a whole go here

$results =~ s/ $//;

#print "results are $results\n";