describe

For an MVFS object, describe lists the object's protections. For information about access control, see the DevOps Code ClearCase Administrator's Guide and the reference pages for protect and protectvob.

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:

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.

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.

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.

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 DevOps Code ClearCase Administrator's Guide.

Default

Describes objects in nongraphical form.

–g/raphical

Starts a browser that describes objects.

Default

describe displays information about the global type object for the specified object-selector.

–local

Displays information for the local copy of the specified object-selector. For more information about global types, see the DevOps Code ClearCase Administrator's Guide.

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 path name. 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. For details about using this report-writing facility, see the fmt_ccase reference page.

Default

None

–eacl

If the object that is to be described is ACL-controlled, lists the effective ACLs that are generated by the object's controlling rolemap.

Default

If you use a view-extended path name to specify an object in (or as seen through) another view, describe lists that view's name for the object:

version: "M:\gamma\vob1\project\src\util.c"

–cvi/ew

Lists an object using the current view's name for it.

version: "/usr/project/src/all_utils.c"

This option is useful when different views select different directory versions, in which elements have been renamed.

–cact

Describes the current activity for your view.

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 path name 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 }, –ali/ases [ –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 path name.

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.

–predecessor	Only the version ID of the predecessor version is listed.
–alabel	Only the version labels are listed.
–aattr	Only the attribute values are listed.
–ahlink	The listing includes the path names of the objects hyperlinked to pname, annotated with → (listed object is the to- object) or ← (listed object is the from-object). For example: -> M:\gamma\vob1\proj\include\db.c@@\main\52 <- M:\gamma\vob1\proj\bin\vega@@\main\5 Inherited hyperlinks are not included in this listing.
–ihlink	The listing includes the hyperlinks inherited by pname, which must specify a version. Path names of the from-object and to-object are listed, one of which is an ancestor of pname, or is pname itself. (That is, –ihlink also includes hyperlinks that are attached to pname itself.)
–aliases	The listing includes any hard links to pname that are visible in the current view. With the –all option, the listing also includes hard links to pname that exist in any version of the directory that contains pname.

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 path names, 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 path name.

• A standard or view-extended path name to an element specifies the version selected by the view.
• A standard or view-extended path name to a derived object specifies the DO in the view.
• An extended path name specifies an element, branch, version, or derived object, different from the one selected by the view. For example:

foo.c	Version of foo.c selected by current view
foo.o	Derived object foo.o built in or winked in to current view
/view/gamma/usr/proj/src/foo.c	Version of foo.c selected by another view; however, the current view must select some version of foo.c
M:\gamma\vob1\proj\src\foo.o	Derived object foo.o built in another view
foo.c@@/main/5	Version 5 on main branch of foo.c
foo.o@@11-Nov.09:19.219	Derived object, specified by DO ID
foo.c@@\REL3	Version of foo.c with version label REL3; however, the view must select some version of foo.c
foo.c@@	The element foo.c@@
foo.c@@/main	The main branch of element foo.c

For versions, –version overrides these interpretations of pname.

–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. For information about closest common ancestors, see the merge reference page.

–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:

Table for object-selector

vob-selector	[vob:]pname-in-vob
	pname-in-vob can be the path name of the VOB tag (whether or not the VOB is mounted) or of any file system object within the VOB (if the VOB is mounted). It cannot be the path name of the VOB storage directory.
attribute-type-selector	attype:type-name[@vob-selector]
branch-type-selector	brtype:type-name[@vob-selector]
element-type-selector	eltype:type-name[@vob-selector]
hyperlink-type-selector	hltype:type-name[@vob-selector]
label-type-selector	lbtype:type-name[@vob-selector]
trigger-type-selector	trtype:type-name[@vob-selector]
pool-selector	pool:pool-name[@vob-selector]
hlink-selector	hlink:hlink-id[@vob-selector]
oid-obj-selector	oid:object-oid[@vob-selector]
policy-selector	policy:policy-name[@vob-selector]
rolemap-selector	rolemap:rolemap-name[@vob-selector]
The following object selectors are valid only if you use MultiSite:
replica-selector	replica:replica-name[@vob-selector]
replica-uuid-selector	oid:replica-uuid@replicauuid:replica-uuid Note: The replica you specify must be located at your current site.
The following object selectors are valid only if you use UCM:
activity-selector	activity:activity-name[@vob-selector]
baseline-selector	baseline:baseline-name[@vob-selector]
component-selector	component:component-name[@vob-selector]
folder-selector	folder:folder-name[@vob-selector]
project-selector	project:project-name[@vob-selector]
stream-selector	stream:stream-name[@vob-selector]