®

IBM Software Group

Essentials of Rational ClearCase

Module 9: Creating Reports

1
Objectives
Upon completing this module, you should be able to:
 Report on ClearCase objects and events using
cleartool subcommands
 Run reports using the ClearCase Report Builder
 View reports using the ClearCase Report Viewer

2
Topics
 Reporting with cleartool subcommands
 Reporting with ClearCase Reports applications

3
Reporting with cleartool
Subcommands
 Many ClearCase commands read data from a VOB,
format it, and write it to standard output
 Scope of reports can be
 Single element
 Set of objects
 Entire VOBs
 cleartool reporting subcommands include
 annotate
 describe
 lshistory
 find
4
annotate: Reporting on File Changes

annotate [ -all | -rm ] [ -nco ] [ -short | -long | -fmt format] ]

 Provides line-by-line detail about changes to versions of

an element (text file)
 Extracts information from element versions
 By default, writes its output to an .ann file

5
annotate: Reporting on File Changes
(cont.)
Example:
M:\Pat_R2_Dev\Hardware\src>cleartool annotate hello.c
Annotated result written
to hello.c.ann
Element path

Event record for

each version

Text line
annotations

6
describe: Reporting on VOB Objects
describe [ -long | -short | -fmt format-string ] { [ -version version-
selector | -ancestor ] [ -pname ] pname ... | -type type-selector ... |
object-selector ... }

Lists information about VOBs and VOB objects:

 Descriptions of elements, versions, or other objects
 Labels attached to a particular version
 Hyperlinks and/or attributes attached to objects
 Predecessor versions of a particular version

7
describe: Reporting on VOB Objects
(cont.)
Example 1:
cleartool describe util.c
Describe the version "util.c@@\main\r2_int\1"
version of created 20-Jul-94.17:05:00 by
element util.c pat.ccusers@flyer
selected by your "define user, home, time functions"
view Element Protection:
User : RATIONAL\pat : r--
Group: RATIONAL\ccusers : r--
Other: : r--
element type: text_file
predecessor version: \main\r2_int\0
Labels:
R2
8
describe: Reporting on VOB Objects
(cont.)
Example 2: Describe a branch of an element, specifying it with
an extended pathname

cleartool describe util.c@@\main\r2_bugfix

branch "util.c@@\main\r2_bugfix"
created 04-Dec-02.12:15:40 by
alex.ccusers@flyer
branch type: r2_bugfix
Element Protection:
User : alex : r--
Group: ccusers : r--
Other: : r--
element type: text_file
branched from version: \main\4

9
lshistory: Reporting on Events
lshistory [ -long | -short | -fmt format-string ]
[ -pname ] pname ... | object-selector ... ]

Lists events for VOB-database objects, including

 Version creation
 Branch creation
 Metadata uses
 Adding and deleting elements

10
lshistory: Reporting on Events (cont.)
Example 1: List event history for an element

cleartool lshistory hello.c

08-Dec.12:05 pat import file element "hello.c@@"
20-May.15:41 alex create version "hello.c@@/main/3" (REL2)
"include name, home dir, and time in message
KNOWN BUG: extra NL at end of time message"
07-May.08:34 kim create version "hello.c@@/main/2" (REL1)
"ANSI compatibility: declare return value type, make explicit
return value
also: clean up wording for The Boss"
04-May.13:35 kim create version "hello.c@@/main/1"
"first implementation"
04-May.13:35 kim create version "hello.c@@/main/0"
04-May.13:35 kim create branch "hello.c@@/main"
04-May.13:35 kim create file element "hello.c@@"
11
lshistory: Reporting on Events:
(cont.)
Example 2: cleartool lshistory -branch r2_bugfix
24-Mar.12:45 pat create version
For all elements "msg.c@@/main/r2_bugfix/0"
in the current
24-Mar.12:45 alex create branch
working "msg.c@@/main/r2_bugfix"
directory, list
"release 2 bugfixes"
events involving
the r2_bugfix 23-Mar.20:40 alex create version
"util.c@@/main/r2_bugfix/1"
branch
"fix bug: extra NL in time string"
23-Mar.20:39 kim create version
"util.c@@/main/r2_bugfix/0"
23-Mar.20:39 kim create branch
"util.c@@/main/r2_bugfix"

