version_selector

Version-selector syntax

APPLICABILITY

SYNOPSIS

• UNIX:

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 meta-data 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) 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:

SELECTION BY VERSION-ID

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

Examples:

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

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

SELECTION BY VERSION LABEL

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

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

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. Standalone labels can be ambiguous, however. 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, however, 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 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/filesystem-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-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.

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.

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 systems, you can use the describe command to work around this restriction:

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

SEE ALSO

config_spec, pathnames_ccase, query_language