pathnames_ccase

ClearCase pathname resolution, dynamic view context, and extended namespace

APPLICABILITY

ClearCase (general information)

SYNOPSIS

• VOB-extended pathname:

  Element:	element-pname@@
  Branch:	element-pname@@branch-pname
  Version:	element-pname@@version-selector
  VOB symbolic link:	link-pname
  Derived object:	derived-object-pname@@derived-object-ID

• Absolute VOB pathname (dynamic views only):

  \vob-tag\pname-in-vob

• View-extended pathname (dynamic views only):

  drive-letter:\view-tag\vob-tag\pname-in-vob

DESCRIPTION

This reference page describes ClearCase extensions to the standard file/directory namespace provided by the operating system. These extensions can be used as follows:

• From a dynamic view, you can use the pathname forms described here as arguments to any cleartool command that takes a pathname.
• From a snapshot view, you can use the VOB-extended pathname forms as arguments to those cleartool commands that return information about elements and versions (for example, describe, ls, lshistory, and diff). Such operations do not require the MVFS. However, you cannot use VOB-extended pathnames forms to check out an element version that is not loaded into your view.

NOTE: cleartool is case-sensitive. In cleartool subcommands, pathnames to MVFS objects, including view-private files in the MVFS namespace, must be case-correct.

DYNAMIC VIEW CONTEXTS

A pathname can access ClearCase data only if it has a view context:

• WORKING DIRECTORY VIEW CONTEXT - You can change the current working directory of a process to a view-extended pathname:

% cd \view\david\vobs\proj

Such a process is said to have a working directory view context.

• VIEW-EXTENDED PATHNAME - A pathname can specify its own view context, regardless of the current working directory view context, if any.

DYNAMIC VIEW ACCESS MODEL

All ClearCase data is accessed through the MVFS, which, by default, occupies drive M: on each ClearCase host. Each active view's view-tag appears in the root directory of M:, and each active VOB's VOB-tag appears as a subdirectory under each active view. See Figure 18.

Figure 18 ClearCase MVFS Namespace