12
-fmt option: Formatting Reports

lshistory [ -long | -short | -fmt format-string ]

 Some commands include a –fmt option, which you

can use to customize the format of reports
 Commands with –fmt option include annotate,
describe, and lshistory
 Extensive formatting capabilities

13
-fmt option Formatting Reports
(cont.)
Example:
cleartool lshistory -since 1-Feb util.c
10-Feb.11:21 anne create version
"util.c@@/main/r2_bugfix/1"
"fix bug: extra NL in time string"
10-Feb.11:21 anne create version
"util.c@@/main/r2_bugfix/0"
10-Feb.11:21 anne create branch
"util.c@@/main/r2_bugfix"

cleartool lshistory -fmt "\tElement: %-13.13En Version:

%Vn\n" -since 1-Feb util.c
Element: util.c Version: /main/r2_bugfix/1
Element: util.c Version: /main/r2_bugfix/0
Element: util.c Version: /main/r2_bugfix
14
find: Searching for VOB Objects
 Uses a pattern, query, or expression to search for
ClearCase objects
 Selects a set or subset of objects, then performs an
action on the subset
 Actions can be
 List the objects
 Execute a command on each object

15
find: Searching for VOB Objects
(cont.)
Example 1:
List all file elements in and below the current working directory

cleartool find . -type f -print

./Makefile@@
./hello.c@@
./hello.h@@
./msg.c@@
./util.c@@

16
find: Searching for VOB Objects
(cont.)
Example 2:
List all elements owned by user pat on the current directory and
subdirectories and apply a label

cleartool find . –user pat -exec "cleartool mklabel PAT1

%CLEARCASE_PN%"
Created label "PAT1" on "." version "\main\1".
Created label "PAT1" on ".\src" version "\main\2".
Created label "PAT1" on ".\src\hello.c" version
"\main\4".
Created label "PAT1" on ".\src\util.c" version
"\main\1".

17
find: Searching for VOB Objects
(cont.)
Example 3:
List the standard name of each element that has (or contains a
branch or version that has) a BugNum attribute with the value
189

cleartool find . -nxname -element “attr_sub(BugNum,==,189)”

-print
./hello.c

18
Topics
 Reporting with cleartool subcommands

 Reporting with ClearCase Reports applications

19
Using ClearCase Reports
 Includes ClearCase Report Builder and ClearCase
Report Viewer
 Uses a library of report programs to support 39 standard
report options
 Use Report Builder to choose report category and type,
define parameter values, and run report
 Use the Report Viewer to view report results
 ClearCase reports can be customized

20
ClearCase Report Builder: Running a
Report

2
Select report
option.

1
Select report
category. 3
Associate a
value with each
parameter.

21
ClearCase Report Viewer: Viewing Repo
Results
The Report Viewer window displays your report results
immediately.

View parameters
and sort order

Run tools from

shortcut menu

Save report in .csv,

.html, or .xml format

Status box

22
Report Output: Example in HTML

23
Report Builder Reports: Example 1
All checkins
for Pat since a
certain date.

24
Report Builder Reports: Example 2
All new
versions since
a certain date.

25
Module Review
 When might you use cleartool annotate?
 When might you use cleartool describe?
 When might you use cleartool lshistory?
 What is the –fmt option?
 When might you use cleartool find?
 How do you access ClearCase Report Builder?

26
Module Lab
In this lab, you will:
 Report on ClearCase objects and events using
cleartool subcommands
 Run reports using the ClearCase Report Builder
 View reports using the ClearCase Report Viewer

27
28