describe

Describes an object

Applicability

Product

Command type

VersionVault

cleartool subcommand

VersionVault Remote Client

rcleartool subcommand

Platform

UNIX®

Linux®

Windows®

Synopsis

  • VersionVault—Describe objects in graphical format:
    des/cribe –g/raphical { object-selector | pname } ...
  • VersionVault—Describe objects:
    des/cribe [ –local ] [ –l/ong | –s/hort | –fmt format-string ] [ –eacl ]
    [ –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 } ]

    [ –ali/ases [ –all ] ]

    [ –pre/decessor] [ –pname ] pname...

    | –type type-selector...

    | –cact

    | object-selector...

    }

  • VersionVault Remote Client—Describe objects:
    des/cribe [ –l/ong | –s/hort | –fmt format-string ] [ –eacl ]
    [ –ala/bel { label-type-selector[,...] | –all } ]

    [ –aat/tr { attr-type-selector[,...] | –all } ]

    [ –ahl/ink { hlink-type-selector[,...] | –all } ]

    { [ –cvi/ew ] [ –pre/decessor ] pname...

    | –type type-selector...

    | –cact

    | object-selector...

    }

Description

The describe command lists information about VOBs and the objects they contain. For example:

  • Attributes, version labels, or both, which are 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:) (VersionVault 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, VOB symbolic links, and hard 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. At feature level 7 or greater, describing a version object displays its association with a CLM task, if such an association exists.

    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. At feature level 8 or greater, describing the VOB object also displays the minimum client feature level, the state of evil twin detection enablement, and case sensitivity. At feature level 6 or greater, describing the VOB object also displays the status of SRFM (synchronous request for mastership) enablement. For VOBs running V8.0 and later releases, describing the VOB object also displays the state of atomic checkin enablement.
  • 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 Help.
  • 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 Help 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:

cleartool: Error: Unable to locate versioned object base with object id:
"51023fa9.68b711cc.b358.08:00:69:02:1d:c7".
.
.
.
Hyperlinks:
@183@/usr/proj /usr/proj/elem2.c@@/main/2 -> <object not available>

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 VersionVaultdynamic 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 Help.

Restrictions

ACL authorization

If ACLs are enabled, the principal must have the following permissions:
  • read-info on VOB object
  • read-name on object
  • read-info on object
Note that
  • In addition to the permissions that are listed above, –eacl requires AclRead on the object
  • short does not require read-info on the object

Non-ACL authorization

If ACLs are not enabled, no restrictions apply.

Limitations

The following limitations affect rcleartool describe:
  • Version-extended pathnames are not supported
  • UCM object selectors are not supported
  • The following Base VersionVault object selectors are not supported: trigger-type, pool, hlink-type, oid-obj

Options and arguments

Describing objects graphically

Default
Describes objects in nongraphical form.
–g/raphical
Starts a browser that describes objects.

Describing local copies of global types

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

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

Displaying effective ACLs

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.

Describing objects in other views

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.

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

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

Examples

The UNIX system and Linux 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 system and Linux shells or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.

  • Describe the version of element msg.c selected by your view.

    cmd-context describe msg.c
    version "msg.c@@/main/3"
    created 2006-12-08T12:12:55 by Chuck Jackson (test user) (cj.dvt@oxygen)
     Element Protection:
       User : sgd      : r--
       Group: user     : r--
       Other:          : r--
     element type: c_source
     predecessor version: /main/2
     Labels:
      REL6
      REL1

  • Describe a branch of an element, specifying it with an extended path name.

    cmd-context describe util.c@@\main\rel2_bugfix
    branch "util.c@@\main\rel2_bugfix"
     created 2006-12-08T12: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.

    cmd-context describe lbtype:REL3
    label type "REL3"
     created 2006-12-08T12:13:36 by Bev Jackson (test user) (bev.dvt@oxygen)
    instance mastership: unshared
     owner: bev
     group: dvt
     scope: this VOB (ordinary type)
     constraint: one version per branch

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

    cmd-context  mkattype -nc -default '"TRUE"' Tested
    cmd-context  mkattr -default Tested util.c
    cmd-context  describe -aattr -all -fmt
    "Name: %Xn\nType of object: %m\n" util.c

    Name: util.c@@/main/CHECKEDOUT
    Type of object: version
    Attributes:
    Tested = "TRUE"

  • Describe ddft, the current VOB's default derived object storage pool.
    cmd-context describe pool:ddft 
    pool "ddft"
     created 2006-12-15T09:34:00 by jenny.adm@oxygen
     "Predefined pool used to store derived objects."
     owner: jenny
     group: dvt
     kind: derived pool
     pool storage global pathname "\\oxygen\users\vb_store\tut\tut.vbs\d\ddft"
     maximum size: 0 reclaim size: 0 age: 96 
  • Describe how the current view names an element that is named hello.mod in the jackson_fix view.

    cmd-context  describe -cview /view/jackson_fix/usr/hw/src/hello.mod
    version "/usr/hw/src/hello.c@@/main/4"
     created 2006-12-08T12:16:29 by Chuck Jackson (test user) (cj.dvt@oxygen)
     Element Protection:
       User : sgd      : r--
       Group: user     : r--
       Other:          : r--
     element type: text_file
     predecessor version: /main/3

  • 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 2006-12-15T09: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.
    cmd-context describe hlink:Merge@516262@/vobs_proj 
    hyperlink "Merge@516262@/vobs_proj"
     created 2006-07-14T16:43:35 by Bill Bo (bill.user@uranus)
     Merge@516262@/vobs_proj /vobs_proj/lib/cvt/cvt_cmd.c@@/main/v1.1_port/8 ->
     /vobs_proj/lib/cvt/cvt_cmd.c@@/main/71
  • Describe a derived object in the current view.

    cmd-context describe -cview util.o
    derived object "util.o@@2006-04-11T12:03.33"
    created 2006-04-11T12:03:33 by Anne Duvo (anne.dev@oxygen)
    references: 2 (shared)
    derived pool: ddft
    => saturn:/usr/anne/views/anne_main.vws
    => oxygen:/usr/jackson/views/jackson_proj2.vws

  • Describe a derived object in the current working directory.

    cmd-context describe util.obj
    derived object "util.o@@2006-04-11T12:03.33"
    created 2006-04-11T12:03:33 by Anne Duvo (anne.dev@oxygen)
    references: 2 (shared)
    derived pool: ddft
    => saturn:\users\anne\views\anne_main.vws
    => oxygen:\users\jackson\views\jackson_proj2.vws

  • For a particular element, list its name, element type, attached triggers, and cleartext and source pools.

     cmd-context describe –fmt ^
    "%n\n\t%[type]p\n\t%[triggers]p\n\t%[pool]Cp,%[pool]p\n" file.txt@@

    file.txt@@
       text_file
       (CI_TRIG, CO_TRIG)
       cdft,sdft

  • For a branch type in a replicated VOB, list the master replica of the branch type.

    cmd-context describe –fmt "%n\t%[master]p\n" brtype:main
    main    lex@/vobs_dev

  • For the current VOB, list the OID, replication status, MS-DOS text mode setting, and creation comment.
    cmd-context describe –fmt "%On\n%[vob_replication]p\n%[msdostext_mode]p\n%c" ^  
    vob:. 
    46cf5bfd.240d11d3.a37e.00:01:80:7b:09:69
    unreplicated
    disabled
    storage of header files
  • Describe the local copy of global label type REL6.

    cmd-context describe –local lbtype:REL6
    label type "REL6"
      created 2007-07-28T14: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 2006-11-07T16:46:28 by ratl.user
     "VersionVault 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:\admin

    This 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

     Hyperlinks:
      AdminVOB <- vob:\admin

    Now describe the hyperlink AdminVOB.

    cmd-context describe hltype:AdminVOB
    hyperlink type "AdminVOB"
    created 2006-11-07T16:46:28 by ratl.user
    "Predefined hyperlink type used to link a VOB to another VOB with
    administrative information."
    owner: 4294967294
    group: user
    scope: this VOB (ordinary type)

  • List the name, master replica, and host of a replica by specifying its OID. (The oid: object-selector must be entered on a single line.)

    cmd-context describe –fmt "%n\n%[master]p\n%[replica_host]p\n" \
    oid:87f6265f.72d911d4.a5cd.00:01:80:c0:4b:e7@
    replicauuid:87f6265f.72d911d4.a5cd.00:01:80:c0
    :4b:e7
    boston_hub
    boston_hub@/vobs_dev
    minuteman

  • List the protecting rolemap and the effective ACLs for the policy, DefaultPolicy.

    cmd-context  describe -eacl policy:DefaultPolicy
    protected by rolemap: "DefaultRolemap"
    effective access for user "jtk": rmver,Change