From the M: drive, you can access VOBs using view-specific pathnames of the form \view-tag\vob-tag\pname-in-vob. Typically, however, you do not work directly on the M: drive, but on a drive you have assigned to a view. Figure 19 shows how the MVFS namespace looks from a drive assigned to a view with the net use command or by clicking Tools`Map Network Drive in Windows Explorer.

Figure 19 The MVFS Namespace from a Drive

From any drive, you can specify view-extended pathnames of the form M:\viewtag\vobtag\rest-of-path. If you move to the M: drive, you are in view-extended namespace, and all VOB access is via view-extended pathnames.

To eliminate any confusion that msy result from unintentional use of view-extended pathnames, we recommend that you work from a drive letter assigned to a view. This permits you to use VOB pathnames of the form \myvob\vob-object-pname in both cleartool and standard operating system commands, from any view. Furthermore, this approach is required if you want to share DOs between views at build time.

KINDS OF PATHNAMES

The following sections describe the kinds of pathnames you can use with ClearCase.

Standard Pathnames

A standard pathname is either full or relative:

• A full pathname begins with an optional drive letter and a backslash (DRIVE:\, or just \). The following full pathnames all refer to the same VOB object, main.c, using view1. The element main.c resides in a vob with VOB-tag \vob3.

M:\view1\vob3\src\main.c
\view1\vob3\src\main.c (current drive is M:)
Z:\vob3\src\main.c (Z: assigned to M:\view1)
\vob3\src\main.c (current drive is Z:)

Full pathnames to non-VOB objects:

C:\users\anne\bin\myperl.exe
Z:\vob3\src\viewPriv.c (view-private file: an MVFS object, but not in a VOB)
\users\anne (current drive is C:)

• A relative pathname does not begin with a backslash character, nor with DRIVE:\:

main.c
..\src\main.c
Z:main.c

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:

• VERSION - If BAR names an element, the pathname references the version of that element selected by the current view's config spec.
• VOB SYMBOLIC LINK - BAR can name a VOB symbolic link that is visible in the current view. Depending on the command, the link may or may not be traversed.
• DERIVED OBJECT - BAR can name a derived object that was built in the current view or was winked in to the view.
• VIEW-PRIVATE OBJECT - BAR can name a view-private object (including a checked-out version) located in the current view's private storage area.
• NON-MVFS OBJECT - BAR can name an object that is not under ClearCase control, such as objects in your home directory or on other machines (for example, \\hyperion\c\misc\files.txt.

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.

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

Z:\myvob\src\test.h
Z:/myvob/src/text.h

Absolute VOB Pathnames

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

Z:\myvob\src\main.c (full pathname to VOB object-Z: drive assigned to some view)

\myvob\src\main.c (absolute VOB pathname- begins with a VOB-tag (\myvob)

Absolute VOB pathnames are legal 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.

ClearCase Extended Pathnames

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

• You can add a view-tag prefix to any MVFS object pathname, turning it into a view-extended pathname:

M:\dri_view\proj_vob\foo.c (view-extended full pathname)
\dri_view\proj_vob\foo.c (view-extended full pathname; M: is the current drive)

• In certain situations, a relative pathname can include a view specification:

..\..\dri_view\proj_vob\foo.c (view-extended relative pathname)

• You can add characters to the end of a relative or full pathname, turning it into a VOB-extended pathname. VOB-extended pathnames that specify versions of elements are the most commonly used; they are termed version-extended pathnames.

foo.c@@\main\12 (version-extended pathname)

\proj_vob\foo.c@@\main\bugfix\4 (version-extended pathname)

foo.c@@\RLS4.3 (version-extended pathname)

foo.c@@\main (VOB-extended pathname to a branch)

foo.c@@ (VOB-extended pathname to an element)

hello.o@@15-Sep.08:10.439 (VOB-extended pathname to a derived object)

VIEW-EXTENDED PATHNAMES

A view-extended pathname is a standard pathname that references a VOB object or view-private object via a specific ClearCase view. For example, M:\dri_view\proj_vob\BAR references file-system object named BAR, as seen through view dri_view. A view-extended pathname can access any kind of file-system object, as described in Standard Pathnames.

NOTE: In general, you perform ClearCase operations in a working view, on a drive assigned to a view with the net use command or by clicking Tools ` Map Network Drive in Windows Explorer. It is rare to work directly on drive M:. It is common to use view-extended pathnames that include the M:\view-tag prefix. If you work directly on M:, you are in view-extended namespace.

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

SYMBOLIC LINKS AND THE VIEW-EXTENDED NAMESPACE

Pathnames are resolved component-by-component by the operating system kernel and the ClearCase MVFS. When a VOB symbolic link is traversed, a full pathname needs a view context to access ClearCase data. Thus, a symbolic link whose text is an absolute VOB pathname such as

\aardvark -> \all_projects\aardvark

is interpreted in the current view context. If the process has no view context (the current drive is not assigned to M:\some-view-tag), traversing such a symbolic link will fail.

VOB-EXTENDED PATHNAMES

ClearCase's transparency feature enables you to use standard pathnames to access version-controlled data; the view_server does the work of locating the data. But you can also bypass transparency and do the work yourself:

• You can access any version of an element by using its version-ID, which specifies its exact version-tree location:

sort.c@@\main\bugfix\4

• If a version has been assigned a version label, you can access it using the label:

  sort.c@@\main\bugfix\RLS_1.3	(branch and version label)
  sort.c@@\RLS_1.3	(version label only)

  Typically, you can use the label, without having to specify the branch on which the labeled version resides; see Version Labels in Extended Namespace.

• You can access any element object or branch object directly:

  sort.c@@	(element object)
  sort.c@@\main	(branch object)
  sort.c@@\main\bugfix	(branch object)

• You can access any derived object directly, regardless of the view it was created in:

  sort.obj@@13-Aug.09:45.569	(derived object created on 13-Aug)
  sort.obj@@23-Sep.19:09.743	(derived object created on 23-Sep)

