version_selector

Version-selector syntax

Applicability

Product

Command type

VersionVault

general information

Platform

UNIX®

Linux®

Windows®

Synopsis

  • UNIX® and Linux®:
    • branch-pathname/version-number
    • [ branch-pathname ]/label
    • [ branch-pathname/ ]{ query }
  • Windows®:
    • branch-pathname\version-number
    • [ branch-pathname ]\label
    • [ branch-pathname\ ]{ query }

Description

A version selector identifies a version of an element in a version tree. You can use it with the –version command-line option, as part of a rule in a config spec, and as part of a version-extended pathname. The version selector has three general forms. Each identifies a version in a different way:

  • By version ID
  • By the version label attached to it
  • By a query on the metadata attached to it, or some other version characteristic

A version selector selects one version of an element, no version of an element, or generates an error, if ambiguous.

Branch pathnames

The branch pathname in a version selector identifies the branch on which a version resides. A branch pathname consists of a series of branch type names separated by slashes (UNIX® and Linux®) or backslashes (Windows®). The root of a version tree is the main branch (default name: main), which must be the first entry in the branch pathname unless you use the ellipsis wildcard (not valid in version-extended pathnames). Examples:

/main

main branch

\main\bugfix

bugfix branch, off the main branch

/main/motif/bugfix

bugfix branch, off the /main/motif branch)

\main\win32\bugfix\anne

jpb branch, off the \main\win32\bugfix branch

Selection by version ID

Selects the version with the specified version ID. This form requires a branch pathname.

Examples:

/main/2

Version 2 on main branch

/main/bugfix/5

Version 5 on bugfix branch off main branch

/main/motif/bugfix/1

Version 1 on subbranch of /main/motif branch

In a version-extended pathname, the version ID follows the element name and extended naming symbol (default: @@). For example:

hello.c@@\main\4

Version 4 on main branch of file hello.c

include@@\main\4\hello.h\main\3

Version 3 on the main branch of file hello.h, in version 4 on the main branch of directory include

Restriction: In a version-extended pathname, you cannot use the ellipsis wildcard (...):

include.h@@/.../bugfix/REL2

Is not valid

Selection by version label

Selects the version with the specified label. The branch pathname is optional, but the slash or backslash is required. Examples:

\main\LATEST

Most recent version on main branch

...\bugfix\REL2

Version labeled REL2 on a branch named bugfix, at any branching level

\main\bugfix\REL2

Version labeled REL2 on a bugfix branch that is a subbranch of main

\main\sunport\openlook\BUG3

Version labeled BUG3 on a particular third-level branch

REL2

Version labeled REL2 on any branch

Restriction: In a version-extended pathname, you cannot use the ellipsis wildcard (...):

include.h@@/.../bugfix/REL2

Is not valid

The label LATEST is predefined; it evaluates to the most recent version on each branch of an element. If the most recent version on the main branch is version 4, these two version selectors identify the same version:

\main\LATEST
\main\4

A version selector can consist of a standalone label, such as REL2. But standalone labels can be ambiguous. For example, /main/bugfix/REL2 and REL2 may or may not be equivalent for a given element:

  • If the REL2 label type was created as one-per-element (default), the two version selectors must be equivalent.
  • If REL2 was created with mklbtype –pbranch, the label can be used once per branch. If the label is actually attached to two or more versions of an element, an error occurs. No error occurs for elements that happen to have only one instance of a one-per-branch label type.

Version labels

Version labels appear as UNIX® or Linux® hard links or as additional Windows® file system objects in an element's directory tree in version-extended namespace. (See the pathnames_ccase reference page.) If a version label was defined to be one-per-element, an additional link/file system object appears at the top level of an element's directory tree. For example, if BL3 is a one-per-element label, these version-extended pathnames are both unambiguous references to the same version:

hello.c@@/BL3
hello.c@@/main/bugfix/patch2/BL3

In effect, this feature allows you to reference a version without knowing its exact location in the version tree.

If a label was defined with the –pbranch option, it does not appear in the element's top-level extended namespace directory (as implied earlier). Thus, if the one-per-element label, BL3, and the one-per-branch label, TEST_LBT, was attached to version \main\1 of file hello.c, its top-level extended namespace directory would look like this:

Z:\myvob\pr1> cd hello.c@@
Z:\myvob\pr1> dir
BL3 main

Selection by query

Selects the version that satisfies the specified query. The branch pathname is optional.

The query expression consists of one or more query primitives and operators, organized according to the syntax rules listed in the query_language reference page. Enclose the query expression in braces ({ }).

UNIX® and Linux—Quoting

Enclose the entire version selector in single quotes (' ')—or double quotes (" ") if it includes spaces or characters that have special meaning to the shell. Use double quotes to set off string literals within the query expression.

/main/{TESTED=="yes"}

The latest version on the main branch for which the TESTED attribute has the value yes

{hltype"(design_spec,<-)"}

The version on any branch that is the to-end of a hyperlink of type design_spec

/main/bugfix/"{!lbtype(REL2)}"

On bugfix branch, the latest version that is not labeled REL2

"{created_by(jpb)&&pool(sr1)}"

The version on any branch created by user jpb that is stored in the sr1 storage pool

Windows—Quoting

Additional quoting and/or character escaping conventions must be used, depending on the command interpreter you are using and whether or not you are using interactive mode cleartool.

The following examples assume interactive mode cleartool (cleartool> prompt), which removes the command interpreter's command-line processing behavior from consideration. In general, enclose the entire version selector in quotes if it includes spaces, and make sure to enclose string literals in double-quotes within the query expression.

\main\{TESTED=="yes"}

The latest version on the main branch for which the TESTED attribute has the value yes

"{hltype(design_spec,<-)}"

The version on any branch that is the "to" end of a hyperlink of type design_spec

\main\bugfix\"{!lbtype(REL2)}"

On bugfix branch, the latest version that is not labeled REL2

"{created_by(anne)&&pool(sr1)}"

The version on any branch created by user anne which is stored in the sr1 storage pool

Branch pathnames

If the version selector includes a branch pathname, the view_server selects the latest version on the branch that satisfies the query. If the version selector does not include a branch pathname, the view_server selects the version on any branch that satisfies the query. However, without a branch pathname, a query is ambiguous when more than one version of the element satisfies the query; versions on different branches, or two versions on the same branch, for example.

The version-selection operation fails if the query selects no version or is ambiguous.

A version-extended pathname can include a query, but is subject to the same restrictions as other version selectors of this form. That is, the query must select exactly one version to succeed. For example, this command displays the most recent version that has an attribute of type TESTED:

% cat include.h@@/"{attype(TESTED)}"

Note the use of quotes to prevent interpretation of the brace and parenthesis characters. As an alternative, you can quote the entire pathname:

Z:\vob_incl> type "include.h@@\{attype(TESTED)}"

If multiple branches have versions with a TESTED attribute, the version selector used in the examples above is ambiguous, and an error occurs.

Restriction: In a version-extended pathname, you cannot use both a branch pathname and a query:

% cat "include.h@@/main/{attype(TESTED)}"

Is not valid

% cat "include.h@@/main/rel2_bugfix/{attype(TESTED)}"

Is not valid

On UNIX® and Linux® systems, you can use the describe command to work around this restriction:

% cat ‘cleartool describe -s \
-ver /main/rel2_bugfix/"{attype(TESTED)}" include.h‘