► ► ► Module 9

Creating Reports

IBM Software Group

Essentials of Rational ClearCase

Module 9: Creating Reports

Topics
Objectives............................................................................................................ 9-2
Reporting with cleartool Subcommands................................................................ 9-3
annotate: Reporting on File Changes.................................................................... 9-4
describe: Reporting on VOB Objects ................................................................... 9-6
lshistory: Reporting on Events.............................................................................. 9-9
-fmt option: Formatting Reports ......................................................................... 9-12
find: Searching for VOB Objects ........................................................................ 9-14
Running Reports from the File Browser ............................................................... 9-18

© Copyright IBM Corp. 2003 9-1

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Objectives

Objectives
Upon completing this module, you should be able to:
Š Report on ClearCase objects and events using
cleartool subcommands
Š Report on ClearCase objects and events using the
File Browser

9-2 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 9 - Creating Reports

Reporting with cleartool Subcommands

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
3

ClearCase includes a number of cleartool subcommands that read VOB information,

format the data, and produce it in standard output forms.
The scope of these reports can cover a single element, a set of objects, or entire VOBs.
In this module, you learn more about the cleartool subcommands:
• annotate
• describe
• lshistory
• find
For a full discussion of cleartool subcommands, see online Help or the ClearCase
Reference manual.

© Copyright IBM Corp. 2003 9-3

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

annotate: Reporting on File Changes

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

You can use the annotate command when you want to examine, line-by-line, changes
made to a text file. For example, imagine you are inspecting a C++ file and notice
some indecipherable code that is uncommented. You want to determine the code’s
author and its reason for its existence.
The annotate command lists the contents of a version, annotating each line to indicate
when, and in which version, the line was added.
By default, annotate writes its output to a file with a .ann extension. By default,
ClearCase puts the .ann file in the same location as the original file.

9-4 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 9 - Creating Reports

annotate: Reporting on File Changes (cont.)

annotate: Reporting on File Changes (cont.)

Example:
/vobs/Hardware/src% cleartool annotate hello.c

Element path

Event record for

each version

Text line
annotations

The .ann file contains the output of the cleartool annotate command.
The standard report output includes the following sections:
• Element pathname — shows path of element being annotated.
• Heading section — lists the event record for each version.
• Text line annotations — includes a bar graph indicating how long ago the line first
appeared in an ancestor version, along with that version’s time stamp, creator, and
version-ID.
• Elision strings — replaces text line annotations that would duplicate the annotation
on the preceding line. Includes a bar graph and single dot (.) character.

© Copyright IBM Corp. 2003 9-5

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

describe: Reporting on VOB Objects

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

The describe command lists information about VOBs and the objects they contain.
The cleartool describe command produces several kinds of listings, including:
• File-system data — Provides information on elements, versions, derived objects,
and VOB symbolic links.
• Type object — Provides information on VOB type objects, for example label,
hyperlink, and branch types.
• VOB object — Provides information on a VOB, including storage area, creation
date, owner, and related views.
• VOB replica — For MultiSite installations, provides information on the object that
represents a VOB replica.

9-6 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 9 - Creating Reports

describe: Reporting on VOB Objects (cont.)

describe: Reporting on VOB Objects (cont.)

Example 1: cleartool describe util.c
Describe the version
version of "util.c@@/main/r2_int/pat_r2/0"
element util.c created 09-Dec-02.10:39:08 by user
(pat.users@butanone)
selected by your
Element Protection:
view
User : pat : r--
Group: users : r--
Other: : r--
element type: text_file
predecessor version: /main/r2_int/1
Labels:
R1.5

In this example, the describe command reports on the version of an element selected
in the current view.
Review the example to see the types of information describe provides about the
element and this particular version.

© Copyright IBM Corp. 2003 9-7

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

describe: Reporting on VOB Objects (cont.)

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_int/pat_r2

branch "util.c@@/main/r2_int/pat_r2"
created 09-Dec-02.10:39:08 by user (pat.users@butanone)
branch type: pat_r2
master replica: UNIXReplica2@/vobs/Hardware (defaulted)
request for mastership: allowed
Element Protection:
User : pat : r--
Group: users : r--
Other: : r--
element type: text_file
branched from version: /main/r2_int/1

In this example, the describe command reports on a branch of an element, branch

/pat_r2 of element util.c.
Review the example to see the types of information describe provides about the
element and the branch.

9-8 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 9 - Creating Reports

lshistory: Reporting on Events

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

The lshistory command lists event records. It describes operations that affect VOB data.
There are several kinds of listings, including:
• File-system data history — Lists events concerning elements, branches, versions,
and VOB links. This includes records for creation and deletion of objects, and
records for attaching and removal of annotations: version labels, attributes, and
hyperlinks.
• Hyperlink history — Lists events concerning hyperlink objects: creation, deletion,
and attaching and removal of attributes.
• Type history — Lists events concerning type objects that have been defined in the
VOB.
• VOB history — Lists events concerning the VOB, including the deletion of type
objects and elements from the VOB.
• VOB replica history — For MultiSite installations, lists events concerning a VOB
replica, including synchronization updates.

