ClearCase& ClearCase MultiSite commands

annotate    catcs    icon    magic    cd    chactivity    chbl    checkin    checkout    checkvob    chevent    chflevel    chfolder    chmaster    chown_container    chown_pool    chpool    chproject    chstream

annotate

The annotate command lists the contents of a version, annotating each line to indicate when, and in which version, the line was added. You can customize the annotations using the –fmt option, which is described in the fmt_ccase reference page. By default, annotate writes its output to a view private file with the .ann extension.
Syntax:
cleartool ann·otate [ –a·ll | –rm ] [ –nco ] [ –out pname ]
[ –s·hort | –l·ong | –fmt format[,hdr-format[,elide-format ] ] ]
[ –rmf·mt rm-format ] [ –nhe·ader ]
[ –nda·ta | –f·orce ] pname ...

catcs

The catcs command displays a view's config spec. This command does not require a product license.
Syntax:

cleartool catcs [ –tag view-tag ]

Examples:

To look at the config spec for the current view run cleartool catcs

To look at the config spec of view outside a View context run cleartool catcs -tag samecs_view

cc.icon, default icon

An icon file contains an ordered set of rules that maps file types to names of bitmap files, which contain icon bitmaps.

In xclearcase, a file browser uses a series of lookups to determine how to represent a file system object:

  1. It searches one or more magic files to determine the list of file types for the file system object. (See the cc.magic reference page for details.)
  2. It searches one or more icon files for a match with the first file type. Finding a match yields the name of a bitmap file. For example, this entry maps the file type text_file to the icon bitmap file name text: text_file : -icon text ;
  3. The semicolon (;) that terminates an icon rule must be preceded by white space.
  4. If no match can be found for the first file type, xclearcase searches the same set of icon files for a match with the second file type, and so on through the entire list of file types, if necessary. (If none of the file types produces a match in any icon file, an error occurs.)
  5. Having determined the name of a bitmap file, xclearcase searches for an actual file in one or more directories that contain bitmap files. (If it cannot locate a bitmap file with this name, an error occurs.)
  6. Bitmap file names must have a numeric extension, indicating the size of the bitmap. For example, text.40. xclearcase selects that bitmap file whose name begins with the string specified by –icon and whose size is 40x40 pixels.

If the file system object is selected, this process includes an extra step: xclearcase tries to match a –selected icon rule for each relevant file type before accepting a bitmap specified by –icon. For example, the following rule specifies both generic and “when selected” icons for use with elements of type text_file:

text_file : -icon text -selected text_selected;

Selecting and deselecting a text_file object from a file browser switches between the two icons.

(xxxxx)file-type [ file-type ... ] : icon-name ; . . .

File type to icon mapping rules (graphical interface)

cc.magic, default.magic

File-typing rules.
A magic file contains an ordered set of file-typing rules, which ClearCase and ClearCase LT use to determine a list of file types for an existing file system object or for one that is about to be created. (For information about predefined element types, see the mkeltype reference page.) A rule can use the object's name, its file(1) or stat(2) data, or its contents. File-typing involves searching one or more magic files for the first rule that matches a file system object. Finding a match yields a single file type or an ordered list of file types; failing to find a match produces an error.

On UNIX systems, file-typing is performed in the following situations:

  • When you create a new element with mkelem, but do not specify an element type (with –eltype), the element's name is file-typed. (If you are converting a view-private file to an element with mkelem –ci or mkelem –nco, the file's contents are also used in the file-typing.) The resulting file type list is compared with the VOB's set of element types (which includes both element types in the VOB and element types in the administrative VOB hierarchy associated with the VOB). The first file type that matches an element type is chosen as the element type; if no file type matches any existing element type, an error occurs:
  • The file browsers have a graphical mode, in which each file system object is displayed as an icon. The icon is selected first by file-typing the object, and then using one of its file types to select a bitmap from the ones listed in an icon file. (See the cc.icon reference page.)

Note: In an MVFS directory (any directory accessed through a VOB tag), file-typing by a browser uses only a file's name and its stat data; for performance reasons, the file's contents are not used.

