Rational ClearCase Commands Referenceannotate
apropos
catcr
catcs
cc.icon
cc.magic
cd
chactivity
chbl
checkin
checkout
checkvob
chevent
chflevel
chfolder
chmaster
chpool
chproject
chstream
chtype
chview
clearaudit
clearbug
cleardescribe
cleardiffbl
cleardiff
clearexport_ccase
clearexport_cvs
clearexport_pvcs
clearexport_rcs
clearexport_sccs
clearexport_ssafe
clearfsimport
cleargetlog
clearhistory
clearimport
clearjoinproj
clearlicense
clearmake
clearmake.options
clearmrgman
clearprojexp
clearprompt
cleartool
clearviewupdate
clearvobadmin
comments
config_ccase
config_spec
cptype
credmap
creds
deliver
describe
diffbl
diffcr
diff
dospace
edcs
endview
env_ccase
events_ccase
export_mvfs
exports_ccase
file
find
findmerge
fmt_ccase
getcache
get
getlog
help
hostinfo
init_ccase
ln
lock
lsactivity
lsbl
lscheckout
lsclients
lscomp
lsdo
lsfolder
lshistory
ls
lslock
lsmaster
lspool
lsprivate
lsproject
lsregion
lsreplica
lssite
lsstgloc
lsstream
lstype
lsview
lsvob
lsvtree
makefile_aix
makefile_ccase
makefile_gnu
makefile_pmake
makefile_smake
makefile_sun
man
merge
mkactivity
mkattr
mkattype
mkbl
mkbranch
mkbrtype
mkcomp
mkdir
mkelem
mkeltype
mkfolder
mkhlink
mkhltype
mklabel
mklbtype
mkpool
mkproject
mkregion
mkstgloc
mkstream
mktag
mktrigger
mktrtype
mkview
mkvob
mount_ccase
mount
msdostext_mode
mvfslog
mvfsstorage
mvfstime
mvfsversion
mv
omake
pathnames_ccase
permissions
profile_ccase
promote_server
protect
protectvob
pwd
pwv
query_language
quit
rebase
recoverview
reformatview
reformatvob
register
relocate
rename
reqmaster
reserve
rgy_backup
rgy_check
rgy_passwd
rgy_switchover
rmactivity
rmattr
rmbl
rmbranch
rmcomp
rmdo
rmelem
rmfolder
rmhlink
rmlabel
rmmerge
rmname
rmpool
rmproject
rmregion
rmstgloc
rmstream
rmtag
rmtrigger
rmtype
rmver
rmview
rmvob
schedule
schemes
scrubber
setactivity
setcache
setcs
setplevel
setsite
setview
shell
snapshot.conf
softbench_ccase
space
startview
type_manager
umount
uncheckout
unlock
unregister
unreserve
update
version_selector
view_scrubber
vob_restore
vob_scrubber
vob_sidwalk
vob_snapshot
vob_snapshot_setup
wildcards_ccase
winkin
xclearcase
xcleardiff
xmldiffmrg
APPLICABILITY
| Product | Command type |
|---|---|
| ClearCase | cleartool subcommand |
| ClearCase LT | cleartool subcommand |
| MultiSite | multitool subcommand |
SYNOPSIS
- ClearCase
and MultiSite only—Describe objects in graphical format:
- ClearCase LT
on Windows only—Describe objects in graphical format:
- Describe
objects:
- des·cribe [ –local ] [ –l·ong | –s·hort | –fmt format-string ]
- [ –ala·bel { label-type-selector[,...]
| –all } ]
[ –aat·tr { attr-type-selector[,...] | –all } ]
[ –ahl·ink { hlink-type-selector[,...] | –all } ]
{[ –cvi·ew][ –ver·sion version-selector | –anc·estor ]
[ –ihl·ink { hlink-type-selector[,...] | –all } ]
[ –pre·decessor] [ –pname ] pname...
|–type type-selector...
| –cact
| object-selector...
}
DESCRIPTION
The describe command lists information about VOBs and the objects they contain. For example:
- Attributes and/or version labels attached to a particular version
- Hyperlinks attached to a particular object
- Predecessor version of a particular version
- Views that have checkouts.
- Views that have unshared derived objects in a particular VOB (describe –long vob:) (ClearCase dynamic views only)
- Family feature level of a VOB or the replica feature level of a MultiSite VOB replica. This information is of interest only to MultiSite users.
describe produces several kinds of listings:
- File system data. Provides information on elements,
branches, versions, derived objects, and VOB symbolic links.
The description of an element (for example, describe hello.h@@) includes a listing of the storage pools to which the element is currently assigned. (See mkpool and chpool for more information.)
A version's description includes the version ID of its predecessor version.
An ordinary derived object is listed with derived object in its header. A derived object that has been checked in as a version of an element (DO version) is listed with derived object version in its header.
- Type object. Provides information on a VOB's type objects
(for example, on a specified list of label types). This form of the command
displays the same information as lstype –long.
For attribute types, hyperlink types, and label types, describe shows the instance mastership of the type (whether the type's mastership can be shared by multiple replicas), even if the VOB is not replicated.
- Hyperlink object. Provides information on a hyperlink object.
- Storage pool. Provides information on a VOB's source, derived object, and cleartext storage pools. This form of the command displays the same information as lspool –long.
- VOB object. Provides information on the object that represents the VOB itself. This includes such information as its storage area, creation date, owner, and related views.
- VOB replica.Provides information on the object that represents a VOB replica, including the replica's master replica, host, mastership request setting, feature level, and TCP connectivity to the current replica. For more information about replicas, see the Administrator's Guide.
- UCM objects. Provides information on UCM objects: activities, baselines, components, folders, projects, and streams. This form of the command displays information similar to that displayed by the UCM commands lsactivity –long, lsbl –long, lscomp –long, lsfolder –long, lsproject –long, and lsstream –long.
Access Control Information
For an MVFS object, describe lists the object's protections. For information about access control, see the Administrator's Guide and the reference pages for protect and protectvob.
Unavailable Remote VOB
File system objects can be hyperlinked to objects in another VOB. If the other VOB is currently unavailable (perhaps it has been unmounted), describe tries to be helpful:
Versions Without Data
The description of a version can include the annotation [version has no data]. A file element version can be created without data, using checkin –cr; an existing version's data can be removed with rmver –data.
Hyperlink Inheritance
By default, a version inherits a hyperlink attached to any of its ancestor versions, on the same branch or on a parent branch. Inherited hyperlinks are listed only if you use the –ihlink option.
A hyperlink stops being passed down to its descendants if it is superseded by another hyperlink of the same type, explicitly attached to some descendant version. You can use a null-ended hyperlink (from-object, but no to-object ) as the superseding hyperlink to effectively cancel hyperlink inheritance.
DOs in Unavailable Views
Note: Derived objects may be present only in ClearCase dynamic views.
describe maintains a cache of tags of inaccessible views. For each view tag, describe records the time of the first unsuccessful contact. Before trying to access a view, describe checks the cache. If the view's tag is not listed in the cache, describe tries to contact the view. If the view's tag is listed in the cache, describe compares the time elapsed since the last attempt with the time-out period specified by the CCASE_DNVW_RETRY environment variable. If the elapsed time is greater than the time-out period, describe removes the view tag from the cache and tries to contact the view again.
The default timeout period is 60 minutes. To specify a different time-out period, set CCASE_DNVW_RETRY to another integer value (representing minutes). To disable the cache, set CCASE_DNVW_RETRY to 0.
Objects in Replicated VOBs
The describe command shows additional information for objects in MultiSite replicated VOBs:
- For
objects that have mastership, describe shows the master
replica of the object.
Note: If the object is a local instance of a global type and you do not specify –local, describe shows the master replica of the global type.
- For branches and branch types, describe shows the current replica's mastership request setting for the object. This setting controls whether users at other sites can request mastership of the object.
For more information about replicated VOBs, see the Administrator's Guide.
OPTIONS AND ARGUMENTS
Describing Objects Graphically
Describing Local Copies of Global Types
Report Format
- Default
- Lists the object's name and some additional
information.
- –l·ong
- Expands the listing. With vob:,
for example, lists all views that have checkouts or unshared derived objects
associated with the specified VOB. This listing includes the UUIDs of those
views, which can be used with rmview.
- –s·hort
- Lists only an object's pathname. The effect
is slightly different when used in combination with –alabel, –aattr, –ahlink, –ihlink, or –predecessor.
- –fmt format-string
- Lists information using the specified format
string. See the fmt_ccase reference page for details about
using this report-writing facility.
Describing Objects in Other Views
Excerpting Description Information
- Default
- describe lists the predecessor
(if the object is a version) and reports on all of the object's version labels,
attributes, and hyperlinks. With one or more of the following options, the
report includes the extended pathname of the object and the requested information
only—for example, only a listing of the predecessor version and version
label.
- –ala·bel { label-type-selector[,...] | –all }, –aat·tr { attr-type-selector[,...] | –all }, –ahl·ink { hlink-type-selector[,...] | –all }, –ihl·ink { hlink-type-selector[,...] | –all }, –pre·decessor
- Specify one or more of these options to
excerpt information from the overall description of an object. A list of names
of type objects must be comma-separated, with no white space; you can use
the special keyword –all to specify all types of a
particular kind.
If you combine –fmt with any of these options, describe uses the format-string to construct and display the object's extended pathname.
For the type-selector arguments, use one of the type selectors shown in the object-selector description.
If you specify –short as well, the listing is restricted even further.
Specifying the Objects to Be Described
- Default
- describe expects at
least one argument that names an element, branch, version, VOB link, derived
object, or hyperlink (pname, DO-name,
or hlink-selector). You can use –version or –ancestor to
control the way pname arguments are interpreted.
- [ –pna·me ] pname ...
- One or more pathnames, indicating objects
to be described: elements, branches, versions, or derived objects. If pname has
the form of an object selector, you must include the –pname option
to indicate that pname is a pathname.
- A standard or view-extended pathname to an element specifies
the version selected by the view.
- A standard or view-extended pathname to a derived object specifies
the DO in the view.
- An extended pathname specifies an element, branch, version,
or derived object, different from the one selected by the view. For example:
For versions, –version overrides these interpretations of pname.
- A standard or view-extended pathname to an element specifies
the version selected by the view.
- –ver·sion version-selector
- (For use with versions only) For each pname,
describes the version specified by version-selector.
This option overrides both version selection by the view and version-extended
naming. See the version_selector reference page for syntax
details.
- –anc·estor
- (For use with elements and versions only)
Describes the closest common ancestor version of all the pname arguments,
which must all be versions of the same element. See the merge reference
page for information about closest common ancestors.
- –typ·e type-selector ...
- Lists information about the type objects
specified by the type-name arguments. If there
are multiple types with the same name (for example, a label type and a hyperlink
type are both named REL3), all of them are listed.
Use one of the type-selectors shown in the description
of the object-selector argument.
- object-selector ...
- One or more object-selectors,
indicating objects to be described. Specify object-selector in
one of the following forms:
EXAMPLES
The UNIX examples in this section are written for use in csh. If you use another shell, you may need to use different quoting and escaping conventions.
The Windows examples that include wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you may need to change the wildcards and quoting to make your command interpreter process the command appropriately.
In cleartool single-command mode, cmd-context represents the UNIX shell or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.
Note: In the UNIX examples that follow, arguments and output that show multicomponent VOB tags are not applicable to ClearCase LT, which recognizes only single-component VOB tags. In this manual, a multicomponent VOB tag is by convention a two-component VOB tag of the form /vobs/vob-tag-leaf—for example, /vobs/src. A single-component VOB tag consists of a leaf only—for example, /src. In all other respects, the examples are valid for ClearCase LT.
- Describe the version of element msg.c selected by your view.
- Describe
a branch of an element, specifying it with an extended pathname.
cmd-context describe util.c@@\main\rel2_bugfix
branch "util.c@@\main\rel2_bugfix"
created 08-Dec-98.12:15:40 by Bev Jackson (test user) (bev.dvt@oxygen)
branch type: rel2_bugfix
Element Protection:
User : sgd : r--
Group: user : r--
Other: : r--
element type: text_file
branched from version: \main\31 - Describe the label type REL3.
- Create a Tested attribute type and apply the attribute to the version of element util.c selected by your current view. Then, use describe to display the newly applied attribute value, and use the –fmt option to format the output.
- Describe ddft, the current VOB's default derived object storage pool.
- Describe how the current view names an element that is named hello.mod in the jackson_fix view.
- Describe
the VOB containing the current working directory. List views with checkouts
or unshared derived objects in that VOB.
cmd-context describe -long vob:.
versioned object base "\hw"
created 15-Dec-98.09:34:00 by jenny.adm@oxygen
"VOB dedicated to development of "hello, world" program"
VOB family feature level: 2
VOB storage host:pathname "oxygen:c:\users\vb_store\tut\tut.vbs"
VOB storage global pathname "\\oxygen\users\vb_store\tut\tut.vbs"
VOB ownership:
owner jackson
group dvt
VOB holds objects from the following views:
oxygen:\vb_store\tut\old.vws [uuid 249356fe.d50f11cb.a3fd.00:01:56:01:0a:4f] - Describe a hyperlink.
- Describe a derived object in the current view.
- Describe a derived object in the current working directory.
- For a particular element, list its name, element type, attached triggers, and cleartext and source pools.
- For a branch type in a replicated VOB, list the master replica of the branch type.
- For the current VOB, list the OID, replication status, MS-DOS text mode setting, and creation comment.
- Describe
the local copy of global label type REL6.
cmd-context describe –local lbtype:REL6
label type "REL6"
created 28-Jul-99.14:00:26 by Suzanne Gets (smg.user@neon)
"Automatically created label type from global definition in
VOB "/vobs/admin"."
instance mastership: unshared
owner: smg
group: user
scope: this VOB (local copy of global type)
constraint: one version per element
Hyperlinks:
GlobalDefinition -> lbtype:REL6@/vobs/admin - Describe
the current VOB, its hyperlinks being of particular interest.
cmd-context describe –long vob:.
versioned object base "\doc"
created 07-Nov-91.16:46:28 by ratl.user
"ClearCase documentation VOB."
VOB family feature level: 1
VOB storage host:pathname "mercury:\usr3\vobstorage\doc_vob"
VOB storage global pathname "\\mercury\usr3\vobstorage\doc_vob"
VOB ownership:
owner 4294967294
group user
Hyperlinks:
AdminVOB -> vob:\adminThis VOB has a hyperlink named AdminVOB; it points from the current VOB to the VOB vob:\admin. If it were pointing to the current VOB, the listing would show
Now describe the hyperlink AdminVOB.
- List the name, master replica, and host of a replica by specifying its OID. (Note that the oid: object-selector must be entered on a single line.)