© Copyright IBM Corp. 2003 9-9

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

lshistory: Reporting on Events (cont.)

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@@"

10

In this example, the lshistory command reports on the event history of an element,
hello.c.
Review the example to see the types of information lshistory provides about events.
The report lists events in reverse chronological order.
Notice the bottom (earliest) three history lines. These events are generated by a single
ClearCase operation — Add to Source Control (from the GUI) or cleartool mkelem
(from the CLI). For more information on the mapping of operations to events, please
see the online Help topic events_ccase.

9 - 10 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 9 - Creating Reports

lshistory: Reporting on Events: (cont.)

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
23-Mar.20:40 alex create version
the r2_bugfix "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"

11

In this example, the lshistory command reports on events for the current directory
involving the r2_bugfix branch.
Review the example to see the types of information lshistory provides about events.
The report lists events in reverse chronological order.

© Copyright IBM Corp. 2003 9 - 11

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

-fmt option: Formatting Reports

-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

12

The –fmt option allows you to customize the format of reports generated by cleartool
subcommands.
-fmt has a large set of capabilities. For complete details on using
–fmt, see online Help topic fmt_ccase or the ClearCase Reference manual.

9 - 12 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 9 - Creating Reports

-fmt option Formatting Reports (cont.)

-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
13

In this example, using the –fmt option with the cleartool lshistory command allows
you to alter the default formatting of the report output.
The formatting parameters of the –fmt option are similar to those of the printf
command in C and C++.
In the example on the slide, the format string "\tElement:
%-13.13En Version: %Vn\n" means the following:
•"\t"
Print a TAB character.
•"Element: "
Characters are printed unmodified in output.
•"%-13.13En"
Print the element name ("%En"), but the field width is specified explicitly with the "-
13.13" modifier, which means minimum width 13 characters and maximum width 13
characters, resulting in an exact width of 13 characters. The "-" says to left-justify the
element name within the specified output field, which means blanks will be added to
the end of the element name if it is shorter than 13 characters. Element names longer
than 13 characters are truncated.
•" Version: "
Characters are printed unmodified in output.
•"%Vn"
Print the Version ID.
"\n"
Print a new-line character.

© Copyright IBM Corp. 2003 9 - 13

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

find: Searching for VOB Objects

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

14

The cleartool find command uses a pattern, query, or expression to search for
ClearCase objects.
cleartool find selects a set of objects, selects a subset, and then performs an action on
the subset. The action can be to list the objects
(–print) or execute a command on each object (-exec).
You can search for objects in the directory structure of the current view, throughout the
VOB, or across all mounted VOBs.
To find objects visible in the directory structure seen in the current view:
find pname ... selection-options action-options
To find all objects in the VOB:
find [ pname... ] -all [ -visible | -nvisible ] selection-options action-options
To find objects throughout all mounted VOBs:
find -avobs [ -visible | -nvisible ] selection-options action-options

9 - 14 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 9 - Creating Reports

find: Searching for VOB Objects (cont.)

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@@

15

In this example, you can see how to use cleartool find to find and list all elements in
and below the current working directory.
The semantic of the ClearCase find command is analogous to a UNIX find command.

© Copyright IBM Corp. 2003 9 - 15

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

find: Searching for VOB Objects (cont.)

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/r2_int/pat_r2/CHECKEDOUT".
Created label "PAT1" on "./Makefile" version
"/main/r2_int/pat_r2/1".
Created label "PAT1" on "./hello" version "/main/0".
Created label "PAT1" on "./hello.c" version
"/main/r2_int/pat_r2/3".
Created label "PAT1" on "./hello.h" version
"/main/r2_int/pat_r2/2".
Created label "PAT1" on "./util.c" version
"/main/r2_int/pat_r2/0".

16

In example 2, you can see how to use cleartool find to find and list all elements owned
by a particular user (pat) on the current directory and subdirectories, and then apply a
label.
For more information, refer to online Help topic query_language.

9 - 16 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 9 - Creating Reports

find: Searching for VOB Objects (cont.)

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

17

In example 3, you can see how to use cleartool find to find and list all elements that
have a BugNum attribute with a value 189 attached to it. The attribute could be
attached to the element or to a branch or version of the element. Using find in this way
allows you to get a change set, a list of elements associated with particular bug fix.

© Copyright IBM Corp. 2003 9 - 17

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Running Reports from the File Browser

Running Reports from the File Browser

Use the reporting feature to run the cleartool
commands discussed in this module.
Run a report on the
history of hello.c

18

9 - 18 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Module 9 - Creating Reports

Module Review

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?

19

© Copyright IBM Corp. 2003 9 - 19

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 Essentials of Rational ClearCase

Module Lab

Module Lab
In this lab, you will:
ƒ Report on ClearCase objects and events using
cleartool subcommands

20

9 - 20 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.