On Windows, ClearCase and ClearCase LT perform file-typing when you create a new element with mkelem, but do not specify an element type (with –eltype). (If you are converting a view-private file to an element with mkelem –ci or mkelem –nco, the file's contents are also used in the file-typing.) The resulting file type list is compared to the VOB's set of element types (which includes both element types in the VOB and element types in the administrative VOB hierarchy associated with the VOB). The first file type that matches an element type is chosen as the element type; if no file type matches any existing element type, an error occurs:

cleartool: Error: Can't pick element type from rules ...

Following are examples of file-typing rules:

directory : -stat d ;
c_source source text_file : -printable & -name "*.c" ;
sh_script script text_file : -printable & (-name ".profile" | -name "*.sh") ;
archive library file: !-printable & -name "*.a" ;
File-typing rule:
file-type-list : selection-expression ;

File-type list:

file-type [ file-type ... ]

Selection expression:

selection-op [ arg(s) ] [ logical-op selection-op [ arg(s) ] ] ...

cd

Changing Directories in a Dynamic View

The cd command changes the current working directory, as does the UNIX cd(1) command. In ClearCase and MultiSite, this command is intended for use in interactive cleartool and multitool sessions and in shell scripts or batch files that simulate interactive sessions.

With a view-extended pathname, cd also changes your working directory view. The specified view's config spec determines which versions of elements are visible in your new working directory.

With a version-extended pathname that specifies an element or branch, cd changes your current working directory to a location in version-extended namespace, wherein element and branch names are treated like directories in a read-only file system. The best way to leave version-extended namespace is to change directories to a full pathname. Typing cd .. does not exit version-extended namespace until you ascend past the VOB root directory. (See the pathnames_ccase reference page.)

Changing Directories in a Snapshot View

The cd command changes the current working directory. If dir-pname specifies a snapshot view, cd changes the view context to that of the snapshot view.

Syntax:
cleartool cd [ dir-pname ]

chactivity (UCM)

The chactivity command modifies one or more activities. Use this command for these tasks:
  • Changing an activity's headline
  • Moving versions from the change set of one activity to the change set of another activity
  • In a single-stream project, closing an activity linked to ClearQuest
Syntax:

Change the headline or change set of an activity:

cleartool chact·ivity [ –c·omment comment | –cfi·le pname | –cq·uery | –cqe·ach
| –nc·omment ] { [ –hea·dline headline activity-selector ... ]
| [ –fcs·et src-activity-selector [ –tcs·et dest-activity-selector version-pname[,...] }

In a project enabled for ClearQuest, check ClearQuest policies and transition an activity accordingly:

cleartool chact·ivity [ –vie·w view-tag ] –cqact·ion
{ –cac·t | activity-selector ... }

chbl (UCM)

The chbl command modifies one or more baselines. You can modify a baseline's labeling status or assign a new promotion level to a baseline.
Syntax:
cleartool chbl [ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach | –nc·omment ]

{ [ [ –inc·remental | –fu·ll ] [ –nre·curse ] ]

[ –level promotion-level ] } baseline-selector ...

checkin

To create a new version of an element, checkin makes changes in the VOB and in the view.
Syntax:
cleartool checkin | ci [ –c·omment comment | –cfi·le comment-file-pname |–cq·uery
| –cqe·ach | –nc·omment ] [ –nwa·rn ]
[ –cr ] [ –pti·me ] [ –kee·p | –rm ] [ –fro·m source-pname ]
[ –ide·ntical ] { –cact | activity-selector ... | pname ... }

checkout

For one or more elements, the checkout command checks out a branch (typically, the most recent version on a branch). In most cases, this creates a writable copy of that version in the current view (the checked-out version), but see the “Checking Out a DO Version ” section.

Syntax:
cleartool checkout | co [ –res·erved ] [–unr·eserved [ –nma· ster ] ]
[ –out dest-pname | –nda· ta ] [ –pti·me ]
[ –bra·nch branch-pname | –ver·sion ] [ –nwa·rn ]
[ –c·omment comment | –cfi·le comment-file-pname | –cq·uery | –cqe·ach
| –nc·omment ][ –q·uery | –nq·uery ] pname ...

checkvob

checkvob can find and fix problems with storage pools, with hyperlinks, and with global types in an administrative VOB hierarchy. It can also find and fix inconsistencies between PVOBs, components, and an optional ClearQuest database in a UCM environment.

Syntax:

Check/fix storage pools

cleartool checkvob [ –vie·w view-tag ] [ –log log-dir-pname ]
[ –fix [ –f·orce ] [ –ign·ore ] ]
[ –dat·a ] [ –pro·tections ] [ –deb·ris ] [ –set·up ]
{
–poo·l [ –sou·rce ] [ –der·ived ] [ –cle·artext ]
{ vob-stg-pname | pname-in-vob } | [ –loc·k ]
file-pname ...
}
Examples:

cleartool checkvob-view samec_view -fix -force -pool -source /net/samecs/samecs.vbs

This command will check and fis the storage pools for a VOB. You will be prompted 3 times, respond "Yes" to the first, hit CR or a date, in the format 20-Apr-06.10:00:00, at the second prompt and "Yes" to the third prompt.

Check/fix hyperlinks

cleartool checkvob –hli·nks [ –to | –fro·m ] [ –hlt·ype hltype-selector ]
[ –f·orce ] [ –pna·me ] object-selector ...

Check/fix global types

cleartool checkvob –glo·bal [ –log log-pname ] [ –fix [ –f·orce ] ]
[ –acq·uire ] [ –pro·tections ] [ –loc·k | –unl·ock ]
{ vob-selector | global-type-selector }

Check/fix relationships between a UCM PVOB and a project's components or ClearQuest database

cleartool checkvob –ucm [ –vie·w view-tag ] [ –log log-dir-pname]
[ –fix [ –f·orce ] ]
[ –verbose ] [ –crm_only | –vob·_only ]
[ –com·ponent component-selector ] object-selector...

Check/fix relationships between a UCM PVOB and a ClearQuest database

checkvob –ucm [ –fix [ –f·orce ] ] [ –log log-dir-pname ]
[ –crm_db·name user-database-name ] { –act·ivity | –pro·ject } cq-display-name

chevent

The chevent command modifies or replaces the comment string in one or more existing event records. It is useful for correcting typing errors and for including information that was omitted in the original comment.
Syntax:
cleartool chevent [ –c·omment comment | –cfi·le comment-file-pname
| –cq·uery | –cqe·ach | –nc·omment ]
[ –app·end | –ins·ert | –rep·lace ]
{ –eve·nt [ –inv·ob vob-selector ] event-ID ...
| [ –pna·me ] pname ...
| object-selector ...
}

chflevel

The chflevel command raises the feature level of a VOB. A feature level is an integer that is incremented at each ClearCase and ClearCase LT release that introduces features that affect VOBs created in an earlier ClearCase or ClearCase LT release. The purpose of raising feature levels is to make all features in a release available to users of the VOB that was created in the earlier release.
Syntax:

Analyze and possibly raise the feature level of a VOB on the local host:

cleartool chflevel [ –f·orce ] –auto

Raise the feature level of a MultiSite replica:

cleartool chflevel -rep·lica feature-level replica-selector

Raise the feature level of a MultiSite VOB family:

cleartool chflevel [ –f·orce] ] [–ove·rride ] –fam·ily feature-level vob-selector

chfolder

The chfolder command moves a folder to another location in the folder hierarchy of a project VOB. The RootFolder cannot be moved.
Syntax:
cleartool chfolder [ –c·omment comment | –cfi·le comment-file-pname
| –cq·uery | –cqe·ach |–nc·omment ]
–to to-folder-selector folder-selector ...

chmaster

This command transfers the mastership of one or more objects from one replica to another. Only the current replica is affected immediately; other replicas are notified of the mastership transfers through the normal exchange of update packets.

Syntax:
cleartool chmaster [ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach | –nc·omment ]
{ master-replica-selector object-selector ...
| [ –pname ] master-replica-selector branch-or-element-pname ...
| –str·eam [ –ove·rride ] master-replica-selector stream-selector ...
| –def·ault [ –pname ] branch-pname ... | –def·ault brtype-selector ...
| –all [ –obsolete_replica old-replica-selector ]
[ –l·ong ] [ –vie·w view-tag ] master-replica-selector
}

chown_container (UNIX)

The chown_container command changes the

chown_pool (UNIX)

The chown_pool command changes the ownership and group on the remote pools  .vbs/s/sdft (source), .vbs/d/ddft (derived objects) and .vbs/c/cdft (ClearText)

Location:

opt/rational/clearcase/etc/

Syntax:

chownpool <vob owner>.<vob group> <stg_pool_dir>

Example:

chown_pool vobadm.samecs /net/samecs/ccvobstore/samecs.vbs/s/sdft

chown_pool vobadm.samecs /net/samecs/ccvobstore/samecs.vbs/d/ddft

chown_pool vobadm.samecs /net/samecs/ccvobstore/samecs.vbs/c/cdft

Note:

Don't forget to run:

cleartool protect -chown vobamd -recurse .

cleartool protect -chgrp samecs -recurse .

after you have run chown_pool to change the protections on the elements in the VOB. If you are using NAS to store VOB data you need to copy and run the chown_pool script on the device to change the permissions on the storage pools. (/vol/vol0/etc on NetApp).  There is also an issue with running chown_pool and chown_container on Linux where in older versions (and possible the current version) you need to add the following to the chown_pool and chown_container scripts.

xxxxxxx

chpool

The chpool command changes the source storage pool, derived object storage pool, or cleartext storage pool to which one or more elements are assigned.
Syntax:
cleartool chpool [ –f·orce ] [ –c·omment comment | –cfi·le comment-file-pname
| –cq·uery | –cqe·ach | –nc·omment ]
pool-selector pname ...

chproject (UCM)

The chproject command modifies one or more UCM projects in the following ways:
  • Adds one or more modifiable components to a project
  • Removes one or more components from the project's modifiable component list
  • Moves a project to another folder
  • Changes the promotion level required of a baseline before it can be recommended by a stream in the project
  • Sets policy for a project
  • Enables or disables a project for use with Rational ClearQuest
  • Defines the baseline name template
Syntax:
cleartool chproj·ect [ –c·omment comment | –cfi·le pname | –cq·uery
| –cqe·ach | –nc·omment ]
{
[ –amo·dcomp component-selector[,...] ]
[ –dmo·dcomp component-selector[,...] ]
[ –to to-folder-selector ] [ –reb·ase_level promotion-level ]
[ –pol·icy policy-keyword[,...] ] [ –npo·licy policy-keyword[,...] ]
[ –spo·licy policy-keyword[,...] ]
[ –crm·enable ClearQuest-user-database-name | –ncr·menable ]
[ –bln·ame_template baseline-naming-template ]
}
project-selector ...

chstream (UCM)

The chstream command allows you to set stream policies, specify the default deliver target for integration streams, and set recommended baselines.
Syntax:
cleartool chstream [ –c·omment comment | –cfi·le pname | –cq·uery
| –cqe·ach | –nc·omment ]
[ –tar·get stream-selector | –nta·rget ] [ –gen·erate ]
[ –pol·icy policy-keyword[,... ]] [ –npo·licy policy-keyword[,...] ]
[ –rec·ommended { baseline-selector[,...] | –def·ault }
| –nre·commended ]
{ stream-selector ... | –cvi·ew }

chtype

The chtype command changes the element type of one or more existing elements or renames one or more existing branches. These operations involve changing the type object associated with the element or branch.
Syntax:
cleartool chtype [ –c·omment comment | –cfi·le comment-file-pname
| –cq·uery | –cqe·ach | –nc·omment ]
[ –f·orce ] [ –pna·me ] type-selector
{ pname ... | object-selector ... }
Examples:

cleartool chtype binary_delta samecs.html 

This would change the type of samecs.html from text_file to binary_delta.

chview

The chview command changes various properties of a view, including the cache size, the type of DOs the view creates, and the access mode. The view server can be running when you enter this command.

Syntax:
cleartool chview { [ –cac·hesize size ] [ –sha·reable_dos | –nsh·areable_dos ]
[ –reado·nly | –readw·rite ] } { –cvi·ew | view-tag }

clearaudit

Non-clearmake build and shell command auditing facility for dynamic view. clearaudit can be used to document the work performed by any process. For example, you can use clearaudit to audit the creation of a UNIX tar(1) file or a Windows backup operation, producing a configuration record that describes exactly which files and/or versions were archived.

Location:

.../rational/clearcase/bin/

Syntax:

UNIX:

clearaudit [ [ –c ] shell_cmd ]

Windows:

clearaudit [ [ /c ] shell_cmd ]

clearbug

Creates problem report for Rational Customer Support. clearbug gathers information from your current processing context: date/time, version of operating system, versions of ClearCase or ClearCase LT tools, your UNIX and ClearCase or ClearCase LT contexts, system error logs, and so on.
Syntax:
clearbug [ –s·hort ] [ –p bug-priority ] [ –r yes/no ]
[ –l alternate-logfile-name ]

cleardescribe

Lists or changes the properties of an object graphically.
Location:

.../rational/clearcase/bin/

Syntax:

cleardescribe { object-selector | pname } ...

clearexport_ccase

The clearexport_ccase utility plays a central role in cross-VOB maintenance by copying VOB objects from one VOB to another, specifically:
  • Elements
  • All the elements and links cataloged within a directory
  • A hierarchy of directories, file elements, and VOB symbolic link
Location:

.../rational/clearcase/bin/

Syntax:
clearexport_ccase [ –r ]
[ [ –s date-time ] [–p date-time ] | –I { now | date-time } ]
[ –t temp-dir-pname ] [–T translation-pname ]
[ –o datafile-pname ] [ source-name ... ]

clearexport_cvs

The clearexport_cvs command processes Concurrent Versions Systems (CVS) files so they can be imported into ClearCase or ClearCase LT elements and versions.

Location:

.../rational/clearcase/bin/

Syntax:

clearexport_cvs [ –r [ –A ] ]

[ [ –s date-time ] [ –p date-time ] | –I { now | date-time } ]
[ –V ] [ –S ] [ –t temp-dir-pname ] [ –T translation-file ]
[ –o datafile-pname ] [ source-name ... ]

clearexport_pvcs

The clearexport_pvcs command processes PVCS files so they can be imported into elements and versions.

Location:

.../rational/clearcase/bin/

Syntax:

clearexport_pvcs [ –r ]
[ [ –s date-time ] [ –p date-time ] | –I { now | date-time } ]
[ –V ] [ –G ] [ –t temp-dir-pname ] [ –T translation-file ]
[ –o datafile-pname] [ source-name ... ]

Examples:

.../rational/clearcase/bin/clearexport_pvcs -r

This command will run recursively from the current directory and  create a cvt_data packet in the current directory ready for import by the clearimport command.

clearexport_rcs

The clearexport_rcs command processes Revision Control System (RCS) files so they can be imported into ClearCase or ClearCase LT elements and versions.

Location:

.../rational/clearcase/bin/

Syntax:

clearexport_rcs [ –r ]
[ [ –s date-time ] [ –p date-time ] | –I { now | date-time } ]
[ –V ] [ –S ] [ –t temp-dir-pname ] [ –T translation-file ]
[ –o datafile-pname ] [ source-name ... ]

clearexport_sccs

The clearexport_sccs command exports Source Code Control System (SCCS) files so that they can be imported into ClearCase or ClearCase LT elements and versions.

Location:

.../rational/clearcase/bin/

Syntax:

clearexport_sccs [ –r ]
[ [ –s date-time ] [ –p date-time ] | –I { now | date-time } ]
[ –V ] [ –t temp-dir-pname ] [ –T translation-file ]
[ –o datafile-pname ] [ source-name ... ]

clearexport_ssafe

clearexport_ssafe and clearimport allow you to copy SourceSafe files to a VOB. You can copy a single file, multiple files, or an entire project tree.

Location:

.../rational/clearcase/bin/

Syntax:

clearexport_ssafe [ –r ]
[ [ –s date-time ] [ –p date-time ] | –I { now | date-time } ]
[ –V ] [ –b target-branch [ –v version-id ] ] [ –T translation-file ]
[ –o datafile-pname] [ source-name]

clearfsimport

The clearfsimport command reads the specified file system source objects and places them in the target VOB.
Location:

.../rational/clearcase/bin/

Syntax:

UNIX only:

clearfsimport [ –preview ] [ –follow ] [ –recurse ] [ –rmname ]
[–comment comment ] [ –mklabel label ] [ –nsetevent ] [ –identical ]
[ –master ] [ –unco ] source-name [ . . . ] target-VOB-directory

Windows only:

clearfsimport [ –preview ] [ –recurse ] [ –rmname ]
[ –comment comment ] [ –mklabel label ] [ –nsetevent ]
[ –identical ] [ –master ] [ –unco ]
[ –downcase ] source-name [ . . . ] target-VOB-directory

cleargetlog (UNIX)

Starts the graphical log browser

Syntax:

cleargetlog [ –hos·t hostname | –cvi·ew | –tag view-tag | –vob pname-in-vob ]

clearhistory

Shows event records for VOB-database objects graphically

Location:

.../rational/clearcase/bin/

Syntax:

clearhistory [ –nop·references [ [ –min·or ] [ –nco ]
[ –use·r login-name ] [ –bra·nch branch-type-selector ] ] ]
[ [ –r·ecurse | –d·irectory | –a·ll | –avo·bs ]
[ –pna·me ] pname ...
| object-selector ...
]

clearimport

Reads data files created by clearexport tools and import elements into a VOB
Location:

.../rational/clearcase/bin/

Syntax:

UNIX only:

clearimport [ –v·erbose] [ –i·dentical] [ –n·setevent ] [ –master ]
[ –d·irectory destination-dir] [ –c·omment comment] [ –no·load ]
[ –nolab·eldir ] datafile

Windows only:

...\rational\clearcase\bin\clearimport [ –v·erbose] [ –i·dentical] [ –n·setevent ] [ –master ]
[ –pcase ] [ –d·irectory destination-dir] [ –c·omment comment]
[ –no·load ] [ –nolab·eldir ] datafile
Examples:
% cleartool setview samecs_view         (set a view) 
% cd /vobs/samecs/       (go to VOB directory where data is to be imported) 
% clearimport -c "CVS Import" ../../../src/cvt_data       (invoke clearimport) 

cleardiffbl (UCM)

The cleardiffbl command starts the diffbl browser, which compares two baselines and displays differences in terms of activities or versions.

Location:

.../rational/clearcase/bin/

Syntax:

cleardiffbl [ baseline-selector1 baseline-selector2 ]

clearjoinproj (UCM)

The clearjoinproj command starts the UCM Join Project Wizard, which takes you through the steps required to start work on an existing UCM project.

Syntax:

clearjoinproj

clearlicense

Monitors and controls the product license database

Location:

.../rational/clearcase/bin/

Example:

clearlicense [ –pro·duct product-name ] [ –hos·tid | –rel·ease [ username | user-ID ] ... ]

clearmake.options

clearmake build options specification (BOS) file. A build options specification (BOS) file is a text file that contains macro definitions and/or ClearCase special targets. We recommend that you place temporary macros (such as CFLAGS=–g (UNIX) or CFLAGS=/Zi (Windows) and others not to be included in a makefile permanently) in a BOS file, rather than specifying them on the clearmake command line.

clearmake

ClearCase build utility. clearmake is the ClearCase variant of the UNIX make(1) utility. It includes most of the features of UNIX System V make(1). It also features compatibility modes, which enable you to use clearmake with makefiles that were constructed for use with other popular make variants, including Gnu make.

Location:

.../rational/clearcase/bin/

Syntax:

UNIX only—Build a target:

clearmake [ –f makefile ] ...  [ –cukinservwdpqUNR ]
[ –J num ] [ –B bldhost-file ] [ –C compat-mode ]
[ –V | –M ] [ –O | –T | –F ]
[ –A BOS-file ] ... [ macro=value ... ] [ target-name ... ]

Windows only—Build a target

clearmake [ –f makefile ] ...  [ –cukinservwdpqUNR ]
[ –C compat-mode ] [ –V | –M ] [ –O | –T | –F ]
[ –A BOS-file ] ... [ macro=value ... ] [ target-name ... ]

Display version information for clearmake:

clearmake { –ver·sion | –VerAll }

clearmrgman

Manages the merging of versions graphically

Location:

.../rational/clearcase/bin/

Syntax:

Start the graphical user interface for a UCM deliver operation:
clearmrgman –del·iver [ –str·eam stream-selector]
[-to target-view-tag] [ –tar·get stream-selector ]
[ –q·uery | –qal·l ]

Start the graphical user interface for a UCM rebase operation:

clearmrgman –reb·ase [ –vie·w rebase-view-tag]
[–str·eam stream-selector] [ –q·uery | –qal·l ]

Start the Merge Manager:

clearmrgman [ –tta·g to-view-tag ]
[ { [ –fta·g from-view-tag | –fbr·anch branch-type
| –fla·bel label-type | –fve·rsion version-selector ]
[ –d·irectory | –nr·ecurse ]
[ –fol·low ] [ –noa·utomerge ] [ –q·uery | –qal·l ]
[ –a·ll vob-names | –avo·bs | pname... ] }
{ –fil·e mrgman-file }

clearprojexp (UCM)

The clearprojexp command starts the Project Explorer, a graphical utility that lets you create, manage, work in, or view UCM projects.

Location:

.../rational/clearcase/bin/

Syntax:

clearprojexp

clearprompt

The clearprompt command prompts the user for input, then either stores the input in a file or returns an appropriate exit status. clearprompt is designed for use in trigger action and GUI scripts.

Location:

.../rational/clearcase/bin/

Syntax:

UNIX only—Prompt for text:

clearprompt text –out·file pname [ –mul·ti_line ] [ –def·ault string

| –dfi·le pname ] –pro·mpt prompt_string [ –pre·fer_gui ]

UNIX only—Prompt for pathname:

clearprompt file –out·file pname [ –pat·tern match_pattern ]
[ –def·ault filename | –dfi·le pname ] [ –dir·ectory dir_path ]
–pro·mpt prompt_string [ –pre·fer_gui ]

UNIX only—Prompt for list:

clearprompt list –out·file pname [ –items choice[,choice] [ –choices ]
| –dfi·le pname ] –pro·mpt prompt_string [ –pre·fer_gui ]

UNIX only—Prompt for continue-processing choice:

clearprompt proceed [ –typ·e type ] [ –def·ault choice ]
[ –mas·k choice[,choice] ] –pro·mpt prompt_string [ –pre·fer_gui ]

UNIX only—Prompt for yes-no choice

clearprompt yes_no [ –typ·e type ] [ –def·ault choice ]
[ –mas·k choice[,choice] ] –pro·mpt prompt_string [ –pre·fer_gui ]

Windows only—Prompt for text:

clearprompt text –out·file pname [ –mul·ti_line ]
[ –def·ault string | –dfi·le pname ] –pro·mpt prompt_string

Windows only—Prompt for pathname:
 

clearprompt file –out·file pname [ –pat·tern match_pattern ]
[ –def·ault filename | –dfi·le pname ] [ –dir·ectory dir_path ]
–pro·mpt prompt_string

Windows only—Prompt for list:

clearprompt list –out·file pname [ –items choice[,choice] [ –choices ]
| –dfi·le pname ] –pro·mpt prompt_string

Windows only—Prompt for continue-processing choice:

clearprompt proceed [ –typ·e type ] [ –def·ault choice ]
[ –mas·k choice[,choice] ] –pro·mpt prompt_string [ –newline ]

Windows only—Prompt for yes-no choice:

clearprompt yes_no [ –typ·e type ] [ –def·ault choice ]
[ –mas·k choice[,choice] ] –pro·mpt prompt_string [ –newline ]
 
proceed choice is one of: proceed, abort
yes_no choice is one of: yes, no, abort
type is one of: ok, warning, error

cleartool

ClearCase and ClearCase LT user-level commands (command-line interface)

Syntax:

Single-command mode:
cleartool subcommand [ options/args ]

Interactive mode:

cleartool [ –e ] [ –status ]
cleartool> subcommand [ options/args ] 
cleartool> quit

Display version information for ClearCase or ClearCase LT, the kernel, and cleartool:

cleartool –ver·sion

Display version information for ClearCase or ClearCase LT, the kernel, cleartool, and the UNIX libraries or ClearCase or ClearCase LT DLLs on Windows that cleartool uses:

cleartool –VerAll

clearviewupdate

The clearviewupdate command provides a graphical user interface to the update command. For one or more loaded elements, clearviewupdate does the following:

Syntax:

clearviewupdate [ –ws pname ] [ –pname pname... ]

clearvobadmin (UNIX)

The clearvobadmin command starts the VOB Admin Browser, which you can use to perform various VOB operations—create, mount, lock, remove, and so on.

Syntax:

clearvobadmin [ –reg·ion region-name ]

comments

Each change to a VOB (checkin of new version, attaching of a version label, and so on) is recorded in an event record, which is created in the VOB database. Many commands allow you to annotate the event records that they create with a comment string. Commands that display event record information (describe, lscheckout, lshistory, lslock, lspool, lsreplica, and lstype) show the comments, as well. See the fmt_ccase reference page for a description of the report-writing facility built in to these commands.

config_ccase

ClearCase and ClearCase LT configuration. Most ClearCase configuration options can be set using a cleartool command or a ClearCase GUI. Only a few require you to edit a text file (on UNIX) or a Windows registry key as described here.

Files in /var/adm/rational/clearcase

Anyone can read the information in this directory, but only the root user can modify it.

license.db
(License server host only) The license database file, which defines a set of ClearCase licenses. See the Administrator's Guide

Files in /var/adm/rational/clearcase/config

Anyone can read and write information in this directory to configure the local host.

alternate_hostnames
If a host has two or more network interfaces (two or more separate lines in the /etc/hosts file or the hosts NIS map), you must create a file with this name on that host to record its multiple entries. For example, suppose that the /etc/hosts file includes these entries:
159.0.10.16 widget sun-005 wid
159.0.16.103 widget-gtwy sun-105 

In this case, the alternate_hostnames file should contain these names:

widget
widget-gtwy

Note that only the first host name in each hosts entry must be included in the file. The file must list each alternative host name on a separate line. There is no commenting facility; all lines are significant. If a host does not have multiple network interfaces, this file should not exist.

automount_prefix
By default, the UNIX automount program mounts remote directories under /tmp_mnt. If automount uses a different location, you must specify it in file /var/adm/rational/clearcase/automount_prefix. For example, if your automatic mounts take place within directory /autom, create an automount_prefix file containing this line:
/autom
bldserver.control
Controls the way in which a host is used during parallel builds. See Building Software.
license_host
(Required for each ClearCase host) Contains the name of the host that acts as the ClearCase license server host for the local host.
snapshot.conf
Configuration information for semi-live VOB backup. See the vob_snapshot reference page for more information.
admin.conf
Controls whether this host's Clearcase properties can be changed by a user logged on to a remote host.
db.conf
Configuration information for the file, vista.tjf, which is a journal of VOB updates. This file can grow large, especially as a result of such operations as rmver, rmview, rmtype, and scrubber. To limit the size of vista.tjf, create the file db.conf (in /var/adm/rational/clearcase/config) and add the line

–journal_file_limit bytes

where bytes may not be less than 5000000. Setting this value too low may degrade performance.

Files in /var/adm/rational/clearcase/rgy

Anyone can read these files but only the root user can modify them to configure the local host.

rgy_hosts.conf
Specifies this host's registry server and backup registry server hosts.
rgy_region.conf
Specifies this host's registry region.

DESCRIPTION—WINDOWS REGISTRY KEYS AND FILES

Values in Registry Key HKEY_LOCAL_MACHINE\SOFTWARE\Atria\ClearCase\CurrentVersion

If necessary, you can modify these values directly with a Windows Registry Editor.
Registry Key Description
snapshot Configuration information for semi-live VOB backup. See the vob_snapshot reference page for more information.
LockMgrCommandLine Startup options for the lockmgr. See the Administrator's Guide for more information.
DomainMappingEnabled Enables this host to use domain mapping (to support ClearCase access by users from multiple Windows NT domains), as described in the Administrator's Guide.

Files in ccase-home-dir\var\config

Anyone can read or write to this directory.
db.conf Configuration information for the file, vista.tjf, which is a journal of VOB updates. This file can grow large, especially as a result of such operations as rmver, rmview, rmtype, and scrubber. To limit the size of vista.tjf, create the file db.conf (in ccase-home-dir\var\config) and add the line –journal_file_limit bytes where bytes may not be less than 5000000. Setting this value too low may degrade performance.

config_spec

Rules for selecting versions of elements to appear in a view. A view's config spec (configuration specification) contains an ordered set of rules for selecting versions of elements. The view's associated view_server process populates a view with versions by evaluating the config spec rules.

Syntax:

Standard rule:

scope pattern version-selector [ optional-clause ]

Create-branch rule

mkbranch branch-type-name [ –override ] , ..., [ end mkbranch [ branch-type-name ] ]

Time rule:

time date-time, ... , [ end time [ date-time ] ]

File-inclusion rule:

include config-spec-pname

Load rule (for snapshot views):

load pname ...

Config Spec Storage / Default Config Spec

Each view is created with a copy of the default config spec, default_config_spec:

element * CHECKEDOUT For any element, select the checked out version, if any)
element * /main/LATEST Otherwise, select most recent version on the main branch

Modifying this file changes the config spec that newly created views receive, but does not affect any existing view.

An individual view's config spec is stored in its view storage directory, in two forms:

  • Source format. The user-visible version, config_spec, contains only the series of config spec rules.
  • Compiled format. A modified version, .compiled_spec, includes accounting information. This version is created and used by the view_server process.

Do not modify either of these files directly; instead, use the commands listed below. Different views' config specs are independent: they may contain the same set of rules, but changing one view's config spec never affects any other view.

Commands for Maintaining Config Specs

Commands for manipulating config specs:

catcs Lists a view's config spec
setcs Makes a specified file a view's config spec
edcs Revises the current config spec of a view
update –add_loadrules Adds load rules to the config spec of a snapshot view while updating the view

HOW A CONFIG SPEC SELECTS VERSIONS

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 isn't 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. ClearCase and ClearCase LT 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.

Order Is Important

Because the rules in a config spec are processed in order, varying the order may affect version selection. For example, suppose this rule appears near the beginning of a config spec:

element * /main/LATEST 

Any subsequent rules in the config spec will never be used, because the rule always provides a match; every element has a most-recent version on its main branch.

Note: The order in which the load rules for a snapshot view are specified is not important.

CHECKEDOUT Rule for Snapshot Views

The config spec for a snapshot view must contain element * CHECKEDOUT as the first element rule.

Failure to Select Any Version

If no version of an element matches any rule in the config spec:

  • In a dynamic view:
    • The element's data is not accessible through the view. The operating system listing command and other standard programs print a not found error when attempting to access the element.
    • The cleartool ls command lists the element with a [no version selected] annotation. You can specify the element in commands that access the VOB database only, such as describe, lsvtree, and mklabel.
  • In a snapshot view, the element will not be loaded.

View-Private Files

A view's config spec has no effect on the private objects in a view, such as view-private files, links, directories; or, in the case of a dynamic view, derived objects. View-private objects are always accessible.

Exception: (Dynamic views only) If a config spec lacks a CHECKEDOUT rule, the view-private file that is a file element's checked-out version is not visible. See “Special Version Selectors” below.

OVERALL SYNTAX GUIDELINES

Each config spec rule must be contained within a single physical text line; you cannot use a backslash (UNIX), 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 pathname in either single-quotes (‘) or double quotes (“).

In general, VOBs, views, and the ClearCase and ClearCase LT tools that access them are case-sensitive. Therefore, config spec rules must use case-correct pathnames.

You can use slashes ( / ) or backslashes ( \ ) as pathname separators in pathname patterns and version selectors unless you are sharing the config spec between UNIX and Windows hosts. In that case, you must use slashes. (See Sharing Config Specs Between UNIX and Windows Hosts.)

SHARING CONFIG SPECS BETWEEN UNIX AND WINDOWS HOSTS

Windows and UNIX 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 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. When the VOB tags diverge between regions, config spec element rules that use full pathnames (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 pathnames in element rules make sense. That is, a config spec with full pathnames 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 pathnames only, which do not include VOB tags.
  • Shared VOBs are registered with identical, single-component VOB tags in both Windows and UNIX 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.

Config Spec Compilation

An in-use config spec exists in both text file and compiled formats (both of which are visible in the view's storage directory). A config spec in its compiled form is portable. The restriction is that full VOB pathnames in element rules must be resolvable at compile time. A config spec is compiled if a client executes either of these cleartool commands: edcs or setcs –current. Therefore, if a client on the “wrong” operating system recompiles a config spec with one of these commands, the config spec becomes unusable by any client using that view. If this happens, recompile the config spec on the “right” operating system.

A sample element rule that could be problematic:

element /vob_p2/src/*    /main/rel2/LATEST

If the VOB is registered with VOB tag \vob_p2 on a Windows network region, but with VOB tag /vobs/vob_p2 on a UNIX network region, only Windows clients can compile the config spec.

Pathname Separators

When writing config specs to be shared by Windows and UNIX clients, use the slash (/), not the backslash (\), as the pathname separator in pathname patterns and version selectors. ClearCase and ClearCase LT on Windows can parse either separator in pathnames; ClearCase and ClearCase LT on UNIX recognizes the slash only.

STANDARD RULES

A standard version-selection rule takes this form:

scope pattern version-selector [ optional-clause ]

The following subsections describe these components.

Scope

The scope specifies that the rule applies to all elements, or restricts the rule to a particular type of element.

element
The rule applies to all elements
element –file
The rule applies to file elements only. This includes any element created with a mkelem command that omits –eltype directory (or a user-defined element type derived from the directory).
element –directory
The rule applies to directory elements only. This includes any element created with mkdir or mkelem –eltype directory (or a user-defined element type derived from the directory).
element –eltype element-type
The rule applies only to elements of the specified element type (predefined or user-defined). This mechanism is not hierarchical: if element type aaa is a supertype of element type bbb, the scope element –eltype aaa does not include elements whose type is bbb. To specify multiple element types, you must use multiple rules:
element –eltype aaa * RLS_1.2
element –eltype bbb * RLS_1.2

Selecting Versions of VOB Symbolic Links. There is no VOB symbolic link scope. A VOB symbolic link is cataloged (listed) in one or more versions of a directory element. The link appears in a view if both of these conditions are true:

  • One of those directory versions is selected by the view's config spec.
  • The config spec includes any element rule, even a –none rule.

Pattern

A pathname pattern, which can include any ClearCase or ClearCase LT wildcard (see the wildcards_ccase reference page for a complete list). For example:

*
Matches all element pathnames; does not match recursively.
*.c
Matches all element pathnames with a .c extension.
src/util.c
Matches any element named util.c that resides in any directory named src.
/vobs/project/include/util.h
Matches one particular element.
src/.../util.c
Matches any element named util.c that resides anywhere within the subtree of a directory named src (including in src itself).
src/.../*.[ch]
Matches all elements with .c and .h extensions located in or below any directory named src
src/...
Matches the entire directory tree (file elements and directory elements) starting at any directory named src.

Note: In non-config-spec contexts, the ... pattern matches directory names only.

Restrictions:

  • A view-extended pathname pattern is not valid.
  • A relative pathname pattern must start below the VOB tag (VOB mount point, VOB root directory). For example, if the VOB tag is /vobs/project, project/include/utility.h is not a valid pattern.
  • A full pathname pattern must specify a location at or beneath a valid VOB tag. For example, if the VOB tag is /vobs/project, then /vobs/project/... and /vobs/project/include/... are both valid.

The setcs or edcs command fails if it encounters an invalid location in any config spec rule:

cleartool: Error: No registered VOB tag in path: "..."
  • VOB symbolic links are not valid in pathname patterns.
  • On Windows systems, patterns can be specified using either backslashes (\) or slashes (/).

Version Selector

You can use a version label, version ID, or any other standard version selector. See the version_selector reference page for a complete list. Some examples follow:

/main/4
Version 4 on an element's main branch.
REL2
The version to which version label REL2 has been attached. An error occurs if more than one version of an element has this label.
.../mybranch/LATEST
The most recent version on a branch named mybranch; this branch can occur anywhere in the element's version tree
/main/REL2
The version on the main branch to which version label REL2 has been attached.

{created_since(yesterday)}

The version that has been created since yesterday. An error occurs if more than one version satisfies this query. Because all queries are evaluated at run time, the value yesterday is always interpreted relative to the day that the query is executed.
{QA_Level>3}
The version to which attribute QA_Level has been attached with a value greater than 3. An error occurs if more than one version satisfies this query
.../mybranch/{QA_Level>3}
The most recent version on a branch named mybranch satisfying the attribute query.

Standard version selectors cannot select checked-out versions in a config spec rule. (They can in other contexts, such as the find command.) Instead, you must use the special version selector, CHECKEDOUT, described below.

Special Version Selectors

The following special version selectors are valid only in a config spec rule, not in any other version-selection context:

CHECKEDOUT
Matches the checked-out version of an element, if this view has a pending checkout. It doesn't matter where (on which branch of the element) the checkout occurred; there is no possibility of ambiguity, because only one version of an element can be checked out to a particular view.

This special version selector actually matches the checked-out version object in the VOB database, which is created by the checkout command.

For file elements, standard commands access the view-private file created by checkout at the same pathname as the element.

–config do-pname [ –select do-leaf-pattern ] [ –ci ]
This special version selector replicates the configuration of versions used in a particular clearmake build. It selects versions listed in one or more configuration records associated with a particular derived object: the same set of versions that would be listed by a catcr –flat command. See the catcr reference page for explanations of the specifications that follow the –config keyword.

When you set or edit a config spec, the view_server resolves the do-pname with respect to the view's preexisting config spec, not on the basis of any preceding rules in the config spec being evaluated.

If the configuration records list several versions of the same element, the most recent version is selected to appear in the view. In such cases, a warning message is displayed when the config spec is set.

–none
Generates an ENOENT (No such file or directory) error when a standard UNIX operating system program references the element. For dynamic views:
  • No error occurs when an operating system listing command lists the element's entire parent directory; the element is included in such a listing. This also applies to other readdir situations, such as expansion of wildcard characters and emacs file name completion.

     
  • An error occurs when an operating system listing command names the element explicitly (perhaps after wildcard expansion) or whenever the name is processed with (UNIX) stat(2); in an ls –F command, when the entire directory is listed with ls –l, and so on.

     
  • The cleartool ls command always lists the element, annotating it with no version selected.

     
  • In ClearCase and ClearCase LT commands, the element's standard pathname refers to the element itself. (–none suppresses the transparency mechanism—translation of an element's standard pathname into a reference to a particular version.
–error
Like –none, except that the annotation generated by the cleartool ls command is error on reference.

Optional Clause

Some config spec rules can include an additional clause, which modifies the rule's meaning.

–time date-time
Modifies the meaning of the special version label LATEST: the rule selects from a branch the last version that was created before a particular time. The date-time argument is specified in one of the standard formats:

date.time | date | time | now where:

date := day-of-week | long-date
time := h[h]:m[m][:s[s]] [UTC [ [ + | - ]h[h][:m[m] ] ] ]
day-of-week := today |yesterday |Sunday | ... |Saturday |Sun | ... |Sat
long-date := d[d]month[[yy]yy]
month := January |... |December |Jan |... |Dec

Specify time in 24-hour format, relative to the local time zone. If you omit the time, the default value is 00:00:00. If you omit date, the default is today. If you omit the century, year, or a specific date, the most recent one is used. Specify UTC if you want to resolve the time to the same moment in time regardless of time zone. Use the plus (+) or minus (-) operator to specify a positive or negative offset to the UTC time. If you specify UTC without hour or minute offsets, Greenwich Mean Time (GMT) is used. (Dates before January 1, 1970 Universal Coordinated Time (UTC) are invalid.)

The creation times of the versions on the branch are looked up in their create version event records. (No error occurs if you use a –time clause in a rule that does not involve the version label LATEST; the clause has no effect.)

The –time clause in a particular rule overrides any general time rule currently in effect. (See Time Rules )

Note: A –time clause must precede any other optional clauses and may not include any query language constructs.

Examples:

/main/LATEST –time 10–Jul.19:00 Most recent version on main branch, as of 7 P.M. on July 10.
.../bugfix/LATEST –time yesterday Most recent version on a branch named bugfix (which can be at any branching level), as of the beginning of yesterday (12 A.M.).
/main/bugfix/LATEST –time Wed.12:00 Most recent version on subbranch bugfix of the main branch, as of noon on the most recent Wednesday.
–time 5–Dec.13:00 December 5, at 1 P.M.
–time 11:23:00 Today, at 11:23 A.M.
–time 12–jun–99 June 12, 1999, at 00:00 A.M.
–time now Today, at this moment.
–time 9-Aug.10:00UTC August 9, at 10 A.M. GMT.

The date/time specification is evaluated when you set or edit the config spec, and whenever the view_server process is started (for example, with startview or setview (dynamic views only)). Thus, the meaning of a relative specification, such as today, may change over time. However, the date/time is not evaluated at run time. Therefore 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.

–nocheckout
Disables checkouts of elements selected by the rule.
–mkbranch branch-type-name
Implements the auto-make-branch facility. When a version selected by this rule is checked out:
  • A branch of type branch-type-name is created at that version
  • Version 0 on the new branch is checked out, instead of the version that was originally selected

(This is a slight oversimplification. See the section “Multiple-Level Auto-Make-Branch”.) A mkelem command invokes the auto-make-branch facility if the config spec includes a /main/LATEST rule with a –mkbranch clause.

Restriction: You cannot use –mkbranch in combination with –none or –error.

Multiple-Level Auto-Make-Branch

A config spec can include a cascade of auto-make-branch rules, causing checkout to create multiple branching levels at once. checkout keeps performing auto-make-branch until version 0 on the newly created branch is not selected by a rule with a –mkbranch clause; then, it checks out that version. For example:

1 element * CHECKEDOUT
2 element * .../br2/LATEST
3 element * .../br1/LATEST -mkbranch br2
4 element * MYLABEL -mkbranch br1
5 element * /main/LATEST
1 element * CHECKEDOUT
2 element * ...\br2\LATEST
3 element * ...\br1\LATEST -mkbranch br2
4 element * MYLABEL -mkbranch br1
5 element * \main\LATEST

If you check out an element in a view that currently selects the version labeled MYLABEL:

  1. A branch of type br1 is created at the MYLABEL version, following the fourth rule.
  2. The third rule selects the newly created version .../br1/0, so a branch of type br2 is created at that version.
  3. Version .../br1/br2/0 is checked out. The checked-out version has the same contents as the MYLABEL version, and is selected by the first rule. When you edit and check in a new version, .../br1/br2/1, the view will select it with the second rule.

CREATE BRANCH RULES

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 may be nested. For example:

element * .../branch2/LATEST
mkbranch branch2

element * .../branch1/LATEST
mkbranch branch1

element * /main/LATEST

end mkbranch branch1
end mkbranch branch2

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

TIME RULES

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, and whenever the view_server process is started (for example, with startview or setview (dynamic views only)). Thus, the meaning of a relative specification, such as today, may 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 may be nested. They may not include any query language constructs.

FILE-INCLUSION RULES

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

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, 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 systems, hard VOB links are followed; symbolic links are copy-created. If a VOB link cannot be resolved, an error results. Non-VOB links are resolved, if possible, but it is not an error if they cannot be resolved.
  • On Windows systems, VOB links (both symbolic links and hard links) are followed. If a VOB link cannot be resolved, an error results. Non-VOB links are resolved, if possible. If they cannot be resolved, the load operation does not fail, but a warning is issued.

UCM CONFIG SPECS

UCM config specs are unlike config specs for base ClearCase and base ClearCase LT in that they are generated by mkstream and regenerated from time to time by chstream and rebase. You may 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.

Note: Never use UCM-generated rules in config specs for base ClearCase or base ClearCase LT.

Custom Element-Selection Rules

Add custom element-selection rules only between the custom element delimiters, as follows:

#UCMCustomElemBegin - DO NOT REMOVE - ADD CUSTOM ELEMENT RULES 
AFTER THIS LINE
rule
.
.
.
#UCMCustomElemEnd - DO NOT REMOVE - END CUSTOM ELEMENT RULES

The typical use for custom element selection is to add an include rule that enables the UCM view to see the contents of base ClearCase or base ClearCase LT VOBs. See File-Inclusion Rules.

Custom Load Rules

Add custom load rules after the custom load delimiter, as follows:

#UCMCustomLoadBegin - DO NOT REMOVE - ADD CUSTOM LOAD RULES AFTER THIS LINE
rule
.
.
.

See Load Rules for more information.

EXAMPLES

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.

  • 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 \atria\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 may or may 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 may 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 off 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

Further Examples:

countdb

The countdb utility count the files in a database.

Location:

...\rational\clearcase\etc\utils

Syntax:

countdb

cptype

The cptype command creates a new type object (for example, a label type or attribute type) that is a copy of an existing type object. The existing and new objects can be in the same VOB or in different VOBs. The copy can have the same name as the original only if you are making the copy in a different VOB.

Syntax:

cleartool cptype [–c· omment comment | –cfi·le comment-file-pname |–cq·uery
| –cqe·ach | –nc·omment ] [ –rep·lace ]
existing-type-selector new-type-selector

credmap (WIN)

Use the credmap utility to verify that your Windows NT user and group assignments match those on the UNIX side. credmap returns the following values:
  • The Windows NT username and the primary group name used by ClearCase or ClearCase LT
  • The UNIX user ID and primary group ID

Location:

...\rational\clearcase\etc\utils

Syntax:

credmap remote-host

creds

The creds utility displays user and group information for the currently logged-in user for the local Windows NT host. The value of the user's primary group is affected by the CLEARCASE_PRIMARY_GROUP environment variable. If this EV is set, creds displays its value, which is used only for ClearCase and ClearCase LT processing. If this EV is not set, creds displays the user's Windows NT primary group.

creds also displays the user's ClearCase/ClearCase LT privilege status:

You have ClearCase administrative privileges 
You are a member of the ClearCase administrators group.
You do not have ClearCase administrative privileges 
You are not a member of the ClearCase administrators group.

Location:

...\rational\clearcase\etc\utils

Syntax:

creds options

Options and arguments

By default, creds displays the credentials for the current user. Lookup is done on the local machine.

Some ClearCase and ClearCase LT operations cannot evaluate group membership information for more than 32 groups per user. If the user is a member of more than 32 groups, creds lists only the 32 groups used by all ClearCase and ClearCase LT operations.

-w
Lists all groups of which the user is a member. If the user is a member of more than 32 groups, this list will include some groups that some ClearCase and ClearCase LT operations do not consider when determining the user's identity
–h
Show options for this command.

Examples:

 

Display credentials for the current user.

c:\Program Files\Rational\ClearCase> \etc\utils\creds 
Login name:    jeri
UID:           0x10040a
Primary group: user (0x100432)
Groups:
user (0x100432)
doc (0x303eb)
Administrators (0x20220)
Users (0x20221)
Domain Users (0x100201)

Current user is ClearCase privileged

dbcheck

The dbcheck utilitiy conducts a database consistency check on a VOBs database

Location:

...\rational\clearcase\etc\utils\

Syntax:

dbcheck

deliver (UCM)

The deliver command lets you deliver work from a source stream to a target stream in the same or a different project. There may be several steps to delivering work:

  • Previewing the changes to be delivered
  • Identifying the activities, stream, or baselines you want to deliver
  • Resolving merge conflicts
  • Testing and building work in the target stream
  • Completing a deliver operation, which checks in new versions and records other information
Syntax:

Deliver changes in the source stream using the graphical user interface:

cleartool deliver –g·raphical [ –str·eam stream-selector ]
[ –to integration-view-tag ]
[ –tar·get stream-selector ] [ –q·uery | –qal·l]

Obtain the status of a deliver operation in progress:

cleartool deliver { –sta·tus [ –l·ong ] } [ –str·eam stream-selector ]

Cancel a deliver operation in progress:

cleartool delivercancel [ –str·eam stream-selector ]
[ –reset –to integration-view-tag ]

Preview a deliver operation:

cleartool deliver –pre·view [ –s·hort | –l·ong ] [ –str·eam stream-selector ]
[ –to integration-view-tag] [ –tar·get stream-selector ]
[ –cac·t | –act·ivities activity-selector ...
| –bas·elines baseline-selector ... ]

Deliver changes in the source stream:

cleartool deliver [ –str·eam stream-selector ] [ –to integration-view-tag]
[ –tar·get stream-selector ]
[ –cac·t | –act·ivities activity-selector ...
| –bas·elines baseline-selector ... ]
[ –com·plete ] [ –gm·erge | –ok ]
[–q·uery | –abo·rt | –qal·l ] [ –ser·ial ] [–f·orce ]

Resume or complete work on a deliver operation:

cleartool deliver { –res·ume |–com·plete } [–str· eam stream-selector ]
[ [ –reset ] –to integration-view-tag ] [ –gm· erge | –ok ]
[–q· uery | –ab·ort | –qal·l ] [ –ser·ial ] [ –f·orce ]

describe

The describe command lists information about VOBs and the objects they contain. For example:
  • Attributes and/or version labels attached to a particular version
  • Hyperlinks attached to a particular object
  • Predecessor version of a particular version
  • Views that have checkouts.
  • Views that have unshared derived objects in a particular VOB (describe –long vob:) (ClearCase dynamic views only)
  • Family feature level of a VOB or the replica feature level of a MultiSite VOB replica. This information is of interest only to MultiSite users.
Syntax:

ClearCase and MultiSite only—Describe objects in graphical format:

cleartool des·cribe –g·raphical { object-selector | pname } ...

ClearCase LT on Windows only—Describe objects in graphical format:

cleartool des·cribe –g·raphical { object-selector | pname } ...

Describe objects:

cleartool des·cribe [ –local ] [ –l·ong | –s·hort | –fmt format-string ]
[ –ala·bel { label-type-selector[,...] | –all } ]
[ –aat·tr { attr-type-selector[,...] | –all } ]
[ –ahl·ink { hlink-type-selector[,...] | –all } ]
{[ –cvi·ew][ –ver·sion version-selector | –anc·estor ]
[ –ihl·ink { hlink-type-selector[,...] | –all } ]
[ –pre·decessor] [ –pname ] pname...
|–type type-selector...
| –cact
| object-selector...
}

diff

The diff command calls an element-type-specific program (the compare method for the type) to compare the contents of two or more file elements or two or more directory elements. Typically, the files are versions of the same file element.

You can also use this command to compare ordinary text files.

diff uses the type manager mechanism to determine how to compare the specified objects.

Syntax:

Display differences graphically:

cleartool diff –g·raphical [ –tin·y ] [ –hst·ack | –vst·ack ] [ –pre·decessor ]
[ –opt·ions pass-through-opts ] pname ...

On UNIX, display differences nongraphically:

cleartool diff [ –tin·y | –win·dow ] [ –ser·ial_format
| –dif·f_format | –col·umns n ]
[ –opt·ions pass-through-opts ] [ –pre·decessor] pname ...

On Windows, display differences nongraphically:

cleartool diff [ –ser·ial_format | –dif·f_format | –col·umns n ]
[ –opt·ions pass-through-opts ] [ –pre·decessor] pname

diffbl (UCM)

The diffbl command compares the contents of two baselines or streams and displays any differences it finds. You can choose to see differences in terms of activities, versions, and for composite baselines, members. You can use the diffbl command to compare a baseline and a stream, a baseline and a baseline, or a stream and a stream. When specifying a stream, all baselines in the stream are used in the comparison as well as any changes in the stream that are not yet captured in a baseline. The diffbl command must be issued from a view context to display versions.

Syntax:

Display differences between two baselines or streams nongraphically:

cleartool diffbl [ –act·ivities ] [ –ver·sions ] [ –bas·elines ]
[ –fir·st_only] [ –nre·curse ]
{ baseline-selector1 | stream-selector1 }
{ baseline-selector2 | stream-selector2 }

Display differences between the specified baseline and its predecessor baseline nongraphically:

cleartool diffbl –pre·decessor [ –act·ivities ] [ –ver·sions ] baseline-selector

Display differences between two baselines graphically:

cleartool diffbl –g·raphical baseline-selector1 baseline-selector2

Display differences between the specified baseline and its predecessor baseline graphically:

cleartool diffbl –g·raphical –pre·decessor baseline-selector

diffcr

The diffcr command compares the configuration records (CRs) of two derived objects.
Syntax:
cleartool diffcr [ –r·ecurse | –fla·t ] [ –sel·ect do-leaf-pattern ]
[ –ci ] [ –typ·e { f | d | l } ... ]
[ –ele·ment_only ] [ –vie·w_only ]
[ –cri·tical_only ] [ –nam·e tail-pattern ]
[ –wd ] [ –nxn·ame ] [ –fol·low ] [ –l·ong | –s·hort ]
do-pname-1 do-pname-2

dospace

The dospace command displays data on VOB disk space used for shared derived objects. The report shows which views refer to shared DOs and shows how much disk space is used by the shared DOs that each view refers to.

Syntax:

cleartool dospace [ –upd·ate ] [ –sin·ce date-time ] [ –bef·ore date-time ]
[ –ref·eren
mber | –a·ll ] [ –siz·e size ] [ –reg·ion network-region ]
[ –poo·l pool-name ] vob-tag ...

Report disk space in raw format:

cleartool dospace [ –upd·ate ] –dum·p [ –reg·ion network-region ] vob-tag...

Generate and cache data on disk space used for local VOBs:

cleartool dospace –gen·erate [ –scr·ub days ] [ vob-tag ... ]

edcs

The edcs command revises a view's config spec by invoking a text editor on an existing config spec. The config spec can be one of the following:

  • The view's current config spec
  • A text file that you want to edit and then make the view's config spec. (If you don't need to edit the file, use setcs.)

Syntax:

cleartool edcs [ –tag view-tag ] [ file ]

ClearCase and ClearCase LT—Edit the config spec of a snapshot view:

cleartool edcs [ file ]

endview

The endview command deactivates the dynamic view. It removes all references to the view from the MVFS on the current host. The view-tag disappears from the MVFS directory (on Windows this directory is, by default, M:\). The –server option terminates the view's view_server process. Without –server, endview does not affect the view's availability from computers other than the current one.

Syntax:

cleartool endview [ –ser·ver ] view-tag

env_ccase

This reference page describes the environment variables (EVs) used by ClearCase, ClearCase LT, and MultiSite commands, programs, utilities, and software installation scripts. It also describes standard UNIX EVs that are particularly important for ClearCase, ClearCase LT, and MultiSite.

Environment Variables Common to UNIX and Windows

CCASE_ABE_START_TIMEOUT
Sets the maximum time allotted for starting the audited build executor (abe).
Default: 10 seconds.
CCASE_ABE_PN (or CLEARCASE_ABE_PN)
The full pathname with which clearmake invokes the audited build executor (abe) on a local or remote host during a parallel build. For more information about abe, see Building Software.
Default: ccase-home-dir/bin/abe
CCASE_AUDIT_TMPDIR (or CLEARCASE_BLD_AUDIT_TMPDIR)
Sets the directory where clearmake and clearaudit create temporary build audit files. If this variable is not set or is set to an empty value, clearmake creates these files in the directory specified by the TMPDIR (UNIX) or TMP (Windows) environment variable.

Note: On UNIX systems, clearmake creates these files in the /tmp directory if neither EV is set.

All temporary files are deleted when clearmake exits. If the value of CCASE_AUDIT_TMPDIR is a directory under a VOB tag, clearmake prints an error message and exits.

Note: Multiple build clients can use a common directory for audit files. Names of audit files are unique because clearmake names them using both the PID of the clearmake process and the host name of the machine on which the process is running.

Default for UNIX: /tmp

Default for Windows: None

CCASE_AUTO_DO_CI
Checks in DOs checked out by clearmake -c or omake -C unless the build of the corresponding target fails or the automatic checkout of the DO or a sibling DO fails. Checkout comments are preserved. The checkin is invoked with the -ptime option to preserve the DO's modification time.
Default: Undefined
CCASE_BLD_HOSTS
Specifies one or more build hosts on which clearmake must build targets. For more information, see Building Software.Default: Undefined.
CCASE_BLD_NOWAIT
Turns off clearmake's sleep-check cycle during a build. When this environment variable is set, clearmake does not check for a VOB lock (or wait for the VOB to be unlocked).
CCASE_BLD_VOBS
A list of VOB tags—separated by a space, tab, comma, or colon (UNIX), or by a semicolon (Windows)—to be checked for lock status during a build. If a VOB on this list is locked, clearmake goes into a sleep-check cycle.
CCASE_CONC (or CLEARCASE_BLD_CONC)
Sets the concurrency level in a clearmake build. This EV takes the same values as the –J option. Specifying a –J option on the clearmake command line overrides the setting of this EV.Default: None.
CCASE_DNVW_RETRY
Specifies time-out period, in minutes, for clearmake, omake, catcr, describe, or lsdo to wait before trying to contact an inaccessible view listed in its cache. To disable the cache, set CCASE_DNVW_RETRY to 0. For more information, see the clearmake or omake reference pages.Default: 60 minutes.
CCASE_HOST_TYPE (or CLEARCASE_BLD_HOST_TYPE)
Determines the name of the build hosts file to be used during a parallel build (–J option): file .bldhost.$CCASE_HOST_TYPE in your home directory. (Your home directory is determined by examining the password database.) See the clearmake reference page. For information about bldhost, see Building Software.Specifying a –B option on the command line overrides the setting of this EVC Shell Users: Set this EV in your .cshrc file, not in your .login file. The parallel build facility invokes a remote shell, which does not read the .login fileCCASE_HOST_TYPE can also be coded as a make macroDefault: None.
CCASE_MAKE_CFG_DIR (or CLEARCASE_MAKE_CONFIG_DIR)
In a makefile read by clearmake, expands to the full pathname of the clearmake configuration directory in the ClearCase installation area—typically ccase-home-dir/config/clearmake (UNIX) or ccase-home-dir\config\clearmake (Windows).
CCASE_MAKE_COMPAT (or CLEARCASE_MAKE_COMPAT)
Specifies one of clearmake's compatibility modes. This EV takes the same values as clearmake's –C option. Specifying –C on the command line overrides the setting of this EV.Default: None.
CCASE_MAKEFLAGS
Provides an alternative or supplementary mechanism for specifying clearmake command options. CCASE_MAKEFLAGS can contain the same string of key letters used for command-line options, except that options that take arguments are not allowed. Options on the clearmake command line override the setting of this environment variable, if there is a conflict. For more information, see Building Software.Default: None.
CCASE_OPTS_SPECS (or CLEARCASE_BLD_OPTIONS_SPECS)
A list of pathnames—separated by colons (UNIX) or semicolons (Windows)— each of which specifies a BOS file to be read by clearmake. You can use this EV instead of specifying BOS files on the clearmake command line with one or more –A options.Default: Undefined.
CCASE_SHELL_FLAGS (or CLEARCASE_BLD_SHELL_FLAGS)
Specifies clearmake command options to be passed to the subshell program that executes a build script command.Default for UNIX: Default for Windows: None.
CCASE_SHELL_REQUIRED
Forces clearmake to execute build scripts in the shell program you specify with the SHELL macro. To make clearmake execute builds scripts in the shell program, set this EV to TRUE. To allow clearmake to execute build scripts directly, unset the EV. Default: clearmake executes build scripts directly.
CCASE_USEPERL5
When set to any nonempty string, specifies that ClearCase Perl (UNIX) and ccperl (Windows) are to use Perl 5.0
CCASE_VERBOSITY (or CLEARCASE_BLD_VERBOSITY)
An integer that specifies the clearmake message logging level, as follows:
1 Equivalent to –v on the command line
2 Equivalent to –d on the command line
0 or undefined Equivalent to standard message logging level

If you also specify –v or –d on the command line, the higher value prevailsDefault: 0

CCASE_WINKIN_VIEWS
A list of white-space-separated view tags. If this environment variable is set, clearmake winks in only derived objects that were built in one of the specified views.
CLEARAUDIT_SHELL
The program that clearaudit runs in an audited shell. You must set this environment variable to the program's full pathname. For example, on UNIX:

/bin/csh or /usr/home/myscript

On Windows:

\windows\system32\cmd.exe or \users\anne\bin\myscript

Default on UNIX: clearaudit runs the program specified by the SHELL environment variable or, if SHELL is undefined, a Bourne shell (/bin/sh).

Default on Windows: clearaudit runs the program specified by the COMSPEC environment variable or, if COMSPEC is undefined, cmd.exe.

See also: SHELL.

CLEARCASE_AVOBS
A list of VOBs to process when you use the –avobs option in the find, findmerge, lscheckout, lshistory, or rmview commands. If this EV is not set, specifying –avobs invokes the command on all VOBs mounted on the host. If there are many such VOBs, the command can take a long time to complete.

Specify CLEARCASE_AVOBS as a list of VOB tags separated by commas, white space, or colons (UNIX) or by semicolons (Windows).

Default: None.

CLEARCASE_CMNT_PN
The pathname of the file in which cleartool and multitool cache the most recent user-supplied comment. Defining or removing this EV enables or disables comment caching.
CLEARCASE_OBSO_SYN
Commented out at MCK per RATLC00688566; this will likely be revived in a post-MCK release.

Detects instances of the obsolete option-argument style of specifying an object (see the cleartool reference page).

If you set this environment variable to the value WARN, it issues warnings when it detects obsolete syntax. When set to SILENT, it silently accepts obsolete syntax. When set to FAIL, it issues errors when it detects obsolete syntax.

Default: FAIL.

CLEARCASE_PERLLIB
Set to non-zero to force ccperl to ignore the PERLLIB environment variable, if it is set.
Default: Undefined. The HTML type manager looks for Perl libraries in the directory specified by the PERLLIB environment variable, if it is set. This can cause conflicts if PERLLIB refers to Perl installations other than ClearCase Perl. To prevent such conflicts, set this environment variable to a non-zero value.
CLEARCASE_PROFILE
The file that contains your ClearCase or ClearCase LT user profile, which includes rules that determine the comment option default for one or more cleartool and multitool commands. This setting must be a full pathname.
Default: For ClearCase and ClearCase LT, .clearcase_profile in your home directory.
CLEARCASE_TAB_SIZE
Specifies the tab width for output produced by cleardiff, xcleardiff, and source lines listed by the annotate command.
Default: 8
CLEARCASE_TRACE_TRIGGERS
A flag variable. If defined as a nonzero value, it causes all triggers to behave when they fire as if they were defined with the –print option. See the mktrtype reference page.
Default: Undefined.
CLEARCASE_VOBLOCKWAIT
(MultiSite only) Specifies the number of minutes for syncreplica to keep retrying exports or imports when the VOB is locked. During that time, syncreplica retries the write operation every minute. If the time elapses and the VOB is still locked, syncreplica exits with an error. For more information, see the syncreplica reference page in the Administrator's Guide for Rational ClearCase MultiSite.
EXPORT_REPLACE_CHAR
A character used by the clearexport_* utilities to replace invalid characters in exported label and branch names.
Default: . (period character)
EXPORT_REPLACE_COMM
A character string used in the data file created by clearfsimport as the comment for create version event records.
Default: made from flat file.
EXPORT_REPLACE_STRING
A character string used by the clearexport_* utilities to replace an invalid string in exported labels and branch names. This environment variable is used if the exporter cannot replace invalid characters with the EXPORT_REPLACE_CHAR EV.
Default: REPLACED
HOME
UNIX systems—Not used. ClearCase and ClearCase LT programs determine your home directory by reading the password database, not by using this environment variable.

Windows systems—User's home directory; must be set for ClearCase and ClearCase LT to work correctly. HOME is used to search for various resources, including file-typing information (see also the cc.magic reference page). HOME must be a full pathname, including drive specification. For example, C:\users\anne is a valid value; \users\anne is not.

Note: Windows sets two variables, HOMEDRIVE and HOMEPATH, which combine to specify the current user's home directory as supplied by the Administrator when the user account was created. So, unless HOMEDRIVE and HOMEPATH have been reassigned, HOME can be set to %HOMEDRIVE%%HOMEPATH%.

MAGIC_PATH
A colon—separated (UNIX) or semicolon-separated(Windows) list of directories to be searched for magic files. Various ClearCase and ClearCase LT programs consult magic files to perform file-typing on file system objects. See the cc.magic reference page.

Default for UNIX: home-directory/.magic:$CLEARCASEHOME/config/magic

Default for Windows: home-directory\.magic;ccase-home-dir\config\magic\

MAKEFLAGS
Provides an alternative (or supplementary) mechanism for specifying clearmake command options. MAKEFLAGS can contain the same string of keyletters used for command-line options, except that options that take arguments are not allowed. Options on the clearmake command line override the setting of this environment variable if there is a conflict.

See also the description of the CCASE_MAKEFLAGS environment variable.

Default: None.

SHELL
The default shell program to be run by various commands and programs, including the shell and setview commands. On UNIX, the clearaudit utility uses the value of SHELL if the environment variable CLEARAUDIT_SHELL is undefined.

Default for UNIX: Set by your shell program.

Default for Windows: Not set by most Windows shells; some shells that are ported from UNIX (for example, Hamilton csh, MKS korn sh, and so on.) may set it.

TZ
Time zone for the host. If the TZ environment variable is set to a value different from the time maintained by the operating system, the TZ time, not the system time, is used. In this case, file creation and change dates can be in error, and config specs do not work as expected.

Environment Variables for UNIX Only

CCASE_ABE_STARTER_PN
Specifies the pathname of the abe_starter link, which is by default a path to rsh. However, in environments where starting a remote shell is not allowed or is undesirable, you could, for example set this environment variable to the path to ssh.
Default: /usr/ucb/rsh.
CLEARCASEHOME
Installation directory for ClearCase, ClearCase LT, and MultiSite software. Set this EV before running the install_release script to specify a nonstandard installation location. On such hosts, users' shell startup scripts must use $CLEARCASEHOME/bin to specify the pathname of the ClearCase, ClearCase LT, or MultiSite executables.
Default: /opt/rational
ATRIA_NO_BOLD
A flag variable: if defined with a nonzero value, it suppresses generation of bold characters in cleartool and clearmake output.
Default: Undefined.
BITMAP_PATH
Bitmap file search path. The icons that an xclearcase directory browser displays for file system objects are stored in bitmap files. It searches in directories on this colon-separated search path for such bitmap files. See the cc.icon reference page.
Default: home-directory/.bitmaps:$CLEARCASEHOME/config/ui/bitmaps See also ICON_PATH.
CCASE_BLD_UMASK (or CLEARCASE_BLD_UMASK)
Sets the umask(1) value to be used for files created from a clearmake build script. It may be advisable to have this EV be more permissive than your standard umask—for example, CCASE_BLD_UMASK = 2 where umask = 22. The reason to create DOs that are more accessible than other files is winkin: a winked-in file retains its original ownership and permissions. For example, when another user winks in a file that you originally built, the file is still owned by you, is still a member of your principal group, and still has the permissions with which you created it. You can use the standard chmod command to change the permissions of a DO after you create it, and these permissions remain in effect while the DO is unshared. However, for a shared DO, you may need to use the standard chmod and protect –chmod to set appropriate permissions.

If you are using a tool that ignores umask (and hence CCASE_BLD_UMASK) settings and you want winkins to work correctly, you have to use chmod on the file in your build script to give it write permissions if the tool creates the file without these permissions.

CLEARCASE_BLD_UMASK can also be coded as a make macro.

Note: If you want to use CCASE_BLD_UMASK, do not set your umask value in your shell startup file. If you set the umask value in your startup file, the umask value is reset to its original value when clearmake starts a shell to run the build script. Setting CCASE_BLD_UMASK in your startup file has no effect.

Default: Same as current umask.

CCASE_GPATH_HINTS
NFS mount points to try when attempting to construct pathnames to remote storage.

When you set this environment variable to a quoted set of colon-separated mount points, the first valid mount point is used when constructing the global pathnames required by the following commands:

  • mkstgloc ... stgloc-pname

     
  • mkview ... dynamic-view-storage-pname

     
  • mkview ... snapshot-view-pname

     
  • mkvob ... vob-storage-pname

For example, when you use mkvob, the first valid entry in CCASE_GPATH_HINTS is used as the mount point when constructing the global path to vob-storage-pname. However, if you specify pathname information using options such as –host, –hpath, and –gpath, this environment variable is disregarded. When you set this environment variable to "", the argument specified as the storage pathname is treated literally. Default: When undefined, or if all specified mount points are invalid (that is, they cannot be used to construct a global path to a directory that exists and has execute (x) permission) one of the following mount points is used: /net, /hosts, /nfs. The mount points are tried in the order indicated, with the first one that yields a valid path being used.

CLEARCASE_DBG_GRP
Set this variable to a nonzero value to force xclearcase to print debugging information when executing button and menu commands in the graphical interface.
Default: None.
CLEARCASE_MSG_PROTO
Enables one-way message forwarding between ClearCase or ClearCase LT and an interprogram messaging system. This feature enables ClearCase and ClearCase LT to notify the messaging system that an operation succeeded (for example, a checkout) without going through an encapsulator. One-way message forwarding succeeds only if all programs involved have the same value for the DISPLAY environment variable.

For more information, see the softbench_ccase reference page.

Default: None. Supported values: SoftBench. See also DISPLAY, WINEDITOR.

CLEARCASE_ROOT
(Set by the setview command; do not set this variable yourself.) The full pathname of the root directory of a set view process, which is a process created by the setview command. For example, the command setview bugfix creates a shell in which CLEARCASE_ROOT is set to/view/bugfix .
Default: Not set in a process that was not created by setview.
DISPLAY
The X Window System display to use for ClearCase and ClearCase LT GUI utilities (and all other X applications). If you are using an interprogram messaging system, all your tools must have the same DISPLAY value.
Default: Undefined.
EDITOR, VISUAL
The pathname of a text editor. The edcs subcommand invokes the editor specified by the environment variable WINEDITOR (first choice), VISUAL (second choice), or EDITOR (third choice). xclearcase invokes the editor specified by the environment variable WINEDITOR (first choice) or EDITOR (second choice). See also WINEDITOR.
Default: vi
GRP_PATH
A colon-separated list of files and directories to be searched for group files when you start xclearcase.
Default: home-directory/.grp:ccase-home-dir/config/ui/grp
ICON_PATH
A colon-separated list of directories to be searched for icon files. xclearcase directory browsers use the bitmap images in such files as icons for file system objects. See the cc.icon reference page.
Default: home-directory/.icon:$CLEARCASEHOME/config/ui/icon See also BITMAP_PATH.
MANPATH
A colon-separated list of directories in which the UNIX man(1) command searches for reference pages. (The cleartool man and multitool man commands do not use MANPATH, but always search in $CLEARCASEHOME/doc/man.)
Default: Varies with operating system.
PATH
The standard UNIX program search path. To access ClearCase or ClearCase LT executables, change your search path to include directory $CLEARCASEHOME/bin. Default: Set by your shell program; typically modified in shell startup script.
Note: Do not specify an MVFS path as a value for PATH.
SCHEMESEARCHPATH
A colon-separated list of directories to be searched for scheme files, which contain X Window System resource settings. See the schemes reference page.
Default: /usr/lib/X11/%T/%N%:$CLEARCASEHOME/config/ui/%T/%N%S
TERM
The kind of terminal for which output is to be prepared. Certain cleartool commands produce output that use special terminal capabilities. For example, catcr uses a bold font to highlight information in a configuration record. To see bold characters in an xterm, set TERM to xterm, and provide a bold font with the X Toolkit option –fb or with the X resource xterm*boldFont. To prevent the control characters that enable bold from appearing in an emacs shell, set TERM to emacs in your emacs startup script, or set ATRIA_NO_BOLD.
Default: None; typically set in shell startup script.
WINEDITOR
An X Window System text editor application (for example, xedit(1)), which is invoked by xclearcase on a browser item. If WINEDITOR is undefined, xclearcase creates a terminal window, and runs the program specified by the EDITOR environment variable. If neither of these variables are defined, no editor is invoked.
Default: None.

Environment Variables for Windows Only

CLEARCASEHOME
Installation directory for ClearCase, ClearCase LT, and MultiSite; same as Windows Registry value HKEY_LOCAL_MACHINE\SOFTWARE \Atria\ClearCase\CurrentVersion\ProductHome. This EV is set by the albd_server when it runs a schedule request. For more information, see the schedule reference page. For information about albd_server, see the Administrator's Guide.

Note: You can create CLEARCASEHOME as a user or system environment variable, but the albd_server overwrites it when it runs a schedule request.

Default: Directory in which you installed ClearCase or ClearCase LT (the installation default is C:\Program Files\Rational\ClearCase)

CCASE_NO_ESC_PATT_CHARS
Overrides the \ escape character in clearmake GNU-compatible mode. For example, both clearmake –C gnu and GNU make assume that the string \% indicates the literal character, %, and do not treat the rule as a pattern rule. To prevent clearmake from using \ to indicate a literal character, set this environment variable to any non-null value.
CLEARCASE_PRIMARY_GROUP
Specifies which of the user's groups ClearCase should consider the primary group. Overrides the Windows primary group assignment for ClearCase operations. This environment variable must be a per-user variable (not a system variable) and must be set to a group that already appears in the user's group list.
CLEARCASE_GROUPS
Specifies a list of up to 32 groups that ClearCase considers first when determining or displaying which groups a user belongs to. Users who are members of more than 32 groups can set this environment variable to designate a subset of those groups that ClearCase considers when evaluating the user's group membership. The value of this variable is a semicolon-separated list of groups to which the user belongs. The list must not include the group that is specified in the environment variable CLEARCASE_PRIMARY_GROUP

CMAKE_PNAME_SEP

Sets the pathname separator for pathnames constructed by clearmake. This variable can be set in the makefile, in a BOS file, on the command line, or as an environment variable.
Default: If this variable is not set or is set to any other value than a slash (/) or a backslash (\), clearmake uses a backslash (\) as the pathname separator.
COMSPEC
The default command shell program to be run by various ClearCase or ClearCase LT commands and programs, including the shell command, and the clearaudit utility (if the environment variable CLEARAUDIT_SHELL is undefined).
Default: Set by Windows to cmd.exe
EDITOR, VISUAL
The pathname of a text editor. The edcs subcommand invokes the editor specified by the environment variable VISUAL (first choice) or EDITOR (second choice). If the pathname contains spaces, enclose the pathname in quotes. For example:
"C:\Program Files\tools\editor.exe"

Default: Notepad.

PATH
The standard executable program search path. The Install Wizard adds the directory ccase-home-dir\bin to your search path.

Default: Set from the system and user path values in the Windows registry.

Note: Do not specify an MVFS path as a value for PATH.

ProductHome (Windows NT Registry key value)
Installation directory for ClearCase and ClearCase LT software. This value is stored in the Windows registry key HKEY_LOCAL_MACHINE\SOFTWARE\Atria\ClearCase\CurrentVersion.
Default: C:\Program Files\Rational\ClearCase

events_ccase

Operations and event records

exports_ccase

List of VOBs to be accessed by non-ClearCase hosts

export_mvfs

Exports and unexports VOBs to NFS clients (non-ClearCase access)

file

cleartool file displays the element type ClearCase or ClearCase LT would use for the specified file if the file were converted to an element.

Syntax:

file [ –invob pname ] [ –all ] pname...

find

Uses a pattern, query, or expression to search for object

Find objects visible in the directory structure seen in the current view:
Syntax:
cleartool find pname ... selection-options action-options

Find all objects in the VOB:

cleartool find [ pname... ] –a·ll [ –vis·ible | –nvi·sible ] selection-options action-options
Find objects throughout all mounted VOBs:
cleartool find –avo·bs [ –vis·ible | –nvi·sible ] selection-options action-options, selection-options:
–nam·e pattern
–dep·th | –nr·ecurse | –d·irectory
–cvi·ew
–use·r login-name
–gro·up group-name
–typ·e { f | d | l } ...
–fol·low
–nxn·ame
–ele·ment query
–bra·nch query
–ver·sion query
ClearCase and ClearCase LT action-options (at least one required, multiple allowed):
–pri·nt
–exe·c command-invocation
–ok command-invocation ...

findmerge

Searches for versions that require a merge and optionally performs the merge.
Syntax:
cleartool findm·erge { pname ... | [ pname ... ] –a·ll
| –avo·bs | activity-selector ...fcs·ets }
{ –fta·g view-tag | –fve·rsion version-selector | –fla·test }
[ –dep·th | –nr· ecurse | –d·irectory ] [ –fol·low ] [ –vis·ible ]
[ –use·r login-name ] [ –gro·up group-name ] [ –typ·e { f | d | fd } ]
[ –nam·e pattern ] [ –ele·ment query ]
[ –nze·ro ] [ –nba·ck ] [ –why·not ] [ –log pname ]
[ –c·omment comment | –cfi·le comment-file-pname |–cq·uery | –cqe·ach
| –nc·omment ] [ –unr·eserved ]
[ –q·uery | –abort | –qal· l ] [ –ser·ial ]
{ –pri·nt [ –l·ong | –s·hort | –nxn·ame ]    
| –mer·ge | –okm·erge | –g·raphical |–gm ·erge | –okg·merge    
| –exe·c command-invocation    
| –ok command-invocation    
| –co } ...

fixprot (UNIX)

A utility to fix permission on VOB and View storage directories in the event of coruption.

fmt_ccase

Format strings for command output.

Syntax:

SYNOPSIS

  • –fmt option syntax (used in various reporting commands: annotate, describe, lshistory, lscheckout, and so on):
     
    –fmt "format-string"
    format-string is a character string, composed of alphanumeric characters, conversion specifications, and escape sequences. It must be enclosed in double quotes ( " ).
Conversion specifications:
 
%a Attributes (modifiers: N, S, [attr-name])
%c Comment string (modifiers: N)
%d Date (modifiers: S, V, N, A, MA, BA, OA)
%e Event description
%f Checked-out version information (modifiers: R, T, [text])
%h Host name
%i Indent level (modifier: [indent-level])
%l Labels (modifiers: C, N)
%m Object kind (version, derived object, and so on) (modifiers: K)
%n Name of object (modifiers: D, E, L, O, S, PS, PV, V, X)
%o Operation kind (checkin, lock, mkelem, and so on)
%p Property value (modifiers: [property], C, D, O, S, T)
%[c]t Starting column number (modifiers: N, S, T)
%u User/group information associated with the object's creation event (modifiers: F, G, L); see also %[owner]p and %[group]p.
%% % character
Escape sequences:
 
\n <NL>
\t <TAB>
\' Single quote
\\ Literal (uninterpreted) backslash
\nnn Character specified by octal code

DESCRIPTION

Many ClearCase and ClearCase LT commands read information from a VOB database, format the data, and send it to standard output. (In most cases, the information is stored in event records, written by the command when it creates or modifies an object in a VOB. See the events_ccase reference page.) Some of these commands have a –fmt option, which you can use to format simple reports on VOB contents. Note that –fmt is a mutually exclusive alternative to the –short and –long options.

The following example shows how output-formatting options affect an lshistory command.

cmd-context lshistory -since 1-Feb util.c
10-Feb.11:21 anne create version "util.c@@/main/rel2_bugfix/1"
 "fix bug: extra NL in time string"
10-Feb.11:21 anne create version "util.c@@/main/rel2_bugfix/0"
10-Feb.11:21 anne create branch "util.c@@/main/rel2_bugfix"

cmd-context lshistory -short -since 1-Feb util.c
util.c@@/main/rel2_bugfix/1
util.c@@/main/rel2_bugfix/0
util.c@@/main/rel2_bugfix

cmd-context lshistory -fmt "\tElement: %-13.13En Version: %Vn\n" -since 1-Feb util.c
Element: util.c Version: /main/rel2_bugfix/1
Element: util.c Version: /main/rel2_bugfix/0
Element: util.c Version: /main/rel2_bugfix 

(A \t escape sequence tabs output to the next tab stop. Tab stops occur at eight-character intervals, except as described in the annotate reference page.)

Note: In commands that output data on multiple versions, such as lshistory and lsvtree, formatting is applied to each version, not to the command output as a whole.

CONVERSION SPECIFICATIONS

A conversion specification identifies a particular data item to display and specifies its display format.

Syntax

%[ min ][.max ][ MODIFIER [, ... ] ]keyletter

The conversion specification format closely resembles that of the C-language function printf():

  • Percent sign (%)
  • Optionally, a minimum and/or maximum field display width specifier, of the form min.max (see “Specifying Field Width”.
  • Optionally (for some conversion specs), one or more modifier characters (uppercase) that specify one or more variants and/or a bracket-enclosed parameter (see the %a conversion specification)
  • A key letter (lowercase), which indicates the kind of data to display

Unlike printf() specifiers, conversion specifications are not replaced by arguments supplied elsewhere on the command line; they are replaced automatically by cleartool, usually with field values extracted from event records.

These are the conversion specifications:

%a
All attached attributes. Attributes are listed as attr-name=value pairs. These pairs are enclosed in parentheses and separated by a comma-space combination (,SPACE). Variants:
%Na No commas. Suppress the parentheses and commas in attribute list output; separate multiple attributes with spaces only.
%Sa Value only. Display attribute values only (rather than attr=value)
%[attype]a This attribute only. Display only the specified attribute, if it has been attached to the object
%c
Comment string. The user-supplied or system-generated comment stored in an event record. A newline character is appended to the comment string for display purposes only. Variant:
%Nc No newline. Do not append a newline character to the comment string.
%d
Date/Time. The time stamp of the operation or event, in date.time format. Variants:
%Sd (Short) Date only.
%Vd (Very long) Day of week, date, and time.
%Nd (Numeric) Date and time in numeric form — yyyymmdd.time (time reported in 24-hour format).
%Ad Age in days.
%MAd Age in months.
%BAd Age as a bar graph (longer bars for more recent events). A bar graph is drawn as a sequence of 0-5 number signs (#), representing the elapsed time since the reported operation as follows:
##### Less than a week
#### Less than a month
### Less than three months
## Less than six months
# Less than a year
  More than a year
%OAd Age as a bar graph (longer bars for older events). A bar graph is drawn as a sequence of 0-5 number signs (#), representing the elapsed time since the reported operation as follows:
##### More than a year
#### Less than a year
### Less than six months
## Less than three months
# Less than a month
  Less than a week
%e
Event kind; a brief description of the event. The event kind is derived from an event record's name, object kind, and operation kind fields. Sample event kinds:
create version
create branch
make hyperlink "Merge" on version
make label "REL2" on version
lock branch type
 
%f
Checked-out version information — For an element checked out to your view, the version ID of the checked-out element; for an element that is not checked out to your view, displays nothing. Variants:
%Rf Checkout status — reserved or unreserved.
%Tf View tag — the view tag of the view that checked out the element.
%[text]f Text — Displays text as a prefix to the version ID.
%h
Name of the host where the event originated (the host on which the user %u was running that user caused the event). The host name is as reported by uname(2) (UNIX) or as stored in the ComputerName key in the Windows Registry (Windows).

For a VOB replica, %h displays the name of the host at which the mkreplica –export command that created the replica was entered. For the original replica in a family, this is the host where the original VOB was located when the first mkreplica –export command was entered.

%l
Labels — For versions, all attached labels; the null string otherwise. Labels are output as a comma-separated list, enclosed in parentheses. A <SPACE> character follows each comma. Variants:
%Cl Max labels — Specify the maximum number of labels to display with the max-field-width parameter (see “Specifying Field Width”. If there are more labels, "..." is appended to the output. If no max-field-width is specified, the maximum default value is 3.
%Nl No commas — Suppress the parentheses and commas in label list output; separate labels with spaces only.
%m
Object kind — The kind of object involved in the operation. For example:
file
element
branch
version
stream
derived object
branch type
label type
Variant:
%Km Object selector kind — For example, brtype or lbtype. For more information about object selectors, see the cleartool reference page.
%n
Name of object — For a file system object, the extended pathname (including the version ID for versions, and the DO ID for derived objects); for a type object, its name. Variants:
%Dn Database identifier (DBID) — The unique database identifier of the object.
%En Element name — For a file system object, its standard file or element name, or its pathname; for a type object, its name.
%Ln Leaf name — For any named object, its simple name. The terminal node of a pathname. This modifier can be combined with others.
%On Object identifier (OID) — The unique identifier of a VOB object.
%Sn Short name — For a version, a short form of the version ID: branch-pathname/version-number. For other objects, the null string.
%PSn Predecessor Short name — For a version, a short form of the predecessor version's version ID: branch-pathname/version-number. For other objects, the null string.
%Vn Version ID — For a version or derived object, the version ID; for other objects, the null string.
%PVn Predecessor Version ID — For a version, the predecessor version's version ID; for other objects, the null string.
%Xn Extended name — Same as default

%n output, but for checked-out versions, append the extension @@\branch-pathname\CHECKEDOUT. For non-file-system objects, prints the object selector. For more information about object selectors, see the cleartool reference page.

%o
Operation kind — The operation that caused the event to take place; commonly, the name of a cleartool subcommand. For example:
mkelem
mklabel
checkin
checkout

See the events_ccase reference page for a complete list of operations and the commands that cause them.

%[p]p
Property value — Displays the value of the property specified in square brackets. The following tables list variants and the objects to which they apply. For ClearCase and ClearCase LT variants, see Table 4. For UCM variants, see Table 5. For MultiSite variants, see Table 6.
Table 4. Variants for ClearCase and ClearCase LT Objects
Variant Applies to Description
%[name]p All objects Same as %n, including variants.
%[object_kind]p All objects Kind of object. For example: version, file element, directory element, versioned object base, replica, branch type, and so on.
%[locked]p All objects that can be locked Lock status of the object: locked, unlocked, or obsolete.
%[activity]p Versions Activity whose change set contains the specified version.
%[version_predecessor]p Versions Version ID (branch pathname and version number) of the version's predecessor version.
%[type]p Versions, elements Name of version or element's element type (see type_manager for a list of element types); not to be confused with the object kind (for which the conversion specification is %m).
%[triggers]p Elements List of trigger types attached to element. Does not list all-element triggers. The list is displayed in the following format:

(trtype, trtype, trtype, ...)

%[triggers]Np Elements Suppresses parentheses and commas.
%[pool]p Elements, shared derived objects For an element, name of source pool. For a shared DO, name of DO pool.
%[pool]Cp Elements Name of cleartext pool.
%[pool]Dp Shared derived objects Name of derived object pool.
%[pool]Sp Elements Name of source pool.
%[DO_kind]p Derived objects Kind of derived object: shared, unshared, non-shareable.
%[DO_ref_count]p Derived objects Reference count for derived object.
%[slink_text]p VOB symbolic links Target of symbolic link, as displayed by cleartool ls.
%[slink_text]Tp VOB symbolic links Target of symbolic link, after link is traversed.
%[type_scope]p Metadata object types Object type's scope.

ordinary means that use of the type is limited to the current (or specified) VOB.

global means that the VOB is an administrative VOB and the type can be used in any client VOB of the administrative VOB or in any client VOB of a lower-level administrative VOB within an administrative VOB hierarchy.

local copy means that the type has been copied to the VOB from the administrative VOB that contains the master version of the type's definition.

%[type_constraint]p Branch types, label types Constraint on type object: one version per element or one version per branch.
%[trigger_kind]p Trigger types Kind of trigger type: element trigger, all element trigger, type trigger.
%[msdostext_mode]p VOBs State of MS-DOS text mode setting for VOB: enabled or disabled.
%[group]p   Group name.
%[owner]p (Windows only)   Login name of the object's current owner.
%[owner]Fp (UNIX only)   Login name of the objects‘ current owner. The optional F argument lists the owner's full name.

The variants in Table 5 apply only to UCM objects.

Table 5. Variants for UCM Objects
Variant Applies to Description
%[contrib_acts]p UCM activities Space-separated list of activities that contributed to the change set of an integration activity
%[crm_record_id]p UCM activities The ClearQuest record ID
%[crm_record_type]p UCM activities The ClearQuest record type
%[headline]p UCM activities The activity's headline
%[name_resolver_view]p UCM activities A “best guess” view for resolving the names of versions in a change set
%[stream]p UCM activities The stream that contains the activity
%[versions]p UCM activities Space-separated list of versions in activity's change set
%[versions]Cp UCM activities Separate items in list with comma and space
%[view]p UCM activities The view that the activity is set in
%[activities]Xp UCM baselines The baseline's activities
%[bl_stream]p UCM baselines The stream in which the baseline is created
%[component]p UCM baselines The component associated with the baseline
%[depends_on]p UCM baselines The baselines that the composite baseline directly depends on
%[depends_on_closure]p UCM baselines All of the baselines in the full dependence graph of a composite baseline
%[member_of]p UCM baselines The composite baselines of which the baseline is a direct member
%[member_of_closure]p UCM baselines All composite baselines of which the baseline is a direct or indirect member
%[label_status]p UCM baselines The label status of a baseline: full, incremental, or unlabeled
%[plevel]p UCM baselines The baseline's promotion level
%[initial_bl]Xp UCM components Initial baseline of the component
%[root_dir]p UCM components The root directory for the component
%[contains_folders]p UCM folders Subfolders of the folder
%[contains_projects]p UCM folders Projects contained by the folder
%[folder]p UCM folders The parent folder for the folder
%[crm_database]p UCM projects The name of the ClearQuest database
%[def_rebase_level]p UCM projects The promotion level required of a baseline before it can be used as the source of a rebase operation
%[dstreams]p UCM projects The project development streams
%[folder]p UCM projects The parent folder for the project
%[istream]p UCM projects The project integration stream
%[mod_comps]p UCM projects The modifiable components for a project
%[model]p UCM projects The project's model
%[rec_bls]p UCM projects The recommended baselines of a project's integration stream
%[plevels] UCM PVOBs The promotion levels defined by the PVOB
%[activities]p UCM streams Activities that are part of the stream
%[config_spec]p UCM streams Config spec of object
%[def_deliver_tgt] UCM streams The default stream that the stream will deliver to
%[dstreams]p UCM streams The child streams of an integration stream or a development stream
%[found_bls]p UCM streams The foundation baselines for the stream
%[latest_bls]p UCM streams Latest baseline in each component in a stream's configuration
%[project]p UCM streams The project the stream is part of
%[read_only]p UCM streams Boolean indicating whether the stream is read-only
%[rec_bls]p UCM streams The recommended baselines of an integration stream or a parent development stream
%[views]p UCM streams Views attached to the stream

The variants in Table 6 apply only to objects in replicated VOBs (ClearCase MultiSite product).

Table 6. Variants for Replicated Objects
Variant Applies to Description
%[master]p All objects that have mastership Name of object's master replica
%[master]Op All objects that have mastership OID of object's master replica
%[reqmaster]p Replicas, branch types, branches Request for mastership status of the object.

For a replica:

disabled means that requests for mastership are not enabled in the replica.

enabled means that requests for mastership are enabled in the replica.

For a branch type:

denied for all instances means that requests for mastership of any instance of the branch type are denied.

allowed for all instances means that requests for mastership of any instance of the branch type are allowed (unless mastership requests for the specific branch are denied).

denied for branch type means that requests for mastership of the branch type are denied .

allowed for branch type means that requests for mastership of the branch type are denied.

For a branch:

denied means that requests for mastership of the branch are denied.

allowed means that requests for mastership of the branch are allowed.

%[type_mastership]p Attribute types, hyperlink types, label types Kind of mastership of the type: shared or unshared.
%[replica_name]p VOBs Replica name of the specified VOB.
%[vob_replication]p VOBs Replication status of VOB: replicated or unreplicated.
%[replica_host]p Replicas Name of replica host.
%[c]t
Starting column number — Starts printing at the column number specified in square brackets. An overflow condition exists if the current position on the line is beyond the starting column number. By default, when an overflow condition occurs, the %t directive is ignored. Variants:
%[c]Nt When an overflow condition occurs, print a newline and resume printing at the starting column number.
%[c]St When an overflow condition occurs, print one space before printing the next value.
%[c]Tt When an overflow condition occurs, print a tab before printing the next value.
%u
Login name of the user associated with the event. Variants:
%Fu Full name of the user. This information is taken from the password database.
%Gu Group name of the user.
%Lu Login name and group of the user, in the form user.group.
%%
Percent character (%).

Specifying Field Width

A conversion specification can include an optional field width specifier, which assigns a minimum and/or maximum width, in characters, to the data field display. For example, the conversion specifier %10.15Lu will display, for each output line, the user's login name and group with a minimum of 10 characters (space padded if necessary) but not more than 15.

Usage rules:

  • A single number is interpreted as a minimum width.
  • To supply only a maximum width, put a decimal point before the number (for example, %.10En) or a zero and decimal point (%0.10En).
  • To specify a constant display width, set the minimum and maximum widths to the same value (%20.20c).
  • Values smaller than the specified minimum width are aligned on the right (padded left). A negative minimum width value (%–20.20c) aligns short values on the left.
  • Values longer than the specified maximum width are truncated from the right. A negative maximum width value (%15.–15Sn) truncates long values from the left.
  • A maximum width specifier has special meaning when used with the %Cl specifier. For example, %.5Cl prints a version's first five labels only, followed by "...".

Examples:

The UNIX examples in this section are written for use in csh. If you use another shell, you may need to use different quoting and escaping conventions.

The Windows examples that include wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you may need to change the wildcards and quoting to make your command interpreter process the command appropriately.

In cleartool single-command mode, cmd-context represents the UNIX shell or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.

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.

  • Format the output from lsco –cview.
    cmd-context lsco -cview -fmt "\t%-10.10n (from %8.8PVn) %d %u\n" 
    util.c (from /main/23) 18-Feb-03.14:12:48 anne
    main.c (from /main/46) 18-Feb-03.18:42:33 anne
    msg.c (from /bugfix/11) 19-Feb-03.10:45:13 anne
    msg.h (from /bugfix/3) 19-Feb-03.14:51:55 anne
  • Format the event history of a file element. (The command line, including the quoted format string, constitutes a single input line. The input line below is broken to improve readability. Spaces are significant.)
    cmd-context lshistory -fmt "OBJ-NAME: %-20.20n\n USER: %-8.8u\n DATE: %d\\n
    OPERATION:\t%-12.12o\n OBJ-TYPE:\t%-15.15m\n EVENT:\t%e\n 
    COMMENT: %c\n" util.c
     
    OBJ-NAME: util.c@@/main/3
    USER: anne
     DATE: 10-May-99.09:24:38
     OPERATION: checkin
     OBJ-TYPE: version
     EVENT: create version
     COMMENT: fix bug r2-307

    OBJ-NAME: util.c@@/main/2
     USER: anne
     DATE: 10-May-99.09:09:29
     OPERATION: checkin
     OBJ-TYPE: version
     EVENT: create version
    COMMENT: ready for code review
  • Describe a checked-out element, util.c.
    cmd-context describe -fmt "\tVer:\t%f\n\tPrefix:\t%[MY TEXT]%f\n\t Status:\t%Rf\n\tView:\t%Tf\n" util.c
      Ver:    /main/23
      Prefix: MY TEXT/main/23
      Status: reserved
      View:   eba_view
           
  • Display the type of a file element.
    cmd-context describe -fmt "Type:  %[type]p\n"  util.c@@
    Type: text_file
  • Display the target of a symbolic link and the target after the link is traversed.
    cmd-context describe –fmt "%n\t%[slink_text]p\t%[slink_text]Tp\n" link1.txt 
    link1.txt     file.txt     ..\dev\file.txt
  • Display the master replica of all label types in a VOB replica.
    cmd-context lstype –fmt "Label type: %n\tMaster: %[master]p\n" –kind lbtype 
    Label type: BACKSTOP    Master: evanston@/vobs/tromba
    Label type: CHECKEDOUT  Master: evanston@/vobs/tromba
    Label type: LATEST      Master: evanston@/vobs/tromba
    Label type: V3.4        Master: paris@/vobs/tromba
  • Display the name of an element, using tabular format. The command is a single input line; line breaks are added for readability.
    cmd-context describe -fmt
    "%[4]tName:%[6]t%[name]p\n
    %[4]tName:%[6]Nt%[name]p\n
    %[4]tName:%[6]St%[name]p\n
    %[4]tName:%[6]Tt%[name]p\n" util.c
       Name:util.c@@\main\30
      Name:
         util.c@@\main\30
      Name: util.c@@\main\30
      Name:        util.c@@\main\30
     
  • Mimic the output from lshistory –long. Note the use of single quotes to enclose the format string, which includes literal double quotes.
    cleartool lshistory -fmt '%d      %Fu (%u@%h)\n  %e "%n"\n  "%Nc"\n'  util.c 
    11-May-99.09:24:38     Anne Duvo (anne@neptune)
      create version "util.c@@/main/3"
      "fix bug r2-307"
    10-May-99.09:09:29     Ravi Singha (ravi@mercury)
      create version "util.c@@/main/2"
      "ready for code review"
    .
    .
    .
  • Mimic the output from lshistory –long. Note that in cleartool single-command mode, backslashes (\) are used to escape double quotes in the format string.
    cleartool lshistory -fmt "%d      %Fu (%u@%h)\n  %e \"%n\"\n  \"%Nc\"\n"  util.c 
    11-May-99.09:24:38     Anne Duvo (anne@neptune)
      create version "util.c@@\main\3"
      "fix bug r2-307"
    10-May-99.09:09:29     Ravi Singha (ravi@mercury)
      create version "util.c@@\main\2"
      "ready for code review"
    .
    .
    .
  • Describe the element main.c in detail. This example illustrates many of the conversion specifications (but does not use field width specifiers). Again, the command is a single input line; line breaks are added for readability.
    cmd-context describe -fmt "Name (default): %n\n 
    Element name: %En\n
    Leaf name: %Ln\n
    Short name: %Sn\n
    Predecessor short name: %PSn\n
    Version ID: %Vn\n
    Predecessor version ID: %PVn\n
    Extended name: %Xn\n
    Attributes: %a\n
    Attr values only: %Sa\n
    Attrs without commas or parens: %Na\n
    This attr only: %[Tested]a\n
    Comment: %c
    Date/Time: \tdefault: %d\n
    \t\tshort: %Sd\n
    \t\tlong: %Vd\n
    Age in days: %Ad\n
    Age in months: %MAd\n
    Age graph (long = new): %BAd\n
    Age graph (long = old): %OAd\n
    Host: %h\n
    Labels: %Cl\n
    Labels without commas or parens: %Nl\n
    Object kind: %m\n
    Operation kind: %o\n
    Event kind: %e\n
    User (default): %u\n
    Full user name: %Fu\n
    Group name: %Gu\n
    Long name: %Lu\n\n" main.c
     

    Name (default): main.c@@/main/34
    Element name: main.c
    Leaf name: 34
    Short name: /main/34
    Predecessor short name: /main/33
    Version ID: /main/34
    Predecessor version ID: /main/33
    Extended name: main.c@@/main/34
    Attributes: (Tested="yes", QAlevel=4, Responsible="anne")
    Attr values only: ("yes", 4, "anne")
    Attrs without commas or parens: Tested="yes" 
    QAlevel=4 Responsible="anne"
    This attr only: (Tested="yes")
    Comment: still needs QA
    Date/Time: default: 30-Jul-99.15:02:49
     short: 30-Jul-99
     long: Tuesday 07/30/99 15:02:49
    Age in days: 42
    Age in months: 1
    Age graph (long = new): ####
    Age graph (long = old): ##
    Host: neptune
    Labels: (Rel3.1C, Rel3.1D, Rel3.1E)
    Labels without commas or parens: Rel3.1C Rel3.1D Rel3.1E
    Object kind: version
    Operation kind: checkin
    Event kind: create version
    User (default): anne
    Full user name: Anne Duvo
    Group name: dev
    Long name: anne.de

Further Examples:

Using -fmt with cleartool lsco to do mass undo checkouts:

cleartool lsco -cview -avobs -fmt 'unco -rm "%n"\n' | cleartool

Using -fmt with cleartool lsco to do mass checkins:

cleartool lsco -cview -avobs -fmt 'ci \"Checking in by the administration team\" "%n"\n' | cleartool

get

Use the get command to copy a specified version of a file element into your snapshot view. You must issue the get command from the root directory of a snapshot view or any directory below it.

Syntax:

cleartool get –to dest-pname pname

getcache

The getcache command displays cache information for a view. In ClearCase dynamic views, you can also use getcache to get information on the multiversion file system (MVFS). View cache information includes cumulative statistics about the number of operations performed and the size of each of the view's caches. (You can specify the total size for the view's caches with the setcache command; that total is allocated among the individual caches.) getcache can also reset the view or MVFS statistics with the –reset option.

Syntax:

Display/reset statistics for a view:

cleartool getcache –vie·w [ –a·ll | –s·hort ] [ –reset ] { –cvi·ew | view-tag }

Display the default cache size for the current host:

cleartool getcache –vie·w –hos·t

Display the site-wide default size for view caches:

cleartool getcache –vie·w –sit·e

ClearCase dynamic views—Display cache information for the MVFS:

cleartool getcache –mvfs [ –per·sistent ] | { [–s·hort ] [–reset ] }

getlog

The getlog command displays extracts from one or more log files (UNIX) or log entries (Windows). Run getlog –inquire to return a list of the available logs.

ClearCase—Display logs graphically:
Syntax:
cleartool getlog –g·raphical [ –hos·t hostname | –cvi·ew | –tag view-tag
| –vob pname-in-vob ]

ClearCase—Display logs nongraphically:

cleartool getlog [ –las·t [ #_lines ] | –fu·ll | –sin·ce date-time
| –aro·und date-time [ #_minutes ] ]
[ –hos·t hostname | –cvi·ew | –tag view-tag | –vob pname-in-vob ]
{ –a·ll | log-name ... }

ClearCase—Display the current set of logs:

cleartool getlog –inq·uire [ –hos·t hostname ]

help

Displays help on command usage.

Syntax:

cleartool h·elp [ command-name ]
command-name –h·elp

hostinfo

Displays configuration data for one or more hosts
Syntax:
cleartool hostinfo [ –l·ong ] [ –pro·perties [ –ful·l ] ] [ hostname ...

init_ccase (UNIX)

Startup/shutdown script

SYNOPSIS

AIX 4, MP-RAS /etc/rc.atria { start | stop }
Digital UNIX, HP-UX 10, HP-UX 11 /sbin/init.d/atria

{ start | stop }

Solaris, IRIX, Reliant UNIX, UnixWare /etc/init.d/clearcase

{ start | stop }

DESCRIPTION

The shell script listed in the Synopsis section is invoked at system startup and shutdown. It can also be executed as a shell command.

CLEARCASE AND CLEARCASE LT STARTUP

When invoked with the argument start (or without an argument), the script performs initialization as follows:

  • Starts the Location Broker Daemon, albd_server.
  • Starts the database lock manager process, lockmgr.
  • (On Solaris, AIX 4, Digital UNIX, UnixWare) Dynamically loads the MVFS (multiversion file system) into the operating system kernel.
  • Initializes the viewroot directory (default name /view).
  • Mounts public VOBs listed in storage registry. If the network is partitioned into multiple network regions, only the VOBs that have public VOB-tags in the local host's region are mounted.
  • Exports VOBs through particular views to enable access by non-ClearCase hosts; the list of VOBs to be exported is read from the ClearCase file /etc/exports.mvfs (all platforms except Digital UNIX) or /etc/exports (Digital UNIX).

Startup Retry Loop

The startup script resides outside the host's ClearCase or ClearCase LT installation area. It calls on another script, which resides inside the installation area, to do the actual startup processing. If this other script, ccase-home-dir /etc/clearcase, cannot be accessed, the startup script enters a retry loop. (This can occur when the ClearCase or ClearCase LT installation area is located on a remote host and that host is currently unavailable.)

In its retry loop, the startup script tries periodically to invoke ccase-home-dir/etc/clearcase.The retries continue indefinitely; if you want to terminate the loop, remove the flag file /tmp/ClearCase.retrying.

The Viewroot Mount Command

The startup script runs a standard mount command to mount the viewroot directory as a file system of type MVFS. This mount command is architecture specific:

Architecture Command
AIX 4 mount –v mvfs –o rw,viewroot hostname:/view /view
Digital UNIX mount –t mvfs –o –o=rw,–o=viewroot /view /view
IRIX, MP-RAS mount –t mvfs –o rw,viewroot /view /view
Reliant UNIX, HP-UX 10, HP-UX 11 mount –F mvfs –o rw,viewroot /view /view
Solaris, UnixWare mount –F mvfs –o rw,viewroot hostname:/view /view

You can change the extending naming symbol by appending a string to the argument that follows the –o option:

,xnsuffix=symbol All platforms except Digital UNIX
,–o=xnsuffix=symbol Digital UNIX

This specifies a character string to be used on the local host as the ClearCase extended naming symbol. By default, the string @@ is used. Be careful: this option affects the local host only; other hosts may use the default extended-naming symbol or another symbol specified with this mount option.

You can specify a directory other than /view as the viewroot. Whatever directory you specify (for example, /ccasevu) must exist at system startup time. Note that you must specify this directory name twice in the mount command.

Mounting the viewroot directory enables use of ClearCase views on the local host. When a view is activated (by startview, setview, or mktag), its view tag is entered into the viewroot directory. For example, activating a view whose view tag is gamma creates the directory entry /view/gamma. See the pathnames_ccase reference page for a discussion of view-extended pathnames that use such directory entries.

A mounted viewroot directory is not actually an on-disk directory. Rather, it is a data structure maintained in main memory by the MVFS code loaded into the operating system kernel. The viewroot directory's list of view tags is lost whenever ClearCase operation on the local host is stopped (including an operating system shutdown).

The viewroot directory cannot be exported and cannot be mounted by any other host. Each ClearCase host must have its own viewroot directory.

SHUTDOWN

When invoked with the argument stop, the script shuts down ClearCase or ClearCase LT as follows:

  • Unexports any view/VOB combinations that were exported through /etc/exports.mvfs to enable non-ClearCase access
  • (On Solaris, Digital UNIX, Reliant UNIX) Kills all user processes that are using the MVFS (multiversion file system)
  • Unmounts all VOBs
  • Kills the vob_server processes for VOBs whose storage directories are on the local host
  • Kills the albd_server process, which also causes view_server, db_server, and vobrpc_server processes to exit
  • Kills the lockmgr process
  • (On Solaris, AIX 4, Digital UNIX, UnixWare) Unloads the MVFS from the operating system kernel
  • Unmounts the viewroot directory

Intro

Introduction to ClearCase, ClearCase LT, and ClearCase MultiSite Reference pages

ln

The links created with the ln command (VOB symbolic links or VOB hard links) are cataloged in directory versions, in the same way as elements. By default, a link can be created in a directory only if that directory is checked out. A VOB link becomes visible to those using other views only after you have checked in the directory in which you created the link. (ln appends an appropriate default checkin comment to the directory version.)

Syntax:

Create one link:
cleartool ln [ –s·link ] [–c·omment comment | –cfi·le comment-file-pname
|–cq·uery | –cqe·ach | –nc·omment ]
[ –nco [ –f·orce ] ] pname target-pname

Create one or more links in a specified directory:

cleartool ln [ –s·link ] [ –c·omment comment | –cfi·le comment-file-pname
|–cq·uery | –cqe·ach | –nc·omment ]
[ –nco [ –f·orce ] ] pname [ pname ... ] target-dir-pname

lock

The lock command creates a lock on an entire VOB or on one or more file system objects, type objects, or VOB storage pools.

Syntax:

cleartool lock [ –rep·lace ] [ –nus·ers login-name[,...] | –obs·olete ]
[ –c·omment comment | –cfi·le comment-file-pname |–cq·uery | –cqe·ach
| –nc·omment ] { [ –pna·me ] pname ... | object-selector ... }

ls

The ls command lists VOB-resident objects, elements loaded into a snapshot view, and view-private objects in a directory.

Syntax:

cleartool ls [ –r·ecurse | –d·irectory ] [ –l·ong | –s·hort ] [ –vob·_only
| –vie·w_only ] [ –nxn·ame ] [ –vis·ible ] [ pname ... ]

lsactivity (UCM)

The lsactivity command lists information about UCM activities.
List information about UCM activities:

Syntax:

cleartool lsact·ivity [ –s·hort | –l·ong | –fmt format-string
| –anc·estor [ –fmt format-string ] [ –dep·th depth ]
[ –obs·olete ] [ –inv·ob vob-selector | –in stream-selector-name
| activity-selector ... | [ [–cac·t | -me | -use·r username ]
[ –vie·w view-tag | –cvi·ew ] ] ]

List activities or baselines that contributed to the change set of an integration activity:

lsact·ivitycontrib activity-selector

lsbl (UCM)

The lsbl command lists information for one or more baselines.

Syntax:

List baseline information per stream or component or by promotion level:
cleartool lsbl [ –s·hort | –l·ong | –fmt format-string | –tre·e
| –mem·ber_of [ –r·ecurse ] ]
[ –lev·el promotion-level | [ –ltl·evel promotion-level ]
[ –gtl·evel promotion-level ] ]
[ –com·ponent component-selector ] [ –obs·olete ]
[ –str·eam stream-selector | –cvi·ew ]

List information for one or more specific baselines:

lsbl [ –s·hort | –l·ong | –fmt format-string | –tre·e
| –mem·ber_of [ –r·ecurse ] ] [ –obs·olete ] [ baseline-selector ... ]

lscheckout

The lscheckout command lists the checkout records (the checkouts) for one or more elements. There are many controls for specifying the scope: which elements, directories, or VOBs; which user; which view; and so on.

Syntax:

List checkouts:
cleartool lsc·heckout | lsco [ –l·ong | –s·hort | –fmt format-string ]
[ –cvi·ew ]
[ –brt·ype branch-type-selector ]
[ –me | –use·r login-name ]
[ -r·ecurse | -d·irectory | -a·ll | -avo·bs ] [ -are·plicas ]
[ pname ... ]
On Windows, list checkouts graphically:
lsc·heckout –g·raphical pname

Examples:

Using cleartool lsco to do mass undo checkouts:

cleartool lsco -cview -avobs -fmt 'unco -rm "%n"\n' | cleartool

Using cleartool lsco to do mass checkins:

cleartool lsco -cview -avobs -fmt 'ci \"Checking in by the administration team\" "%n"\n' | cleartool

lsclients

Displays the client host list for a ClearCase license or registry server host.

Syntax:
cleartool lsclients –hos·t hostname [ –typ·e { registry | license | all } ]
[ –s·hort | –l·ong ]

lscomp (UCM)

The lscomp command lists information about one or more components.
Syntax:
cleartool lscomp [ –s·hort | –l·ong | –fmt format-string |–tre·e ]
[ –inv·ob vob-selector | component-selector ...] [ –obs·olete ]

lsdo

Lists derived objects created by clearmake, omake, or clearaudit (dynamic views only)
Syntax:
cleartool lsdo [ –r·ecurse ] [ –me ] [ –l·ong | –s·hort | –fmt format-string ]
[ –zer·o ] [ –sti·me | –sna·me ] [ –nsh·areable_dos ] [ pname ... ]

lsfolder (UCM)

The lsfolder command displays information that describes one or more folders.
Syntax:
cleartool lsfolder [ –s·hort | –l·ong | –fmt format-string
| –tre·e [ –fmt format-string ] [ –dep·th depth ]
| –anc·estor [ –fmt format-string ] [ –dep·th depth ] ]
[ –inv·ob vob-selector | –in folder-selector | –vie·w view-tag | –cvi·ew
| folder-selector ...] [ –obs·olete ]

lshistory

The lshistory command lists event records in reverse-chronological order, describing operations that have affected a VOB's data.

ClearCase—Display event records graphically:
Syntax:
cleartool lsh·istory –g·raphical [ –nop·references [ [ –min·or ] [ –nco ]
[ –use·r login-name ] [ –bra·nch branch-type-selector ] ] ]
[ [ –r·ecurse | –d·irectory | –a·ll | –avo·bs ]
[ –pna·me ] pname ...
| object-selector ...
]

Display event records in the command window:

cleartool lsh·istory [ –l·ong | –s·hort | –fmt format-string ] [ –eve·ntid ]
[ –min·or ] [ –nco ] [ –las·t [ num-events ] ] [ –sin·ce date-time ]
[ –me | –use·r login-name ] [ –bra·nch branch-type-selector ]
[ [ –r·ecurse | –d·irectory | –a·ll | –avo·bs | –local ]
[ –pna·me ] pname ... | object-selector ... ]

lslock

The lslock command lists locks that have been placed on one or more VOB-database objects (with the lock command).

Syntax:
cleartool lslock [ –local ] [ –l·ong | –s·hort | –fmt format-string ] [ –obs·olete ]
[ [ –a·ll ] [ –pna·me ] pname ...
| object-selector ...
]

lsmaster

This command lists objects mastered by a replica. By default, the command uses only the information known to your current replica.

Syntax:
cleartool lsmaster [ –kind object-selector-kind[,...] ] [ –fmt format-string ]
[ –view view-tag ] [ –inr·eplicas { –all | replica-name[,...] } ]
master-replica-selector ...

lspool

The lspool command lists information about one or more VOB storage pools.

Syntax:
lspool [ –l·ong | –s·hort | –fmt format-string ] [ –obs·olete ]
[ –inv·ob vob-selector | pool-selector ... ]

lsprivate

The lsprivate command lists the file system objects that belong to a dynamic view.

Syntax:
cleartool lsp·rivate [ –tag view-tag ] [ –inv·ob vob-selector ] [ –l·ong | –s·hort ]
[ –siz·e ] [ –age ] [ –co ] [ –do ] [ –oth·er ]

lsproject (UCM)

The lsproject command lists information for one or more projects.
Syntax:
cleartool lsproj·ect [ –s·hort | –l·ong | –fmt format-string
| –tre·e [ –fmt format-string] [ –dep·th depth]
| –anc·estor[ –fmt format-string ] [ –dep·th depth ] ]
[ –obs·olete ] [ –inv·ob vob-selector | –in folder-selector
| –vie·w view-tag | –cvi·ew | project-selector ... ]

lsregion

The lsregion command lists one or more ClearCase network regions.

Syntax:

cleartool lsregion [ –s·hort | –l·ong ] [ 'region-tag-pattern' ...]

lsreplica

This command lists information about all VOB-replica objects recorded in the VOB database of the current replica (except for deleted replicas).

Syntax:
cleartool lsrep·lica [ –l·ong | –s·hort | –fmt format ]
[ –sib·lings | [ –sib·lings ] –invob vob-selector | replica-selector ... ]

lssite

The lssite command lists site-wide properties set in the ClearCase or ClearCase LT site config registry and properties that are not currently set.

Syntax:

cleartool lssite [ –inq·uire | setting-name ]

lsstgloc

The lsstgloc command lists registry information about server storage locations for views and/or VOBs.

Syntax:
cleartool lsstgloc [ –vie·w | –vob ] [ –s·hort | –l·ong ]
[ –reg·ion network-region ] [ –hos·t hostname ]
[ stgloc-name | ‘stgloc-name-pattern‘ ...
| –sto·rage stgloc-pname ]

lsstream (UCM)

The lsstream command displays information about one or more streams.

Syntax:
cleartool lsstream [ –s·hort | –l·ong | –fmt format-string
| –tre·e [ –fmt format-string ] [ –dep·th depth ]
| –anc·estor [ –fmt format-string ] [ –dep·th depth ] ] [ –obs·olete ]
[ –inv·ob vob-selector | –in { project-selector | stream-selector }
| –vie·w view-tag | –cvi·ew | stream-selector ... ]

lstype

The lstype command lists information about one or more of a VOB's type objects.

List type objects:
Syntax:
cleartool lstype [ –local ] [ –l·ong | –s·hort | –fmt format-string ]
[ –obs·olete ]
{ –kin·d type-kind [ –inv·ob vob-selector ]
| type-selector ...
}

On Windows only—List type objects graphically:

cleartool lstype –g·raphical [ –kin·d type-kind ] [ –inv·ob vob-selector ]

lsview

In ClearCase, the lsview command lists one or more views, including nonactive dynamic views.

Syntax:
cleartool lsview [ –s·hort | –l·ong ] [ –hos·t hostname ]
[ –pro·perties [ –ful·l ] | –age ] [ –reg·ion network-region ]
[ –cview | view-tag ... | –sto·rage view-storage-dir-pname ...
| –uui·d view-uuid ]

lsvob

The lsvob command lists one or more VOBs. To be accessible to cleartool subcommands, including lsvob, a VOB must be registered.

ClearCase—List VOBs:
Syntax:
cleartool lsvob [ –s·hort | –l·ong ] [ –hos·t hostname ]
[ –reg·ion network-region ]
[ vob-tag ... | –sto·rage vob-storage-dir-pname ...
| –uui·d replica-uuid | –fam·ily vob-family-uuid ]
 

ClearCase—List VOBs using the graphical VOB browser:

cleartool lsvob –g·raphical [ –reg·ion network-region ]

lsvtree

The lsvtree command lists part or all of the version tree of one or more elements.

Syntax:
UNIX only—Display the version tree in graphical form:
cleartool lsvtree –g·raphical [ –a·ll ] [ –nme·rge ] [ –nco ]
[ –opt·ions pass-through-opts ] pname ...

Windows only—Display the version tree in graphical form:

cleartool lsvtree –g·raphical [ –a·ll ] [ –nme·rge ] [ –nco ] pname ...

List the version tree in the command window:
 

cleartool lsvtree [ –nr·ecurse ] [ –s·hort ] [ –a·ll ] [ –mer·ge ] [ –nco ]
[ –obs·olete ] [ –bra·nch branch-pname ] pname ...

makefile_aix

clearmake compatibility with AIX make (on IBM hosts)

makefile_ccase

makefiles processed by clearmake

makefile_gnu

makefilesGNU compatibilityclearmake compatibility with GNU make

makefile_pmake

makefilesIRIX pmake compatibilityclearmake compatibility with IRIX pmake (on SGI hosts)

makefile_smake

clearmake compatibility with IRIX smake (on SGI hosts)

makefile_sun

clearmake compatibility with SunOS 5.x (Solaris) make

man

This command displays a reference page, the table of contents for the online documentation, or the product tutorial.

Syntax:
Display a reference page (UNIX):
cleartool man [ –g·raphical ] [ command_name ]

Display the table of contents (UNIX):

cleartool man contents

Display the product tutorial (UNIX):

cleartool man tutorial

Display a reference page (Windows):

cleartool man [ command_name ]

merge

The merge command calls an element-type-specific program (the merge method) to merge the contents of two or more files, or two or more directories. Typically the files are versions of the same file element. A directory merge must involve versions of the same directory element.
Syntax:

On UNIX:

cleartool merge { –out output-pname | –to contrib-&-result-pname }
[ –g·raphical [ –tin·y ] | –tin·y | –win·dow ]
[ –ser·ial_format | –dif·f_format | –col·umns n ] ]
[ –bas·e pname | –ins·ert | –del·ete ]
[ –nda·ta | –nar·rows ] [ –rep·lace ]
[ –q·uery |–abo·rt | –qal·l ]
[ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach | –nc·omment ] [ –opt·ions pass-through-options ]
{ –ver·sion contrib-version-selector ... | contrib-pname ... }

On Windows:

cleartool merge { –out output-pname | –to contrib-&-result-pname }
[ –g·raphical [ –tin·y ] | [ –ser·ial_format | –dif·f_format
| –col·umns n ] ]
[ –bas·e pname | –ins·ert | –del·ete ] [ –nda·ta | –nar·rows ]
[ –rep·lace ] [ –q·uery | –abo·rt | –qal·l ]
[ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach| –nc·omment ] [ –opt·ions pass-through-options ]
{ –ver·sion contrib-version-selector ... | contrib-pname ... }

mkactivity (UCM)

The mkactivity command creates an activity. Activities track the work you do in completing a development task. An activity consists of a headline, which describes the task, and a change set, which identifies all versions of elements that are created or modified by work on the activity.

Each stream can have one current activity, which records any changes being made. Use –nset if you do not want to use an activity immediately. To begin recording changes in an activity, issue a setactivity command from a view that is attached to the activity's stream.

Syntax:
cleartool mkact·ivity [ –c·omment comment | –cfi·le pname | –cq·uery
| –cqe·ach | –nc·omment ] [ –hea·dline headline ]
[ –in stream-selector ] [ –nse·t ] [ –f·orce ] [ activity-selector ...]

mkattr

The mkattr command attaches an attribute to one or more objects. You can specify the objects themselves on the command line, or you can specify a particular derived object. In the latter case, mkattr attaches attributes to versions only—some or all of the versions that were used to build that derived object.
Attach attributes to specified file system objects:
Syntax:
cleartool mkattr [ –rep·lace ] [ –r·ecurse ] [ –ver·sion version-selector ]
[ –pna·me ] [ –c·omment comment | –cfi·le comment-file-pname
|–cq·uery | –cqe·ach | –nc·omment ]
{ attribute-type-selector value
| –def·ault attribute-type-selector }
pname ...

Attach attributes to specified non-file-system objects:

cleartool mkattr [ –rep·lace ] [ –c·omment comment | –cfi·le comment-file-pname
| –cq·uery | –cqe·ach | –nc·omment ]
{ attribute-type-selector value
| –def·ault attribute-type-selector }
object-selector ...

Attach attributes to versions listed in configuration record:

cleartool mkattr [ –rep·lace ] [ –c·omment comment | –cfi·le comment-file-pname
| –cq·uery | –cqe·ach | –nc·omment ]
[ –sel·ect do-leaf-pattern ] [ –ci ] [ –typ·e { f | d } ... ]
[ –nam·e tail-pattern ] –con·fig do-pname
{ attribute-type-selector value
| –def·ault attribute-type-selector }

mkattype

The mkattype command creates one or more attribute types for future use within a VOB. After creating an attribute type in a VOB, you can use mkattr to attach attributes of that type to objects in that VOB.
Syntax:
cleartool mkattype [ –rep·lace ] [ –glo·bal [ –acq·uire ] | –ord·inary ]
[ –vpe·lement | –vpb·ranch | –vpv·ersion ] [ –sha·red ]
[ –vty·pe { integer | real | time | string | opaque } ]
[ [ –gt low-val | –ge low-val ] [ –lt high-val | –le high-val ]
| –enu·m value[,...] ]
[ –def·ault default-val ]
[ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach | –nc·omment ] attribute-type-selector ...

mkbl

The mkbl command creates baselines or composite baselines. A baseline represents a snapshot of the changes made to a particular component in the context of a particular stream: it is a version of a component. For each element in the component, the baseline records the version of that element selected by the stream's configuration at the time mkbl is executed. The baseline also records the list of activities in the stream whose change sets contain versions of the component's elements.

A baseline selects one version of each element of a component. You can create multiple baselines per component, just as you can create multiple versions of an element. A baseline is associated with only one component, and you can only create one baseline per component per invocation of mkbl.

By default, all components that have been modified since the last full baseline are considered as candidates for new baselines. You can also create baselines for a subset of components in the stream or for components modified by specific activities.

If your project team works on multiple components, you may create a composite baseline. A composite baseline is a baseline that selects baselines in other components. You can use a composite baseline to represent the entire project baseline; this is easier than keeping track of a set of baselines, one for each component. We recommend that you create a component for storing the composite baselines.

Syntax:

Create a baseline of a component or set of baselines of components:

cleartool mkbl [ –c·omment comment | –cfi· le pname | –cq· uery| –nc·omment ]
[ –com·ponent component-selector[,...]
[ –ide·ntical ] | –all [ –ide·ntical ] | –act·ivities activity-selector[,...] ]
[ –nla·bel | –inc·remental | –fu·ll ] [ –vie·w view-tag ]
baseline-root-name

Create or change the dependency relationships for a composite baseline:

cleartool mkbl [ –c·omment comment | –cfi· le pname | –cq· uery| –nc·omment ]
–com·ponent component-selector [ –vie·w view-tag ]
{ [ –adep·ends_on depend-component-selector[,...] ]
[ –ddep·ends_on depend-component-selector[,...] ] }
[ –nla·bel | –inc·remental | –fu·ll ] [ –nac·t ]
baseline-root-name

Create a baseline by importing a label type:
 

cleartool mkbl [ –c·omment comment | –cfi· le pname | –cq· uery| –nc·omment ]
–imp·ort [ –com·ponent component-selector[,...] ] label-type-selector ...

mkbranch

The mkbranch command creates a new branch in the version trees of one or more elements. The new branch is checked out, unless you use the –nco option.
Syntax:
cleartool mkbranch [ –c·omment comment | –cfi·le comment-file-pname |–cq·uery
| –cqe·ach | –nc·omment ] [ –nwa·rn ]
[ –nco ] [ –ver·sion version-selector ] branch-type-selector pname ...

mkbrtype

The mkbrtype command creates one or more branch types with the specified names for future use within a particular VOB. After creating a branch type in a VOB, you can create branches of that type in that VOB's elements, using mkbranch.
Syntax:
cleartool mkbrtype [ –rep·lace ] [ –glo·bal [ –acq·uire ] | –ord·inary ]
[ –pbr·anch ] [ –c·omment comment | –cfi·le comment-file-pname
| –cq·uery | –cqe·ach | –nc·omment ] branch-type-selector ...

mkcomp (UCM)

The mkcomp command creates a component. The scope of a UCM project is declared in terms of components. A project must contain at least one component, and it can contain multiple components. Projects can share components.
Syntax:
cleartool mkcomp [ –c·omment comment | –cfi·le pname | –cq·uery | –nc·omment ]
{ –roo·t root-dir-pname | –nro·ot }
component-selector

mkdir

The mkdir command creates one or more directory elements. (Operating system directory creation commands create view-private directories, not elements.) Unless you specify the –nco (no checkout) option, the new directory is checked out automatically. A directory element must be checked out before you can create elements and VOB links within it.

The mkelem –eltype directory command is equivalent to this command.

Syntax:
cleartool mkdir [ –nco ] [ –c·omment comment | –cfi·le comment-file-pname |–cq·uery
| –cqe·ach | –nc·omment ] [–master ] dir-pname ...

mkelem

The mkelem command creates one or more new elements. By default, a new element can be created in a directory only if that directory element is checked out. mkelem appends an appropriate line to the directory's checkout comment.

mkelem processes each element as follows:

  1. Determines an element type from the specified –eltype option or by performing file-typing.
  2. Creates an element object with that element type in the appropriate VOB database.
  3. On UNIX systems, if you are using the –ci option to convert a view-private file to an element, uses the permissions of that file including setuid and/or setgid bits; otherwise, sets the mode of the new element to 444 (for a file element) or 777 (for a directory element), as modified by your current umask(1) setting
  4. Initializes the element's version tree by creating a single branch (named main), and a single, empty version (version 0) on that branch
  5. Does one of the following:
    • By default, checks out the element to your view.

      Note: At this point, other views see an empty file when they look at the element.

    • With the –nco option, does nothing.
    • With the –ci option, creates version 1 by copying a view-private file or an uploaded view-private file.
  6. Assigns the element to the same source storage pool, cleartext storage pool, and (for new directory elements) derived object storage pool as its parent directory element.
  7. In a snapshot view, updates the newly created element.

Note: Error messages appear if your config spec lacks a /main/LATEST rule. The mkelem command succeeds in creating version /main/0. However, because your view does not have a rule to select this version, you cannot see or check out the element.

Syntax:
cleartool mkelem [ –elt·ype element-type-name ] [ –nco | –ci [ –pti·me ] ]
[ –mkp·ath ] –master ] [ –nwa·rn ]
[ –c·omment comment | –cfi·le comment-file-pname
| –cq·uery | –cqe·ach | –nc·omment ] element-pname ...

mkeltype

The mkeltype command creates one or more user-defined element types for future use within a VOB. User-defined element types are variants of the predefined types.

Note: You cannot remove an element type from a replicated VOB or change the definition of an element type in a replicated VOB.
Syntax:
cleartool mkeltype [ –rep·lace ] [ –glo·bal [ –acq·uire ] | –ord·inary ]
–sup·ertype elem-type-selector [ –man·ager mgr-name ]
[ –pti·me ] [ –att·ype attr-type-selector[,...] ]
[ –mer·getype { auto | user | never } ]
[ –c·omment comment | –cfi·le comment-file-pname |–cq·uery
| –cqe·ach | –nc·omment ] element-type-selector ...

mkfolder (UCM)

The mkfolder command creates a folder for a project. Folders have these characteristics:
  • They can contain projects or other folders.
  • They must reside in a project VOB.
  • Each folder must have a parent folder.

The parent folder for a top-level folder is named RootFolder, a predefined object.

Syntax:
cleartool mkfolder [–c·omment comment | –cfi·le pname | –cq·uery
| –cqe·ach | –nc·omment ]
–in parent-folder-selector [ folder-selector...

mkhlink

The mkhlink command creates a hyperlink between two objects, each of which may be an element, branch, version, VOB symbolic link, or non-file-system VOB object (except another hyperlink).

Logically, a hyperlink is an “arrow” attached to one or two VOB-database objects:

  • A bidirectional hyperlink connects two objects, in the same VOB or in different VOBs, with optional text annotations at either end. It can be navigated in either direction: from-object → to-object or to-object → from-object.
  • A unidirectional hyperlink connects two objects in different VOBs, with optional text annotations at either end. It can be navigated only in the from-object → to-object direction.
  • A text-only hyperlink associates one object with a user-defined text string (for example, an element that implements a particular algorithm with the name of a document that describes it).
  • A null-ended hyperlink has only a from-object. Use this kind of hyperlink to suppress hyperlink inheritance.

Hyperlink Inheritance

By default, a version implicitly inherits a hyperlink attached to any of its ancestor versions, on the same branch or on a parent branch. Inherited hyperlinks are listed by the describe command only if you use the –ihlink option.

A hyperlink stops being passed down to its descendents if it is superseded by another hyperlink of the same type, explicitly attached to some descendent version. You can use a null-ended hyperlink (from-object, but no to-object) as the superseding hyperlink to effectively cancel hyperlink inheritance.

Syntax:
cleartool mkhlink [ –uni·dir ] [ –tte·xt to-text ] [ –fte·xt from-text ]
[ –fpn·ame ] [ –tpn·ame ] [ –acq·uire ]
[ –c·omment comment | –cfi·le comment-file-pname |–cq·uery | –cqe·ach
| –nc·omment ] hlink-type-selector from-obj-selector [ to-obj-selector ]

mkhltype

The mkhltype command creates one or more hyperlink types for future use within a VOB. After creating a hyperlink type, you can connect pairs of objects with hyperlinks of that type, using mkhlink.

Conceptually, a hyperlink is an “arrow” from one VOB-database object (version, branch, element, or VOB symbolic link) to another. To enable objects in two different VOBs to be connected, a hyperlink type with the same name must be created in both VOBs.

For example, you create a hyperlink type named design_spec, for use in linking source code files to the associated design documents. Later, you can use mkhlink to create a hyperlink of this type between my_prog.c and my_prog.dsn.

Syntax:
cleartool mkhltype [ –rep·lace ] [ –glo·bal [ –acq·uire ] | –ord·inary ]
[ –att·ype attr-type-selector[,...] ] [ –sha·red ]
[ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach | –nc·omment ] hlink-type-selector ...

mklabel

The mklabel command attaches a version label to one or more versions. You can attach a label to only one version of a particular element. You can specify the versions themselves on the command line, or you can specify a particular derived object. In the latter case, mklabel labels some or all the versions that were used to build that derived object.
Syntax:

Attach label to specified versions:

cleartool mklabel [ –rep·lace ] [ –r·ecurse ] [ –fol·low ]
[ –ver·sion version-selector ]
[ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach | –nc·omment ] label-type-selector pname ...

Attach label to versions listed in configuration record:

cleartool mklabel [ –rep·lace ] [ –c·omment comment | –cfi·le comment-file-pname
| –cq·uery | –cqe·ach | –nc·omment ]
[ –sel·ect do-leaf-pattern ][ –ci ] [ –typ·e { f | d } ... ]
[ –nam·e tail-pattern ] –con·fig do-pname label-type-selector

mklbtype

The mklbtype command creates one or more label types with the specified names for future use within a VOB. After creating a label type in a VOB, you can attach labels of that type to versions of that VOB's elements, using mklabel.
Syntax:
cleartool mklbtype [ –rep·lace ] [ –glo·bal [ –acq·uire ] | –ord·inary ]
[ –pbr·anch ] [ –sha·red ]
[ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach | –nc·omment ] label-type-selector ...

mkpool

The mkpool command creates a source storage pool, derived object storage pool, or cleartext storage pool, and initializes the pool's scrubbing parameters. You can also use this command to update the scrubbing parameters of an existing storage pool.

Storage pools are directories used as physical storage areas for different kinds of data:

  • A source storage pool stores the data containers that contain versions of elements.
  • A derived object storage pool stores shared derived objects—those that are referenced by more than one view.
  • A cleartext storage pool is a cache of text files. If an element's versions are stored in a compressed format, accessing a particular version involves some processing overhead; a type manager program is invoked to extract the cleartext of that version from the data container. As a performance optimization, the extracted version is cached as a file in a cleartext storage pool. The next access to that same version uses the cached copy, saving the cost of extracting the version from the data container again.

Creating a new VOB with the mkvob command creates one default pool of each kind: sdft (source pool), ddft (derived object pool), and cdft (cleartext pool).

mkpool creates a storage pool as a directory within the VOB storage area. Source pools are always created within subdirectory s of the VOB storage directory; derived object pools are created within subdirectory d; cleartext pools are created within subdirectory c. The –ln option allows you to create pools elsewhere, to be accessed at the standard locations through symbolic links.

Syntax:
UNIX only—Create source pool:
cleartool mkpool –sou·rce [ –ln pname ]
[ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach | –nc·omment ] pool-selector ...

UNIX only—Create derived object pool or cleartext pool:

cleartool mkpool { –der·ived | –cle·artext } [ –ln pname ]
[ –siz·e max-kbytes reclaim-kbytes [ –age hours ]
[ –ale·rt command ] ]
[ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach | –nc·omment ] pool-selector ...

Windows only—Create source pool:

cleartool mkpool –sou·rce
[ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach | –nc·omment ] pool-selector ...

Windows only—Create derived object pool or cleartext pool:

cleartool mkpool { –der·ived | –cle·artext }
[ –siz·e max-kbytes reclaim-kbytes [ –age hours ]
[ –ale·rt command ] ]
[ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach | –nc·omment ] pool-selector ...

Update pool parameters:

cleartool mkpool –upd·ate [ –siz·e max-kbytes reclaim-kbytes ] [ –age hours ]
[ –ale·rt command ]
[ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach | –nc·omment ] pool-selector ...

mkproject (UCM)

The mkproject command creates a project. A project includes policy information and configuration information.

Projects are created in folders. A folder or folder hierarchy must be in place before you create a project. If no folder exists, you can specify RootFolder as the folder selector with the –in option. RootFolder is a predefined object that represents the parent folder of a folder hierarchy. See mkfolder for more information.

Projects maintain a list of components that can be modified within the project. You can specify these with the –modcomp option. Streams in the project can make changes, such as checking out files, only in modifiable components; all other components are read-only.

The basic UCM process uses an integration stream and multiple development streams in a project. However, small teams of developers working together closely may prefer a single-stream project. You can create a project with single or multiple streams by using the –model option with keywords SIMPLE or DEFAULT.

Syntax:
cleartool mkproj·ect [ –c·omment comment | –cfi·le pname | –cq·uery
| –cqe·ach | –nc·omment ] [ –mod·comp component-selector[,... ] ]
–in folder-selector
[ –pol·icy policy-keyword[,...] ] [ –npo·licy policy-keyword[,...] ]
[ –spo·licy policy-keyword[,...] ]
[ –model { SIMPLE | DEFAULT } ]
[ –crm·enable ClearQuest-user-database-name ]
[ –bln·ame_template baseline-naming-template ]
[ project-selector ... ]

mkregion

The mkregion command registers a new network region by adding a new region tag (region name) and, optionally, a comment to the regions file on the ClearCase registry server host. Use the lsregion command to display the region tags contained in regions.

After creating a new region, you can create VOB tags and view tags for the region with mktag, mkvob, and mkview.

Syntax:

cleartool mkregion –tag region-tag [ –tco·mment tag-comment ] [ –rep·lace ]

mkstgloc

The mkstgloc command creates and registers a named server storage location for view or VOB storage directories. The command initializes a physical directory and writes information describing that directory to the ClearCase or ClearCase LT registry.

Syntax:
cleartool mkstgloc { –vie·w | –vob } [ –f·orce ] [ –c·omment comment ]
[ –reg·ion network-region ]
[ –hos·t hostname –hpa·th host-storage-pname
–gpa·th global-storage-pname | –ngp·ath
[ –hos·t hostname –hpa·th host-storage-pname ] ]
stgloc-name stgloc-pname

mkstream (UCM)

The mkstream command creates a stream for use with a UCM project. A stream consists of a name, a set of baselines that configure the stream, and a record of the set of activities associated with the stream.

There are two kinds of streams with UCM projects:

  • As a shared work area for integrating work from different sources. This is called the project's integration stream. Each project has exactly one integration stream.
  • As an isolated work area for use in code development. This is called a development stream. A project can have any number of development streams. A development stream can have child streams. There is no limitation on the number of nested levels of streams.

To create an integration stream, you must specify its project. Note that a project's integration stream must be present before a development stream can be created.

To create a development stream, you must specify a stream as its parent. Specifying a project is equivalent to specifying the project's integration stream. By default, the development stream delivers to the integration stream and rebases from recommended baselines of the integration stream. If you specify a development stream as its parent, the stream becomes the child of that development stream and delivers to and rebases from its parent.

Optionally, you can assign the stream a set of foundation baselines. Foundation baselines specify a stream's configuration by selecting the file and directory versions that are accessible in the stream.

Streams are accessed through views (see mkview –stream). A stream can have more than one view attached to it.

Syntax:

Create an integration stream in a project:

cleartool mkstream –int·egration –in project-selector
[ –c·omment comment | –cfi· le pname | –cq·uery
| –cqe·ach | –nc·omment ]
[ –bas·eline baseline-selector[,... ]]
[ –pol·icy policy-keyword[,... ]]
[ –npo·licy policy-keyword[,...]]
[ –tar·get stream-selector ]
[ stream-selector...]

Create a development stream in a project or a stream:

cleartool mkstream {–in project-selector | stream-selector }
[ –c·omment comment |–cfi·le pname | –cq·uery
| –cqe·ach | –nc·omment ]
[ –bas·eline baseline-selector[,... ]]
[ –pol·icy policy-keyword[,... ]]
[ –npo·licy policy-keyword[,...]]
[ –reado·nly ]
[ stream-selector...]

mktag

For an existing view or VOB, the mktag command creates or replaces an entry in the registry. A view or VOB gets one tag when it is created with mkview or mkvob.
Syntax:

ClearCase on UNIX—Create a tag for a dynamic view:

cleartool mktag –vie·w –tag dynamic-view-tag [ –tco·mment tag-comment ]
[ –rep·lace | –reg·ion network-region ] [ –nst·art ]
[ –nca·exported ]
[ –hos·t hostname –gpa·th global-storage-pname ] dynamic-view-storage-pname

ClearCase on Windows—Create a tag for a dynamic view:

cleartool mktag –vie·w –tag dynamic-view-tag [ –tco·mment tag-comment ]
[ –rep·lace | –reg·ion network-region ] [ –nst·art ]
[ –hos·t hostname –gpa·th global-storage-pname ] dynamic-view-storage-pname

ClearCase—Create a tag for a snapshot view:

cleartool mktag –vie·w –tag snapshot-view-tag [ –tco·mment tag-comment ]
[ –rep·lace | –reg·ion network-region ] [ –nst·art ]
[ –hos·t hostname –gpa·th global-storage-pname
| –ngpath [ –host hostname ] ] snapshot-view-storage-pname

ClearCase on UNIX—Create a VOB tag:

cleartool mktag –vob –tag vob-tag [ –tco·mment tag-comment ]
[ –rep·lace | –reg·ion network-region ] [ –opt·ions mount-options ]
[ –pub·lic ] [ –pas·sword tag-registry-password ] [ –nca·exported ]
[ –hos·t hostname –gpa·th global-storage-pname
| –ngp·ath [ –hos·t hostname ] ] vob-storage-pname

ClearCase on Windows—Create a VOB tag:

cleartool mktag –vob –tag vob-tag [ –tco·mment tag-comment ]
[ –rep·lace | –reg·ion network-region ] [ –opt·ions mount-options ]
[ –pub·lic ] [ –pas·sword tag-registry-password ]
[ –hos·t hostname –gpa·th global-storage-pname
| –ngp·ath [ –hos·t hostname ] ] vob-storage-pname

ClearCase LT—Create a view tag:

cleartool mktag –vie·w –tag view-tag [ –tco·mment tag-comment ] [ –rep·lace ]
[ –nst·art ] snapshot-view-storage-pname

ClearCase LT—Create a VOB tag:

cleartool mktag –vob –tag vob-tag [ –tco·mment tag-comment ]
[ –rep·lace ] vob-storage-pname

mktrigger

The mktrigger command attaches a trigger to one or more elements or UCM objects. An attached trigger fires (executes the trigger action) when the element (or any of its versions) or the UCM object is involved in an operation specified in the trigger type definition. For example, if a trigger type is defined to fire on a checkin command, the attached trigger fires when the specified element is checked in. If a VOB operation causes multiple attached triggers to fire, the order of firing is undefined.

Note: A trigger type object, created with mktrtype –element must already exist in the VOBs containing the specified elements. Similarly, you use mktrtype –ucmobject to create a trigger type object in the project VOB containing the specified UCM objects before you can use this command.

Element Trigger Inheritance

By means of a trigger inheritance scheme, newly created elements (but not existing elements) inherit the triggers that are currently associated with their parent directory element. But a simple inherit-all-triggers strategy does not suit the needs of many sites. For example:

  • You may not want some of a directory's triggers to propagate to its subtree.
  • You may want some triggers to fire only for file elements, not for directory elements.

To enable such flexibility, each directory element has two independent lists of trigger types:

  • Its attached list specifies triggers that fire on operations involving the directory element.
  • Its inheritance list specifies triggers that elements created within the directory inherit.

By default, attaching a trigger to a directory element updates both lists:

cmd-context  mktrigger trig_co proj 
Added trigger "trig_co" to inheritance list of "proj".
Added trigger "trig_co" to attached list of "proj".

Each file element has only an attached list:

cmd-context  mktrigger trig_co util.c 
Added trigger "trig_co" to attached list of "util.c".

You can use the –ninherit and –nattach options to control exactly which triggers on a directory element are inherited. (And you can make adjustments using the –ninherit and –nattach options of the rmtrigger command.)

Syntax:
cleartool mktrigger [ –c·omment comment | –cfi·le comment-file-pname |–cq·uery
| –cqe·ach | –nc·omment ]
[ –r·ecurse ] [ –nin·herit | –nat·tach ] [ –f·orce ]
trigger-type-selector { pname | ucm-object-selector } ...

mktrtype

The mktrtype command creates one or more trigger types for use within a VOB or UCM project VOB. A trigger type defines a sequence of one or more trigger actions to be performed when a specified ClearCase or ClearCase LT operation occurs. The set of operations that initiates each trigger action—that is, causes the trigger to fire—can be very limited (for example, checkout only) or quite general (for example, any operation that modifies an element). You can use a restriction list to further limit the circumstances under which a trigger action is performed.

The trigger types are as follows:

  • An element trigger type works like a label type or attribute type: an instance of the type (that is, a trigger) must be explicitly attached to one or more individual elements with the mktrigger command. The trigger actions are performed when the specified operation is invoked on any of those elements. An element must exist before the trigger can be attached. (Putting a trigger on a mkelem operation has no effect.)

    A variant of this type, called an all-element trigger type, is associated with the entire VOB. (Hence, no mktrigger command is required.) In effect, an instance of the type is implicitly attached to each element in the VOB, even those created after this command is executed. This trigger type is useful for disallowing creation of elements that have certain characteristics.

  • A type trigger type is associated with one or more type objects. The trigger actions are performed when any of those type objects is created or modified.
  • A UCM trigger type is attached to one or more UCM objects, such as a stream or activity, and fires when the specified operation is invoked on the UCM object. You can also create an all-UCM-object trigger type. Like the all-element type, this type is implicitly attached to all existing and potential UCM objects in the project VOB (that is, no mktrigger command is required).

Unlike other types, trigger types cannot be global.

Syntax:

Create element trigger type:

cleartool mktrtype –ele·ment [ –a·ll ] [ –rep·lace ]
{ –pre·op | –pos·top } opkind[,...] [ –nus·ers login-name[,...] ]
{ –exe·c command
| –execu·nix command
| –execw·in command
| –mkl·abel label-type-selector
| –mka·ttr attribute-type-selector=value
| –mkh·link hlink-type-selector, to=pname
| –mkh·link hlink-type-selector, from=pname } ...
[ restriction-list ]
[ –pri·nt ]
[ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach | –nc·omment ] type-selector ...

Create type trigger type:

cleartool mktrtype –typ·e [ –rep·lace ] { –pre·op | –pos·top } opkind[,...]
[ –nus·ers login-name[,...] ]
{ –exe·c command
| –execu·nix command
| –execw·in command
| –mkl·abel label-type-selector
| –mka·ttr attribute-type-selector=value
| –mkh·link hlink-type-selector,to=pname
| –mkh·link hlink-type-selector, from=pname } ...
inclusion-list [ –pri·nt ]
[ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach| –nc·omment ] type-selector ...

Create a UCM trigger type:

cleartool mktrtype –ucm·object [ –a·ll ] [ –rep·lace ]
{ –pre·op | –pos·top } opkind[,...] [ –nus·ers login-name[,...] ]
{ –exe·c command
| –execu·nix command
| –execw·in command
| –mka·ttr attribute-type-selector=value
| –mkh·link hlink-type-selector,to=pname
| –mkh·link hlink-type-selector,from=pname } ...
[ restriction-list ]
[ –pri·nt ]
[ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach | –nc·omment ] type-selector ...

A restriction-list for an element trigger type contains one or more of:

–att·ype attr-type-selector[,...] –hlt·ype hlink-type-selector[,...]
–brt·ype branch-type-selector[,...] –lbt·ype label-type-selector[,...]
–elt·ype elem-type-selector[,...] –trt·ype trigger-type-selector[,...]

An inclusion-list for a type trigger type contains one or more of:

–attype attr-type-selector[,...] or –att·ype –all
–brt·ype branch-type-selector[,...] or –brt·ype –all
–elt·ype elem-type-selector[,...] or –elt·ype –all
–hlt·ype hlink-type-selector[,...] or –hlt·ype –all
–lbt·ype label-type-selector[,...] or –lbt·ype –all
–trt·ype trigger-type-selector[,...] or –trt·ype –all

A restriction-list for a UCM trigger type contains one or more of:

–com·ponent component-selector[,...] (Default: All components)
–pro·ject project-selector[,...] (Default: All projects)
–str·eam stream-selector[,...] (Default: All streams)

Note: xxxtype aaa,bbb is equivalent to xxxtype aaa –xxtype bbb.

mkview

The mkview command creates a new view as follows:
  • Creates a view storage directory. The view storage directory maintains information about the view. Along with other files and directories, the directory contains the view's config spec and the view database. In ClearCase LT, the locations of view storage directories are restricted to the ClearCase LT server host.
  • Creates a view tag, the name by which users access a dynamic view. Snapshot views also have view tags, but these are for administrative purposes; users access snapshot views by setting their working directory to the snapshot view directory (for example, using the cd command.
  • For a snapshot view, creates the snapshot view directory. This is the directory into which your files are loaded when you populate the view using update. This directory is distinct from the view storage directory.
  • Places entries in the network's view registry; use the lsview command to list view tags.
  • Starts a view_server process on the specified host. The view_server process manages activity in a particular view. It communicates with VOBs during checkout, checkin, update, and other operations.
Syntax:
ClearCase on UNIX—Create and register a dynamic view:
cleartool mkview –tag dynamic-view-tag [ –tco·mment tag-comment ]
[ –tmo·de { insert_cr | transparent | strip_cr } ]
[ –reg·ion network-region ] [ –ln remote-storage-dir-pname ]
[ –nca·exported ] [ –cac·hesize size ]
[ –sha·reable_dos | –nsh·areable_dos ] [ –str·eam stream-selector ]
{ –stg·loc { view-stgloc-name | –aut·o }
| [ –hos·t hostname –hpa·th host-storage-pname
–gpa·th global-storage-pname ] dynamic-view-storage-pname

ClearCase on Windows—Create and register a dynamic view:

cleartool mkview –tag dynamic-view-tag [ –tco·mment tag-comment ]
[ –tmo·de { insert_cr | transparent | strip_cr } ]
[ –reg·ion network-region ] [ –cac·hesize size ]
[ –sha·reable_dos | –nsh·areable_dos ] [ –str·eam stream-selector ]
{ –stg·loc { view-stgloc-name | –aut·o }
| [ –hos·t hostname –hpa·th host-storage-pname
–gpa·th global-storage-pname ] dynamic-view-storage-pname }

ClearCase—Create and register a snapshot view:

cleartool mkview –sna·pshot [ –tag snapshot-view-tag ]
[ –tco·mment tag-comment ]
[ –tmo·de { insert_cr | transparent | strip_cr } ]
[ –cac·hesize size ] [ –pti·me ] [ –str·eam stream-selector ]
[ –stg·loc view-stgloc-name | –col·ocated_server
[ –hos·t hostname –hpa·th host-snapshot-view-pname
–gpa·th global-snapshot-view-pname ] | –vws view-storage-pname
[ –hos·t hostname –hpa·th host-storage-pname
–gpa·th global-storage-pname ] snapshot-view-pname

ClearCase LT—Create and register a snapshot view:

cleartool mkview [–sna·pshot ] [ –tag view-tag ]
[ –tco·mment tag-comment ]
[ –tmo·de { insert_cr | transparent | strip_cr } ]
[ –pti·me ] [ –str·eam stream-selector ]
[ –stg·loc view-stgloc-name ] snapshot-view-pname

mkvob

The mkvob command creates a new versioned object base, or VOB, as follows:
  • Creates a VOB storage directory at a specified path or in a VOB server storage location created with mkstgloc.
  • Creates a VOB tag with which the VOB is accessed by users.
  • Places entries in the network's VOB registries; use the lsvob command to list registered VOBs.
  • Starts a VOB server process on the named host.

A VOB storage directory is the root of a directory tree whose principal contents are a VOB database and a set of storage pools.

Syntax:

ClearCase on UNIX:

cleartool mkvob –tag vob-tag [ –ucm·project ]
[ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach | –nc·omment ]
[ –tco·mment tag-comment ] [ –reg·ion network-region ]
[ –opt·ions mount-options ] [ –nca·exported ]
[ –pub·lic ] [ –pas·sword tag-registry-password ]
{ [ –hos·t hostname –hpa·th host-storage-pname
–gpa·th global-storage-pname ] vob-storage-pname
| -stgloc { vob-stgloc-name | –auto } }

ClearCase on Windows:

cleartool mkvob –tag vob-tag [ –ucm·project ]
[ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach | –nc·omment ]
[ –tco·mment tag-comment ] [ –reg·ion network-region ]
[ –opt·ions mount-options ] [ –pub·lic ]
[ –pas·sword tag-registry-password ]
{ [ –hos·t hostname –hpa·th host-storage-pname
–gpa·th global-storage-pname ] vob-storage-pname
| -stgloc { vob-stgloc-name | –auto } }

ClearCase LT:

cleartool mkvob –tag vob-tag [ –ucm·project ]
[ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach | –nc·omment ] [ –tco·mment tag-comment ]
[ -stg·loc vob-stgloc-name ]

mount

The mount command activates one or more VOBs on the local host. The mount command mounts a VOB as a file system of type MVFS (multiversion file system) and is inapplicable to non-MVFS installations.

Syntax:

UNIX only—Mount a single VOB:

cleartool mount [ –opt·ions mount-options ] vob-tag

Windows only—Mount a single VOB:

cleartool mount [ –per·sistent ] [ –opt·ions mount-options ] vob-tag

UNIX only—Mount all public VOBs:

cleartool mount –a·ll

Windows only—Mount all public VOBs:

cleartool mount [ –per·sistent ] –a·ll

mount_ccase

This reference page describes the mechanisms that mount VOBs as file systems of type MVFS (the ClearCase multiversion file system).

Automatic VOB Activation at System Startup

 At system startup, the architecture-specific ClearCase startup script (see the init_ccase reference page) issues a mount –all command. This activates on the local host all the VOBs that are registered as public in the local host's network region of the ClearCase tags registry. During this procedure, the architecture-specific mount command performs the actual work of mounting the VOB as a file system of type MVFS. (The command is actually a symbolic link to ccase-home-dir/etc/mount_mvfs.)

VOB Activation After System Startup

 After system startup, a mount command can be used to activate or reactivate any VOB that is listed in the tags registry.

  • root can activate any VOB in this way.
  • Another identity can activate any public VOB, or any private VOB owned by that identity.

Automatic VOB Deactivation at System Shutdown

 At system shutdown, the architecture-specific ClearCase startup script is invoked with the stop option to execute the ClearCase shutdown procedure. As part of this procedure, a umount –all command deactivates all VOBs currently active on the local host. On all platforms except for AIX 4, umount –all invokes the standard umount(1M) utility directly. On AIX 4, umount –all invokes the architecture-specific mount command /sbin/helpers/mvfsmnthelp with U as its first argument, and /sbin/helpers/mvfsmnthelp then invokes umount(1M).

Individual VOB Deactivation

 While ClearCase is running, a umount command can be used to deactivate any mounted VOB:

  • root can deactivate any VOB in this way.
  • A non-root user can deactivate any public VOB, or any private VOB owned by that user.
The mount_mvfs program must never be invoked explicitly.
The cleartool mount subcommand invokes an architecture-specific mount command:
 
Solaris, Reliant UNIX /usr/lib/fs/mvfs/mount
AIX 4 /sbin/helpers/mvfsmnthelp
Digital UNIX /sbin/mount_mvfs
IRIX, MP-RAS /usr/etc/mount_mvfs
HP-UX 10, HP-UX 11 /sbin/fs/mvfs/mount
UnixWare /etc/fs/mvfs/mount

msdostext_mode

Before a VOB can be accessed from an interop text-mode view, the VOB must be enabled for interop text mode support. The msdostext_mode utility enables or disables the ability of a VOB to support interop text mode views. This utility does not physically convert or modify files in any way; rather, it affects the information recorded for text file versions in the VOB database. For more information about interop text mode, see the Administrator's Guide.
Location:

../rational/clearcase/etc/utils

Syntax:

msdostext_mode [ –c | –d | –r ] [ –f ] vob-stg-pname

mv

The mv command changes the name or location of an element or VOB symbolic link. For a file element that is checked out to your view, it relocates the checked-out version, also. (That is, it moves the view-private file with the same name as the element.) If the version is checked out to another view, it issues a warning:

Syntax:

Rename:

cleartool mv | move [ –c·omment comment | –cfi·le comment-file-pname |–cq·uery
| –cqe·ach | –nc·omment ] pname target-pname

Move to another directory:

cleartool mv | ove [ –c·omment comment | –cfi·le comment-file-pname |–cq·uery
| –cqe·ach | –nc·omment ] pname [ pname ... ] target-dir-pname

mvfslog

The mvfslog command sets or displays the verbosity level and location for MVFS console error logging. The initial setting is error, in which only RPC errors and actual MVFS errors are logged; warnings and diagnostics are suppressed.

Each logging level includes messages from the previous levels. For example, info includes messages from error and warn.

Location:

../rational/clearcase/bin

Syntax:

UNIX only:

mvfslog [ –kern·log file | –nokern·log ]
[ none | error | warn | info | stale | debug ] [ –quiet ]

Windows only:

mvfslog [ none | error | warn | info | stale | debug ]

mvfsstorage

mvfsstorage lists the pathname of the data container of an MVFS file. The pathname may be within view-private storage, the source pool, or the cleartext pool, depending on the kind of file.

Location:

../rational/clearcase/bin

Syntax:

UNIX:

mvfsstorage pname ...

Windows only—Display pathname of data container:

mvfsstorage [ –a | –k | –u ] pname ...

Windows only—Display help on command options:
 

mvfsstorage –h

mvfstime

The mvfstime command executes a command and reports on these statistics:
  • Timing statistics,
  • MVFS usage statistics; for information about these, see the Administrator's Guide,.

Use this command to perform timing experiments for applications running in a ClearCase environment.

The statistics gathered while command is running under mvfstime are systemwide statistics for that time period and are not limited to that command's activities. To get an accurate reading of the MVFS activity of command, make sure that no other activity is taking place on the machine when you invoke mvfstime.

For information about UNIX statistics, see the csh(1) reference page.

Note: Use of this command is not supported except with the direct assistance of Rational Customer Support.
Location:

../rational/clearcase/bin

Syntax:

UNIX:

mvfstime [ –icrvVhalzAd ] [ –o outfile] command [ args ]

Windows:

mvfstime [ –iIcrvVhalzAd ] [ –o outfile] command [ args ]

mvfsversion

The mvfsversion command displays the version string of your host's MVFS, in RCS or SCCS format. This string also appears at operating system startup.
cleartool mvfsversion [ –r ] [ –s ]

omake

omake is a ClearCase utility for building software. It includes many of the configuration management facilities provided by the clearmake utility. It also features emulation modes, which enable you to use omake with makefiles that were constructed for use with other popular make variants, including Microsoft NMAKE, Borland Make, and the PVCS Configuration Builder (Polymake).

Note: omake is intended for use in dynamic views. You can use omake in a snapshot view, but none of the features that distinguish it from ordinary make programs — build avoidance, build auditing, derived object sharing, and so on — works in snapshot views. The rest of the information in this reference page assumes you are using omake in a dynamic view.

Location:

../rational/clearcase/bin

Syntax:

omake features a number of ClearCase extensions:

  • Configuration lookup. A build-avoidance scheme that is more sophisticated than the standard scheme based on the time-modified stamps of built objects. For example, this scheme guarantees correct build behavior as C-language header files change, even if the header files are not listed as dependencies in the makefile.
  • Derived object sharing. Developers who work in different views can share the files created by omake builds.
  • Creation of configuration records. Software bill-of-materials records that fully document a build and support rebuildability; also includes automatic dependency detection.
omake [ –f makefile ...] [ –b builtins-file ...]
[ –akinservdphzACDGM] [ –x file ] [ -OLWT ]
[ -EN | -EP | -EO] [ -#1] [ -#2] [ -#4] [ -#8]
[ macro=value ...] [ target_name ...]

pathnames_ccase

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: For 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. For information about restrictions on object names, see the cleartool reference page.

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:
/vob-tag/pname-in-vob

Windows dynamic views—Absolute VOB pathname:
\vob-tag\pname-in-vob

UNIX dynamic views—View-extended pathname:
/view /view-tag/full-pathname

Windows dynamic views—View-extended pathname:
drive-letter:\view-tag\vob-tag\pname-in-vob

permissions

In general, only commands that modify (write to) a VOB or a project VOB are subjected to identity checking. The following hierarchy of identity checking is used, in a command-specific manner, to determine whether a command can proceed or be canceled:
  • All products on UNIX only—root
  • All products except ClearCase LT on Windows only—Member of the ClearCase administrators group
  • ClearCase LT on Windows only—Local administrator of the ClearCase LT server host

    Note: We strongly recommend that you do not make ordinary ClearCase users members of the ClearCase administrators group or allow ClearCase LT users to log on as the local administrator at the ClearCase LT server host.

  • VOB owner
  • Owner of the relevant element (for modifications to branches and versions)
  • Owner of the relevant type object (for modifications to objects of that type)
  • Creator of a version or derived object
  • Owner of the object (pool, hyperlink, replica, activity, checkpoint, domain, role, state, user)
  • User associated with an event
  • Members of an object's group (same group ID)

Both file system and non-file-system objects have an owner and a group; this information is stored with the object. When an object is created, its owner and group are set to that of the user who created it. Use the protect command to change the owner (–chown) or group (–chgrp) of the object. The describe command displays the owner and group of the object.

The scheduler maintains its own access control list (ACL), which determines who is allowed access to the scheduler and to the ACL itself. See the schedule reference page for more information.

profile_ccase

The cleartool user profile (.clearcase_profile) is an ordered set of rules that determine certain command option defaults for one or more cleartool commands. An option you supply in a command line overrides the command option default specified in .clearcase_profile.

For example, many cleartool commands accept user comments with the –c, –cfile, –cq, –cqe, or –nc option. If you specify none of these options, cleartool invokes one of them by default. The option invoked is different for each command, but is always one of –cq, –cqe, or –nc. If cleartool finds a file named .clearcase_profile in your home directory, it checks to see whether the file contains a comment rule that applies to the current command. If so, it invokes the comment option indicated by that rule. No error occurs if this file does not exist; cleartool invokes the command's standard comment default.

An alternative name for the user profile can be specified with the environment variable CLEARCASE_PROFILE. Its value must be a full pathname.

command_name  flag 

promote_server

The promote_server program migrates a derived object's data container file from private storage to shared storage. When clearmake or omake winks in a derived object (DO) that was previously unshared, it invokes promote_server to copy the data container file from view-private storage to a VOB storage pool.

Note: clearmake or omake also migrates a DO's configuration record from private storage to shared storage at the same time. This work is performed by clearmake or omake itself, not by promote_server.

The destination storage pool is determined by the DO's pathname. By definition, this pathname is under a VOB tag; that is, the DO is in some VOB directory. The DO storage pool to which the directory element is assigned is the destination of the promotion. (On UNIX systems, some build scripts create multiple hard links, in different directories, to a derived object. In this case, the data container is promoted to the storage pool of only one of the directories.)

clearmake or omake invokes promote_server by making a request to the ClearCase master server, albd_server. promote_server runs as the owner of the view in which the data container to be copied resides (UNIX) or as the user clearcase (Windows), which guarantees read access to the data container.

After promoting a DO, the promote_server remains active for several minutes to ensure that subsequent promotions from the same view are processed with the least overhead. During this time, the promote_server remains associated with the view from which the DO was promoted; if two users try to promote DOs from the same view, at the same time, they share (serially) the same promote_server.

Note: Never run promote_server manually. It must be invoked only by clearmake or omake. For information about transferring a derived object's data container to VOB storage, see the view_scrubber reference page.

protect

The protect command sets the owner, group, or permissions for one or more elements, shared derived objects, or named VOB objects. This information is maintained in the VOB database.

Note: This command does not apply to files loaded in a snapshot view.

The main use of protect is to control access by standard programs to an element or object's data. For example, you can make some elements readable by anyone and make others readable by only their group members.

Modifying the permissions of an element changes the permissions of all of its source containers and (if applicable) its cleartext containers. That is, the change affects all versions, not just the version selected by the current view. There is no way to change the permissions of an individual version.

Some forms of protect affect ClearCase and ClearCase LT access. For example, a checkout or checkin is permitted only if the user is the element's owner or is a member of the element's group.

Syntax:
cleartool protect [ –cho·wn login-name ] [ –chg·rp group-name ]
[ –chm·od permissions ]
[ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach | –nc·omment ]
{ [ –fil·e | –d·irectory ] [ –r·ecurse ] [ –pna·me ] pname ...
| object-selector ...
}

protectvob

protectvob manages the ownership and group membership of the files and directories in a VOB, by changing the OS-level permissions on files and directories within the VOB storage area.

ClearCase on UNIX only. If the VOB has remote storage pools, you may need to execute this command on the remote host also to complete the permissions update.

Replicated VOBs. If you run protectvob -chown or protectvob -chgrp on a VOB replica that preserves identities, you must follow these steps to prevent metadata divergence among replicas in the VOB family:

  1. Stop synchronization among identities-preserving replicas in the family. Make sure that all update packets have been imported.
  2. Run protectvob -chown or protectvob -chgrp on all identities-preserving replicas in the family. You must use the same options and arguments in each command.
  3. Restart synchronization.

If the storage pools are remote, such as when using NAS devices, you will need to run the chown_pool and chown_container utilities, to change the protect of the files and directories in the  .s (source) .d (data) and .c (cleartext pools) raw storage areas, if you change the primary group (-chgrp option) or the ownership (-chown option).

Syntax:
cleartool protectvob [ –f·orce ] [ –cho·wn user ] [ –chg·rp group ]
[ –add·_group group[,...] [ –del·ete_group group[,...] ]
vob-storage-pname ...

pwd

The pwd command lists the current working directory. This command is intended for use in interactive cleartool and multitool sessions, and in batch files or shell scripts that simulate interactive sessions.
Syntax:
cleartool pwd

pwv

The pwv command lists the view tag of your current view context, or ** NONE ** if there is none. There are two kinds of view contexts, as follows:
  • The working directory view context, which any view may have
  • The set view context, which only a UNIX dynamic view may have

Note: This command does not require a product license.

Syntax:

ClearCase:

cleartool lpwv [ –s·hort ] [ –wdv·iew | –set·view | –root]

ClearCase LT:

cleartool pwv [ –s·hort ] [ –wdv·iew | –root]

query_language

The query language is used to formulate queries on VOBs. It includes logical operators similar to those in the C programming language. A query searches one or more VOBs and returns the names of objects: versions, branches, and/or elements. A query may return a single object, many objects, or no objects at all.

A query primitive evaluates to TRUE or FALSE. A TRUE value selects an object, such as an element, branch, or version; a FALSE value excludes it.

A query must be enclosed in quotes if it includes spaces. You may also need to enclose a query in quotes to prevent shell-level interpretation of characters such as ( (open parenthesis). Quoting parentheses in config specs is not required.

Query primitives:
query-function (arg-list)
attribute-type-name  comparison-operator  value
 
Compound queries:
query && query
query || query ! query ( query )
 

Queries in Version Selectors

You can use a query in a version selector in these contexts:

  • Command-line options in the following cleartool commands:

    describe, merge, mkattr, mkbranch, mklabel, rmattr, rmlabel, rmver

  • Configuration rules; see the config_spec reference page
  • Version-extended pathnames in ClearCase and ClearCase LT commands; see the pathnames_ccase reference page

A query in a version selector must be enclosed in braces ( {} ).

When a query is applied to a single branch, ClearCase and ClearCase LT select the most recent version on that branch that satisfies the query. For example:

cmd-context  describe -ver '/main/{attype(QAed)}' util.c 

Using a query without a branch pathname causes an element's entire version tree to be searched. If the query returns a single version, the version-selection operation succeeds; the operation fails if the query returns no version (not found) or returns more than one version (ambiguous). For example:

cmd-context  describe -ver "{attype(QAed)}" util.c 
cleartool: Error: Ambiguous query: "{attype(QAed)}" 

Queries in the find and findmerge Commands

You can also use queries in the find and findmerge commands. In this context, the query can be enclosed in braces ({...}). The query returns the names of all matching objects. For example:

  • UNIX:
    cleartool find util.c -ver attype(QAed) -print 
    util.c@@/main/1
    util.c@@/main/3
  • Windows (notice the quotes):
    cleartool find util.c -ver "attype(QAed)" -print 
    util.c@@\main\1
    util.c@@\main\3

QUERY PRIMITIVES

The query language includes these primitives:

attribute-type-name  comparison-operator  value

comparison-operator is one of the following:

==     !=    <    <=    >    >=

Examples:

BugNum==4053
BugNum>=4000
Status!="tested"
 

This primitive is TRUE if the object itself has an attribute of that type and the value comparison is true. To test whether an object or its subobjects has a particular attribute (for example, an element or its branches and versions), use the attr_sub primitive.

Note: If no attribute named BugNum has been attached to an object, then !BugNum==671 is TRUE, but BugNum!=671 is FALSE. The second query would be true if an attribute of type BugNum existed, but had a different value.

attr_sub (attribute-type-name, comparison-operator, value)
With elements TRUE if the element or any of its branches or versions has an attribute of type attribute-type-name that satisfies the specified comparison with value.
With branches TRUE if the branch or any of its versions has an attribute of type attribute-type-name that satisfies the specified comparison with value.
With versions TRUE if the version itself has an attribute of type attribute-type-name that satisfies the specified comparison with value.
attype (attribute-type-name)
With elements TRUE if the element itself has an attribute of type attribute-type-name.
With branches TRUE if the branch itself has an attribute of type attribute-type-name.
With versions TRUE if the version itself has an attribute of type attribute-type-name.
attype_sub (attribute-type-name)
With elements TRUE if the element or any of its branches or versions has an attribute of type attribute-type-name.
With branches TRUE if the branch or any of its versions has an attribute of type attribute-type-name.
With versions TRUE if the version itself has an attribute of type attribute-type-name.
brtype (branch-type-name)
With elements TRUE if the element has a branch named branch-type-name.
With branches TRUE if the branch is named branch-type-name.
With versions TRUE if the version is on a branch named branch-type-name.
created_by (login-name)
In all cases, TRUE if the object was created by the user login-name (as shown by the describe command).

 
created_since (date-time)
In all cases, TRUE if the object was created since date-time. The date-time argument can have any of the following formats:

date.time | date | time |now where:

date := day-of-week | long-date
time := h[h]:m[m][:s[s]] [UTC [ [ + | - ]h[h][:m[m] ] ] ]
day-of-week := today |yesterday |Sunday | ... |Saturday |Sun | ... |Sat
long-date := d[d]month[[yy]yy]
month := January |... |December |Jan |... |Dec

Specify the time in 24-hour format, relative to the local time zone. If you omit the time, the default value is 00:00:00. If you omit the date, the default is today. If you omit the century, year, or a specific date, the most recent one is used. Specify UTC if you want to resolve the time to the same moment in time regardless of time zone. Use the plus (+) or minus (-) operator to specify a positive or negative offset to the UTC time. If you specify UTC without hour or minute offsets, Greenwich Mean Time (GMT) is used. (Dates before January 1, 1970 Universal Coordinated Time (UTC) are invalid.)

eltype (element-type-name)
In all cases, TRUE if the element to which the object belongs is of type element-type-name.

 
hltype (hlink-type-name), hltype (hlink-type-name, ->), hltype (hlink-type-name ,<-)
In all cases, TRUE if the object is either end of a hyperlink (first form) named hlink-type-name, or is the from-end of a hyperlink (second form), or is the to-end of a hyperlink (third form)

 
lbtype (label-type-name)
In all cases, TRUE if the object itself is labeled label-type-name. (Because elements and branches cannot have labels, this primitive can be true only for versions.)

 
lbtype_sub (label-type-name)
With elements TRUE if the element has a version that is labeled label-type-name.
With branches TRUE if the branch has a version that is labeled label-type-name.
With versions TRUE if the version itself is labeled label-type-name.
merge (from-location , to-location)
In all cases, TRUE if the element to which the object belongs has a merge hyperlink (default name: Merge) connecting the from-location and to-location. You can specify either or both locations with a branch pathname or a version selector. Specifying a branch produces TRUE if the merge hyperlink involves any version on that branch. The branch pathname must be complete (for example, /main/rel2_bugfix, not rel2_bugfix).

 
pool (pool-name)
In all cases, TRUE if the element to which the object belongs has a source pool or cleartext pool named pool-name.

 
trtype (trigger-type-name)
In all cases, TRUE if the element to which the object belongs has an attached or inherited trigger named trigger-type-name.

 
version (version-selector)
With elements TRUE if the element has a version with the specified version-selector.
With branches TRUE if the branch has a version with the specified version-selector.
With versions TRUE if the version itself has the specified version-selector.

Note that in this context, version-selector cannot itself contain a query. For example, version(REL1) is valid, but version(lbtype(REL1)) is not.

COMPOUND QUERIES

Primitives can be combined into expressions with logical operators. An expression can take any of these forms, where query is a primitive or another expression:

query || query Logical OR
query && query Logical AND
! query Logical NOT
( query ) Grouping to override precedence

OPERATOR PRECEDENCE

The precedence and associativity of the operators for attribute comparisons and formation of logical expressions are the same as in the C programming language:

Highest precedence: ! Right associative
Lower precedence: <   <=   >   >= Left associative
Lower precedence: ==   != Left associative
Lower precedence: && Left associative
Lowest precedence: || Left associative

EXAMPLES

The UNIX examples in this section are written for use in csh. If you use another shell, you may need to use different quoting and escaping conventions.

The Windows examples that include wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you may need to change the wildcards and quoting to make your command interpreter process the command appropriately.

In cleartool single-command mode, cmd-context represents the UNIX shell or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.

  • On a UNIX system, display all versions of test.c for which the attribute QAed has the value Yes.
    cat ‘cleartool describe –s –ver /main'{QAed==”Yes”}' test.c‘ 
  • Attach the label REL6 to the version of test.c that is already labeled REL5.

    UNIX:

    cleartool mklabel -ver '{lbtype(REL5)}' REL6 test.c 
    Created label "REL6" on "test.c" version "/main/4". 

    Windows:

    Z:\vob2\src> cleartool mklabel -ver "{lbtype(REL5)}" REL6 test.c
    Created label "REL6" on "test.c" version "\main\4".
  • Attach an attribute to the latest version of test.c created since yesterday at 1 P.M. by user asd. Note the use of backslashes (\) to escape quote characters (") required to specify a string argument to mkattr.

    UNIX:

    mkattr -ver '{created_since(yesterday.13:00)&&created_by(asd)}' QAed \"No\" test.c
    Created attribute "QAed" on "test.c@@/main/5".

    Windows:

    cleartool> mkattr -ver "{created_since(yesterday.13:00)&&created_by(asd)}" QAed ^ \"No\" test.c
    Created attribute "QAed" on "test.c@@\main\5".
  • List each branch named rel2_bugfix that occurs in an element to which a trigger named mail_all has been attached.

    UNIX:

    cleartool find . -branch 'brtype(rel2_bugfix)&&trtype(mail_all)' -print
    ./util.c@@/main/rel2_bugfix
     

    Windows:

    Z:\vob2\src> cleartool find . -branch "brtype(rel2_bugfix)&&trtype(mail_all)" -print
    .\util.c@@\main\rel2_bugfix

quit

The quit command ends an interactive cleartool or multitool session , returning control to the parent process. You can also exit by entering the exit command.On UNIX, you can also type a UNIX EOF character (typically CTRL+D).
Syntax:

cleartool q·uit

rebase (UCM)

The rebase command reconfigures a stream by adding, dropping, or replacing one or more of the stream's foundation baselines. The file and directory versions selected by those new baselines (and thus their associated activities) then become visible in the stream's views.

Only labeled baselines can serve as foundation baselines.

Any changes made in the stream before a rebase operation are preserved during the rebase. For any file modified in the stream, rebase merges any changes that are present in versions of that file in the new foundation baselines into the latest version of that file in the stream, thereby creating a new version. All such merged versions are captured in the change set of an integration activity that rebase creates. This integration activity becomes the view's current activity until the rebase operation is completed or canceled.

You must perform a rebase operation in a view belonging to the stream that is being rebased. Before starting the rebase operation, check in all files in that view. By default, the rebase operation stops when it encounters a checkout conflict. However, for single stream project only, rebase skips the checked-out file and continue with other files.

If you want to recommend a baseline after rebasing to it, you must add it to the list of recommended baselines with chstream –recommended.

As a rule, you should rebase development streams often to pick up changes in the project's recommended baselines. By doing so, you can find integration problems early, when they are easier to fix. In addition, rebasing just before performing a deliver operation reduces or eliminates the need for manual merging during the delivery.

You cannot rebase when a deliver operation is in progress.

Rules for Rebasing a Stream

A stream can be rebased to a baseline that meets the following criteria:

  • The baseline is not from the stream that is being rebased.
  • The baseline is labeled. Baselines created by deliver operations are not labeled by default. For information about how to change a baseline's labeling status, see the chbl reference page.

Additional rules apply to integration streams and development streams in selecting a baseline:

  • An integration stream can be rebased only to a baseline created in another project or to an imported or initial baseline of that project.
  • A development stream can be rebased to a baseline that meets one of the following criteria:
    • The baseline was created in its parent stream.
    • The baseline is in its parent stream's foundation.
    • The baseline was created in a stream other than its parent stream and is contained in its parent stream. A baseline is contained in another baseline if all changes in the first baseline are included in the second baseline.

    Note: Read-Only streams and nonmodifiable components in a development stream are exempt from the above rules. However, if the component's modifiability changes in the future, the development stream may or may not be able to modify the component at the baseline it is configured with. It may if the baseline is contained in its parent stream for this component. Otherwise it may not until the baseline is rebased to a compatible baseline for that component.

Rebase is typically used to advance a stream's configuration, that is, to replace its current foundation baselines with more recent ones. However, under certain conditions, rebase can be used to revert a baseline, and to add or drop a component in a stream's configuration. It can also switch to a baseline that is neither an ancestor nor a descendant of the current foundation. The rules explained above are general rules for all rebase operations. You need to satisfy only the general rules when adding a component to a stream. When you advance, revert, drop, or switch a baseline, you need to satisfy the general rules and some additional ones.

  • To advance a stream's configuration, the new baseline must contain the current foundation baseline.
  • To revert or drop a baseline for a component in a stream, one of the following conditions must be met:
    • The component is nonmodifiable.
    • The component is modifiable but has not been modified in the stream, and the component is not in the configuration of any child streams.
  • To switch to a baseline that is neither an ancestor nor a descendant of the current foundation, one of the following conditions must be met:
    • The component is nonmodifiable.
    • The component is modifiable but has not been modified in the stream, and the component is not in the configuration of any child streams.
    • The component has been modified but the new baseline contains the current foundation baseline, and the component is not in the configuration of any child streams.

These rules ensure that any changes made in a stream are not lost when the configuration changes.

Handling of Elements of Nondefault Merge Types

In a rebase operation, automatic merging is the default behavior for elements, unless user or never merge types were set for the elements. For information about setting merge behavior for an element type, see mkeltype.

Rebase and deliver operations handle elements of user or never merge types in much the same way. For more information, see this topic in deliver.

Syntax:
Begin a rebase operation using the graphical user interface:
cleartool rebase –gr·aphical [ –vie·w rebase-view-tag ]
[ –str·eam stream-selector ] [ –q·uery | –qal·l ]

Cancel or check the status of a rebase operation:

cleartool rebase { –can·cel | –sta·tus [–l·ong ] }
[ –vie·w rebase-view-tag ] [ –str·eam stream-selector ]

Preview a rebase operation:
 

cleartool rebase –pre·view [ –s·hort | –l·ong ] [ –vie·w rebase-view-tag ]
[ –str·eam stream-selector ]
{ –rec·ommended | { –bas·eline baseline-selector[,...]
–dba·seline baseline-selector[,...] }

Begin a rebase operation:

cleartool rebase { –rec·ommended | { –bas·eline baseline-selector[,...]
–dba·seline baseline-selector[,...] } }
[ –vie·w rebase-view-tag ] [ –str·eam stream-selector ]
[ –com·plete ] [ –gm ·erge | –ok ]
[ –q·uery | –abo·rt | –qal·l ] [ –ser·ial ]

Resume or complete a rebase operation:

cleartool rebase { –res·ume | –com·plete } [ –vie·w rebase-view-tag ]
[ –str·eam stream-selector ] [ –gm·erge | –ok ]
[ –q·uery | –abo·rt | –qal·l ] [ –ser·ial ] [–f· orce ]

recoverview

The recoverview command repairs a view database and the associated private storage area of a dynamic view. (A snapshot view has no private storage in the same sense as a dynamic view has.) Typically, you use this command after a system crash or similar mishap. You may also want to use this command to regain access to stranded view-private files.

Recovering View-Private Files: View lost+found Directory

A file in view-private storage is normally accessed through a VOB pathname. That is, the file appears to be located in the VOB, but is actually stored in the view. But this view-VOB correspondence can be disrupted:

  • A VOB can become temporarily unavailable, for example, by being unmounted.
  • A VOB can become permanently unavailable, by being deleted.
  • A particular VOB directory can become unavailable permanently, by being deleted with an rmelem command.

In all these cases, view-private files that are accessed through the unavailable VOB structure become stranded; the files cannot be used for normal ClearCase operations, because there are no VOB pathnames through which they can be accessed. You can resynchronize your view with the available VOBs with the –vob and –dir options. This recovers stranded files by moving them into the view's lost+found directory. Recovered files remain inaccessible to normal ClearCase operations; you can access them through the view storage directory, using standard operating system utilities and commands.

Syntax:

Recover files associated with deleted VOB or deleted directory:

cleartool recoverview [ –f·orce ] { –vob vob-identifier | –dir dir-identifier }
{ –tag view-tag | view-storage-dir-pname }

Synchronize a view with one or more VOBs, moving stranded objects to a known location:

cleartool recoverview –syn·chronize [ –vob pname-in-vob ]
{ –tag view-tag | view-storage-dir-pname }

Example:

reformatview

The reformatview command changes the format of a view database from that used in a previous release of ClearCase or ClearCase LT to the current format. A view database is a set of binary files in the db subdirectory of the view storage directory. A new release may use a different database format to support new product features, to enhance storage efficiency, or to improve performance.

Converting the view database involves two major steps:

  1. Dumping the existing database to a set of ASCII files. This step invalidates the view database, which is renamed to db.dumped. You cannot use the view until its database is reloaded.
  2. Loading the ASCII files into a new database that uses the new format.

Note: This does not overwrite the old, invalid view database; it remains in the view storage directory, as db.dumped, until you explicitly delete it with a standard operating system command.

A view's view_server process detects the need for reformatting, logs a message, and automatically reformats the view. reformatview itself writes status messages to view_log, not to stdout or stderr.

You can also use reformatview to move a view storage area between hosts of different architectures—that is, hosts on which there are differences in the binary files that implement the view database.

Possible Data Loss

In the case of a dynamic view, if the view database requires recovery, some information may be lost in the dump/load process. In addition, some view-private files may be moved into the view's lost+found directory. See the recoverview reference page for details.

Note: On UNIX, if a view-private file is owned by someone other than the owner of the view storage area, reformatview always strips its setuid bit (if the bit is set)

In the case of a snapshot view, the lost information may included loaded files as well as view-private files.

Syntax:
cleartool reformatview [ –dum·p | –loa·d ]
{ –tag view-tag | view-storage-dir-pname }
If a view's database does not require reformatting (it is up to date), reformatview displays a message and takes no other action; if the database is out of date, reformatview performs a dump, then a load.
–dum·p
Performs only the first step—creating an ASCII dump of the view database in file view_db.dump_file in the view storage directory.
–loa·d
Performs only the second step—replacing the old view database with a new one, using the contents of a previously created ASCII dump file.

Examples:

reformatvob

reformatvob changes the format of a VOB database by dumping it to an ASCII file and then loading the ASCII file into a new database. You use reformatvob for these purposes:
  • To upgrade the schema version of a VOB.
  • When moving a VOB to a host with a different architecture (binary data format).
  • To decrease the size of a VOB database, physically deleting records that have been logically deleted by vob_scrubber

reformatvob is a one-way command. The dump and load phases must be allowed to complete (although they can take place at different times). You cannot abort and undo a reformat operation after you have started it; you can only restart and complete the operation. reformatvob locks the VOB before reformatting it. If the VOB is already locked, reformatvob proceeds with the reformatting and then unlocks the VOB.

Note: Unless invoked with the –rm option, reformatvob does not overwrite the old, invalid VOB database; it renames the old database to db.date. The old database remains in the VOB storage directory until you delete it with a standard operating system command.

Note: Always back up a VOB before you reformat it

Syntax:
ClearCase on UNIX:
cleartool reformatvob [ –dum·p | –loa·d ] [ –rm ] [ –f·orce ]
[ –to dumpfile-dir-pname ]
[ –hos·t hostname –hpa·th local-pname ] vob-storage-dir-pname

ClearCase on Windows:

cleartool reformatvob [ –dum·p | –loa·d ] [ –rm ] [ –f·orce ]
[ –hos·t hostname –hpa·th local-pname ] vob-storage-dir-pname

ClearCase LT on UNIX:

cleartool reformatvob [ –dum·p | –loa·d ] [ –rm ] [ –f·orce ]
[ –to dumpfile-dir-pname ] vob-storage-dir-pname

ClearCase LT on Windows:

cleartool reformatvob [ –dum·p | –loa·d ] [ –rm ] [ –f·orce ]
vob-storage-dir-pname

register

The register command creates or replaces an entry in VOB or view object registries. The registries enable clients to determine the physical storage locations of VOBs and views they access. Note that register has no effect on the VOB or view tag registries. You can also use register to update an existing registry entry, or to re-register a VOB or view that was temporarily removed from service with unregister.
Syntax:
ClearCase—Register a view:
cleartool reg·ister –vie·w [ –rep·lace ]
[ –hos·t hostname –hpa·th host-storage-pname ]
view-storage-pname

ClearCase—Register a VOB:

cleartool reg·ister –vob [ –ucm·project ] [ –rep·lace ]
[ –hos·t hostname –hpa·th host-storage-pname ] vob-storage-pname

ClearCase LT—Register a view:

cleartool reg·ister –vie·w [ –rep·lace ] view-storage-pname

ClearCase LT—Register a VOB:

cleartool register –vob [ –ucmproject ] [ –replace ] vob-storage-pname

relocate

The relocate command moves elements, including directory trees, from one VOB to another. All related VOB database entries and data containers are moved to the target VOB. relocate preserves the “move from” VOB's namespace by substituting VOB symbolic links for moved elements.

The more common use of relocate involves splitting a piece from one VOB and moving it to a newly created VOB. However, you can move an arbitrary collection of elements from one VOB to a location in any other VOB. You cannot use relocate to move an element to a new location in the same VOB. Use cleartool mv for this purpose.

For a dynamic view, view-private files and nonversioned DOs are not relocated. If a relocated directory contains view-private files, they are stranded; DOs are removed.

Warning: The relocate command makes irreversible changes to at least two VOBs and their event histories. We recommend that you not use it frivolously or routinely for minor adjustments. Furthermore, you are advised to stop VOB update activity before and during a relocate operation.

Syntax:
cleartool relocate [ –f·orce ] [ –qal·l ] [ –log log-pname ] [ –upd·ate ]
pname [ pname ... ] target-dir-pname

rename

The rename command renames a ClearCase, ClearCase LT or MultiSite object—for example, a VOB storage pool, a replica, or a type object such as a label type.

If you are renaming a pool, no data container in the pool is affected.

If you are renaming a replica, the name change is propagated to other replicas, through the standard synchronization mechanism. This command is valid only at the replica that masters the VOB-replica object being renamed.

If you are renaming a type object, all instances of the type object, throughout the VOB, are also renamed. If the type object is global, all local copies of the type object are renamed. For example, if you rename a branch type from bugfix to rel1.3_fixes, all existing bugfix branches are also renamed to rel1.3_fixes. (For more information about global type renaming, see the Administrator's Guide.)

Restriction: A VOB cannot contain a branch type and a label type with the same name.

Note: Do not use this command to rename an instance of a type, for example to rename a particular branch of a particular element. For that purpose, use chtype

Note: To move or change the name of a ClearCase or ClearCase LT file or directory element, use the mv command.
Syntax:
cleartool rename [ –c·omment comment | –cfi·le comment-file-pname
| –cq·uery | –cqe·ach | –nc·omment ]
[ –acq·uire ] old-object-selector new-object-selector

reqmaster

This command has three forms: two forms to configure access controls for mastership requests and one form to request mastership of a branch or branch type from the replica that masters the object.

Syntax:
Display or set the ACL for mastership requests:
cleartool|multitool reqmaster –acl [ –edi·t | –set pname | –get ] vob-selector

Set access controls for the replica, branches, or branch types:

cleartool|multitool reqmaster [ –c·omment comment | –cq·uery | –nc·omment ]
{ { –enable | –dis·able } vob-selector
| { –den·y | –allow } [ –inst·ances ] branch-type-selector ...
| { –den·y | –allow } branch-pname ... }

Request mastership of a branch or branch type:
 

cleartool|multitool reqmaster [ –c·omment comment | –cq·uery | –nc·omment ]
[ –lis·t ] { [ branch-pname ... ] [ branch-type-selector ... ] }

reserve

The reserve command changes the checkout status of a checked-out version of an element to reserved. A temporary reserve checkout of version event record is written to the VOB database.
Syntax:
cleartool res·erve [ –c·omment comment | –cfi·le comment-file-pname
| –cq·uery| –cqe·ach | –nc·omment ] [ –cact ] pname ...

rgy_backup

By default, the ClearCase scheduler runs rgy_backup periodically. For information about describing and changing scheduled jobs, see the schedule reference page.

When it runs on a host that is not a backup registry host, rgy_backup checks the backup server configuration and exits. When it runs on a backup registry server host, rgy_backup takes two snapshots:

  • ClearCase registry files on the primary registry server host.
  • Primary registry host's client list, which is maintained by the registry server host.

rgy_backup stores these snapshot files in the directory /var/adm/rational/clearcase/rgy/backup (UNIX) or ccase-home-dir\var\rgy\backup (Windows) on the backup registry server host. rgy_backup removes files older than 96 hours.

rgy_backup names the snapshot file after the original file and appends a time stamp to the file name.

  • On UNIX, rgy_backup also creates a symbolic link, with the same name as the original file, that points to the snapshot file. For example, for registry file vob_tag, rgy_backup creates in the backup directory:
    • vob_tag .17-Jul-99.18:30:15
    • A symbolic link named vob_tag that points to vob_tag .17-Jul-99.18:30:15
  • On Windows, rgy_backup names the snapshot file after the original file and appends a time stamp to the file name. rgy_backup also creates a file, with the same name as the original file, that contains the full, time-stamp-extended name of the most recent snapshot file. For example, for registry file vob_tag, rgy_backup creates in the backup directory:
    • vob_tag.17-Jul-99.18:30:15
    • A file named vob_tag that contains the string vob_tag.17-Jul-99.18:30:15

If the primary registry server fails, you can run rgy_switchover to activate the backup registry server and reset all client hosts accordingly. The backup server must be running the same release of ClearCase as that running on the primary server.

rgy_backup logs its snapshot activity in the UNIX file rgy_backup_log or the Windows event log.

UNIX Systems Only—Designating a Backup Registry Host

Each ClearCase host has a text file, /var/adm/rational/clearcase/rgy/rgy_hosts.conf. The name of the primary registry server host appears on the first line, and the name of the backup registry server host appears on the second line. For example, the following rgy_hosts.conf file names mercury as the primary registry server host and venus as the backup registry server host:

cat /var/adm/rational/clearcase/rgy/rgy_hosts.conf
mercury
venus

Typically, you name a backup registry server host on each ClearCase host by supplying information to the site_prep utility when you install ClearCase.

Windows Systems Only—Designating a Backup Registry Host

The Windows Registry key HKEY_LOCAL_MACHINE\SOFTWARE\Atria\ClearCase\CurrentVersion\RegBackup contains the name of the backup registry server host (or the string Unknown, if no backup host has been designated). You can change this key value on the Registry tab in the ClearCase Control Panel.

Typically, a backup registry server host is specified for each client when ClearCase is installed (although designating the backup registry host is not part of the installation procedure itself).

Changing the Backup Registry Server Host

To change the backup registry server host:

  1. Modify the rgy_hosts.conf file on the intended backup registry server to include the host name of the backup registry server as the second line of the file.
  2. Execute rgy_backup on the backup registry server. After you do this, the backup registry server will include current registry information, which it requires to assume the role of the primary registry server.
  3. Modify the rgy_hosts.conf file on each client to be served by the backup registry server, so that the second line of the file contains the host name of the backup registry server.

The next time rgy_backup runs, the primary registry server host updates the name of the backup registry server for all its clients.

Do not designate a backup registry host that is unsuitable to serve as primary registry server host.

If your site uses multiple ClearCase registries, you cannot configure one primary registry server as the backup server for a different registry.

RESTRICTIONS

You must have write permission to the directory /var/adm/rational/clearcase/rgy (UNIX) or ccase-home-dir\var\rgy (Windows).

UNIX FILES

/var/adm/rational/clearcase/rgy/*
/var/adm/rational/clearcase/rgy/backup/*
/var/adm/rational/clearcase/rgy/rgy_hosts.conf
/var/adm/rational/clearcase/rgy/rgy_svr.conf
/var/adm/rational/clearcase/log/rgy_backup_log
/var/adm/rational/clearcase/client_list.db

WINDOWS FILES

ccase-home-dir \var\rgy\*
ccase-home-dir\var\rgy\backup\*

WINDOWS REGISTRY KEYS

HKEY_LOCAL_MACHINE\SOFTWARE\Atria\ClearCase\CurrentVersion\AtriaRegy
HKEY_LOCAL_MACHINE\SOFTWARE\Atria\ClearCase\CurrentVersion\ServerType
HKEY_LOCAL_MACHINE\SOFTWARE\Atria\ClearCase\CurrentVersion\RegBackup
Location:

.../rational/clearcase/bin

Syntax:

rgy_backup

rgy_check

The rgy_check command examines the contents of ClearCase or ClearCase LT VOB and/or view registries, and reports any errors or inconsistencies.

Registry problems have various causes:

  • Editing registry entries with editors such as emacs or Notepad.
  • Improper administration procedures; for example, removing a VOB with an operating system command rather than with rmvob
  • Faulty upgrade procedures; for example, migrating a VOB to a new release that introduces a database schema change without reformatting the VOB (using reformatvob)
  • Defects in older releases of ClearCase or ClearCase LT

If rgy_check finds errors or inconsistencies, it displays a line like the following at the end of its output:

Error: 21 total registry errors/inconsistencies detected.

For each problematic registry entry, rgy_check displays the registry entry and a warning or error message.

Location:

.../rational/clearcase/bin

Syntax:
ClearCase:
rgy_check { –vie·ws | –vob·s } ... [ –reg·ion region ] [ –sto·rage ]

ClearCase LT:

rgy_check { –vie·ws | –vob·s } ... [ –hst·orage ]

rgy_passwd

UNIX Systems

The rgy_passwd command places an encrypted password in the VOB tag password file: /var/adm/rational/clearcase/rgy/vob_tag.sec on the network's registry server host. This file need not already exist.

Knowledge of this password enables an administrator to create public VOBs. Nonprivileged users can mount public VOBs by using the ClearCase mount command. For more information about public VOBs, see the mkvob, mktag, and mount reference pages.

Windows Systems

The rgy_passwd command creates a Security subkey in the Windows Registry and places an encrypted VOB tag password in HKEY_LOCAL_MACHINE\SOFTWARE\Atria\ClearCase\CurrentVersion\Security\RegPasswd. The Security subkey and RegPasswd value exist only on the registry server host.

Knowledge of this password enables a user to create public VOBs.

Location:

.../rational/clearcase/bin

Syntax:

rgy_passwd [ –pas·sword tag-registry-password ]

rgy_switchover

The rgy_switchover command upgrades a backup registry server host (see rgy_backup) to primary registry server host and resets ClearCase clients to use the new primary registry server host. rgy_switchover logs its activities to /var/adm/rational/clearcase/log/albd_log (UNIX) or the Windows event log.

rgy_switchover can modify configuration information only on hosts that are running ClearCase. This means that if the failure of a primary registry server causes a switchover, the (former) primary registry server cannot be informed of the switchover.

To Reinitialize the Tag Registry Password

Because rgy_backup does not copy the tag registry password file to a backup registry, you must initialize the tag registry password with the rgy_passwd command after you run rgy_switchover.

Location:

.../rational/clearcase/bin

Syntax:
rgy_switchover [ –time file-timestamp]
–backup new-backup-server ]  old-registry-server  new-registry-server

rmactivity (UCM)

The rmactivity command deletes one or more activities.

When executed in a view that is associated with a project enabled for ClearQuest, this command unlinks the activity from its associated ClearQuest record and deletes the activity but it does not delete the ClearQuest record.

Syntax:
cleartool rmact·ivity [ –c·omment comment | –cfi·le comment-file-pname
| –cq·uery | –nc·omment ] [ –f·orce ] activity-selector ...

rmattr

The rmattr command removes one or more attributes from VOB-database objects. Attributes can be attached to objects by the mkattr command and by triggers (mktrtype –mkattr). See the mkattr reference page for a list of objects to which attributes can be attached.

rmattr deletes an instance of an attribute type object. To delete the attribute type object itself or to delete the type object and all its instances, use the rmtype command.

Syntax:

cleartool rmattr [ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach | –nc·omment ]
{ [ –ver·sion version-selector ]
[ –pna·me ] attribute-type-selector pname ...
| attribute-type-selector object-selector ... }

rmbl (UCM)

The rmbl command deletes one or more baselines. Versions associated with the baseline are not deleted, only the baseline relationship among the versions.

Syntax:

cleartool rmbl [ –c·omment comment | –cfi·le pname | –cq·uery
| –cqe·ach | –nc·omment ] [ –f·orce ] baseline-selector ...

rmbranch

This command destroys information irretrievably. Using it carelessly may compromise your organization's ability to support old releases.

The rmbranch command deletes one or more branches from their elements. For each branch, deletion entails the following:

  • Removal from the entire branch structure from the VOB database: branch object and version objects
  • Removal of all metadata items (labels, attributes, hyperlinks, and triggers) that were attached to the deleted objects
  • Removal of all event records for the deleted objects
  • (File elements only) Removal of the data containers that hold the file system data of the deleted versions
  • Creation of a destroy sub-branch event record for the parent branch of the deleted branch

Note: If all of an element's versions are stored in a single data container, the deleted versions are removed logically, not physically.

To delete all instances of a branch and the branch type object, use the rmtype command.

Syntax:
cleartool rmbranch [ –c·omment comment | –cfi·le comment-file-pname |–cq·uery
| –cqe·ach | –nc·omment ]
[ –f·orce ] pname ...

rmcomp (UCM)

The rmcomp command deletes a component object. Elements of the component and the VOB associated with the component are not deleted.

Syntax:

cleartool rmcomp [ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
| –cqe·ach |–nc·omment ]
[ –f·orce ] component-selector ...

rmdo

The rmdo command deletes one or more derived objects (DOs). Use rmdo to remove DOs (for example, damaged DOs or DOs that were built incorrectly) so that other users do not use them inadvertently.

Note: This command does not apply to snapshot views.

The details of the removal process depend on the kind of DO (use lsdo –long to determine the kind of DO):

  • For a shared derived object whose data container is in VOB storage, rmdo deletes the entry in the VOB database and also deletes the data container file from one of the VOB's DO storage pools.

    Caution: If you need to remove a shared DO, use lsdo –long to identify the views that reference the DO. Ask the owner of each view to remove the DO from the view with an operating system command or by running make clean or an equivalent command. If the DO is not removed from the referencing views before you use rmdo, error messages appear. For example, when users try to access the DO from the referencing views, the view_server logs VOB warnings. Also, you may see INTERNAL ERROR messages in the ClearCase error_log file; these messages are generated when clearmake or an OS-level command tries to access the DO. The derived object's name is removed from the directory by the OS-level access; thus, subsequent accesses return not found errors.

  • For an unshared derived object whose data container is in view-private storage, rmdo deletes the entry from the VOB database, but does not delete the data container from view storage. The data container is an ordinary file that can still be listed, executed, and so on, but it cannot be a candidate for configuration lookup. The ls –long command lists it with a [no config record] annotation. To delete the data file, use an operating system command.
  • For a nonshareable derived object, which does not have an entry in the VOB database, rmdo converts the DO into an ordinary view-private file. To delete the file, use an operating system command.

In each case, rmdo also deletes the associated configuration record if it is no longer needed. Both of the following conditions must be true:

  • No other sibling DO (created in the same build script execution) still exists.
  • The DO is not a build dependency (subtarget) of another DO that still exists.

rmdo does not delete DO versions. To delete a DO that has been checked in as a version of an element, use rmver.

Scrubbing of Derived Objects

ClearCase includes a utility, scrubber, that deletes shareable DOs. scrubber deletes the entries in the VOB database and (for shared DOs) the data containers in the VOB's storage pools. By default, the ClearCase scheduler runs scrubber periodically. See the schedule reference page for information on describing and changing scheduled jobs.

Each DO pool has scrubbing parameters, which you can modify with the mkpool –update command.

 
Syntax:

Remove individual derived objects:

cleartool rmdo do-pname ...

Remove collections of derived objects:

cleartool rmdo { –a·ll | –zer·o } [ –bef·ore date-time ]
[ –sin·ce date-time ] [ pname ... ]

rmelem

The rmelem command completely deletes one or more elements or symbolic links. In a snapshot view, rmelem also unloads the element from the view.

This command destroys information irretrievably. Use it thoughtfully to avoid compromising your organization's ability to support old releases. In many cases, it is better to use the rmname command.

For each element, rmelem does the following:

  • Removes the entire version tree structure from the VOB database: element object, branch objects, and version objects.
  • Removes all metadata (labels, attributes, hyperlinks, and triggers) attached to the element.
  • Removes all event records for the element.
  • (File elements) Removes the data containers that hold the element's file system data from its source storage pool.
  • Removes all references to the element from versions of the VOB's directory elements. (As a result, subsequent listings and comparisons of those directory versions will be historically inaccurate.)
  • Creates a destroy element event record in the element's VOB; this event record is displayed by lshistory vob:.

For each symbolic link, rmelem does the following:

  • Removes the symbolic link and link object from the VOB.
  • Removes all metadata (attributes and hyperlinks) attached to the symbolic link .
  • Removes all event records for the symbolic link.
  • Removes all references to the symbolic link from versions of the VOB's directory elements. (As a result, subsequent listings and comparisons of those directory versions will be historically inaccurate.)

Note: rmelem does not create an event record when you remove a symbolic link.

rmelem deletes only the instance of an element type object that is attached to the element. To delete the element type object or to delete the type object and all its instances, use the rmtype command.

Deleting a Directory Element

Deleting a directory element may cause some other elements (and symbolic links, if the VOB is replicated) to be orphaned; that is, it is no longer cataloged in any version of any directory. rmelem displays a message and moves an orphaned element or symbolic link to the VOB's lost+found directory:

cleartool: Warning: Object "foo.c" no longer referenced.
cleartool: Warning: Moving object to vob lost+found directory
as "foo.c.a0650992e2b911ccb4bc08006906af65".

Each derived object in the deleted directory is also moved to lost+found. (Only dynamic views have derived objects.) The derived object has no data, but you can use it in such commands as lsdo and catcr. View-private objects in the deleted directory are temporarily stranded, but can be transferred to the view's own lost+found directory, as follows:

  1. Use lsprivate to locate stranded files and to determine the identifier of the deleted directory element:
    cmd-context  lsprivate –invob /tmp/david_phobos_hw 
    .
    .
    .
    #<Unavailable-VOB-1>/<DIR-c8051152.e2ba11cc.b4c0.08:00:69:06:af:65>/myfile
  2. Use recoverview to move all the stranded files that resided in the deleted directory:
    cmd-context  recoverview –dir c8051152.e2ba11cc.b4c0.08:00:69:06:af:65 –tag myview 
    Moved file /usr/people/david/myview.vws/.s/lost+found/5ECC880E.00A5.myfile

Deleting Elements and Symbolic Links from the lost+found Directory

Use rmelem carefully when deleting elements or symbolic links from the lost+found directory. While the content of lost+found is typically unwanted elements and symbolic links, in some circumstances it can contain elements that are cataloged elsewhere in the VOB (that is, not orphaned). For this reason, we do not recommend executing rmelem recursively in lost+found.

If you need an element in lost+found, catalog it in a versioned directory using mv.

If the element you are trying to remove has no versions with attached metadata and you created all branches, you need only be the element owner.

Syntax:

cleartool rmelem [ –f·orce ] [ –c·omment comment | –cfi·le comment-file-pname
| –cq·uery | –cqe·ach | –nc·omment ] pname ...

rmfolder (UCM)

The rmfolder command deletes one or more folders.
  • Syntax:
  • cleartool rmfolder [ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
    | –cqe·ach | –nc·omment ]
    [ –f·orce ] folder-selector ...
  • rmhlink

    The rmhlink command removes one or more hyperlinks from VOB-database objects. Hyperlinks can be attached to objects by the mkhlink command and by triggers (mktrtype –mkhlink). For a list of objects to which hyperlinks can be attached, see the mkhlink reference page.

    rmhlink deletes a reference to a hyperlink type object. To delete the hyperlink type object itself or the type object and all its instances, use the rmtype command.

    To list existing hyperlinks, use the describe command, or use the find command with the hltype primitive.

    Syntax:

    cleartool rmhlink [ –c·omment comment | –cfi·le comment-file-pname |–cq·uery
    | –cqe·ach | –nc·omment ] hlink-selector ...

    rmlabel

    The rmlabel command removes one or more version labels from versions of elements. Labels can be attached to versions by the mklabel command and by triggers (mktrtype –mklabel).

    rmlabel deletes a reference to a label type object. To delete the label type object itself or the type object and all its instances, use the rmtype command.

    Syntax:

    cleartool rmlabel [ –c·omment comment | –cfi·le comment-file-pname |–cq·uery
    | –cqe·ach | –nc·omment ]
    [ –ver·sion version-selector ] label-type-selector pname ...

    rmmerge

    The rmmerge command deletes an existing merge arrow (a hyperlink of the predefined type Merge) between two versions of an element. Thus, this command is a specialized form of the rmhlink command. Both commands have an identical result; they differ only in the way you specify the merge arrow:
    • With rmhlink, you specify the merge arrow itself, using a hyperlink selector.
    • With rmmerge, you specify the versions linked by the merge arrow.

    To list existing merge arrows, use the describe command, or use the find command with the hltype primitive. For example:

    cmd-context  describe util.c 
    version "util.c@@/main/3"
     created 05-Apr-99.17:01:12 by Allison (akp.user@starfield)
     element type: text_file
     Hyperlinks:
     Merge@148@/usr/tmp/poolwk
     /usr/tmp/poolwk/src/util.c@@/main/rel2_bugfix/1 ->
     /usr/tmp/poolwk/src/util.c

    Renaming the Merge Hyperlink Type

    Renaming the predefined hyperlink type for merge arrows does not defeat rmmerge. You specify the element's versions; rmmerge then determines the hyperlink type used for merge arrows in that element's VOB.

    Syntax:

    cleartool rmmerge [ –c·omment comment | –cfi·le comment-file-pname |–cq·uery
    | –cqe·ach | –nc·omment ] from-pname to-pname

    rmname

    By default, a name can be removed from a directory only if that directory is checked out and there are no checkouts for that element. rmname appends an appropriate line to the directory's checkout comment.

    rmname modifies one or more checked-out directories by removing the names of elements and/or VOB symbolic links (in the manner of the UNIX unlink(2) system call). Old versions of the directories do not change; the names continue to be cataloged in the old versions.

    To remove a name from a checked-in directory version, you can use the –nco option. For example, you may want to remove an old symbolic link that points to a file that has been removed.

    In a snapshot view, this command implicitly executes an update operation on the affected elements.

    Example: Suppose you checked out version 3 of a directory named a.dir. Only your view sees this directory version while it is checked out. The command rmname foo.c deletes the name foo.c from the checked-out version of the directory, but leaves references to foo.c in earlier versions (if any) intact. When you check in the directory, all views can access the new version 4, which does not include foo.c.

    Keep the following points in mind:

    • rmname does not delete elements themselves, only references to elements. Use rmelem (very carefully) to delete elements and all their names from their VOBs.
    • Removing the last reference to an element name causes the element to be orphaned. Such elements are moved to the VOB's lost+found directory. (See the mkvob command for details.)
    • Removing the last reference to a VOB symbolic link works differently depending on whether the VOB is replicated:
      • If the VOB is unreplicated, the link object is deleted.
      • If the VOB is replicated, the link object is moved to the VOB's lost+found directory.

    Undoing the rmname Command

    To restore a directory entry for an element that has been removed with rmname, use the ln command to create a VOB hard link to the element's entry in any previous version of the directory. For example:

    cmd-context checkout src Checkout parent directory
    cmd-context rmname src/msg.c Oops!
    cmd-context ln src@@/main/LATEST/msg.c src/msg.c Restore deleted name

    If there are no entries for the element in any previous version of the directory, the element is orphaned; that is, moved it to its VOB's lost+found directory. You can move the element to its proper location with the cleartool mv command. (You cannot use ln to link elements that are in the lost+found directory.)

    Syntax:

    cleartool rm·name [ –c·omment comment | –cfi·le comment-file-pname |–cq·uery
    | –cqe·ach | –nc·omment ]
    [ –nco ] [ –f·orce ] pname ...

    rmpool

    The rmpool command deletes one or more storage pool directories from a VOB, along with all the data container files stored within them.

    Reassigning Elements

    Before removing a storage pool, you must reassign all its currently assigned elements to a different pool, using the chpool command. Otherwise, rmpool aborts with an elements using pool error. To list all the elements in a source or cleartext pool, use a find command. For example

    • UNIX
      cmd-context  find -all -element 'pool(source_2)' –print
    • Windows
      cmd-context  find -all -element pool(source_2) –print

    This command does not work with derived object pools.

    Deleting Derived Object Pools

    There is no way to move a shared derived object from one pool to another. Thus, you can delete a derived object pool only if either condition is true:

    • No directory elements have been assigned to the pool.
    • All data containers in the pool have been removed by the scrubber program or rmdo commands, and each directory element that currently uses the pool has been assigned to a different derived object pool.

    Syntax:

    cleartool rmpool [ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
    | –cqe·ach | –nc·omment ] pool-selector ...

    rmproject (UCM)

    The rmproject command deletes one or more projects. All streams must be removed before deleting a project. You cannot delete a project that contains a stream.

    Projects Enabled for ClearQuest

    When you delete a project that uses the UCM-ClearQuest integration, the project is unlinked from its associated ClearQuest record, but the ClearQuest record is not deleted.

    Syntax:

    cleartool rmproj·ect [ –c·omment comment | –cfi·le comment-file-pname
    | –cq·uery | –nc·omment ] [ –f·orce ] project-selector ...

    rmregion

    The rmregion command removes a region entry from the ClearCase registry's regions file.

    rmregion modifies the ClearCase registry only. It does not affect client host region assignments. If you remove a region to which ClearCase client hosts are assigned, those clients receive error messages.

    Syntax:

    cleartool rmregion –tag region-tag [ –rma·ll [ –pas·sword tag-registry-password ] ]

    rmstgloc

    The rmstgloc command deletes registrations for view and VOB server storage locations. The associated physical storage is not deleted, and views and VOBs residing at the server storage location continue to be accessible. However, no views or VOBs may be created at the server storage location after you have removed its registry entries.

    To remove view or VOB physical storage (and their registrations), always use rmview or rmvob, never an operating system command.

    Syntax:

    ClearCase:
    cleartool rmstgloc [ –all] [ –reg·ion network-region ]
    { stgloc-name | –sto·rage stgloc-pname }

    ClearCase LT:

    cleartool rmstgloc { stgloc-name | –sto·rage stgloc-pname }

    rmstream (UCM)

    The rmstream command deletes one or more streams.

    Syntax:

    cleartool rmstream [ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
    | –cqe·ach | –nc·omment ] [ –f·orce ] stream-selector ...

    rmtag

    The rmtag command removes one or more entries from the network's view tag registry or VOB tag registry. For a discussion of the registries, see the Administrator's Guide. You cannot remove a tag that is currently in use.

    Syntax:

    ClearCase—Remove a view tag:
    cleartool rmtag –vie·w [ –reg·ion network-region | –a·ll ] view-tag ...

    ClearCase—Remove a VOB tag:

    cleartool rmtag –vob [ –reg·ion network-region | –a·ll ]
    [ –pas·sword tag-registry-password ] vob-tag ...

    ClearCase LT—Remove a view or VOB tag:

    cleartool rmtag { –vie·w view-tag ... | –vob vob-tag ... }

    rmtrigger

    The rmtrigger command removes an attached trigger from one or more elements or UCM objects. The specified trigger-type-selector is not affected by rmtrigger. To delete the trigger type, use the rmtype command.
    Syntax:

    cleartool rmtrigger [ –c·omment comment | –cfi·le comment-file-pname |–cq·uery

    | –cqe·ach | –nc·omment ]
    [ –nin·herit | –nat·tach ] [ –r·ecurse ]
    trigger-type-selector { pname | ucm-object-selector } ...

    rmtype

    The rmtype command removes one or more type objects from a VOB.

    The file vista.tjf records updates to the VOB that result from rmtype operations. vista.tjf can grow very large. For information about limiting its size, read about the file db.conf in the config_ccase reference page.

    Syntax:

    cleartool rmtype [ –ign·ore ] [ –rma·ll [ –f·orce ] ]
    [ –c·omment comment | –cfi·le comment-file-pname |–cq·uery | –cqe·ach
    | –nc·omment ] type-selector ...

    rmver

    This command destroys information irretrievably. Using it carelessly may compromise your organization's ability to support old releases.

    rmver deletes one or more versions from their elements. For each version, this entails the following:

    • Removal of the version object from the VOB database
    • Removal of all metadata items (labels, attributes, hyperlinks, and triggers) that were attached to the deleted version
    • Removal of all event records for the deleted version
    • (File elements only) Removal of the data containers that hold the deleted version's file system data

    A destroy version event record is created for the element.

    In general, a removed version is physically deleted from the VOB source pool. However, a removed version is logically deleted if it has a descendant and is managed by the z_text_file_delta or text_file_delta type managers. For more information about the type managers, see the type_manager reference page.

    Behavior in Snapshot Views

    In a snapshot view, rmver does not unload the element, but leaves a view-private copy of the element in the view. In other respects, rmver behaves the same in a snapshot view as it does in a dynamic view.

    Deleted Version IDs

    The version ID of a deleted version is never reused. There is no way to collapse a branch to fill the gaps left by deleted versions. If a deleted version was the last version on a branch (say, version 6), the next checkin on that branch creates version 7.

    A reference to a deleted version produces a not found or no such file or directory error.

    Controlling the Size of the vista.tjf File

    The file vista.tjf records updates to the VOB that result from rmver operations. vista.tjf can grow very large. For information about limiting its size, read about the file db.conf in the config_ccase reference page.

  • Syntax:
    cleartool rmver [ –f·orce ] [ –xbr·anch ] [ –xla·bel ] [ –xat·tr ]
    [ –xhl·ink ] [ –dat·a ]
    [ –ver·sion version-selector | –vra·nge low-version high-version ]
    [ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
    | –cqe·ach | –nc·omment ] pname ...
  • rmview

    The rmview command performs different, but related, tasks:
    • Removing a view and its related records from a VOB
    • Removing only the view-related records from a VOB

    Removing a View and Its Related Records

    Use this form of the command to remove a view completely. Complete removal of a view entails the following:

    • Removing the view-storage directory
    • Removing view-related records for that view from all accessible VOBs: checkout records, derived object records (ClearCase dynamic views)
    • Killing its associated view_server process, if the view is currently active
    • For a snapshot view, also removing recursively the snapshot view's root directory, which is the directory tree of loaded versions and view-private objects
    • For a dynamic view, removing its entry in the root directory.
    • Removing the view's information from the view registry

    Be sure that the current working directory is not within the view storage area that you are deleting.

    By default, rmview refuses to delete a view if any element is checked out to that view. You can override this behavior with the –force option.

    rmview does not allow you to remove your current set view or working directory view (the view in which you are executing rmview). However, you can remove a view (set view or working directory view) that you are currently using if you issue the rmview command from a shell in which you are not using the view.

    Note: On UNIX, if the view was created with mkview –ln, its view-private objects are stored in a directory tree in an alternate location. rmview attempts to delete this directory tree; if it does not succeed, an error occurs and the view storage area remains unaffected.

    Note: On Windows, if you use the subst or net use commands to assign a drive letter to the snapshot view directory, use the corresponding subst /d or net use /delete command to remove the assignment after you use rmview. Also, if you use the form rmview snapshot-view-storage-pname, the snapshot view directory is not deleted; use the form rmview snapshot-view-pname.

    Purging View-Related Records Only

    Use this form of the command in either of these situations:

    • Complete purging of view-related records from all VOBs is not possible. (For example, some of the VOBs may be offline when you remove the view.)
    • A view storage area cannot be deleted with rmview, because it has become unavailable for another reason: disk crash, accidental deletion with some operating system command, and so on.

    To remove view-related records only, use rmview and specify a view by its UUID (universal unique identifier; see the “View UUIDs” section). Despite being invoked as rmview, this form of the command has no effect on any view or view_server process, only on the specified VOBs.

    Caution

    Incorrect results occur if a VOB loses synchronization with its views. To avoid this problem:

    • Never remove a view with any command other than rmview.
    • If a view still exists, do not use rmview –uuid to delete records relating to it from any VOB. Make sure that the view need not be used again before using this command.

    View UUIDs

    Each view has a universal unique identifier. For example:

    52000002.4ac711cb.a391.08:00:69:02:18:22 

    The listing produced by a describe –long vob: command includes the UUIDs of all views for which the VOB holds checkout records and derived object records.

    Controlling the Size of the vista.tjf File

    The file vista.tjf records updates to the VOB that result from rmview operations. vista.tjf can grow very large. For information about limiting its size, read about the file db.conf in the config_ccase reference page.

    Syntax:

    ClearCase—Remove a dynamic view and its related records:
    cleartool rmview [ –f·orce ]
    { –tag dynamic-view-tag | dynamic-view-storage-pname }

    Remove a snapshot view and its related records:

    cleartool rmview [ –f·orce ]
    { snapshot-view-pname | snapshot-view-storage-pname }

    Remove only view-related records from a VOB:

    cleartool rmview [ –f·orce ] [ –vob vob-selector| –avo·bs | –a·ll ]
    –uui·d view-uuid

    rmvob

    The rmvob command deletes one or more VOB storage directories. Confirmation for each VOB is required, unless you use the –force option. In addition to removing the VOB storage directory, rmvob removes all relevant entries from the network's VOB registry. However, rmvob does not unmount the VOBs.

    Caution: Be sure that the current working directory is not within the VOB storage area that you are deleting.

    Note: If you mistakenly remove a VOB storage area with operating system commands, you must unregister the VOB with the rmtag and unregister commands.

    Procedures for Removing VOBs

    To remove a nonreplicated VOB, follow the procedure in the Administrator's Guide. To remove a replicated VOB, follow the procedure in the Administrator's Guide for Rational ClearCase MultiSite. rmvob fails if the VOB replica masters any objects, unless you specify the –force option.

    Syntax:

    cleartool rmvob [ –f·orce ] vob-storage-dir-pname ...

    schedule

    The schedule command creates and manages jobs related to ClearCase and ClearCase LT and arranges to execute them at specified times. A job consists of an executable program, or task, that the scheduler runs one or more times with a given set of arguments.

    In ClearCase, the scheduler is available on any host that runs the albd_server. In ClearCase LT, the scheduler is available on the ClearCase LT server host only.

    Note: For the pathnames of the files and directories described in this section, see the sections, UNIX Files and Windows Files.

    Task and Job Storage

    The scheduler relies on two data repositories:

    • A database of tasks available for scheduling
    • A database of jobs, or scheduled tasks

    A task must be defined in the task database before you can schedule it. The task database is a single text file, task_registry. You can add task definitions to the task database by editing this file using a text editor. You must not change the definitions of standard tasks, but you can add your own task definitions at the end of the file. For more information, see “Task Definition Syntax”.

    Standard tasks reside in the directory tasks. These tasks are not editable. Tasks that you define can reside anywhere in the file system, but the recommended location is the directory tasks. This directory contains a task, ccase_local_day, that is intended for user-defined operations to be run daily. The directory contains another task, ccase_local_wk, that is intended for user-defined tasks to be run weekly. You can customize these two tasks using a text editor or can create entirely new tasks.

    The database of jobs is the file db. This is a binary file that you read and edit by using the schedule command. When you use the schedule command to change the job database, you use the job definition language described in “Job Definition Syntax”.

    Task and Job Database Initialization

    ClearCase and ClearCase LT install a template for an initial task database, which contains definitions for standard tasks, as the file task_registry. The albd_server uses this template to create the first version of the actual task database, task_registry.

    Templates are installed for two customized tasks, ccase_local_day and ccase_local_wk, in the directory templates. The albd_server uses these templates to create initial versions of these tasks in the directory tasks.

    ClearCase and ClearCase LT install an initial set of job definitions as the text file initial_schedule. These job definitions rely on task definitions in the task registry template. The albd_server uses these job definitions to create the first version of the job database, db.

    Note: Do not edit or delete any files in the directory tree whose root is scheduler.

    Default Schedule

    When no job database exists, the albd_server uses the initial set of job definitions in the file initial_schedule to create a default schedule. This schedule consists of some jobs run daily and other jobs run weekly.

    Daily jobs:

    • Scrub cleartext and derived object storage pools of all local VOBs, using scrubber.
    • Copy the VOB database for all local VOBs that are configured for snapshots, using vob_snapshot.
    • Copy the ClearCase registry from the primary registry server host (when run on a backup registry server host), using rgy_backup.
    • Run user-defined daily operations in ccase_local_day.
    • Generate and cache data on disk space used by all local views, using space.
    • Generate and cache data on disk space used by all local VOBs, using space.

    Weekly jobs:

    • Scrub some logs (see the Administrator's Guide).
    • Scrub the databases of all local VOBs, using vob_scrubber.
    • Run user-defined weekly operations in ccase_local_wk.
    • Generate and cache data on disk space used by derived objects in all local VOBs, using dospace.

    The default schedule also includes three jobs to automate the synchronization of MultiSite replicas. These jobs are designed to run daily but are disabled by default, whether or not MultiSite is installed. For more information about these jobs and how to enable them for use with MultiSite, see the Administrator's Guide for Rational ClearCase MultiSite.

    Job Timing Options

    You can arrange for a job to run under a variety of schedules:

    • Run daily or every n days, starting at a specified time of day and possibly repeating at a specified time interval during the day.
    • Run weekly or every n weeks, on one or more days of each week, starting at a specified time of day and possibly repeating at a specified time interval during the day.
    • Run monthly or every n months, on a specified day of the month, starting at a specified time of day and possibly repeating at a specified time interval during the day.
    • Run immediately after another job finishes.

    For daily, weekly, and monthly schedules, you can specify starting and ending dates for the job. To run a job one time, you can specify a daily schedule with identical start and end dates.

    Job Definition Syntax

    The –edit and –set options create or modify jobs by using a declarative job definition language. The –get option displays a textual representation of currently defined jobs using the same language.

    The job definition language has the following general features:

    • Each statement must occupy a single line, though job descriptions and output messages can occupy more than one line.
    • The language is case-insensitive.
    • Leading white space, lines beginning with a number sign (#), and blank lines are ignored, except within job descriptions.
    • The quotation character is double quote (").

    A job definition file consists of a sequence of job definitions. Each job definition begins with the statement Job.Begin and ends with the statement Job.End. Between these statements are other statements that define job properties. A statement that defines a job property has the following form:

    Job.property_namevalue

    Some properties have fields. In this case the definition of a property consists of a sequence of statements, one for each field, with the following form:

    Job.property_name.fieldvalue

    Some fields themselves have subfields.

    The value portion of some property definitions can contain a sequence of individual values separated by commas. No white space can appear before or after a comma that separates two values in a sequence. For the Args property, individual values are separated by white space.

    Job properties are of two types:

    • Editable. You can define or modify the property. Some properties and fields are required; others are optional and have default values. When you define or modify a property, you must specify fields and subfields of that property in the order listed in Table 12 and Table 13.
    • Read-only. The scheduler defines the property, and you cannot define or modify it. When you create a job definition, the scheduler ignores all definitions of read-only properties. When you edit an existing job definition, the scheduler ignores all definitions of read-only properties except for Id. When you edit an existing job definition, the scheduler uses the Id, if present (and if not present, the Name), to identify the job to modify.

    Table 12 lists editable job properties.

    Table 12. Editable Job Properties
    Property Field Value Default
    Name   name_string (quoted if it contains white space; must be unique across jobs) No default; a value is required.
    Description Begin desc_string (on subsequent lines only; maximum 255 characters) ""
    End (none)  
    Schedule [a] [b] No default; a value is required.
    Task   task_id (unsigned) | task_name (string) No default; a value is required.
    Args   arg_string [...] (arg_string quoted if it contains white space) No args
    DeleteWhenCompleted   TRUE | FALSE FALSE
    NotifyInfo OnEvents JobBegin | JobEndOK | JobEndOKWithMsgs | JobEndFail | JobDeleted | JobModified [,...] If no NotifyInfo field is specified, no notifications are issued; if any NotifyInfo field is specified, all must be specified.
    Using email
    Recipients address [,...]

    Table 13 lists fields of the Schedule property. Schedules are of two types:

    • Periodic. The job runs on one or more days specified by the Monthly, Weekly, or Daily field.
    • Sequential. The job runs following completion of another job specified by the Sequential field.

    The Monthly, Weekly, Daily, and Sequential fields are mutually exclusive; each job must have one and only one of these fields.

    The StartDate, LastDate, FirstStartTime, StartTimeRestartFrequency, and LastStartTime fields are optional. One or more of these fields can appear along with a Monthly, Weekly, or Daily field. StartDate and LastDate determine the first and last dates the job is eligible to run on its monthly, weekly, or daily schedule. FirstStartTime determines what time the job first runs on each day it is scheduled. StartTimeRestartFrequency specifies an interval to wait before running the job again. LastStartTime is meaningful only with StartTimeRestartFrequency; it determines the last time the job is eligible to run on each day it is scheduled. If StartTimeRestartFrequency is specified for a job, the job will run every StartTimeRestartFrequency (for example, every two hours) until midnight or LastStartTime, whichever is earlier.

    All dates and times are local to the host on which the scheduler is running. Date outputs are displayed in ISO format regardless of any user-specified preference for the display format of dates.

    Table 13. Fields of the Job Schedule Property
    Schedule field Subfield Value Default
    Monthly Frequency every_n_months (unsigned) No default; if any Monthly subfield is specified, all must be specified.
    Day day_number | ordinal_spec day_spec

    (day_number ::= 1 ... 31)

    (ordinal_spec ::= First | Second | Third | Fourth | Last)

    (day_spec ::= Mon | Tue | Wed | Thu | Fri | Sat |Sun | Weekday | Weekendday | Day)

    Weekly Frequency every_n_weeks (unsigned) No default; if any Weekly subfield is specified, all must be specified.
    Days Mon | Tue | Wed | Thu | Fri | Sat | Sun [,...]
    Daily Frequency every_n_days (unsigned) No default
    StartDate   [d]dmonth[yy]yy

    (month ::= January ... December | Jan ... Dec)

    (Dates in ISO format are also accepted.)

    Today
    LastDate   StartDate |[d]dmonth[yy]yy

    (month ::= January ... December | Jan ... Dec)

    (Dates in ISO format are also accepted.)

    No last date
    FirstStartTime   [h]h:[m]m:[s]s (24-hour format) Now
    StartTimeRestart Frequency   [h]h:[m]m:[s]s (24-hour format) No restart
    LastStartTime   [h]h:[m]m:[s]s (24-hour format) Midnight
    Sequential FollowsJob job_id (unsigned) | job_name (string) No default

    Table 14 lists read-only job properties. For the LastCompletionInfo property, ExitStatus is the value returned by the wait() system call on UNIX or by the GetExitCodeProcess() function on Windows. Only the first 511 bytes of standard output and error messages are displayed.

    Table 14. Read-Only Job Properties
    Property Field Value
    Id   job_id (unsigned)
    Predefined   TRUE | FALSE
    Created   YYYYMMDDThh:mm:ss±hh:mm by user.group@host
    LastModified   YYYYMMDDThh:mm:ss±hh:mm by user.group@host
    NextRunTime   YYYYMMDDThh:mm:ss±hh:mm
    RunningStatus ProcessId process_id (unsigned)
    Started YYYYMMDDThh:mm:ss±hh:mm
    LastCompletionInfo ProcessId process_id (unsigned)
    Started YYYYMMDDThh:mm:ss±hh:mm
    Ended YYYYMMDDThh:mm:ss±hh:mm
    ExitStatus exit_status (hexadecimal)
    Begin output_and_error_messages (on subsequent lines only)
    End (None)

    Following is an example definition the scheduler could display with the –get option for a job scheduled to run sequentially, including job properties defined by the scheduler:

    Job.Begin
        Job.Id: 1
        Job.Name: "Daily VOB Pool Scrubbing"
        Job.Description.Begin:
    Scrub the cleartext and derived object storage pools of all local VOBs.
        Job.Description.End:
        Job.Schedule.Daily.Frequency: 1
        Job.Schedule.StartDate: 2002-12-30
        Job.Schedule.FirstStartTime: 04:30:00
        Job.DeleteWhenCompleted: FALSE
        Job.Task: 3
        # Job.Task: "VOB Pool Scrubber"
        Job.Args:
        Job.NotifyInfo.OnEvents: JobEndOKWithMsgs,JobEndFail
        Job.NotifyInfo.Using: email
        Job.NotifyInfo.Recipients: root
        Job.Created: 2002-12-30T15:18:06-05 by rational.com/root@phenol
        Job.LastModified: 2002-12-30T15:18:06-05 by rational.com/root@phenol
        Job.Predefined: TRUE
        Job.NextRunTime: 2003-01-10T04:30:00-05
        Job.LastCompletionInfo.ProcessId: 21511
        Job.LastCompletionInfo.Started: 2003-01-09T04:30:00-05
        Job.LastCompletionInfo.Ended: 2003-01-09T04:39:27-05
        Job.LastCompletionInfo.ExitStatus: 0x100
        Job.LastCompletionInfo.Messages.Begin:
    Thu Jan  9 04:39:26 EST 2003
    ClearCase scrubber failed on phenol with exit status 1
    Some VOBs were NOT scrubbed
    See phenol:/var/adm/rational/clearcase/log/scrubber_log
        Job.LastCompletionInfo.Messages.End:
    Job.End
     

    Task Definition Syntax

    A task must be defined in the task database before you can schedule the task. The task database is a text file, which you can edit using a text editor. The task database contains definitions that use a declarative task definition language similar to the job definition language.

    The task definition language has the following general features:

    • Each statement must occupy a single line.
    • The language is case insensitive.
    • Leading white space, lines beginning with a number sign (#), and blank lines are ignored.
    • The quotation character is double quote (").

    The task database file consists of a sequence of task definitions. Each task definition begins with the statement Task.Begin and ends with the statement Task.End. Between these statements are other statements that define task properties. A statement that defines a task property has the following form:

    Task.property_namevalue

    In the task database, definitions of standard tasks appear first. You must not change or delete any of these definitions. You can add task definitions of your own at the end of the task database file.

    Table 15 lists task properties.

    Table 15. Task Properties
    Property Value
    Id task_id (unsigned; must be unique across tasks; for user-defined tasks, must be 100 or greater)
    Name name_string (quoted if it contains white space; must be unique across tasks)
    Pathname pathname_string (quoted if it contains white space)
    UIInfo info_string (private to ClearCase and ClearCase LT)

    The scheduler uses the task Id property in a job definition to identify the task to run. If any scheduled jobs use a task Id, you must be careful not to change the task's Id property in the task database without also changing all references to that property in the database of scheduled jobs.

    The Pathname value is the pathname of the executable to be invoked when the task is run. The pathname can be relative or absolute. If it is relative, the scheduler looks first for the task in these directories in this order:

    Platform First location Second location
    UNIX ccase-home-dir/config/scheduler/tasks /var/adm/rational/clearcase/scheduler/tasks
    Windows ccase-home-dir\config\scheduler\tasks ccase-home-dir\var\scheduler\tasks

     

    The optional UIInfo property describes the task's command-line interface, such as the types of arguments the task can take. This property is used internally by ClearCase and ClearCase LT; do not specify it for a user-defined task.

    Following is an example read-only definition for a standard task:

    Task.Begin
        Task.Id:       2
        Task.Name:     "View Space"
        Task.Pathname: view_space.sh
        Task.UIInfo:   "view-spec"
    Task.End

    Following is an example definition for a user-defined task:

    Task.Begin
        Task.Id:       100
        Task.Name:     "Daily Local Tasks"
        Task.Pathname: ccase_local_day.sh
    Task.End

    Job Execution Environment

    Each task runs in a separate process started by the albd_server. A task has the following execution environment:

    • The user identity of the task is the same as that of the albd_server (root on UNIX; typically, the clearcase_albd account on Windows).
    • The standard input stream is closed.
    • Standard output and error messages are redirected to a file and captured by the scheduler as part of the job's LastCompletionInfo property.
    • The current directory is undefined.
    • Environment variables are those in effect for the albd_server. In addition, on Windows systems, CLEARCASEHOME is set to ccase-home-dir.

    RESTRICTIONS

    The scheduler maintains a single access control list (ACL). The ACL determines who is allowed access to the scheduler and to the ACL itself.

    The –edit –acl and –set –acl options modify the ACL using a declarative ACL definition language. The –get –acl option displays the current ACL.

    The ACL definition consists of a sequence of ACL entries. Each ACL entry must occupy a single line. Leading white space, lines beginning with number sign (#), and blank lines are ignored. Each ACL entry has the following form:

    identity_type:identity access_type

    Table 16 lists the identity types and identities allowed in ACL entries. The identity types are case insensitive.

    Table 16. Identity Types and Identities in Scheduler ACL Entries
    Identity Type Identity
    Everyone (None)
    Domain domain_name
    Group domain_name/group_name | domain_name\group_name
    User domain_name/user_name | domain_name\user_name

    In the identity portion of an ACL entry, the domain_name is an NIS domain for UNIX clients of the scheduler and a Windows NT Server domain for Windows clients of the scheduler. Note that you must supply a domain in the identity portion of a Group or User ACL entry. For an ACL entry with a Windows NT Server domain, group_name must be a global group, and user_name must be a domain user account. Names of domains, groups, and users are case insensitive for the scheduler.

    Note that no white space can appear anywhere in an identity_type:identity specification.

    Table 17 lists the access types allowed in ACL entries. The access types are case insensitive.

    Table 17. Access Types In Scheduler ACL Entries
    Access type Access to schedule Access to ACL
    Read Read only Read only
    Change Read and write; can start jobs Read only
    Full Read and write; can start jobs Read and write

    Each combination of domain and group or of domain and user represents a single identity. (Note that NIS domains differ from Windows NT Server domains, so a group or user in an NIS domain represents a different identity from the same group or user in a Windows NT Server domain.) Each single identity can have only one access type. However, access rights are inherited from Everyone to Domain to Group to User in such a way that each user has the least restrictive of all these access rights that apply to that user. For example, if a user's ACL entry specifies Read access but the ACL entry for the user's group specifies Change access, the user has Change access. The order of ACL entries is not significant.

    • In ClearCase, root (UNIX) or a member of the ClearCase administrators group (Windows) always has Full access to the scheduler on the local host (the computer where that user is logged on).
    • In ClearCase LT, Full access is granted to the local administrator of the ClearCase LT server running on a Windows host or to root on a UNIX host

    Access rights of these identities to a scheduler on a remote host are determined by the scheduler's ACL. The default ACL is as follows:

    Everyone: Read

    This means that by default, everyone can read the schedule, but only the highly privileged identities logged on to the computer where the scheduler is running can modify the schedule or the ACL.

    Following is an example ACL definition:

    # NIS domain acme.com
    Domain:acme.com Read
    # Windows NT Server domain acme
    Domain:acme Read
    Group:acme\users Change
    User:acme.com\fran Full
    User:acme\fran Full

    Syntax

    ClearCase—Display information about jobs, tasks, or protection:
    cleartool sched·ule [ –f·orce ] [ –hos·t hostname ] –get
    [ –sch·edule | –job job-id-or-name | –tas·ks | –acl ]

    ClearCase—Edit a schedule or the scheduler's protection information:

    cleartool sched·ule [ –f·orce ] [ –hos·t hostname ] –edi·t [ –sch·edule | –acl ]

    ClearCase—Set a schedule or protection using definitions in a file:

    cleartool sched·ule [ –f·orce ] [ –hos·t hostname ] –set
    [ –sch·edule | –acl ] defn-file-pname

    ClearCase—Perform an operation on a scheduled job:

    cleartool sched·ule [ –f·orce ] [ –hos·t hostname ]
    [ –del·ete | –run | –wai·t | –sta·tus ] job-id-or-name

    ClearCase LT—Display information about jobs, tasks, or protection:

    cleartool sched·ule [ –f·orce ] –get [ –sch·edule | –job job-id-or-name
    | –tas·ks | –acl ]

    ClearCase LT—Edit a schedule or the scheduler's protection information:

    cleartool sched·ule [ –f·orce ] –edi·t [ –sch·edule | –acl ]

    ClearCase LT—Set a schedule or protection using definitions in a file:

    cleartool sched·ule [ –f·orce ] –set [ –sch·edule | –acl ] defn-file-pname

    ClearCase LT—Perform an operation on a scheduled job:

    cleartool sched·ule [ –f·orce ] [ –del·ete | –run | –wai·t | –sta·tus ]
    job-id-or-name

    schemes

    Scheme files are collections of X Window System resource settings that control the geometry, colors, and fonts used by application GUIs. By default, ClearCase and ClearCase LT do not enable schemes. Instead, the GUIs use the settings that your Common Desktop Environment (CDE) specifies. However, you can enable schemes and use the ClearCase and ClearCase LT schemes mechanism by adding the following resource to your .Xdefaults file:
    *useSchemes: all

    All ClearCase and ClearCase LT GUIs except the following support the schemes mechanism:

    • cleardescribe
    • clearhistory

    Each scheme is implemented as a separate directory. For example, the scheme Turner consists of four files:

    Turner/palette Defines mnemonic names for colors and fonts, using a subset of standard cpp(1) syntax:
    #ifndef GAMMA_1_0
    #define TextForeground         #fffff
    #define BasicBackground        #002e5c
    #define ScrolledListBackground  #623463
    .
    .

     
    Turner/Turner Specifies resources for use by the X Toolkit widgets that make up the GUI panels. These resources can be specified absolutely, or in terms of the mnemonic names defined in the palette file:
    *XmText*marginHeight: 4
    .
    .
    .
    *foreground: TextForeground
    *background: BasicBackground
    Turner/ClearCasepalette Extends and/or overrides the standard palette definitions.
    Turner/ClearCase Extends and/or overrides the standard Turner file definitions,

    The two mnemonic map declaration files are combined, as are the two resource definition files. If the same resource is specified in the standard file and the ClearCase or ClearCase LT file, the specification in the ClearCase or ClearCase LT file is used. To add your own definitions or to replace existing ones, either edit one or both of the files specific to ClearCase and ClearCase LT or create your own scheme files and specify a scheme file search path, as described in the section “Search Path for Schemes”.

    Note that the palette and ClearCasePalette files are not actually processed by cpp; they are processed by the ClearCase or ClearCase LT GUI itself. The resources (Turner and ClearCase) apply only to the program that reads them. They are not added to the RESOURCE_MANAGER property of the root window and, therefore, do not affect other X applications.

    Schemes are configured at two levels:

    • Your display's X resources enable scheme use and specify the name of a particular scheme.
    • A search path capability supports maintenance of systemwide and personal schemes.

    Resources for Schemes

    The scheme resource specifies a scheme to be used by the ClearCase or ClearCase LT GUI. For example:

    *scheme: Turner Specifies scheme for all GUI utilities
    xclearcase*scheme: Turner Specifies scheme for xclearcase

    If you enable scheme use but do not specify a particular scheme, the color scheme Lascaux or the black-and-white scheme Willis is used. If you do not explicitly enable schemes, the CDE resource settings are used.

    Monochrome and Grayscale Schemes

    By default, users working on a monochrome monitor get the Willis scheme, and users working on a grayscale monitor gets the Print scheme. You can override these assignments with the resources *monoScheme and *grayScheme, respectively. If you specify an alternative scheme, it must be located in the scheme search path, which is described in the following section.

    Search Path for Schemes

    The GUIs use a search path to find scheme directories. The default search path is /usr/lib/X11/Schemes:/opt/rational/config/ui/Schemes.

    You can use the environment variable SCHEMESEARCHPATH to specify a colon-separated list of directories to be searched instead. Each entry on this list must be in the following standard X Toolkit form:

    pathname/%T/%N%S

    The GUIs always make these substitutions:

    %T ➔⇒ Schemes
    %N➔ ⇒ scheme-name
    %S ⇒ ➔(null)
     

    For example, if your SCHEMESEARCHPATH value is

    /netwide/config/ui/%T/%N%S:/home/gomez/%T/%N%S 

    and your .Xdefaults file includes the line

    *scheme: Rembrandt 

    then the GUI reads resource schemes from these two directories:

    /netwide/config/ui/Schemes/Rembrandt
    /home/gomez/Schemes/Rembrandt

    The GUI searches for the first instance of each scheme file (the standard map declaration file, the standard resource definition file, and the versions of the standard files), and then concatenates the files.

    Note: If the GUI does not find a complete set of scheme files, it returns an error. Therefore, we recommend that you include the default search path in the SCHEMESEARCHPATH environment variable.

    International Language Support

    If your site uses the language resource *xnlLanguage to implement pathname substitutions based on national language and/or codeset, you may want to expand customized SCHEMESEARCHPATH entries to use one or more of these optional substitution parameters:

    %L ⇒ ➔value of *xnlLanguage (language[_territory][.codeset])
    %l➔ ⇒ language
    %t ⇒ ➔ territory (if any)
    %c ➔⇒ codeset (if any)

    For more information about constructing directory trees to store language-dependent application text files, see X Windows System Toolkit documentation.

    Platform-Specific Support

    On some platforms, there are specific requirements for the location of the Schemes directory. For information about platform-specific requirements, see the Release Notes.

    FILES

    ccase-home-dir/config/ui/Schemes/Gainsborough/*
    ccase-home-dir/config/ui/Schemes/Lascaux/*
    ccase-home-dir/config/ui/Schemes/Leonardo/*
    ccase-home-dir/config/ui/Schemes/Monet/*
    ccase-home-dir/config/ui/Schemes/Print/*
    ccase-home-dir/config/ui/Schemes/Rembrandt/*
    ccase-home-dir/config/ui/Schemes/Sargent/*
    ccase-home-dir/config/ui/Schemes/Titian/*
    ccase-home-dir/config/ui/Schemes/Turner/*
    ccase-home-dir/config/ui/Schemes/VanGogh/*
    ccase-home-dir/config/ui/Schemes/Whistler/*
    ccase-home-dir/config/ui/Schemes/Willis/*

    scrubber

    The scrubber program deletes (scrubs) data container files from the cleartext storage pools and derived object (DO) storage pools of one or more VOBs. It also deletes corresponding (DOs) from a VOB database. Only cleartext pools and DO pools are affected; scrubbing is not defined for source pools.

    Note: DOs are associated with dynamic views only; they are not applicable to snapshot views.

    Scrubbing Algorithms

    scrubber implements the following scrubbing algorithms:

    • Heuristic scrubbing

      By default or with the –o option, scrubber uses a free-space-analysis heuristic: it compares the current free-space level of a disk partition with a lower limit computed during its previous execution. This lower limit is stored in file /var/adm/rational/clearcase/cache/scrubber_fs_info (UNIX) or ccase-home-dir\var\cache\scrubber_fs_info (Windows).

      • If the free-space level is still above the computed limit, scrubber does no scrubbing in that partition, regardless of the state of the storage pools within it. This performance optimization allows a quick check to take place frequently (for example, once an hour), without much system overhead.
      • If the free-space level has fallen below the limit, scrubber performs parameter-driven scrubbing of each storage pool in the partition.
    • Parameter-driven scrubbing

      With the –f option, scrubber removes data container files from a storage pool according to the pool's scrubbing parameter settings. (The heuristic scrubbing algorithm can also fall through to this algorithm.)

      When a derived object pool or cleartext pool is created with mkvob or mkpool, its scrubbing parameters are set to user-specified or default values:

      maximum size Maximum pool size (specified in KB; default=0)
      reclaim size Size to which scrubber attempts to reduce the pool (specified in KB; default=0)
      age Threshold to prevent premature scrubbing of recently referenced objects (specified in hours; default=96)

      Parameter-driven scrubbing proceeds as follows:

      1. Files are removed from a pool only if its current size exceeds its maximum size setting. In this case, scrubber begins deleting data containers that have not been referenced within age hours, proceeding on a least-recently-referenced basis.
      2. The data container for a derived object is deleted only if the DO's reference count is zero. In this case, the derived object in the VOB database is deleted, too. The associated configuration record is also deleted if no other derived object is associated with it.
      3. Cleartext data containers do not have reference counts; they are deleted solely on the basis of recent use.
      4. Scrubbing stops when the pool's size falls below its reclaim size setting. But in no case does scrubber delete any object that has been referenced within the last age hours.

      A maximum size of zero is a special case: it instructs scrubber to delete all data containers that have not been referenced within age hours, regardless of the reclaim size setting.

      Note: The scrubber considers access time rather than modification time. If your backup utility changes the access time on objects, scrubber does not delete the object if the backup utility ran within the period of time specified by age.

    • Everything-goes scrubbing

      With the –e option, scrubber ignores a pool's scrubbing parameters and deletes these files:

      • All files from each cleartext pool
      • All files with zero reference counts from each derived object pool

        To avoid deleting files that are currently being used, scrubber does not delete any file that has been accessed in the preceding two minutes.

    Automatic Scrubbing

    By default, the scheduler runs scrubber periodically with the –f option, so that each pool is examined individually. For information about describing and changing scheduled jobs, see the schedule reference page.

    You can scrub one or more pools manually at any time.

    Scrubber Log File

    scrubber documents its work in the host's scrubber log file:

    • UNIX—/var/adm/rational/clearcase/log/scrubber_log
    • Windows—ccase-home-dir\var\log\scrubber_log

    For example, the following partial report describes the results of scrubbing a derived object pool.

    04/27/99 08:03:00 Stats for VOB betelgeuse:/usr1/vobstorage/orange.vbs
    Pool ddft:

    04/27/99 08:03:00 Get cntr tm 918.928979
    04/27/99 08:03:00 Setup tm 10631.121127
    04/27/99 08:03:00 Scrub tm 1207.099240
    04/27/99 08:03:00 Total tm 12757.149346
    04/27/99 08:03:00 Start size 404789 Deleted 3921 Limit size 0
    04/27/99 08:03:00 Start files 20349 Deleted 121 Subdir dels 0
    04/27/99 08:03:00 Statistics for scrub of DO Pool ddft:
    04/27/99 08:03:00 DO's 3671 Scrubs 121 Strands 1760
    04/27/99 08:03:00 Lost refs 1790 No DO's 20228 
    04/27/99 08:03:00 No fscntrs        2

    The first six lines, which contain elapsed times and file statistics, are included in the report for every pool. The last four lines are specific to DO pools.

    Get cntr tm Elapsed time for first scrubbing phase: walk the file system tree to get pathname, size, and referenced-time information for each container in the pool.
    Setup tm Elapsed time for second scrubbing phase: perform setup processing specific to the kind of storage pool. For a cleartext pool, no setup is required. For a DO pool, setup is complicated; see “Processing of Derived Object Pools”.
    Scrub tm Elapsed time for third scrubbing phase: determine which containers to delete and then delete them.
    Start size Total size (KB) of all the container files in the storage pool directory before this scrubbing.
    Deleted Amount of storage (KB) reclaimed by this scrubbing.
    Limit size Desired size of the pool (KB), as specified by the pool's maximum size parameter.
    Start files Total number of container files in the storage pool directory before this scrubbing.
    Deleted Number of container files deleted by this scrubbing.
    Subdir dels Number of empty subdirectories of the storage pool directory deleted by this scrubbing.
    DO's Total number of zero-reference-count DOs in the VOB database before scrubbing.
    Scrubs Total number of shared zero-reference-count DOs deleted by this scrubbing. (This number equals the Deleted count, unless the scrubber removed shared zero-reference-count DOs that were missing their file system containers.)
    Strands Total number of stranded DOs deleted by this scrubbing. (These are described below.)
    Lost refs Total number of lost DO reference counts deleted by this scrubbing. (These are described below.)
    No DO's Total number of containers in the DO pool before scrubbing that are not associated with a zero-reference-count shared DO. (Each is presumably associated with a DO that is still referenced by some view, and hence cannot be scrubbed).
    No fscntrs Total number of shared zero-reference-count DOs that were missing their file system containers.

    This statistic is printed only when this condition occurs; also, the scrubber_log displays warning messages like this one:

    04/21/99 10:11:17 scrubber: Warning: Unable to remove “d/do_pool2/21/5/73f1f66679f611cea15c080009935288”: No such file or directory.

    Processing of Derived Object Pools

    For a DO pool, scrubber does more than delete old, unreferenced data containers.

    • It finds and deletes all stranded DOs from the VOB database: DOs that were never shared and whose data containers have been deleted from view-private storage. (The VOB database is not updated when the DO's data file is removed or overwritten in the view, because of implementation restrictions.) There are no data containers in the DO storage pool for such DOs, because they were never shared. This occurs during the second phase of scrubbing.
    • It finds and deletes all lost DO reference counts from the VOB database. Such entries are an implementation artifact; they correspond to files that were created during a build, but deleted before the build completed. This occurs during the second phase of scrubbing.
    • It deletes the derived object in the VOB database corresponding to the data container, and possibly its associated configuration record as well. This occurs during the third phase of scrubbing.
    • It finds and deletes all stranded configuration records: CRs that do not correspond to any existing derived object.

    Derived Statistics

    Some interesting results can be derived from these statistics:

    • Total number of derived object data containers in this pool after scrubbing:
      Start files - scrubs
    • Total number of unreferenced data containers in this pool after scrubbing:
      Start files - scrubs - No DO's
    • Total size (KB) of the storage pool after scrubbing:
      Start size - deleted

    Controlling the Size of the vista.tjf File

    The file vista.tjf records updates to the VOB that result from scrubber operations. vista.tjf can grow very large. For information about limiting its size, read about the file db.conf in the config_ccase reference page.

    Removes data containers from VOB storage pools and removes DOs from VOB database.

    Location:

    ...\rational\clearcase\bin

    Syntax:

    ../rational/clearcase/bin/scrubber [ –e | –f | –o ] [ –p pool[,...] | –k kind[,...] ]
    [ –a | vob-storage-dir-pname ... ]

    setactivity (UCM)

    The setactivity command sets or unsets a current activity for a view. The current activity is one whose change set records your current work. Each view can have no more than one current activity. When you check out an element, it is associated with the current activity.

    Before resetting to another activity, the setactivity command determines whether any elements of the current activity are checked out in the view and, if so, issues a warning before proceeding.

    You can set an activity for a view while the activity is being delivered, but the changes made to the activity are not delivered.

    To clear the current activity, specify a new activity or use the –none option.

    You cannot reset an integration activity that is in use as part of a deliver or rebase operation (nor can you clear it with –none).

    Behavior for Projects Enabled for ClearQuest

    When executed in a view that is associated with a project enabled for ClearQuest, this command takes an activity-selector that is a ClearQuest record ID (for example, SAMPL123456) of an existing ClearQuest record. If the ClearQuest record is not already linked to an activity, the command causes an activity to be created and linked to the ClearQuest record.

    Stopping Work on an Activity

    You can stop work on an activity in these ways:

    • Deliver the activity to the project's integration stream.
    • Issue another setactivity command, specifying a different activity selector.
    • Use the –none option to unset the current activity in your view.

    Syntax:

    cleartool setact·ivity [ –c·omment comment | –cfi·le pname | –cq·uery | –nc·omment ]

    [ –vie·w view-tag ] { –none | activity-selector }

    setcache

    The setcache command sets MVFS and view cache sizes. Although both dynamic and snapshot views use caches, cache size is more significant for a dynamic view than for a snapshot view.

    Syntax:

    Specify the cache size for a single view:

    cleartool setcache –vie·w { –def·ault | –cac·hesize size }
    { –cvi·ew | view-tag }

    Specify the cache size for a host:

    cleartool setcache –vie·w –hos·t { –def·ault | –cac·hesize size }

    Specify the site-wide view cache size:

    cleartool setcache –vie·w –sit·e { –def·ault | –cac·hesize size }
    [ –pas·sword registry-password ]

    ClearCase dynamic views—Specify MVFS cache sizes:

    cleartool setcache –mvfs [–per·sistent | –persistent_only ]
    { –reg·dnc cnt | –noe·ntdnc cnt | –dir·dnc cnt | –vob·freemax cnt
    | –cvp·freemax cnt | –rpc·handles cnt | –vobfreemin cnt
    | –cvpfreemin cnt | –mnmax cnt
    | { –cto | –ncto } | { –aca·che | –nac·ache }
    | { –dnc·ache | –ndnc·ache }
    { –rlc·ache | –nrlc·ache } | { –rvc·ache | –nrvc·ache } } ...

    ClearCase dynamic views—Specify MVFS scaling factor or readdir cache sizes and make persistent:

    cleartool setcache –mvfs { –per·sistent | –persistent_only }
    {–rea·ddir_blocks cnt | –scalefactor val } ...

    ClearCase dynamic views—Reset MVFS cache sizes to default values and make persistent

    cleartool setcache –mvfs –per·sistent –def·ault

    setcs

    This command does not require a product license.

    The setcs command changes the config spec of a view to the contents of a user-specified or system-default file, or it causes the view's associated view_server process to flush its caches and reevaluate the current config spec.

    • For UCM views, the setcs command verifies that the view's configuration matches the configuration defined by the stream it is attached to and, if needed, reconfigures the view. Load rules already in the view's configuration are preserved.
    • For ClearCase on UNIX, if the working directory view differs from the set view (established by the setview command), setcs displays a warning message and uses the working directory view.
    • In a snapshot view, setcs initiates an update -noverwrite operation for the current view and generates an update logfile with the default name and location. (For information about this log file, see the update reference page.)

    For more information about view contexts, see the pwv reference page. For a complete discussion of config specs, see the config_spec reference page.

    UNIX—Export View Config Specs

    If you change the config spec of a view that is being exported for non-ClearCase access, make sure that all users who may currently have the view mounted for that purpose unmount and remount the view. Unmounting and remounting the view ensures access to the correct set of files as specified in the updated config spec.

    Syntax:

    cleartool setcs [ –tag view-tag ] { –cur·rent | –def·ault | pname | –stre·am }

    setplevel (UCM)

    The setplevel command allows you to redefine the list of baseline promotion levels for a project VOB and to designate one of these levels as the default promotion level for new baselines.

    Each project VOB includes an ordered set of promotion levels. Promotion levels are ordered from lowest to highest and can be assigned to baselines to indicate the quality or degree of completeness of the activities and versions represented by the baseline. When a project VOB is created, it includes the following ordered set of promotion levels: REJECTED, INITIAL, BUILT, TESTED, RELEASED. The default promotion level is INITIAL. This is the level that is assigned to newly created baselines.

    A baseline's promotion level is used in computing a project's list of recommended baselines. The recommended baseline for a component is the latest baseline of that component in the project's integration stream that has a promotion level greater than or equal to the project's recommended promotion level (see the chproject reference page).

    Ordered promotion levels can be used to filter lists of baselines. Promotion level is also used to populate the default list of baselines during a rebase operation on a stream. Each project defines a default rebase level. When a project is created, the default rebase level is set to the project VOB's default promotion level. For more information, see chproject.

    When you delete a level that is in use, it is not completely removed from the project VOB. Instead, its place in order is changed so that it is considered to be lower than the lowest defined level. You can list information for baselines labeled with such a promotion level lsbl –level command.

    The promotion levels available in a VOB can be listed by running the describe command on the project VOB object. Promotion levels can be used to filter lsbl output (see the lsbl reference page).

    Syntax:

    cleartool setplevel [ –c·omment comment | –cfi·le comment-file-pname | –cq·uery

    | –nc·omment ]
    [ –inv·ob vob-selector ]
    def·ault default-promotion-level promotion-level ...

    setsite

    The site config registry contains site-wide properties for ClearCase and ClearCase LT. ClearCase and ClearCase LT use the value for a site-wide property when you perform an operation that uses that property without specifying the property's value. For example, when you create a view and do not specify one of the shareable DOs options, ClearCase uses the site-wide value.

    If you do not set a site-wide property in the registry or if you unset a property, the property's default value is used. To list the properties that you can set and their default values, use the lssite –inquire command.

    You can set the following properties in the registry:

    view_cache_size=value When a view_server process is started and cannot find a cache size associated with the view or the view host, it uses the value of view_cache_size.

    value must be an integer value of bytes.

    view_interop_text_mode=value When a user creates a view through the Windows GUI and does not specify the text mode, the value of view_interop_text_mode is used.

    value must be TRUE (equivalent to –tmode insert_cr) or FALSE (equivalent to –tmode transparent).

    The value set for this property does not affect views created either on UNIX machines or by using the MS-DOS command line.

     

    view_shareable_dos=value When a user creates a view and does not specify one of the options –nshareable_dos or –shareable_dos, ClearCase uses the value of view_shareable_dos.

    value must be either TRUE or FALSE.

    Note: Changing the site-wide property for shareable DOs does not change the property for existing views. To change an existing view's property, use the chview command.

     

    rfm_gui_visibility=value (ClearCase on Windows only; for use only if your site uses MultiSite) This property controls the display of request for mastership features in the graphical interface. If value is FALSE, the Request Mastership command does not appear on shortcut menus in the Version Tree Browser, the Merge Manager, or the Find Checkouts window, and you cannot use the Properties Browser to request mastership. If value is TRUE, these features appear in the graphical interface.
    checkin_preserve_time=value Sets the default behavior for preserving the modification time of a file being checked in through a GUI. If value is TRUE, the default for GUI checkin operations is to preserve the file modification time; if FALSE, the default is to use the time of the checkin operation itself (see the description of –ptime in the checkin reference page). Note that this setting is ignored by the checkin command.
    checkout_preserve_time=value Sets the default behavior for preserving the modification time of a file being checked out through a GUI. If value is TRUE, the default for GUI checkout operations is to preserve the file modification time; if FALSE, the default is to use the time of the checkout operation itself. (See the description of –ptime in the checkout reference page.) Note that this setting is ignored by the checkout command.

    Syntax:

    Set a site-wide property:
    cleartool setsite [ –pas·sword registry-password ] property-name=value ...

    setview

    This command does not require a product license; also, it does not apply to snapshot views.

    The setview command creates a process that is set to the specified dynamic view. The new process is said to have a set view context. If you specify an inactive dynamic view—one whose view tag does not appear in the local host's viewroot directory, view—a startview command is invoked implicitly to activate that view.

    After you set the dynamic view, you can take advantage of transparency: the ability to use standard pathnames to access version-controlled objects. The associated view_server process resolves a standard pathname to an element into a reference to one of the element's versions. For more information, see the pathnames_ccase reference page.

    Using setview in Interactive Mode

    The shell command setview creates a subprocess. If you enter the setview command in interactive mode (at the cleartool prompt), the new dynamic view is set in the current process. To push to a subprocess of an interactive cleartool process, use setview –exec cleartool.

    Whether or not you have set a dynamic view, a view-extended pathname is interpreted with respect to the explicitly named dynamic view. For example, /view/bugfix/usr/project/foo.c always specifies the version of element foo.c selected by the view bugfix.

    Syntax:

    cleartool setview [ –log·in ] [ –exe·c cmd-invocation ] view-tag

    shell

    The shell command creates a subshell.

    UNIX—View Context

    The subshell is created with the same view context as the current process. If the current process is set to one view, but the working directory view is different, shell uses the working directory view. (For more information, see the pwv reference page.)

    The shell command is intended for use in cleartool and multitool interactive mode. If you are using single-command mode, there is no need for this command.

    Syntax:

    cleartool sh·ell  |   !  [ command [ arg ... ] ]

    snapshot.conf (UNIX)

    VOB snapshot configuration file. The file /var/adm/rational/clearcase/config/snapshot.conf file stores information that ClearCase and ClearCase LT use to notify interested parties of VOB database snapshot activity on the local VOB host. Here are the parameters in snapshot.conf and their default values (which are established at installation time):

    Location:

    /var/adm/rational/clearcase/config/

    Syntax:

    snapshot.conf

    NOTIFICATION_PROGRAM=/opt/rational/bin/notify
    NOTIFICATION_LIST=root
    CONFIRMATION_ON_SUCCESS=yes
    NOTIFICATION_PROGRAM=email-program-pathname

    The default electronic mail program specified in the configuration file supplied with ClearCase and ClearCase LT is /opt/rational/bin/notify. (This program is also used if no NOTIFICATION_PROGRAM entry exists.) This is an architecture-specific script that invokes a native mail program.

    NOTIFY_LIST=userid[,...]

    A comma-separated list of user IDs to notify of VOB snapshot activity on the local VOB host. List default is a single user ID, root.

    CONFIRMATION_ON_SUCCESS=yes | no

    Specifies whether to notify the NOTIFY_LIST after successful VOB snapshot operations. Default value is yes.

    softbench_ccase

    ClearCase and ClearCase LT Encapsulation for SoftBench. Invoked as needed by SoftBench Broadcast Message Server Invoked as needed by SoftBench Broadcast Message Server  The ClearCase and ClearCase LT Encapsulation for SoftBench enables integration of ClearCase and ClearCase LT with all of the SoftBench tools on the HP-UX 10.X, HP-UX 11, and Solaris platforms. ClearCase and ClearCase LT service and broadcast all the messages prescribed for CM systems in the document CASE Communique: Configuration Management Operation Specifications from the historical standard.

    space

    Reports on disk space use for views, VOBs, or filesystem files or directories. The space command displays data on disk space use for views, VOBs, or file system files or directories. Reports are organized by disk partition, with disk-use statistics listed both in absolute units (megabytes) and as a percentage of the capacity of the disk partition that contains the storage directory.
    • The report for a view includes view-private storage and administration data, as well as the space occupied by the view database. For a snapshot view, the report does not include the space occupied by the snapshot view directory tree. To display that information, use the –directory option and specify the root directory of the snapshot view. The information reported varies according to the availability of information on the view, as follows:
      • If the view resides in the default region of the host on which space is run, the view tag is listed.
      • If the view does not reside in the default region of the host on which space is run, the view tag and its region are listed.
      • If the view is not found in the registry, but the VOB database has a record of its location, the view's UUID, host, and host path are listed. Views in this state are likely candidates for the rmview –uuid command.
      • If the view is not found in the registry and the VOB database has no record of it, the view's UUID is listed. Views in this state are also likely candidates for the rmview –uuid command.
    • The report for a VOB includes disk use information for the VOB database and for each storage pool. Among other statistics, it includes information on backup VOB databases left behind when reformatvob was used.

    With the –view or –vob option, space uses previously generated, cached data for a view or VOB. The –update option generates fresh data and updates the cache before displaying the report. With the –directory option, space does not use cached data.

    The –generate option is intended for use by scheduled jobs. By default, the scheduler periodically runs space with the –generate option to generate and cache data on disk space use for all local views and VOBs. For information about describing and changing scheduled jobs, see the schedule reference page .

    Note: On Windows 95 and Windows 98 machines, output from the space command is incorrect for disk volumes larger than 2 GB. The total file system size is limited to 2048 MB, and the in-use value for the file system is wrong.

    Syntax:

    ClearCase—Report disk space used by a view or VOB:

    cleartool space { –vie·w | –vob } [ –a·ll ] [ –upd·ate ]
    [ –reg·ion network-region ] { –host hostname | tag... }

    ClearCase LT—Report disk space used by a view or VOB:

    cleartool space { –vie·w | –vob } [ –a·ll ] [ –upd·ate ]

    Report disk space used by file system files or directories

    cleartool space –dir·ectory pname ...

    Generate and cache data on disk space use for local views or VOBs:

    cleartool space { –vie·w | –vob } –gen·erate [ –scr·ub days ] [ tag ... ]

    startview

    Starts or connects to a dynamic view's view_server process. Prerequisite: The dynamic view being started must already have a view tag in the network's view tag registry file. See the mkview and mktag reference pages.

    The startview command enables processes on the local host to access a dynamic view, as follows:

    • Establishes an RPC connection between the local host's MVFS (ClearCase multiversion file system) and the dynamic view's view_server process.
    • Creates a view tag entry in the local host's viewroot directory. If a view_server process is not already running, startview invokes one on the host where the view storage area physically resides.

    On UNIX, the default name of the viewroot directory is /view. (See the init_ccase reference page for more information.) On Windows, it is drive M (M:\.)

    Thus, starting a dynamic view that has been registered with view tag main creates the directory entry /view/main or M:\main. After this directory entry is created, any process on the local host can access the view through view-extended pathnames.

    The dynamic view's view tag must already be registered, which is accomplished either at view creation time (with a mkview command) or subsequently (with mktag –view).

    Note: startview is not applicable to a snapshot view. To activate a snapshot view, change to the views's view-storage directory and issue a ClearCase command.

    When to Use startview

    Both mkview and mktag invoke startview. Typically, startview is used to establish view-extended naming access. There are two main cases:

    • Because mkview and mktag invoke startview on the local host only, remote users who want only view-extended naming access to the dynamic view must use startview.
    • After your system has been stopped and restarted (see the Examples section), both local and remote users can use startview to reestablish view-extended naming access to a dynamic view.

    Note: For UNIX users, setview also invokes startview, if necessary. Therefore, it is rarely necessary to invoke startview explicitly. startview is used to establish view-extended naming access without creating a process that is set to the view (as happens with setview).

    Syntax:

    cleartoolvstartview view-tag ...

    O

    type_manager

    Manages contents of element versions. A type manager is a suite of programs that manipulates files with a particular data format; different type managers process files with different formats. A directory type manager provides programs that compare and/or merge versions of directory elements. ClearCase and ClearCase LT provide several type managers. On UNIX, users can create additional ones.

    Several version-control methods for file elements are implemented in two phases:

    1. Updating of the VOB database. This phase is independent of the element's data format and is handled directly by cleartool.
    2. Manipulation of the element's data. In this phase, the data format is extremely significant, and so is handled by a particular type manager. The type manager is invoked as a separate program, rather than as a subroutine. This provides flexibility and openness, allowing users to integrate their own data-manipulation routines with ClearCase or ClearCase LT.

    For example, checking in a text_file element involves the following:

    1. Storing information in the VOB database about the creator of the new version, when it was created, and so on
    2. Computing and storing the delta (incremental difference) between the new version and its predecessor.

    For a different type of element—for example, a bitmap file—the delta is computed differently, or not at all, and so requires a different type manager.

    TYPE MANAGERS

    Following are descriptions of the type managers:

    Manager Function
    whole_copy Stores any data. Stores a whole copy of each version in a separate data container file.
    z_whole_copy Stores any data. Stores each version in a separate, compressed data container file using the gzip compression program.

    Note that compressed files generally take more time to check in (because they must be compressed) and to reconstruct when first accessed (first cleartext fetch).

    text_file_delta Stores text files only (including those with multibyte text characters). Stores all versions in a single structured data container file. (On UNIX, similar to an SCCS s. file or an RCS ,v file.) Uses incremental file differences to reconstruct individual versions on the fly.
    z_text_file_delta Stores text files only. Stores all versions in a single structured data container file, in compressed format using both the gzip compression program and deltas.
    binary_delta Stores any data. Stores each branch's versions in a separate, structured compressed data container file using gzip. Uses incremental file differences to reconstruct individual versions on the fly. Version deltas are determined by comparing files on a per-byte basis.
    _html Stores HTML source. Stores information and reconstructs versions in the same way as the text_file_delta manager from which it is derived. Has its own compare, xcompare, merge and xmerge methods.
    _html2 Same as the _html manager, except that _html2 is based on the binary_delta manager.
    _ms_word Stores Microsoft Word documents. Stores information and reconstructs versions in the same way as the z_whole_copy manager from which it is derived. On Windows, has its own xcompare and xmerge methods.
    _rose Stores Rational Rose artifacts. Stores information and reconstructs versions in the same way as the text_file_delta manager from which it is derived. On Windows, has its owncompare, xcompare, merge, and xmerge methods.
    _rose2 Same as the _rose manager, except that _rose2 is based on the binary_delta manager.
    _rosert Stores Rational Rose RealTime artifacts. Stores information and reconstructs versions in the same way as the binary_delta manager from which it is derived. On Windows, has its owncompare, xcompare, merge, and xmerge methods
    _xde Stores Rational XDE artifacts. Stores information and reconstructs versions in the same way as the text_file_delta manager from which it is derived. On Windows, has its own merge, xmerge, compare, and xcompare methods.
    _xde2 Same as the _xde manager, except that _xde2 is based on the binary_delta manager and it provides a context_merge method.
    _xml Stores XML source. Stores information and reconstructs versions in the same way as the text_file_delta manager from which it is derived. On Windows, has its own compare, xcompare, merge, and xmerge methods.
    _xml2 Same as the _xml manager, except that _xml2 is based on the binary_delta manager.
    directory Not involved in storing/retrieving directory versions, which reside in the VOB database, not in a source storage pool. This type manager compares and merges versions of the same directory element.

    Syntax:

    USING A TYPE MANAGER

    To have a particular file element use a particular type manager, you must establish two connections as indicated:

    file element – > element type – > type manager
    1. Verify that the VOB has an element type that is associated with the desired type manager. Use the lstype command to identify an existing element type. Alternatively, use the mkeltype –manager command to create a new element type that is associated with the desired type manager.
    2. Create the file element, specifying the element type with the –eltype option. If the file element already exists, use the chtype command to change its element type.

    You can automate the assignment of the new element type to newly created elements using the file-typing facility, driven by .magic files. For more information, see the cc.magic reference page.

    TYPE MANAGER STRUCTURE

    A type manager uses different methods to manipulate ClearCase and ClearCase LT data. Methods are invoked at the appropriate time by a version-control command.

    On UNIX, a type manager is a collection of programs in a subdirectory of ccase-home-dir /lib/mgrs; the subdirectory name is the name by which the type manager is specified with the –manager option in a mkeltype command. Each program in a type manager subdirectory implements one method (data-manipulation operation). A method can be a compiled program, a shell script, or a link to an executable. It is invoked at the appropriate time by a ClearCase or ClearCase LT version-control command.

    A type manager can include the following methods, which are invoked by a command or server process:

    create_element Invoked by mkelem to create an element's initial data container.
    create_branch Invoked by mkbranch to create a branch in an element's version tree.
    create_version Invoked by checkin to store a new version of an element.
    annotate Invoked by annotate to produce an annotated listing of a version's contents.
    construct_version Invoked by a view's view_server process when a file element is opened, from versions stored in delta or compressed format. This method constructs a readable, cleartext copy of a particular version.

    After the cleartext version is constructed, its line terminators may be adjusted by the view_server, according to the view's text mode. See the mkeltype and mkview reference pages.

    get_cont_info Invoked by checkvob to determine the contents of a container. This method must be implemented to enable checkvob to fix container problems for the type manager.
    delete_branches_versions Invoked by rmver and rmbranch to delete versions of an element.
    compare, xcompare Invoked by diff to run a file-comparison program that is specific to the element's data format.
    merge, xmerge Invoked by merge to run a file-merge program that is specific to the element's data format.

    A type manager need not implement every method. For example, a type manager for bitmap graphics images may omit the merge method, because the operation doesn't make sense for that file format. In this case, the command cleartool merge produces an error when invoked on an element that uses this type manager.

    UNIX—Method Inheritance and Links

    A type manager can use symbolic links to inherit one or more of its methods from another type manager. A typical use of symbolic links is to have individual methods be links to a master type manager program, which implements several (or all) of the methods. For an example, see directory ccase-home-dir/lib/mgrs/z_whole_copy.

    A link to the cleardiff program can implement the compare and/or merge method for text files. Similarly, a link to the xcleardiff program can implement the xcompare and/or xmerge method. Again, see directory ccase-home-dir/lib/mgrs/z_whole_copy for an example.

    Windows—The Type Manager Map File

    The map file, located in the ccase-home-dir\lib\mgrs directory, associates type manager methods with the programs that carry them out. A map file entry has three fields: type manager, method, and program. Below are some example entries from the map file:

    Manager Method Implementing Program
    text_file_delta construct_version ..\..\bin\tfdmgr.exe
    text_file_delta compare ..\..\bin\cleardiff.exe
    z_whole_copy create_branch ..\..\bin\zmgr.exe
    _rose xmerge HKEY_LOCAL_MACHINE\SOFTWARE

    \Software\Rose\AddIns\Rose Model Integrator

    \Install Path

    When a type manager is invoked by a ClearCase or ClearCase LT command, it scans through the map file, finds the matching type manager and method in the first and second fields, and then runs the program specified in the third field. Note that the entry in the third field must be either a pathname relative to ccase-home-dir\lib\mgrs; for example, ..\..\bin\cleardiff.exe, a Windows Registry key under HKEY_LOCAL_MACHINE that points to an absolute pathname, or an absolute pathname.

    Data Containers

    Type managers process data containers, each of which stores the actual data for one or more versions of some element. (Although growth may cause a container to split, versions never span container boundaries.) All data containers are files, and are stored in the VOB's source pools, which are directories. Only type managers deal with data containers directly; users always manipulate data using the names of elements and UNIX links.

    Performing the data manipulation for a version-control operation involves several programs. For example, when ClearCase or ClearCase LT create a new version of an element:

    1. The pathname (within a source pool) is generated for a new data container.
    2. On the VOB host (where the VOB storage area resides), a vob_server process creates an empty file at that pathname.
    3. On the client host (where the user is working), the type manager fills the new data container with the data for the new version. (If the type manager implements deltas, it writes the data for one or more other versions to the new container, too.)
    4. The vob_server changes the access mode of the new data container, making it unwritable.
    5. The db_server updates the VOB database to reference the new container.
    6. Using the MGR_DELETE_KEEP_JUST_NEW exit status returned by the type manager, the vob_server deletes the old data container.

    Note: Even with a type manager that implements deltas, a new data container is created each time a new version is created. In this case, the old container (which may have stored 27 versions) is replaced by the new container (which stores 28 versions). A type manager must never write to an old container or delete a old container (it usually does not have rights to do so).

    Source Pool Data Container Names

    A container leaf name includes a type manager ID to aid checkvob in salvaging nonreferenced containers. Here is the format of a source pool data container name (in s/sdft, for example):

    ./nn/nn/type-mgr-idorig-oid-strxx 

    type-mrg-id is a one-, two-, or three-character string. One-character values correspond to the predefined type managers. Two-digit values correspond to type managers with names that begin with underscore (_), and three-digit values are computed by hashing user-defined type manager names.

    Names of user-defined type managers must not begin with underscore.

    UNIX FILES

    ccase-home-dir/lib/mgrs/*
    ccase-home-dir/lib/mgrs/mgr_info.h
    ccase-home-dir/lib/mgrs/mgr_info.sh

    WINDOWS FILES

    ccase-home-dir\lib\mgrs\map

    umount

    Deactivates a VOB. The unmount command deactivates one or more VOBs on your host by unmounting them as operating-system-level file systems. A VOB is activated on a host by mounting it as a file system of type MVFS (ClearCase multiversion file system type). The VOB tag by which an individual VOB is referenced is the same as the full pathname to its mount point.

    Note: On UNIX, umount calls the standard umount(1M) command.

    Syntax:

    Unmounting All VOBs

    cleartool umount –all unmounts all public VOBs listed in the VOB registry and all private VOBs owned by the user.

    UNIX Only—Unmounting the View Root Directory

    Except on Solaris, if you enter umount –all as root on a platform that supports the operating system command umount –a, the viewroot directory (/view) is unmounted. To remount the viewroot directory, you must stop and restart ClearCase.

    uncheckout

    Cancels a checkout of an elemen. The uncheckout command cancels a checkout for one or more elements, deleting the checked-out version. Any metadata (for example, attributes) that you attached to a checked-out version is lost. After you cancel a checkout:
    • A dynamic view reverts to selecting a checked-in version of each element.
    • A snapshot view performs an update operation for each unchecked-out element. (For snapshot views, there is an exception for the canceling of a directory checkout. For more information, see “Canceling a Directory Checkout”).

    The checkout version event record for each element is removed from its VOB's database. (There is no uncheckout event record.) Reserve and unreserve records are also removed.

    If you checked out a file under an alternate name (checkout –out), you cannot use the alternate name to cancel the checkout; you must use the element name listed by ls –vob_only.

    Canceling a Checkout in an Inaccessible View

    You can cancel another dynamic view's checkout by using a view-extended pathname to the element. For a snapshot view or when a dynamic view is no longer accessible (for example, it was deleted accidentally), a view-extended pathname does not work. Instead, do the following:

    1. Enter the command describe –long vob:pname-in-vob, where pname-in-vob is the VOB tag of the VOB that contains the checked-out file. The output of this command includes a list of views with checkouts in the VOB.
    2. Look for the view-storage pathname of the inaccessible view, and note the view's unique identifier (UUID).
    3. Use the UUID in the command rmview –uuid uuid to remove all of the view's checkout records from the VOB.
    4. Repeat Step 3 for each VOB that may have been accessed with the view.

    You can also change reserved checkouts in that view to unreserved. There is no way to cancel checkouts in an inaccessible view.

    Canceling a Directory Checkout

    If you cancel a directory's checkout after changing its contents, the changes made with rmname, mv, and ln are lost. Any new elements that were created (with mkelem or mkdir) become orphaned; such elements are moved to the VOB's lost+found directory, stored under names of this form:

    element-name.UUID

    Syntax:

    cleartool uncheckout displays a message in such cases:

    unlock

    Unlocks an object. The unlock command removes an existing lock from an entire VOB, or from one or more objects, type objects, or VOB storage pools. For a description of locks, see the lock reference page.

    Syntax:

    cleartool unlock [ –c·omment comment | –cfi·le comment-file-pname | –cq·uery
    | –cqe·ach | –nc·omment ]
    { [ –pna·me ] pname ... | object-selector ... }

    unregister

    Removes an entry from the vob_object or view_object registry. The unregister command removes the entry for a particular VOB or view from the network's vob_object or view_object registry. This does not affect VOB tag or view tag registry entries, and it does not affect the contents of the physical storage directories. See the Administrator's Guide.

    If you remove a VOB or view storage directory with an operating system command instead of with rmvob or rmview, the VOB or view remains registered. In this case, you must use the –uuid option to unregister the associated storage directory (and use rmtag to remove relevant tag entries, if any still exist).

    Other Commands That Affect Storage Registries

    The mkview and mkvob commands add an entry to the appropriate registry; the rmview and rmvob commands remove registry entries (and the actual storage directories as well). You can use the register command to update an existing entry or to re-register a VOB or view that has been unregistered.

    The reformatvob command updates a VOB's object registry entry (or creates one, if necessary), but does not affect its tag registry entries.

    Syntax:

    Unregister a VOB:
     
    cleartool unreg·ister –vob { –uui·d uuid | vob-storage-dir-pname }

    Unregister a view:

    cleartool unreg·ister –view { –uui·d uuid | view-storage-dir-pname }

    unreserve

    Changes a reserved checkoutto unreserved. The unreserve command changes the checkout status of a checked-out version of an element to unreserved. A temporary unreserve checkout of version event record is written to the VOB database.

    Syntax:

    cleartool unres·erve [ –vie·w view-storage-dir-pname ] [ –cact ]
    [ –c·omment comment | –cfi·le comment-file-pname |–cq·uery | –cqe·ach
    | –nc·omment ] pname ...

    update

    Syntax:

    Update elements using the graphical update tool:

    cleartool update –g·raphical [ pname ... ]

    Update elements from the command line:
     

    cleartool update [ –print ] [–f·orce ] [ –ove·rwrite | –nov·erwrite | –ren·ame ]
    [ –cti·me | –pti·me ] [ –log pname ] [ pname ... ]

    Load elements from the command line by specifying one or more load rules:

    cleartool  update –add·_loadrules [ –print ] [ –f·orce ] [ –ove·rwrite
    | –nov·erwrite | –ren·ame ] [ –cti·me | –pti·me ]
    [ –log pname ] pname [ pname ... ]

    version selector

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

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

    view_scrubber

    Removes derived object data containers from dynamic view storage

    Location:

    .../rational/clearcase/bin

    Syntax:

    view_scrubber [ –p | -a ] [ –k ] [ –n ] [ DO-pname ... ]

    vob_restore

    The vob_restore command restores a damaged VOB. It prompts for all required input and displays explanatory text at each step. If you quit vob_restore before it completes, you can use the –restart option to resume VOB restoration at the point where you stopped it.

    If the VOB is replicated, you must run the MultiSite restorereplica command immediately after restoring the VOB from backup. For more information, see the Administrator's Guide.

    Note: We strongly recommend that you do not retrieve VOB storage from backup until prompted to do so by vob_restore. If you get the VOB storage directory from backup media before running vob_restore, you must either unregister the VOB before retrieving the backup or stop ClearCase or ClearCase LT before retrieval and restart it afterward. If you wait until prompted, vob_restore performs the necessary steps, safeguarding the integrity of your restored VOB.

    Location:

    .../rational/clearcase/bin

    Syntax:

    vob_restore [ –restart restart-path ]  vob-tag

    vob_scrubber

    The vob_scrubber program deletes old event records and MultiSite oplog entries from a VOB database. This retards VOB growth by logically deleting the items, freeing space in the VOB database for storage of new event records and oplog entries. (Physical deletion requires processing with the reformatvob command.)

    The file vista.tjf records updates to the VOB that result from vob_scrubber operations. vista.tjf can grow very large. For information about limiting its size, read about the file db.conf in the config_ccase reference page.

    vob_scrubber does not need to run in a view and does not require the VOB it processes to be mounted

    Location:

    .../rational/clearcase/etc/utils

    Syntax:

    vob_scrubber [ –stats_only ] [ –long ] [ –nlog ]
    { –lvobs | vob-storage-dir-pname ... }

    vob_sidwalk, vob_siddump

    vob_sidwalk and vob_siddump are administrative utilities that can be used to read or change security identifiers (Windows SIDs or UNIX UIDs and GIDs) stored in VOB databases that are formatted with schema version 54. vob_sidwalk is installed only on hosts that are configured to support local VOBs and views and to support VOB schema version 54. vob_siddump is installed on all hosts.

    The programs are typically needed for these tasks:

    • Moving a VOB from one Windows domain to another Windows domain
    • Migrating a Windows NT domain to an Active Directory domain
    • Moving a VOB from a Windows host to a UNIX host or vice versa

    vob_siddump is a read-only version of vob_sidwalk. It can be executed on the VOB server or any client to list the security principal (user and group) names and SIDs stored in a VOB.

    vob_sidwalk has all of the capabilities of vob_siddump and can also change SIDs in the VOB database. In addition, vob_sidwalk can be executed with the -recover_filesystem option to reset the protections on a VOB storage directory so that they are consistent with the SID of the VOB's owner and group.

    Location:

    .../rational/clearcase/bin

    Syntax

    vob_sidwalk [ –p·rofile profile-path ] | [ –s·idhistory ]
    [ –u·nknown ] [ –m·ap mapfile-path ] [ –l·og logfile-path ]
    [ –e·xecute ] [ –delete·_groups ]
    [ -raw·_sid ] vob-tag SIDfile-pat

    Recover VOB storage directory protections:

    vob_sidwalk –recover·_filesystem vob-tag SIDfile-path

    Read security identifiers in a VOB database:

    vob_siddump [ –p·rofile profile-path ] | [ –s·idhistory ]
    [ –u·nknown ] [ -raw·_sid ] [ –m·ap mapfile-path ]
    [ –l·og logfile-path ] vob-tag SIDfile-path

    vob_snapshot

    The vob_snapshot command makes an on-disk copy of a local, locked VOB database. Using this command reduces the amount of time a VOB database needs to be locked when you back up the VOB. Later, as part of your standard system backup procedure, the VOB storage directory (minus the VOB database directory) and the VOB database snapshot can be backed up without locking the VOB. Because the database snapshot and VOB storage pool backups occur at different times, they are likely to be slightly out of sync. To correct this skew, the checkvob utility resynchronizes the VOB database and storage pools when you run vob_restore.

    Location:

    .../rational/clearcase/etc

    Syntax:

    vob_snapshot

    vob_snapshot_setup

    Use vob_snapshot_setup to control VOB database snapshot activity on each VOB host. By default, the scheduler runs vob_snapshot periodically. When vob_snapshot runs on a VOB host, it checks each locally stored VOB for the existence of a multipart string attribute that specifies snapshot parameters. A VOB's database is copied by vob_snapshot only if this attribute has been applied to the VOB with vob_snapshot_setup. Use vob_snapshot_setup lsvob to list the local VOBs currently processed by vob_snapshot and, with –long, to display the snapshot parameters for each VOB in the list.

    Use vob_snapshot_setup modparam to add a VOB to the database snapshot list, or to change snapshot parameters for a VOB already on the list. (You cannot modify individual parameters with modparam, but must replace them all.)

    Use vob_snapshot_setup rmparam to remove a VOB from the snapshot list.

    See also vob_snapshot and vob_restore

    Warning: Do not run vob_snapshot_setup on a V2.x VOB, until you have reformatted the VOB for V3 with reformatvob, and you are certain that checkvob –setup has completed successfully. checkvob –setup updates storage container names and verifies the presence of V3 type managers. If either operation fails, checkvob cannot synchronize a database snapshot at vob_restore time. If you are using a homegrown or third-party type manager, code that implements the get_cont_info method must be added to the type manager so that elements managed by the type manager can be processed by checkvob at vob_restore time

    Location:

    .../rational/clearcase/etc

    Syntax:

    vob_snapshot_setup lsvob [ –short | –long ] [ vob-tag... ]

    UNIX only—Configure a VOB for vob_snapshot processing:

    ccase-home-dir/etc/vob_snapshot_setup modparam –snap_to snap-dir-pname
    { –dbcheck yes | –dbcheck no }  –notify login-name[,...]  vob-tag

    Windows only—Configure a VOB for vob_snapshot processing:

    ccase-home-dir\etc\vob_snapshot_setup modparam –snap_to snap-dir-pname
    { –dbcheck yes | –dbcheck no }  vob-tag

    Remove a VOB from the database snapshot list:
     

    vob_snapshot_setup rmparam vob-tag

    wildcards_ccase

    Wildcard (pattern-matching) characters are recognized in these contexts:

    • UNIX—cleartool single-command mode. The operating system shell, not cleartool, interprets pathnames and expands wildcards. With some cleartool commands (catcr –select, find –name, lsvob), you can specify a pathname pattern as a quoted argument; these are always interpreted by cleartool:
      cleartool catcr –select "bug?.o" bgrs@@04-Mar.22:54.426 
    • Windows—cleartool single-command mode. The command shell, not cleartool, interprets pathnames and expands wildcards. Therefore, unless you are using a command shell that expands pathname wildcards (cmd.exe does not), these wildcards are disallowed. You can, however, use wildcards in special pattern arguments in some cleartool subcommands (catcr –select, find –name, and lsvob). For example:
      Z:\> cleartool ls *.c Fails; command shell does not understand wildcards.
      Z:\> cleartool lsvob *src* “Pattern” argument wildcards accepted; no quotes required because cleartool does not expand the command line.
    • cleartool interactive mode. cleartool expands wildcards in pathnames. In cleartool commands that accept pattern arguments (catcr –select,find –name, and lsvob), you must quote a wildcard pattern to protect it from evaluation by cleartool itself. For example:
      cleartool> lsvob –region "dev*"  "*src*" “Pattern” argument; quotes required
      cleartool> ls *.c Standard pname argument; no quotes required.
    • Config spec rules. The pathname pattern in a config spec rule is interpreted by a view's associated view_server process.

    ClearCase and ClearCase LT recognize these wildcard characters:

    ? Matches any single character.
    * Matches zero or more characters.
    ~ Indicates your home directory.
    [xyz] Matches any of the listed characters.
    [x-y] Matches any character whose ASCII code falls between that of x and that of y, inclusive.
    . . . Ellipsis; matches zero or more directory levels.
    For example:

    foo/.../bar matches any of the following pathnames:

    foo/bar

    foo/usr/src/bar

    foo/rel3/sgi/irix5/bar

    Also:

    foo\... matches the foo directory itself, along with the entire directory tree under it.

    For more information, including restrictions, see the config_spec reference page .

    Syntax:

    ?        *        ~        [ ... ]        ...

    winkin

    The winkin command enables you to access the data of any existing DO, even if it does not match your view's build configuration (and, thus, would not be winked in by a clearmake build). Note that you cannot access a DO's file system data directly, using a version-extended pathname, such as hello@@21-Dec.16:18.397. Instead, you must wink in the DO to a dynamic view and then access it using that view.

    winkin also converts nonshareable DOs to shareable (promoted) DOs. If you specify a nonshareable DO, winkin first advertises the DO by writing information about it to the VOB, and then promotes it by copying its data container into the VOB and moving its configuration record into the VOB. Because a shareable DO cannot have nonshareable sub-DOs or sibling DOs, winking in a nonshareable DO also advertises its sub-DOs and siblings, converting them to shareable DOs. With –siblings, winkin advertises and promotes the DO's siblings.

    Note: When a nonshareable DO is converted to a shareable DO, its DO ID changes. For more information, see Building Software.

    Effect on View-Resident DO Data Containers

    If you specify a shared DO while working in the view where it was originally built and if a view-resident data container for the DO in that view still exists, then the view-resident data container is scrubbed, and your view accesses the shared data container in VOB storage. This is equivalent to executing a view_scrubber command.

    If you specify an unshared DO or nonshareable DO in your view, the data container is promoted to the VOB. The view-resident data container is scrubbed, and your view accesses the data container in VOB storage. This is equivalent to executing a view_scrubber –p command.

    When you need to process a large number of DOs, use view_scrubber rather than winkin.

     

    Syntax:

    Wink in a single DO or a list of explicitly named DOs:

    cleartool winkin [ –print ] [ –noverwrite ] [ –siblings [ –adirs ] ]
    [ –out pname ] do-pname ...

    Recursively wink in a DO and all of its subtargets:

    cleartool winkin [ –print ] [ –noverwrite ] [ –recurse [ –adirs ]
    [ –select do-leaf-pattern ] [ –ci ] ] do-pname ...

    xclearcase (UNIX)

    The xclearcase command invokes the ClearCase or ClearCase LT GUI (graphical user interface). xclearcase is implemented as an X Window System application using a standard window system toolkit. For a description of mouse and keyboard conventions, see your X Window System documentation.

    Location:

    ........(TBD)

    Syntax:

    Start in File Browser:

    xclearcase [ X-options ] [ –file ] [ –ngraph ] pname ...

    Start in Version Tree Browser:
     

    xclearcase [ X-options ] –vtree [ –all ] [ –nmerge ] [ –nco ]
    [ –label ] [ –ngraph ] [ –tag view-tag[,...] ] pname ...

    Start in Hyperlink Tree Browser:

    xclearcase [ X-options ]
    –htree [ –direct | { –nelement | –nbranch | –nversion } ] ...
    [ –include hlink-type[,...] | –exclude hlink-type[,...] ]
    [ –to_only | –from_only ] [ –text ] [ –ngraph ] pname ..

    Start in Type Browser:

    xclearcase [ X-options ]
    { –attype | –brtype | –eltype | –hltype | –lbtype | –trtype }

    xcleardiff (UNIX)

    xcleardiff is a graphical diff and merge utility for text files. It implements the xcompare and xmerge methods for the text_file and compressed_text_file type managers, as well as the graphical portions of these methods for the directory and _html type managers. On color display monitors, xcleardiff uses different colors to highlight changes, insertions, and deletions from one or more contributing files. During merge operations, contributors are processed incrementally and, when necessary, interactively, to visibly construct a merge results file. You can edit this file directly in the merge results pane as it is being built to add, delete, or change code manually, or to add comments.

    xcleardiff is implemented as an X Window System application using a standard Motif toolkit. For a description of general mouse and keyboard conventions, see your X Window System documentation .

    Location:

    ........(TBD)

    Syntax:

    Compare files:
    xcleardiff [ –b·lank_ignore ] [ –tin·y ] [ –html ]
    [ –hst·ack | –vst·ack ] [ X-options ] pname1 pname2 ...

    Merge filees:

    xcleardiff –out output-pname [ –b·lank_ignore ]
    [-favor·_contrib n (base=1,...) ] [ –bas·e pname ]
    [ –tin·y ] [ –html ] [ –hst·ack | –vst·ack ]
    [ -q·uery | -qal·l | –abo·rt ] [ X-options ] contrib-pname ...

    xmldiffmrg (UNIX)

    The xmldiffmrg command starts a GUI in which you compare and merge versions of XML elements. xmldiffmrg parses XML, which enables you to do the following:

    • Compare and merge XML structure and content without understanding XML markup.
    • Expand, collapse, browse, and filter the data tree resulting from a comparison or merge operation.

    For general information about comparing and merging element versions, see Developing Software.

    Location:

    ........(TBD)

    Syntax:

    Start the GUI without specifying an operation:

    xmldiffmrg

    Parse one file:

    xmldiffmrg [ –xview ] [ –visible_blank ] [ pname1 ]

    Compare files:

    xmldiffmrg –xcompare [ –blank_ignore –visible_blank ]
    [ –hstack |–vstack ] [ pname1 ... pname7 ]

    Merge files:

    xmldiffmrg –xmerge [ –out pname | –to to-version ] [ –query | –abort
    | –qall ] [ –encoding { utf-16 | utf-8 | iso-8859-1 | ascii } ]
    [ –hstack |–vstack ] [ –visible_blank ] [ –base base_contributor ]
    [ pname1 ... pname7 ]