The pathnames in the above examples are termed VOB-extended pathnames. A VOB's file/directory namespace is extended in two ways from the standard namespace: one extension enables direct access to elements, branches, and versions; the other enables direct access to derived objects. Both extensions allow you to access objects not visible in your own view (and perhaps not currently visible in any other view, either).

Extended Namespace for Elements, Branches, and Versions

An element's version tree has the same form as a standard directory tree (see Figure 20).

Figure 20 Version Tree and Extended Namespace

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

• When appended to the name of any element, the extended naming symbol turns off transparency (automatic version-selection). Thus, you must specify one of the element's versions explicitly.
• The extended naming symbol is part of an element's official name. For example, foo.c is the name of a version (the particular version that appears in the view); foo.c@@ is the name of the element itself.

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. To change the extended naming symbol:

1. Open the ClearCase Control Panel.
2. Click the MVFS tab.
3. In the Extended Naming Suffix box, type the new characters.
4. Click OK.

Version Labels in Extended Namespace

Version labels appear in the extended namespace as additional files. 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:

Z:\myvob\src> dir sort.c@@\main
11/10/98 05:34p                1846 4
 ...
11/10/98 05:34p                1846 RLS_1

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

Z:\myvob\src> dir sort.c@@
11/10/98 05:34p                1846 RLS_1

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

sort.c@@\RLS_1 (version label at top level of element)
sort.c@@\main\4 (version-ID)
sort.c@@\main\RLS_1 (version label at branch level)

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

\proj_vob\src\include\sort.h

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

\proj_vob\src\include@@\main\4\sort.h\main\LATEST

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:

\proj_vob\src@@\RLS_1\include\RLS_1\sort.h\RLS_1

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:

\proj_vob@@\main\1\src\main\4 (invalid)
\proj_vob\.@@\main\1\src\main\4 (valid)

SPECIAL CASE: When crossing over into extended namespace at the VOB root directory (that is, at the VOB-tag or VOB mount point), you must use \.@@ 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:

\proj_vob\src@@\RLS_1\include@@\RLS_1\sort.h@@\RLS_1

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:

Z:\myvob> cleartool mklabel RLS2.1 util.c@@\RLS2.0 (attach an additional label to a version)
Z:\myvob> cleartool rmattr BugNum util.c@@\main\3 (remove an attribute)

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

Z:\myvob\src> find "env" util.c@@\main\rel2_bugfix\1 (valid)
Z:\myvob\src> del util.c@@\main\rel2_bugfix\1 (invalid)

Access is denied.

Extended Namespace for Derived Objects

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

sort.obj@@14-Sep.09:54.418
sort.obj@@13-Sep.09:30.404
sort.obj@@02-Sep.16:23.353
.
.
.

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 standard directory-navigation commands (for example, cd and dir) in a VOB's extended namespace. For example, these are two equivalent ways to display the contents of an old version:

• Use a version-extended pathname from a standard directory:

Z:\myvob\src> type util.c@@\main\rel2_bugfix\1

• Change to branch "directory" in the VOB-extended namespace, and then display the version:

Z:\myvob\src> cd util.c@@\main\rel2_bugfix

Z:\myvob\src> type 1

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

You can access versions of file elements as ordinary files, with type, comp, and so on-even executing versions that happen to be compiled programs or scripts.

SPECIAL "@@" VIEW-TAGS VISIBLE ON M:. When you activate a view, a subdirectory, view-tag, appears on the M: drive for that view. If you enter version-extended namespace while in that view, a parallel subdirectory, view-tag@@, also appears on M:. For example:

C:\> net use f: \\view\myview
...

C:\> dir M:\
11/15/98 10:24p        <DIR>     myview

C:\> f:
F:\> cd \dev\lib@@
F:\dev\lib@@> dir M:
11/15/98 10:24p        <DIR>     myview
11/15/98 10:24p        <DIR>     myview@@

SEE ALSO

query_language, version_selector, wildcards_ccase