Pathname resolution, dynamic view context, and extended namespace
Product | Command Type |
|---|---|
ClearCase | general information |
ClearCase LT | general information |
Platform |
|---|
UNIX |
Windows |
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 |
UNIX dynamic views-Absolute VOB pathname:
Windows dynamic views-Absolute VOB pathname:
UNIX dynamic views-View-extended pathname:
/view /view-tag /full-pathname
Windows dynamic views-View-extended pathname:
This reference page describes ClearCase and ClearCase LT 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 TO WINDOWS USERS: cleartool is case-sensitive. In cleartool subcommands, pathnames to MVFS objects, including view-private files in the MVFS namespace, must be case-correct. Also see the cleartool reference page for information on restrictions on object names.
A pathname can access ClearCase or ClearCase LT data only if it has a view context:
UNIX ONLY-SET VIEW CONTEXT - A process, typically a shell, created with the setview command is said to have a set view context. That process, along with all of its children, is "set to the view."
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.(The process may or may not also have a set view context.)
VIEW-EXTENDED PATHNAME - A pathname can specify its own view context, regardless of the current (UNIX) set view or (UNIX and Windows) working directory view contexts, if any.
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.
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.
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 may 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.
The following sections describe the kinds of pathnames you can use with ClearCase and ClearCase LT.
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.
A standard pathname is either full or relative:
A full pathname begins with a slash (/):
/usr/bin/cc
The slash can be implied. For example:
~bertrand/proj/doc
A full pathname is interpreted in the process's set view context. An error occurs if you attempt to use a full pathname to access ClearCase data in a process that is not set to a view.
A relative pathname does not begin with a slash:
foo.c
../motif/libX.a
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:
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 or ClearCase LT control, such as objects in your home directory or in /usr/bin.
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.
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 or ClearCase LT 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 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:
Z:\myvob\src\test.h
Z:/myvob/src/text.h
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.
The MVFS supports two kinds of extensions to the standard pathname scheme:
You can add two pathname components (UNIX) or a view-tag prefix (Windows) to any MVFS object pathname, turning it into a view-extended pathname:
/view/david/vobs/proj/foo.c (view-extended full 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:
../../david/vobs/proj/foo.c (view-extended relative pathname)
..\..\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)
/vobs/proj/foo.c@@/main/motif/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)
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)
On UNIX systems, a view-extended pathname is a standard pathname, along with a specification of a view. For example, /view/david/vobs/proj/BAR references file-system object named BAR, as seen through view david.A view-extended pathname can access any kind of file-system object, as described in UNIX Only-Standard Pathnames.
On Windows systems, a view-extended pathname is a standard pathname that references a VOB object or view-private object via a specific 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 UNIX Only-Standard Pathnames.
NOTE TO WINDOWS USERS: In general, you perform ClearCase and ClearCase LT operations in a view, on a drive assigned to a view with the net use command. 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.
In most view-extended pathnames, a full pathname is prepended 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. See the init_ccase reference page and the Administrator's Guide for details.
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.
Pathnames are resolved component-by-component by the operating system kernel and the MVFS. When a UNIX symbolic link or VOB symbolic link is traversed, a full pathname needs a UNIX set view context or a Windows view context to access ClearCase data. Thus, a symbolic link whose text is a full UNIX pathname such as
/vobs/aardvark -> /vobs/all_projects/aardvark ...
or a Windows absolute VOB pathname such as
\aardvark -> \all_projects\aardvark
is interpreted in the current UNIX set view context or Windows view context. If the process has no context, traversing such a symbolic link will fail.
The 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/motif/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/motif | (branch object) |
You can access any derived object directly, regardless of the view it was created in:
sort.o@@13-Aug.09:45.569 | (derived object created on 13-Aug) |
sort.o@@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).
An element's version tree has the same form as a standard directory tree.
Component of Version Tree | Component of Directory Tree in Extended Namespace |
|---|---|
element | Root of tree: The element itself appears to be a directory, which contains a single subdirectory, corresponding to the main branch. (It can also contain some version label; see Version Labels in Extended Namespace.) |
branch | Subdirectory: Each branch appears to be a directory, which contains files (individual versions and version labels), directories (subbranches), and links (version labels). |
version | Leaf name: Each version appears to be a leaf of a directory tree. For a file element, the leaf contains text lines or binary data. For a directory element, the leaf contains a directory structure. |
Accordingly, any location within an element's version tree can be identified by a pathname in this extended namespace:
sort.c@@ | (specifies an element) |
sort.c@@/main | (specifies a branch) |
sort.c@@/main/branch1 | (specifies a branch) |
sort.c@@/main/branch1/2 | (specifies a version) |
doctn/.@@/main/3 | (special case: extra component is required in VOB's top-level directory) |
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. See the init_ccase reference page for details.
Version labels appear in the extended namespace as hard links (UNIX) or as additional files (Windows).
In 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:
% ls -il sort.c@@/main
246 -r--r--r-- 1 drp user 217 Oct 6 21:12 4
.
.
.
246 -r--r--r-- 1 drp user 217 Oct 6 21:12 RLS_1
In 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:
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 UNIX hard link to the labelled version the labeled version appears in the element's top-level directory:
% ls -il sort.c@@
246 -r--r--r-- 1 drp user 217 Oct 6 21:12 RLS_1
or a Windows 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)
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.)
A VOB can implement a deep directory structure. Thus, a pathname can involve several elements. For example:
UNIX:
Windows:
\proj_vob\src\include\sort.h
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:
UNIX:
/vobs/proj/src/include@@/main/4/sort.h/main/LATEST
Windows:
\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:
UNIX:
/vobs/proj/src@@/RLS_1/include/RLS_1/sort.h/RLS_1
Windows:
\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:
UNIX:
/vobs/proj@@/main/1/src/main/4 (invalid)
/vobs/proj/.@@/main/1/src/main/4 (valid)
Windows:
\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 /.@@ 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:
UNIX:
/vobs/proj/src@@/RLS_1/include@@/RLS_1/sort.h@@/RLS_1
Windows:
\proj_vob\src@@\RLS_1\include@@\RLS_1\sort.h@@\RLS_1
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:
UNIX:
% cleartool mklabel RLS2.1 util.c@@/RLS2.0 (attach an additional label to a version)
% cleartool rmattr BugNum util.c@@/main/3 (remove an attribute)
Windows:
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:
UNIX:
% grep 'env' util.c@@/main/rel2_bugfix/1 (valid)
% rm util.c@@/main/rel2_bugfix/1 (invalid)
ERROR: util.c@@/main/rel2_bugfix/1 not removed: Read-only file system.
Windows:
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.
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:
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).
You can use the operating systems 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 UNIX:
Use a version-extended pathname from a standard directory:
% cat util.c@@/main/rel2_bugfix/1
Change to branch "directory" in the VOB-extended namespace, and then display the version:
% cd util.c@@/main/rel2_bugfix
% cat 1
In Windows:
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 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:
% cd /view/akp_vu/vobs/proj/special@@
% pwd
/view/akp_vu@@/vobs/proj/main/4/special
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:
% cd /vobs/proj/src@@/main (enter VOB-extended namespace)
% pwd /view/david@@/vobs/proj/main/4/src/main
/view/david@@/vobs/proj/main/4/src/main
% cd /vobs/proj (exit VOB-extended namespace)
% pwd
/vobs/proj
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:
% cd util.c@@/main/rel2_bugfix
% ls
0 1 2 LATEST
% pwd
/view/drp_fix@@/usr/hw/main/1/src/main/2/util.c/main/rel2_bugfix
% cd ../../..
% pwd
/view/drp_fix@@/usr/hw/main/1/src/main/2
% cd ../..
% pwd
/view/drp_fix@@/usr/hw/main/1/src
% cd ../../../
% pwd
/view/drp_fix@@/usr/hw
WINDOWS ONLY-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@@
cleartool, query_language, version_selector, wildcards_ccase
|
Feedback on the documentation in this site? We welcome any comments!
Copyright © 2001 by Rational Software Corporation. All rights reserved. |