scm271_ecc_s09

8/9/2019 scm271_ecc_s09

1/20

Copyright IBM Corp. 2003 9 - 1

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

Module 9Creating Reports

1

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

8/9/2019 scm271_ecc_s09

2/20


9 - 2 Copyright IBM Corp. 2003


Objectives

2

Report on ClearCase objects and events using

cleartool subcommands

Report on ClearCase objects and events using the

File Browser

Upon completing this module, you should be able to:

Objectives

8/9/2019 scm271_ecc_s09

3/20

Module 9 - Creating Reports



Reporting with cleartool Subcommands

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

ClearCase includes a number ofcleartool 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 ofcleartool subcommands, see online Help or the ClearCaseReference manual.

8/9/2019 scm271_ecc_s09

4/20




annotate: Reporting on File Changes

4

annotate: Reporting on File Changes

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

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

You can use the annotate command when you want to examine, line-by-line, changesmade to a text file. For example, imagine you are inspecting a C++ file and noticesome indecipherable code that is uncommented. You want to determine the codes

author and its reason for its existence.

The annotate command lists the contents of a version, annotating each line to indicatewhen, 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.

8/9/2019 scm271_ecc_s09

5/20




annotate: Reporting on File Changes (cont.)

5

annotate: Reporting on File Changes (cont.)Example:

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

Element path

Event record foreach version

Text lineannotations

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 versions time stamp, creator, andversion-ID.

Elision strings replaces text line annotations that would duplicate the annotationon the preceding line. Includes a bar graph and single dot (.) character.

8/9/2019 scm271_ecc_s09

6/20




describe: Reporting on VOB Objects

6

describe: Reporting on VOB Objects

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

describe [ -long | -short | -fmt format-string] { [ -version version-

selector| -ancestor ] [ -pname ] pname ... | -type type-selector... |

object-selector... }

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, creationdate, owner, and related views.

VOB replica For MultiSite installations, provides information on the object thatrepresents a VOB replica.

8/9/2019 scm271_ecc_s09

7/20




describe: Reporting on VOB Objects (cont.)

7

describe: Reporting on VOB Objects (cont.)Example 1:

Describe the

version of

element util.c

selected by your

view

cleartool describe util.c

version"util.c@@/main/r2_int/pat_r2/0"

created 09-Dec-02.10:39:08 by user(pat.users@butanone)

Element Protection:

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 selectedin the current view.

Review the example to see the types of information describe provides about the

element and this particular version.

8/9/2019 scm271_ecc_s09

8/20




describe: Reporting on VOB Objects (cont.)

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_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 elementutil.c.

Review the example to see the types of information describe provides about the

element and the branch.

8/9/2019 scm271_ecc_s09

9/20




lshistory: Reporting on Events

9

lshistory: Reporting on Events

Lists events for VOB-database objects, including

Version creation

Branch creation

Metadata uses

Adding and deleting elements

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

[ -pname ] pname ... | object-selector ... ]

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, andrecords for attaching and removal of annotations: version labels, attributes, andhyperlinks.

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 theVOB.

VOB history Lists events concerning the VOB, including the deletion of typeobjects and elements from the VOB.

VOB replica history For MultiSite installations, lists events concerning a VOBreplica, including synchronization updates.

8/9/2019 scm271_ecc_s09

10/20




lshistory: Reporting on Events (cont.)

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

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 singleClearCase operationAdd to Source Control (from the GUI) or cleartool mkelem(from the CLI). For more information on the mapping of operations to events, pleasesee the online Help topic events_ccase.

8/9/2019 scm271_ecc_s09

11/20




lshistory: Reporting on Events: (cont.)

11

lshistory: Reporting on Events: (cont.)Example 2:

For all elements

in the current

working

directory, list

events involving

the r2_bugfix

branch

cleartool lshistory -branch r2_bugfix

24-Mar.12:45 pat create version"msg.c@@/main/r2_bugfix/0"

24-Mar.12:45 alex create branch"msg.c@@/main/r2_bugfix"

"release 2 bugfixes"

23-Mar.20:40 alex create version"util.c@@/main/r2_bugfix/1"

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

In this example, the lshistory command reports on events for the current directoryinvolving 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.

8/9/2019 scm271_ecc_s09

12/20




-fmt option: Formatting Reports

12

-fmt option: Formatting Reports

Some commands include afmt option, which you

can use to customize the format of reports

Commands withfmt option include annotate,

describe, and lshistory

Extensive formatting capabilities

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

The fmt option allows you to customize the format of reports generated by cleartoolsubcommands.

-fmt has a large set of capabilities. For complete details on usingfmt, see online Help topic fmt_ccase or the ClearCase Reference manual.

8/9/2019 scm271_ecc_s09

13/20




-fmt option Formatting Reports (cont.)

13

-fmt option Formatting Reports (cont.)

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

Example:

In this example, using the fmt option with the cleartool lshistory command allowsyou to alter the default formatting of the report output.The formatting parameters of the fmt option are similar to those of the printfcommand 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 13characters, resulting in an exact width of 13 characters. The "-" says to left-justify theelement name within the specified output field, which means blanks will be added tothe 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.

8/9/2019 scm271_ecc_s09

14/20




find: Searching for VOB Objects

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

The cleartool find command uses a pattern, query, or expression to search forClearCase objects.

cleartool find selects a set of objects, selects a subset, and then performs an action onthe 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 theVOB, 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

8/9/2019 scm271_ecc_s09

15/20




find: Searching for VOB Objects (cont.)

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

In this example, you can see how to use cleartool find to find and list all elements inand below the current working directory.

The semantic of the ClearCase find command is analogous to a UNIX find command.

8/9/2019 scm271_ecc_s09

16/20





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/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".

In example 2, you can see how to use cleartool find to find and list all elements ownedby a particular user (pat) on the current directory and subdirectories, and then apply alabel.

For more information, refer to online Help topic query_language.

8/9/2019 scm271_ecc_s09

17/20





17

find: Searching for VOB Objects (cont.)Example 3:

List the standard name of each element that has (or contains abranch or version that has) a BugNum attribute with the value189

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

./hello.c

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

8/9/2019 scm271_ecc_s09

18/20




Running Reports from the File Browser

18

Running Reports from the File Browser

Use the reporting feature to run the cleartool

commands discussed in this module.

Run a report on thehistory of hello.c

8/9/2019 scm271_ecc_s09

19/20




Module Review

19

When might you use cleartool annotate?

When might you use cleartool describe?

When might you use cleartool lshistory?

What is thefmt option?

When might you use cleartool find?

Module Review

8/9/2019 scm271_ecc_s09

20/20



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

Module Lab

20

In this lab, you will:

Report on ClearCase objects and events using

cleartool subcommands

Module Lab

Date post:	30-May-2018
Category:	Documents
Upload:	jagadeesh
View:	219 times
Download:	0 times

scm271_ecc_s09

Documents