pathnames_ccase

A standard path name is either full or relative:

• A full path name begins with a slash (/):

  /usr/bin/cc

  The slash can be implied. For example:

  ~bertrand/proj/doc

  A full path name is interpreted in the process's set view context. An error occurs if you attempt to use a full path name to access ClearCase data in a process that is not set to a view.

• A relative path name does not begin with a slash:

  foo.c
  ../motif/libX.a

A relative path name 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 path name 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 path name 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 in /usr/bin.

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

A standard path name is either full or relative:

• A full path name begins with an optional drive letter and a backslash (drive-letter:\, or just \). The following full path names 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 path names to non-VOB objects:

  C:\users\anne\bin\myperl.exe	View-private file: an MVFS object, but not in a VOB
  \users\anne	Current drive is C

• A relative path name does not begin with a backslash or with drive-letter:\:

  main.c
  ..\src\main.cZ:\main.c

A standard path name 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 path name 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 path name 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 path names to reference MVFS objects is called transparency: a view's view_server process resolves the standard path name into a reference to the appropriate MVFS object. In essence, transparency makes a VOB appear to be a standard directory tree.

An absolute VOB path name is full path name that starts with a VOB tag.

Absolute VOB path names 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 path names.) This form of path name 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 path name scheme:

• You can add two path name components (UNIX or Linux) or a view tag prefix (Windows) to any MVFS object path name, turning it into a view-extended path name:

  /view/david/vobs/proj/foo.c	View-extended full path name
  M:\dri_view\proj_vob\foo.c	View-extended full path name
  \dri_view\proj_vob\foo.c	View-extended full path name; M is the current drive

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

  ../../david/vobs/proj/foo.c	View-extended relative path name
  ..\..\dri_view\proj_vob\foo.c	View-extended relative path name

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

  UNIX or Linux:

  foo.c@@/main/12	Version-extended path name
  /vobs/proj/foo.c@@/main/motif/4	Version-extended path name
  foo.c@@/RLS4.3	Version-extended path name
  foo.c@@/main	VOB-extended path name to a branch
  foo.c@@	VOB-extended path name to an element
  hello.o@@2007-09-15T08:10.439	VOB-extended path name to a derived object

  Windows:

  foo.c@@\main\12	Version-extended path name
  \proj_vob\foo.c@@\main\bugfix\4	Version-extended path name
  foo.c@@\RLS4.3	Version-extended path name
  foo.c@@\main	VOB-extended path name to a branch
  foo.c@@	VOB-extended path name to an element
  hello.o@@2007-09-15T08:10.439	VOB-extended path name to a derived object

In most view-extended path names, a full path name 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 path name of the viewroot directory is /view. For more information, see the init_ccase reference page and the IBM Rational ClearCase Administrator's Guide.

Most view-extended path names are full path names that begin with the view tag of a particular view. Unless you are working explicitly on drive M, the view-extended path name 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.

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 path name in this extended namespace:

The previous path name 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.

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

On UNIX or Linux, 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 or Linux 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 path names to the labeled version:

UNIX or Linux:

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

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

• UNIX or Linux:

  /vobs/proj/src/include/sort.h

• 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 path name crosses over into the extended namespace with @@, you must specify a version for each succeeding element in the path name. For example:

• UNIX or Linux:

  /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 or Linux:

  /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 or Linux:

  /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

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

• UNIX or Linux:

  /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 path name 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 or Linux:

  % 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 path name can also read the version's data, but cannot write or delete it:

• UNIX or Linux:

  % grep 'env' util.c@@/main/rel2_bugfix/1	Valid
  % rm util.c@@/main/rel2_bugfix/1	Not valid
  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 path name. Multiple versions of an element also exist at the same standard path name, 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).

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:

• On UNIX or Linux:
  • Use a version-extended path name 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

• On Windows:
  • Use a version-extended path name 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 and Linux 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 and Linux only: Exiting from VOB-extended namespace. To exit VOB-extended namespace, change to a standard full path name or a view-extended path name. (The path name 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: