Rational ClearCase Commands Reference

UNIX Only—Standard Pathnames

A standard pathname is either full or relative:

A relative pathname is interpreted in the process's working directory view context, if it has one. Otherwise, it uses the process's set view context. If a process has neither kind of view context, an error occurs.

A standard pathname can reference any kind of file system object: For example, /vobs/proj/BAR references "file system object named BAR, as seen through the current view." This can be any of the following:

Using standard pathnames to reference MVFS objects is termed transparency: a view's view_server process resolves the standard pathname into a reference to the appropriate MVFS object. In essence, transparency makes a VOB appear to be a standard directory tree.

Windows Only—Standard Pathnames

A standard pathname is either full or relative:

A standard pathname can reference any kind of file system object. Typically, you use the net use command or click Tools > Map Network Drive in Windows Explorer to set a working view (myview , for example), and then work from the drive assigned to M:\myview. In this case, a pathname like \vob1\proj\bar references “file system object named bar, as seen through the current view.” The referenced object can be any of the following:

Using standard pathnames to reference MVFS objects is called transparency: a view's view_server process resolves the standard pathname into a reference to the appropriate MVFS object. In essence, transparency makes a VOB appear to be a standard directory tree.

Note: Most ClearCase and ClearCase LT utilities, including cleartool, accept a slash (/) or backslash (\) as pathname separators. That is, the following pathnames, when used as arguments to ClearCase or ClearCase LT programs, are equivalent:

Windows Only—Absolute VOB Pathnames

An absolute VOB pathname is full pathname that starts with a VOB tag.

Absolute VOB pathnames are valid only if the current drive is assigned to a view. (Manually attaching a drive letter to M:\view-tag with the subst command also enables absolute VOB pathnames.) This form of pathname is commonly used in config specs (see config_spec), and it is also the form in which configurations records store references to MVFS objects.

Extended Pathnames

The MVFS supports two kinds of extensions to the standard pathname scheme:

UNIX Only—The Viewroot Directory / View Tags

In most view-extended pathnames, a full pathname is prefixed with two components: the name of the host's viewroot directory and the view tag of a particular view. The viewroot directory is a virtual data structure, whose contents exist only in MVFS buffers in main memory. Each view is made accessible to standard programs and ClearCase programs through a view tag entry in the viewroot directory. No standard command or program can modify this directory. Only a few ClearCase commands use or modify it: mkview, mktag, rmtag, rmview, startview.

The viewroot directory is activated by a standard mount(1M) command, which considers the virtual data structure to be a file system of type MVFS. The ClearCase pathname of the viewroot directory is /view. For more information, see the init_ccase reference page and the Administrator's Guide.

Windows Only—The MVFS Directory / View Tags

Most view-extended pathnames are full pathnames that begin with the view tag of a particular view. Unless you are working explicitly on drive M, the view-extended pathname also includes the M: prefix. Each view is made accessible to standard programs and ClearCase programs through a view tag entry on the dynamic-views drive, M. No standard command or program can modify the dynamic-views drive's root directory. Only a few ClearCase commands use or modify it: mkview, mktag, rmtag, rmview, and startview.

Extended Namespace for Elements, Branches, and Versions

An element's version tree has the same form as a standard directory tree.

Accordingly, any location within an element's version tree can be identified by a pathname in this extended namespace:

Extended Naming Symbol

The previous pathname examples incorporate the extended naming symbol (@@). This symbol is required to effect a switch from the standard file/directory namespace to the extended element/branch/version namespace. There are two equivalent ways to think of @@:

Note: The establishment of @@ as the extended naming symbol occurs at system startup time with a file system table entry. Thus, different symbols may be used on different hosts. See the init_ccase reference page for details.

Version Labels in Extended Namespace

Version labels appear in the extended namespace as hard links (UNIX) or as additional files (Windows).

On UNIX, if version /main/4 of an element is labeled RLS_1, the extended namespace directory corresponding to the element's main branch lists both 4 and RLS_1 as hard links to the version:

On Windows, if version \main\4 of an element is labeled RLS_1, the extended namespace directory corresponding to the element's main branch lists both 4 and RLS_1:

If the label type was created with the once-per-element restriction, an additional UNIX hard link to the labeled version appears in the element's top-level directory:

On Windows, an entry for the labeled version appears in the element's top-level directory:

In this case, all the following are equivalent extended pathnames to the labeled version:

UNIX:

Windows:

(The once-per-element restriction is the mklbtype default. A mklbtype –pbranch command creates a label type that can be used once on each branch of an element.)

Pathnames Involving More Than One Element

A VOB can implement a deep directory structure. Thus, a pathname can involve several elements. For example:

If proj or proj_vob is the VOB's root directory element, then src and include also name directory elements, and sort.h names a file element.

After a pathname crosses over into the extended namespace with @@, you must specify a version for each succeeding element in the pathname. For example:

To automatically select versions for elements proj and src: cross over to extended namespace at directory element include, specifying a version of include and a version of sort.h:

To automatically select versions for element proj only: cross over to extended namespace at directory element src, specifying the version labeled RLS_1 of each succeeding element:

Note: When crossing over into extended namespace at the VOB root directory (that is, at the VOB tag or VOB mount point), you must use /.@@ or \.@@ instead of @@.

The extended naming symbol need be used only once in a pathname, to indicate the crossover into extended namespace. You can, however, append it to any element name:

Reading and Writing in the Extended Namespace

A VOB-extended pathname references an object in a VOB database. The reference can either read or write the database, that is, either query metadata or modify metadata:

For a version, an extended pathname can also read the version's data, but cannot write or delete it:

Extended Namespace for Derived Objects

The extended namespace allows multiple derived objects to exist at the same standard pathname. Multiple versions of an element also exist at the same standard pathname, but the two extensions work differently. Derived objects created at the same location are distinguished by their unique derived object identifiers, or DO IDs:

An extended name provides access only to the derived object's metadata in the VOB database, principally, its configuration record. DO IDs can be used only with ClearCase commands; they cannot be used in non-ClearCase programs (for example, editors or compilers).

Navigating the VOB-Extended Namespace

You can use the operating system's directory-navigation commands in a VOB's extended namespace. For example, these are two equivalent ways to display the contents of an old version:

In VOB-extended namespace, elements and branches are directories; you can change to such directories with cd; you can lists their contents—branches and versions—with operating system commands.

You can access versions of file elements as ordinary files with operating system commands—even executing versions that happen to be compiled programs or scripts.

UNIX Only—Special view tag reported by pwd. When you have changed to a VOB-extended namespace directory, the pwd(1) command reports your current working directory as under a special view tag: For example:

The special view tag akp_vu@@ appears as a separate entry from akp_vu in your host's viewroot directory. When in the context of a special view tag, version-selection is suppressed completely. To access a particular version of any file or directory element, you must specify the version explicitly. These special entries are periodically deleted on a least-recently-used basis.

UNIX Only—Exiting from VOB-extended namespace. To exit VOB-extended namespace, change to a standard full pathname or a view-extended pathname. (The pathname can specify a VOB or non-VOB location.) For example:

Repeated use of cd .. does not work as you may expect. You do not exit extended namespace where you entered it; instead, you ascend through all the extended-namespace directories listed by pwd. For example:

Windows Only—Special “@@” view tags visible on drive M. When you activate a view, a subdirectory, view-tag, appears on drive M for that view. If you enter version-extended namespace while in that view, a parallel subdirectory, view-tag@@, also appears on drive M. For example: