config_spec

A view's config spec (configuration specification) contains an ordered set of rules for selecting versions of elements. For a dynamic view, the associated view_server process populates the view with versions by evaluating the config spec rules. The rview_agent process performs the same function for an automatic view.

In dynamic and automatic views, version selection is dynamic. Each time a reference is made to a file or directory element (either by VersionVault software or by standard programs), the config spec is used to select a particular version of the element. (In practice, a variety of caching techniques and optimizations reduce the computational requirements.)

In a snapshot or web view, users invoke an update operation to select versions from the VOB.

UCM config specs are different from those for base VersionVault in that their rules are generated, not user-specified; read UCM config specs before reading any other section of this reference page.

The set of elements considered for version selection is different for the two kinds of views:

• In a dynamic view, all elements in VOBs mounted on the current host are considered for version selection.
• In a snapshot view:
  • If you are updating a loaded element, the behavior is the same as in a dynamic view and the selected version is loaded into the view.
  • If you are not updating and the element is loaded, the selection from the last update is used.
  • If the element is not loaded, the behavior is the same as in a dynamic view.

For each element, the following procedure determines which version, if any, is in the view.

1. The view's associated view_server process tries to find a version of the element that matches the first rule in the config spec:
   • If such a version exists, that version is in the view.
   • If multiple versions match the rule, an error occurs, and no version of the element is in the view. VersionVault commands that access the element print errors like this one:

     cleartool: Error: Trouble looking up element "ht.c" in directory ".".

     Standard commands that access the element print errors like this one:

     The request could not be performed because of an I/O device error.

   • If no version matches the first rule, the search continues.
2. If no matching version was found for the first rule, the view_server tries to find a version that matches the second rule.
3. The view_server continues in this way until it finds a match or until it reaches the last rule.

Each config spec rule must be contained within a single physical text line; you cannot use a backslash (UNIX® and Linux®), a caret (Windows®), or any other line continuation character to continue a rule onto the next line. Multiple rules can be placed on a single line, separated by semicolon (;) characters.

Lines that begin with a number sign (#) are comments.

Extra white space (<SPACE>, <TAB>, vertical-tab, and form-feed) characters are ignored, except within the version selector. If a version selector includes white space, enclose it in single quotes.

If a load rule specifies a file or directory name that includes one or more <SPACE> characters, you must enclose the entire path name in either single-quotes (') or double quotes (").

In general, VOBs, views, and the VersionVault tools that access them are case-sensitive. Therefore, config spec rules must use case-correct path names.

You can use slashes (/) or backslashes (\) as path name separators in path name patterns and version selectors unless you are sharing the config spec between UNIX® or Linux® and Windows® hosts. In that case, you must use slashes. (See Sharing config specs between UNIX or Linux and Windows hosts.)

Windows® and UNIX® or Linux® clients can share config specs, which are portable between the two operating systems. That is, clients on both systems, using views whose storage directories reside on either kind of host, can set and edit the same set of config specs. However, Windows® and UNIX® or Linux® network regions often use different VOB tags to register the same VOBs. Only single-component VOB tag names, like \src2vob, are permitted on Windows® clients; multiple-component VOB tags, like /vobs/src/proj1, are common on UNIX® and Linux®. When the VOB tags diverge between regions, config spec element rules that use full path names (which include VOB tags) are resolvable (at config spec compile time) only by hosts in the applicable network region. This implies a general restriction regarding shared config specs: a given config spec must be compiled only by hosts on one operating system or the other; the operating system for which full path names in element rules make sense. That is, a config spec with full path names can be shared across network regions, even when VOB tags disagree, but it must be compiled in the right place.

This restriction does not apply if any of the following are true:

• The config spec's element rules use relative path names only, which do not include VOB tags.
• Shared VOBs are registered with identical, single-component VOB tags in both Windows® and UNIX® or Linux® network regions. (The VOB tags \r3vob and /r3vob are logically identical, differing only in their leading slash characters.)
• The config spec does not include any load rules or element rules.

A standard version-selection rule takes this form:

scope pattern version-selector [ optional-clause ]

The following subsections describe these components.

A create branch rule takes the following form:

mkbranch branch-type-name [ -override ]
  <config spec lines> 
[ end mkbranch [ branch-type-name ] ] 

This rule is similar to the -mkbranch clause; use it when you want to add a -mkbranch clause to many lines in a complex config spec.

mkbranch branch-type-name [ -override ]

Attaches an implicit -mkbranch branch-type-name clause to all element rules between mkbranch and end mkbranch (or the end of the file) that do not have a -mkbranch clause or include the CHECKEDOUT version selector.

Specifying -override will override any explicit -mkbranch clauses or mkbranch rules within the scope and replace them with -mkbranch branch-type-name. Use -override if you do not want multilevel branch creation.

end mkbranch [ branch-type-name ]

Ends the mkbranch branch-type-name rule. If end mkbranch is omitted, the rule is ended at the end of the config spec. The branch-type-name argument is optional, but if you include it, it must match the branch type specified with the mkbranch rule.

mkbranch and end mkbranch rules might be nested. For example:

Checking out foo.c creates foo.c@@/main/branch1/branch2/CHECKEDOUT. This is a multiple-level mkbranch.

A time rule takes this form:

time date-time
[ end time [ date-time ]  ] 

It is analogous to the -time clause. A time rule modifies the meaning of the special version label LATEST in subsequent rules, with the following exceptions:

• An optional -time clause in a particular rule overrides any general time rule currently in effect.
• A subsequent time rule cancels and replaces an earlier one.

Use end time to limit the effect of a time rule to a certain range. The date-time argument is optional with end time, but if you include it, it must match the date-time argument specified with the time rule.

The date-time specification is evaluated when you set or edit the config spec (however, it is not evaluated by a startview or setview operation (dynamic views only)). Thus, the meaning of a relative specification, such as today, might change over time. However, the date-time is not evaluated at run time. So if you last performed one of the commands listed above four days ago, the meaning of a relative specification, such as today, has the value of the date four days ago, not the value of the date today.

Time rules might be nested. They might not include any query language constructs.

A file-inclusion rule takes this form:

include config-spec-pname

The argument specifies a text file that contains one or more config spec rules (possibly other include rules). Include files are re-read on each execution of setcs and edcs. A file-inclusion rule must be the last rule in a line. For example,

include config-spec-pname

and

time date-time; include config-spec-pname

are both valid.

Load rules define which elements are loaded (copied) into a snapshot view. (By contrast, element rules define which version of an element is selected.) A load rule takes this form:

load pname ...

The argument specifies one or more file or directory elements. Naming a directory element implies the directory and all elements below the directory. Naming a file element specifies that element only. Wildcarding is not supported; you must explicitly specify all elements to be loaded.

More than one load rule can appear in a config spec; you must have at least one to see any files in a snapshot view. (Load rules in the config spec of a dynamic view are ignored.)

Load rules can be positioned anywhere in a config spec, and their order is irrelevant.

An element can be selected by more than one load rule without causing an error.

In the context of loading a snapshot view, symbolic links can be characterized as VOB links, which point to objects inside the VOB, and non-VOB links, which point outside the VOB. Links are treated as follows:

• On UNIX® and Linux® systems, hard VOB links are followed; symbolic links are copy-created. Both VOB links and non-VOB links are resolved, if possible. If a symbolic link cannot be resolved because, for example, it is to an object that does not exist yet, the symbolic link is loaded but a warning is issued about the nonexistent link target.
• On Windows® systems, VOB links (both symbolic links and hard links) are followed. Both VOB links and non-VOB links are resolved, if possible. If a symbolic link cannot be resolved because, for example, it is to an object that does not exist yet, the load operation does not fail, but the symbolic link is not loaded and a warning is issued about the nonexistent link target.

UCM config specs are unlike config specs for base VersionVault in that they are generated by mkstream and regenerated from time to time by chstream and rebase. You can edit UCM config specs only as follows:

• To add custom element-selection rules
• To add custom load rules for snapshot views

Only custom rules that are correctly delimited are preserved when a UCM config spec is regenerated.

• Include a standard set of rules to be used by every user on a particular project.

  include /proj/cspecs/v1_bugfix_rules

• Modify the meaning of "most recent" to mean "as of 7 P.M. on July 10."

  time 10-Jul.19:00
         element \versionvault\lib\* ...\new\LATEST
         element * \main\LATEST
  end time

• Select version 3 on the main branch of a particular header file.

  element /usr/project/include/utility.h /main/3

• Select the most recent version on the main branch for all elements with a .c file name extension.

  element *.c \main\LATEST

• Select the most recent version on the bugfix branch.

  element * .../bugfix/LATEST

• Select versions of elements from a particular development branch, or with a related label.

  element * CHECKEDOUT
  element * ...\maint\LATEST	If no checked-out version, select latest version on the maint branch, which might or might not be a direct subbranch of main
  element * BL2.6	Else, select version labeled BL2.6 from any branch
  element * \main\LATEST

• Select versions of C language source files (.c file extension) based on the value of an attribute. A config spec such as this might be used by a developer to select versions of files for which he is responsible.

  element * CHECKEDOUT
  element -file *.c /main/{RESPONSIBLE=="jpb"}	For any .c file, select latest version on main branch for which jpb is responsible)
  element -file /project/utils/.../*.c /main/BL2.6	Else, select version labeled BL2.6 on main branch from /project/utils directory, or any of its subdirectories
  element * /main/LATEST

• Use the -mkbranch qualifier to create a new BL3 branch automatically. Create the branch from the version labeled BL2.6, or the latest version on the main branch if no version is labeled BL2.6.

  element * CHECKEDOUT
  element * ...\bl3_bugs\LATEST	If no version is checked out, select latest version on bl3_bugs branch)
  element -file * BL2.6 -mkbranch bl3_bugs	Else, select version labeled BL2.6 and create bl3_bugs branch on checkout
  element -file * \main\LATEST -mkbranch bl3_bugs	Else, select latest version on main branch and create new branch on checkout

• Same as above, but use a mkbranch rule.

  element * CHECKEDOUT
  element * .../bl3_bugs/LATEST
  mkbranch bl3_bugs
  element -file * BL2.6
  element -file * /main/LATEST
  end mkbranch bl3_bugs

• Select the version labeled REL3 for all elements, preventing any checkouts to this view:

  element * REL3 -nocheckout

• Select the most recent version on the bug_fix_v1.1.1 branch, making sure that this branch is a subbranch of bug_fix_v1.1, which is itself a subbranch of bug_fix_v1.

  element * CHECKEDOUT
  element * bug_fix_v1.1.1\LATEST
  element * ...\bug_fix_v1.1\LATEST -mkbranch bug_fix_v1.1.1
  element * ...\bug_fix_v1\LATEST -mkbranch bug_fix_v1.1
  element * \main\LATEST -mkbranch bug_fix_v1

  When a user checks out an element for which none of these branches yet exists, a cascade of auto-make-branch activity takes place:

  Z:\myvob> cleartool checkout -nc .
  Created branch "bug_fix_v1" from "." version "\main\0".
  Created branch "bug_fix_v1.1" from "." version
  "\main\bug_fix_v1\0".
  Created branch "bug_fix_v1.1.1" from "." version
  "\main\bug_fix_v1\bug_fix_v1.1\0".
  Checked out "."
  from version "\main\bug_fix_v1\bug_fix_v1.1\bug_fix_v1.1.1\0".

• Modify the previous config spec to create branch bug_fix_v2 off an existing branch rather than creating multiple subbranches.

  element * CHECKEDOUT
  mkbranch bug_fix_v2 -override
  element * .../bug_fix_v1.1.1/LATEST
  element * .../bug_fix_v1.1/LATEST -mkbranch bug_fix_v1.1.1
  element * .../bug_fix_v1/LATEST -mkbranch bug_fix_v1.1
  element * /main/LATEST -mkbranch bug_fix_v1
  end mkbranch bug_fix_v2

• For a snapshot view, select the most recent version on the main branch. Use load rules to select in the applets VOB all elements below the \cmdlg directory and one specific element in the \testdlg directory.

  element * CHECKEDOUT
  element *... \main\LATEST
  load \applets\cmdlg
  load \applets\testdlg\opendlg.h

• /opt/hcl/ccm/versionvault/default_config_spec
• view-storage-directory/config_spec
• view-storage-directory/.compiled_spec

• versionvault-home-dir\default_config_spec
• view-storage-directory\config_spec
• view-storage-directory\.compiled_spec

catcr, catcs, checkout, checkin, chstream, clearmake, cleartool, csh(1), describe, edcs, find, ls, lsvtree, mkbranch, mkdir, mkelem, mklabel, mkstream, rebase, setcs, setview, startview, update, version_selector, wildcards_ccase