Eric J Ostrander's

ClearCase / ClearQuest / Git/Stash "how to" pages.

ClearCase, how do I ...


Attributes   |   Branches   |   CAL   |   CCRC   |   CQ integration   |   CM API   |   Derived Objects   |   Elements   |   Hyperlinks   |   Interop UNIX/NT   |   Labels   |   MetaData   |   Misc.   |   MultiSite   |   Regions / licenses / registry   |   Reports   |   Triggers   |   Views   |   VOBs   |   UCM

This page is my own personal work. Anyone can use it for their own edification, but must realize that this material is not supported by me and the site is not affiliated with IBM Rational Software or Atlassian.



Attributes
Back to the TOP
Create an attribute type.   (mkattype)
Modify an attribute type.
Remove an attribute type.   (rmtype)
Attach an attribute.   (mkattr)
Remove an attribute from an element.   (rmattr)
Modify an object's attribute value.
Rename an attribute type.   (rename)
Find objects with a certain attribute/value.   (find)
Change an attribute type's constraints.
Include spaces in the value from the CLI.
Read an attribute value.
Prevent certain users from modifying an attribute value.

Branches
Back to the TOP
Create a branch.   (mkbranch)
Remove a branch.   (rmbranch)
Merge branches.   (merge,findmerge,clearmrgman,xmldiffmrg)
Create a branch type.   (mkbrtype)
Remove a branch type.   (rmtype)
Modify an existing branch type.   (mkbrtype)
Rename a branch or branch type.   (chtype,rename)
Set up a private branch.   (Windows only)
Finish a private branch.   (Windows only)
Find all elements that have an instance of a branch type.   (find)

CAL
Back to the TOP
Overview.
Error messages.
Things you can't do with CAL.
Get a branch object.
Lock objects.

CCRC
Back to the TOP
General ClearCase Remote Client (CCRC) notes.
Determine the temp directory used by CCRC.
Add a file to source control.
View VOB contents without specifying a load rule.
CLI.
Apply a baseline.
Write the .Rational\CCRC71\workspace\.metadata folder to a custom location.
Determine the location where CCRC writes .ccase_wvreg, .keystore_clearcase, and .ccase_wvreg_lockfile

ClearQuest integration
Back to the TOP
CC/CQ non-UCM integration.
Remove the CC/CQ non-UCM integration.
Reset the CC/CQ integration CQ login.
Set CC/CQ non-UCM integration policy.

ClearQuest integration
Back to the TOP
Overview

Derived Objects
Back to the TOP
Derived objects.
List derived objects.   (lsdo)
Remove a derived object.   (rmdo)
Configuration records.
Winkin a derived object.   (winkin)
Use clearaudit.
View a configuration record.   (catcr)
Diff configuration records.   (diffcr)
Create non-shareable derived objects.
Build in CC.   (clearmake)

Elements
Back to the TOP
Checkout an element.   (co)
Checkin an element(s).   (ci)
Uncheckout an element.   (unco)
Uncheckout an element that belongs to a missing view.
Refer to an element.
Create an element.   (mkelem)
Remove an element.   (rmelem)
Change an element's permissions.   (protect)
Rename an element.   (mv)
Link to another element.   (ln)
Remove a reference to an element or symbolic link.   (rmname)
Remove references to view related elements from a VOB.
Merge elements.   (findmerge,merge,clearmrgman,xmldiffmrg)
Create an element type.   (mkeltype)
Change an element's type.   (chtype)
Set a default element type.
Move an element between VOBs.   (relocate)
Describe an element.
Diff two text elements.   (diff,cleardiff,xcleardiff)
Remove a merge arrow from an element's version tree.   (rmmerge)
Remove a version of an element.   (rmver)
Create a directory element.   (mkdir)
List details about the contents of an element version.   (annotate)
List/find CHECKEDOUT elements.   (lsco,lscheckout,lsprivate,ls,clearfindco)
Remove a trigger from an element.   (rmtrigger)
Find all elements with a certain characteristic.   (find)
Modify element attributes en masse.
Label an element.   (mklabel)
Recursively checkin/uncheckout all checkouts.
Recursively checkout all elements in a tree.
Determine what pools are assigned to an element. (describe)
Assign different storage pools to an element.   (chpool)
Change the checkout status to unreserved/reserve.   (unreserve,reserve)
Checkin all elements from all views.
Find ALL elements in a VOB.   (find)
Create a symbolic link. (ln)
Retrieve element versions not loaded in a snapshot view. (get)
Restore a single element from backup.
Recover a previous version of an element. (merge)
Recover a removed element.
Find symbolic links. (find)
Find the LATEST versions. (find)
Remove elements from the lost+found directory.
Unreserve a snapshot checkout even if the loaded files are offline.
Find all elements that have a particular branch.
Determine an element's name given its data container.
Preserve the modification time during mkelem or checkin.
Recursively import large numbers of elements.   (clearexport_*,clearimport,clearfsimport)
Force the merge tool to appear even if a merge isn't necessary. (merge)
Find all elements modified since a certain date-time.
Increase the maximum size allowed for an element.
Find objects created by a certain user.
Find objects created since a certain date.
Count the number of elements in a VOB.
Describe an element that has spaces in its name.
Change a version's comments at any time.   (chevent)
Determine the storage location (container) of an element.   (mvfsstorage, dump)
Determine the unique object identifier (oid) of an element.   (dump)
Print out all files and the latest version number for the view.
Programmatically determine a version's predecessor on another branch.
View the contents of an older version of a file.
View the contents of a file logically removed with rmname.
List all branches of an element.
List all versions of all branches of an element.
Determine if an element was renamed.

Hyperlinks
Back to the TOP
Create a hyperlink type.   (mkhltype)
Remove a hyperlink type.   (rmtype)
Rename a hyperlink type.   (rename)
Attach a hyperlink.   (mkhlink)
Remove a hyperlink.   (rmhlink)
Use predefined hyperlinks: AdminVOB, Merge, etc...
Determine a hyperlink ID.
View hyperlinks.
Stop hyperlink inheritance.

Interop UNIX/NT
Back to the TOP
Connect Windows to Unix. (general)
Convert end-of-line characters.   (msdostext_mode)
Install hclnfsd/pcnfsd.
ClearCase File Server (CCFS)
MicroSoft Service for Unix (MS-SFU or WSFU)
File access between operating systems.
Set VOB interop mode.
Access a Windows VOB from a Unix client.

Labels
Back to the TOP
Create a label type.   (mklbtype)
Remove a label type.   (rmtype)
Rename a label type.   (rename)
Attach a label.   (mklabel,clearapplywizard)
Remove a label.   (rmlabel)
Find instances of a label.   (find)
Find all label types that begin with a specified string.

MetaData
Back to the TOP
Types & supertypes.
Create a type.   (mk??type)
Remove a type.   (rmtype)
Set a default element type.
Rename a type.   (rename)
Global types.   (Administrative VOBs)
Copy a type.   (cptype)
Lock and/or obsolete a type.   (lock,unlock)
List all MetaData types in a VOB.
Change the scope of a type.

Misc.
Back to the TOP
cleartool command
CC tutorial.
clearcase_albd   (general)
Lock and unlock objects.   (lock,unlock,lslock)
Change event record comments.   (chevent)
View CC logs.   (getlog,cleargetlog)
Collect info for Rational support.   (clearbug,clearbugnt)
Get information about CC objects.
Get information about a CC host.   (hostinfo)
Get information about CC commands/man pages.   (apropos,man)
Create command aliases.
.clearcase_profile   (general)
Customize a Windows context (right-click/shortcut) menu.   (clearmenuadmin)
Performance tuning.
Use the UNIX CC GUI.   (xclearcase)
CC group permissions.
Schedule jobs.   (at, winat, crontab, schedule, disprun)
Stop and start CC services.
Enable checksums on SunOS 4.1.x, HP-UX 9.0.x and UnixWare 2.1.x.
cleardlg
Patch CC.
Get help. (man hyperhelp apropos)
Build in CC.   (clearmake)
Customize ClearCase Explorer tools.
Prompt users with/for information. (clearprompt)
Disconnect CC from the network.
Determine what ports CC uses.
Web Authoring Integration Wizard.
Determine where CC is installed. (ATRIAHOME)
Determine the MVFS drive letter.
Remotely/automatically reset a Windows albd service password. (albd_pw_util.exe)
Get the status of a remote albd service.
Change the "clearcase" group on Windows.
ClearCase File System (CCFS)
Merge non-CC files. (merge)
Create separate "site defaults" files for installation.
Perform a silent un/install.
Change permissions on all objects in a VOB.
Uninstall CC even if MVFS isn't working on Unix.
Recompile MVFS on Red Hat Linux.
Determine what version of CC all the client installs are running.
Execute heavy commands in the background on Windows.
Adjust lock manager parameters.
Send scripted emails.
Programmatically create an Excel spreadsheet using Perl.
Reset CC credentials on Windows.
Work with object names that start with a dash or hyphen.

Regions, licenses & registry
Back to the TOP
Create a region.   (mkregion)
Remove a region.   (rmregion)
Rename a region.
List regions.   (lsregion)
Licenses.   (clearlicense)
Check the consistency of a registry.   (rgy_check)
Switch to the backup registry server.   (rgy_switchover)
List the clients of a registry/license server.   (lsclients)
List the registry/license servers of a client.   (hostinfo)
Move a client to a new region.
Determine a computer's current region. (hostinfo)
Designate a backup registry server. (rgy_backup)
Set the registry password. (rgy_passwd)
Set up a backup license server.

Reports (Windows only)
Back to the TOP
Generate a CC report.
Create a custom CC report.
Create a CC report using SoDA for Word.
Extend SoDA source domains.

Triggers
Back to the TOP
Set up a trigger type.   (mktrtype)
Remove a trigger from an element.   (rmtrigger)
Remove a trigger type.   (rmtype)
Find all elements with a certain trigger attached.   (find)
Find all triggers attached to an element.
Attach a trigger to a specific element.   (mktrigger)
Prompt users with/for information. (clearprompt)
Ensure duplicate element names are not used (evil twin).
Replicate triggers in a MultiSite environment.
Triggers and multisite syncs.
CCRC triggers

Views
Back to the TOP
Create a dynamic view.   (mkview)
Set to a dynamic view.   (setview)
Remove a view.   (rmview)
List views or a view's properties.   (lsview)
Snapshot views. (create,remove,update,hijacked)
Modify a view's rules.   (edcs,setcs)
Rename a view.   (rmtag,mktag)
View profiles.
Reformat a view. (reformatview)
List view-private files.   (lsprivate)
Start and stop a view.   (startview,endview,stopview)
Recover "stranded" view-private files from an unavailable VOB.   (recoverview)
Remove derived objects from view storage.   (view_scrubber)
Remove references to view related elements from a VOB.   (rmview)
Uncheckout an element that belongs to a missing view.
Modify a view's properties/permissions.   (setcache,chview)
Set and list sitewide view properties.   (setsite,lssite)
Determine diskspace used by a VOB or view.   (space)
Determine the currently set view.   (pwv)
Determine view and VOB server processes.   (albd_list)
Designate registered view and VOB storage locations. (mkstgloc)
List registered view and VOB storage locations. (lsstgloc)
Remove view and VOB storage location registrations. (rmstgloc)
Add an existing view or VOB to a new region. (mktag)
Dynamic view .specdev file.
Retrieve element versions not loaded in a snapshot view. (get)
Determine the location of snapshot view loaded files.
Automatically have views restart after reboot. (Windows only)
Determine when a view was last accessed. (lsview)
Set what shell is used when setting to a view.
Load snapshot view files to multiple locations.
Access elements from non-CC hosts.
Remove a snapshot view whose view root is missing.
Emulate a UCM view with a base CC view.
Add/remove a view shortcut or page to/from the ClearCase Explorer. (Windows only)
Determine if a view is dynamic or snapshot given its viewtag.
Add/remove a view shortcut page to/from the CC Explorer.
Determine the MVFS drive letter for dynamic views.
Delete a view-private file or directory.
Update a snapshot view.
Access a dynamic view without using a drive letter.
Programmatically assign a view to its own drive letter.
Remove a Unix VOB/view storage area across NFS.
Find all the hijacked files in a shapshot view.

VOBs
Back to the TOP
Create a VOB.   (mkvob,clearvobtool)
Remove a VOB.   (rmvob)
Rename a VOB.   (register,rmtag,mktag)
List available VOBs.   (lsvob,clearvobadmin)
List VOB history.   (lshistory)
Get a listing of a VOB's properties. (describe)
Mount or unmount a VOB.   (mount,umount)
Move a VOB. (vob_siddump,vob_sidwalk)
Modify a VOB's permissions/properties.   (protectvob,mktag)
Register a VOB in a new region.   (register,mktag)
Check a VOB's consistency.   (checkvob,dbcheck)
Make a copy of a VOB.
Designate an administrative VOB.
List VOB replicas.   (lsreplica)
Reformat a VOB.   (reformatvob)
Determine diskspace used by a VOB or view.   (space)
Backup a VOB.
Restore a VOB from backup.   (vob_restore)
Remove a vob-tag from a region.   (rmtag)
Clean out a VOB database.   (vob_scrubber)
Create/modify a storage pool.   (mkpool)
Remove a storage pool.   (rmpool)
Rename a storage pool.   (rename)
Scrub the derived object and cleartext pools.   (scrubber)
List the pools associated with a VOB.   (lspool)
Change a VOB's feature level.   (chflevel)
Change the mastership of a VOB.   (chmaster)
Determine view and VOB server processes.   (albd_list)
Designate registered view and VOB storage locations. (mkstgloc)
List registered view and VOB storage locations. (lsstgloc)
Remove view and VOB storage location registrations. (rmstgloc)
Add an existing view or VOB to a new region. (mktag)
Set or determine a VOB's text mode. (msdostext_mode dump)
Get a listing of all owners of all VOB objects. (vob_siddump)
Create a multi-component VOB.
Fix VOB protections.
Lock or unlock a VOB.
Determine the VOB database schema version.
Enable/disable VOB auto-remounting after reboot.
Ensure nobody outside a specific group can even read a VOB's contents.
Determine the replica name of a VOB. (describe)
Link VOBs together. (ln)
Change protections on all objects in a VOB. (vob_siddump,vob_sidwalk)
List all MetaData types in a VOB.
Lock down a VOB to a couple of users.
Private vs. public VOBs.
Determine which VOBs are locked.
Programmatically determine the current VOB's tag.
Programmatically determine the current VOB's owner.
Provide read-only access to a VOB.
Programmatically determine a view-private file's VOB.
Determine when a VOB was last accessed.
Remove a Unix VOB/view storage area across NFS.




Create an attribute type.
Note that attribute types cannot be viewed in CCRC.
Attributes are name/value pairs. The types are integer, real, time, string and opaque. The opaque type is used for arbitrary byte strings. The default types are:
CLI (Windows & UNIX) string (no limit on length)
Windows Type Explorer integer
xclearcase no default
Attribute types can be applied as widely or narrowly as desired. That is, you can apply an attribute type to a specific version of a specific element if desired. However, once the scope of the attribute type is defined and instances of it exist, the scope cannot be tightened. For example, a "once per version" attribute type cannot be changed to "once per element", if instances of it already exist. The default for all interfaces is to create an attribute type local to the current VOB.
In xclearcase, Metadata -> Attribute -> Attribute type... -> Type -> Create...
In Windows CC Type Explorer, right-click on mounted VOB in Windows Explorer and go to ClearCase -> Explore Types, double-click on attribute type and go to Type -> Create...
From the CLI:
  # ct mkattype [option(s)] attribute-name
Some common options:
-vty.pe integer, real, time, string or opaque   (see above for default)
-vpe -vpb -vpv (scope) Attributes can only be applied to elements, branches or versions respectively (default is all 3).
-enu.m Specify a comma separated list of permitted values.
-def.ault Supply a default value.
-glo.bal Allow the attribute to be used by other VOBs.
[ -gt | -ge ][ -lt | -le ] Allowed value ranges can be used for integer, real and time attribute types.
-sha.red Multiple CCMS sites can rmattr and mkattr on this type, but not if the object to which it is attached is mastered elsewhere.
NOTE: String values enumerated in the CLI need to be enclosed in double quotes which must be escaped with backslashes. String values enumerated in the Windows Type Explorer or xclearcase don't need the quotes attached. In xclearcase, values can only be enumerated after creation and via Metadata -> Attribute -> Attribute type... -> attribute -> Type -> Describe. Unfortunately, in the Windows and UNIX GUIs, enumerated values must be entered one at a time.
NOTE: If an attribute type's allowed range values are changed after there are already instances of that type, CC will not complain if those existing values are now "out of range". That is, validation only happens at the time of mkattr.

Table of Contents





Modify an attribute type.
From the CLI, simply use the   -replace   option with the mkattype subcommand, replacing any values desired. There is apparently no way to do a replace from a GUI.
  # ct mkattype -replace [option(s)] attribute-name

WARNING!   If you do not use the options that were specified in the original mkattype, they will be replaced by default values with the exception of the scope options, ordinary or global.

Table of Contents





Attach an attribute.
Updated: 01/06/12
Version: 7.0.1.8
An attribute type must be created separately prior to assigning it to an element. If the value that the attribute is to be set to is a ClearCase variable, use the   \"$VARIABLE\"   construct. Attributes can be applied via triggers using the "mktrype -mkattr" subcommand. Attributes can be attached to almost anything in CC, including other metadata types.
In xclearcase, highlight the element to be modified and go to Metadata -> Attribute -> Attach to element ... It will prompt for the value after selecting the attribute type.
In Windows, right-click on the element and go to Properties of Element/Version -> Custom, right-click in the large field and chose Add Attribute ... Unfortunately, in the Windows version you must know the attribute type name apriori. If the name is unknown, go to the command-line in that VOB and type "ct lstype -attype".
Using CAL: The five arguments to Apply are the object to which the attribute is to be applied, the value, a comment, a boolean if the attribute is being replaced, and a boolean to apply it recursively.
	$vob_o->AttributeType("My_Attribute_Type")->Apply($version_o,"My_New_Value","",1,0);
On the command-line:
	ct mkattr attribute-name \"value\" object-selector
Some CLI common options:
-rep.lace Change an existing attribute to a new value.
-con.fig derived object Apply the attribute to all elements that went into a build.
-r.ecurse If applying to a directory, apply it recursively.
-v.ersion version-selector Apply it to a version other than selected by your view.
-default Use the predefined default value instead of providing one.

Table of Contents





Remove an attribute from an element.
In UNIX xclearcase, highlight the element and go to Metadata -> Attribute -> Remove from version... or Remove from element...
In Windows, access the properties sheet of the CC object. Go to the Custom tab, right-click on the attribute and select "Remove Attribute".
On the command-line:
  # ct rmattr attribute-name element
A useful option:
-ver.sion version-selector Specify a version other than selected by your view. For example, -ver '/main/{TESTED="False"}'.

Table of Contents





Modify an object's attribute value.
In xclearcase, unknown if it's possible.
In Windows, access the properties sheet of the CC object. Go to the Custom tab, right-click on the attribute and select "Change Value".
From the CLI, simply use the   -replace   option with the new value.
  # ct mkattr -replace attribute-name new-value element
Table of Contents



Rename an attribute type.
All instances of the attribute type are automatically changed.
In xclearcase, unknown if it's possible. Changes made to the attribute type's name are ignored when OK is selected (as of CC 4.1).
In Windows, open the Type Explorer under the VOBs tab of the ClearCase Home Base. Select the desired VOB and double-click on the "attribute type" folder. Right-click on the attribute and select Rename.
From the CLI:
  # ct rename attype:old-name new-name
Table of Contents



Find objects with a certain attribute/value.
Updated: 01/06/12
Version: 7.0.1.8
In UNIX xclearcase, Report -> Find query.
The find command is only available on the command-line in Windows.
Versions:
  # ct find . -version "attr_sub(attribute,operator,value)" -print
Elements:
  # ct find . -element "attr_sub(attribute,operator,value)" -print
Branches:
  # ct find . -branch "attr_sub(attribute,operator,value)" -print
The attribute,operator,value set looks like: my_attribute,==,"this is a comment". For Windows, skip the single quotes around the attribute-selector and escape the double quotes. Acceptable operators are: ==, !=, <, <=, > and >=. If a symbol such as < is used, the entire attribute selector must be enclosed in double quotes. The operators containing ">" and "<" can be used even if the values have been enumerated. In addition, they can also be used on strings. For all the variations on the syntax, see the query_language page in the CC Reference Manual.
One can act upon the results of the find command. That is, instead of the -print option, use the -exec option. As an example, change the attribute status="built" to status="tested" everywhere label BLD1.1 appears:
On UNIX:
  # ct find . -ver "lbtype(BLD1.1)" -exec 'cleartool mkattr -replace status \"tested\" $CLEARCASE_XPN'
On Windows:
  # ct find . -ver "lbtype(BLD1.1)" -exec "cleartool mkattr -replace status \\\"tested\\\" %CLEARCASE_XPN%"
If using the "cmd" executable to, say, copy files around, invoke it as "cmd /c copy ..." instead of simply "cmd copy ..." in the exec option's argument.
NOTE: Even though attributes can be attached to other objects, such as hyperlinks and VOBs, there is no direct way to query for them on those objects after they've placed there.

Table of Contents





Change an attribute type's constraints.
An attribute can be applied to almost any object in CC. With respect to elements, it can be applied to the element itself, one of its branches and all of its versions. However, the ability to apply it to an element can be constrained to one of those element sub-objects. That is, it can be constrained to apply only to versions, only to branches or only to the element itself. There is no default constraint for all interfaces. If there are instances of the attribute type already in existence, the constraint cannot be tightened. For example, if an attribute type is created with the default of no constraints and then it is applied somewhere, one cannot change the constraint to "one per version" (or some other tighter constraint). However, the opposite CAN occur. One can always go from once per version, branch or element to "no constraint".
In xclearcase, Metadata -> Attribute -> Attribute type... -> select type -> Type -> Describe -> General (Cont'd)
In Windows Explorer, right-click on VOB -> ClearCase -> Explore Types -> go to "attribute type" folder -> right-click on "attribute type" -> Properties -> Type Details
From the CLI:
  # ct mkattype -replace constraint attribute-name
The constraints are -vpe, -vpb and -vpv for one per element, branch and version respectively. No constraint argement means no constraints.

Table of Contents





Include spaces in the value on the CLI.
Updated: 10/18/11
Version: 7.1.0.8
It's very difficult to include spaces in an attribute value from the CLI or a trigger. So much so that I think it can't be done. No amount of playing with various quoting mechanisms will get it to accept a space. If anyone has an example from the Windows CLI, please forward it.
As a workaround, for example if placing the user's login name and a date/time in the value, use a construct such as: LOGIN,10/18/11_08:22:00

Table of Contents





Read an attribute value.
Updated: 01/06/12
Version: 7.0.1.8
ClearCase Explorer
Right-click on the object (element,VOB,branch,version,etc...) bring up its properties. Attributes are under the Custom tab.

CLI
	ct describe -fmt "%[attribute]a\n" object
CAL
	$element_o	= $vob_o->Element("My_File");
	$attr_o		= $element_o->Attribute("My_Attribute");
	if ( "$attr_o" ne "" ) {
		$value = $attr_o->Value;
	}
Table of Contents



Prevent certain users from modifying an attribute value.
Updated: 06/11/13
Version: 7.1.2
One way to ensure only a certain group of users can modify an attribute is to create a preop trigger for the mkattr command. The mkattr command is called when a modification is done, as opposed to the mkattype when the attribute type is defined.
The trigger could have a list of -nusers who are excluded from the lock.
The trigger could call a script that checks to see if the user is a member of a specified domain group.
Instead of a trigger, another way to do it is to lock the attribute type and add users to the excluded users list.

Table of Contents





Create a branch.
Branches can be created three different ways:
1) Command line: The branch-type must exist prior to creating the branch. You can use the   -version   option to designate an element version other than that being selected by the current view.
  # ct mkbranch branch-type element-name
2) Set up a private branch. (Windows only)
3) Automatically in a config_spec:
A view's config_spec file can be configured to automatically create a branch when a file is checked out. The branch point must be pre-determined by using a label on the version from which to be branch or by specifying a a version such as LATEST. If using a view profile, it will configure the config_spec automatically.
element * LABEL -mkbranch branch-type
To set up automatic creation of nested branches:
element * CHECKEDOUT
element -directory * /main/LATEST
element * /main/branch1/branch2/LATEST
element * /main/branch1/LABEL2 -mkbranch branch2
element * /main/branch1/LATEST -mkbranch branch2
element * /main/LABEL1  -mkbranch branch1
element * /main/LATEST  -mkbranch branch1
NOTE: I personally always have my directories as /main/LATEST. While versioning of directories is very important, from experience, branching of directories can be too confusing. The above example can be alternatively written:
element * CHECKEDOUT
element -directory * /main/LATEST
element * /main/branch1/branch2/LATEST
mkbranch branch2
element * /main/branch1/LABEL2
element * /main/branch1/LATEST
end mkbranch
mkbranch branch1
element * /main/LABEL1
element * /main/LATEST
For the above example, EOF can be used in lieu of "end mkbranch".
WARNING!   If using auto-mkbranch in a config_spec and you add an existing file to source control, it will correctly place that file's contents on the final branch in your tree (based on the -mkbranch rules), but the 0'th version on all intermediate branches, including main, will be empty. This is noted because it is a possible point of confusion. To see the new elements contents on other branches, simply merge to them.
NOTE: The mkbranch operation can be triggered, but the trigger will not fire for creation of the main branch during mkelem.

Table of Contents





Remove a branch.
  # ct rmbranch element-name@@/main/branch-name
Table of Contents



Create a branch type.
In UNIX xclearcase, Versions -> Branch -> Branch type... -> Type -> Create...
In Windows CC Type Explorer, right-click on mounted VOB in Windows Explorer and go to ClearCase -> Explore Types, double-click on branch type and go to Type -> Create...
On the command-line:
  # ct mkbrtype branch-name
Some useful options:
-rep.lace Change the parameters of an existing branch type.
-glo.bal Declare it so that other VOBs can use it (see adminstrative VOB).
-pbr.anch Override the default to allow more than one branch of this name per element (not recommended).

Table of Contents





Rename a branch or branch type.
Branch type:
All instances of the branch type are automatically changed. View config_specs and profiles referring to the old-name are not automatically updated.
In xclearcase, Admin->Branch type, select the type then Type->Rename.
In Windows, right-click on the VOB and select ClearCase->Explore Types. Enter the "branch type" folder, right-click on the type and select Rename.
From the CLI:
  # ct rename brtype:old-name new-name

Branch instance:

A single instance of a branch type can be renamed using chtype. For example, if you mistyped dev1.0 in your config_spec and it was really suppose to be dev1.1, you can simply correct your config_spec and change the branch name on an instance by instance basis.
In xclearcase version tree browser, highlight the branch to be changed then Branch->Change type.
In Windows, unknown if it's possible.
From the CLI:
  # ct chtype new-branch-name element@@old-branch-path
ex:
  # ct chtype dev1.1 foo.c@@/main/dev1.0
WARNING!   In a UCM environment, if the branch type is part of a UCM environment, see "Rename a project's Integration stream/branch". However, you can rename a development branch type without issue. After renaming the branch type, just be sure to rebase the stream and run "ct setcs -stream -tag view-tag" on any views associated with the stream. If a snapshot view, you need to be in the view root folder and then don't need to specify the -tag parameter.

Table of Contents





Set up a private branch. (Windows only)
"Set Up Private Branch" based on a view profile via ClearCase Home Base -> Branches or by right-clicking on the view in Explorer. A view profile must exist prior to branch creation.
NOTE: Setting up a private branch does not extend the rules currently in your config_spec, but overwrites them. Currently there is no way to nest private branches, they branch from main. That is, if you have a view profile that, say, automatically creates an integration branch off of main, and you want to set up a private branch off of that, using the "Set Up Private Branch..." menu option won't work properly. It will prompt you whether you want to associate the private branch with the existing rules or choose a different label point. If you choose to associate the private branch with the existing rules, the -mkbranch options for the integration branch will be replaced by the -mkbranch for the private branch, essentially branching the private off main. If you answer that you want to create the private branch from a label, it removes all references to "integration" branch and just has the private branch off main at the new label. The upshot of this is, if you want to have a branch off of the integration branch, the config_spec will have to edited by hand.

Table of Contents





Finish a private branch. (Windows only)
Finish Private Branch via ClearCase Home Base -> Branches or by right-clicking on the view in Explorer. Finishing a private branch will prompt whether you want to abandon the branch or merge it. If you choose to merge, it runs a findmerge for you. If the window comes up blank, it didn't find any. Since private branches are mandatorily associated with view profiles, the merge is automatically back to the integration branch or main, depending on what you set up during the view profile creation.
NOTE: When a view is dissociated from a view profile, the view's config_spec remains the same as the view profile. However, when you "Finish Private Branch...", the config_spec reverts back to that of the associated view profile.

Table of Contents





Find all elements that have an instance of a branch type.
In UNIX xclearcase, Report -> Find query.
The find command is only available on the command-line in Windows.
  # ct find path -element brtype(branch-name) -print
The path is the directory in which you want the search to begin.

Table of Contents





Overview. (Windows only)
Updated: 01/03/12
Version: 7.0.1.8
The ClearCase Automation Library (CAL) is only available on Windows. It's much more efficient to use CAl in a script than to call out to cleartool. However, note that the CAL documentation is VERY poor and there are a number of things that can't be done. To start CAL:
	use Win32::OLE;
	$CC = Win32::OLE->new("ClearCase.Application");
	if ( "$CC" eq "" ) {
		print "ERROR: Can't create ClearCase application object via call to Win32::OLE->new(): $!\n";
		exit 1;
	}

	# Basic objects.
	$vob_o		= $CC->VOB("\\vobtag");
	$element_o	= $CC->Element("relative_path\\file.txt");
	$version_o	= $CC->Version("file.txt\@\@\\main\\1");
To get help, type Start -> Run -> cc_cal.chm.

Table of Contents





Error messages.
Updated: 12/23/11
Version: 7.0.1.8
Each time a CAL method is called, a return status is set. The LastError method will return an integer (error number) or a string (error message) depending on context. Errors in CAL calls do not cause the script to fail.
	$attribute_o = $element_o->Attribute("Attribute_Name");
	if ( Win32::OLE->LastError() ) {
		print "ERROR: Unable to read the \"Attribute_Name\" attribute on file.txt.\n".Win32::OLE->LastError();
		exit;
	}
	$value = $attribute_o->Value;
Warning: Be careful that CAL will produce error messages where the corresponding cleartool command does not. For example, in the above code snippet, you can run a cleartool describe command to get an attribute's value. If there is no value, the command returns nothing. If there is no attribute attached, the command returns nothing. However, when using CAL, if there is no attribute attached, it returns an error message. In that case, you can use a construct like:
	$attribute_o = $element_o->Attribute("Attribute_Name");
	if ( "$attribute_o" ne "" ) {
		$value = $attribute_o->Value;
	}
Table of Contents



Things you can't do using CAL.
Updated: 07/05/13
Version: 7.1.2
While using CAL is much more efficient than calling cleartool, it's a bit thin in some areas. That is, there are many things that cannot be done using CAL. If anyone knows how to do any of the above in CAL, I'd be very interested in hearing from you.

The following are in CAL, but don't appear to work correctly:
IsActive supposedly can make the view active on the current machine, but doesn't work.
There are methods listed for creating and replacing trigger types. However, they either simply don't work or the documentation is poor, or both.
There are methods listed as collection objects, such as Elements, but there doesn't seem to be a way to get that collection, other than building the collection in a loop.
An lsview on a CCRC view will show a view attribute of "snapshot". However, the IsSnapShot method doesn't return a positive. That call only seems to work for regular snapshot views.
Any call that requires SQUID (UCM CQ integration) will fail even if using CmdExec. For operations such as deliver, setact, etc.. that require a connection to CQ, use a regular system call to cleartool.

Table of Contents





Get a branch object.
Updated: 11/27/12
Version: 7.1.2
Branch objects are specific to branch instances, so you can't just say $CC->Branch(branch-name). The branch must be derived from a branch instance associated with a version. If you need the branch object for a branch associated with a version not selected by the view, you'll need to get the version object for it explicitly in a different manner. In all the following cases, the version selection is done by the current view. If you know the element path, version path, or branch path, you can do one of the following.
	$branch_o = $CC->Element(element-path)->Version->Branch;
	$branch_o = $CC->Version(version-path)->Branch;
	$branch_o = $CC->Version("branch-path\\0")->Branch;
Table of Contents



Lock objects.
Updated: 07/24/13
Version: 7.1.2
Note that the "Lock" method doesn't appear in the man pages of any of the objects, but can be used on any lockable object.
The following applies to all metadata, but "branch" is used for clarity. If a branch type is locked and obsoleted, the type cannot be used anymore and the branch instances will appear as obsoleted as well in a version tree. If you view the properties of a branch instance, the instance will still show unlocked though.
If you attempt to get the lock object for a branch instance and the it's unlocked, the $branch_o->Lock will not return anything, nor will it return an error. That call only returns a lock object if the branch instance is locked and/or obsoleted.
When the type gets locked, so that you don't have to explicitly lock all branch instances as well and still get the Lock method to return a useful value, you'll have to look at the lock on the type instead, as in: $type_lock_o = $branch_o->Type->Lock;

Table of Contents





General ClearCase Remote Client (CCRC) notes.
Updated: 07/26/11
Version: 7.1.1
CCRC does not support the creation and viewing of attribute or trigger types.

Table of Contents





Determine the temp directory used by CCRC.
Updated: 08/05/11
Version: 7.1.1
On the server, run commands similar to the following:
	cd "C:\Program Files\IBM\RationalSDLC\common\CM\scripts"
	set WAS_BIN="C:\Program Files\IBM\RationalSDLC\common\eWAS\bin"
	%WAS_BIN%\wsadmin -profileName cmprofile
	wsadmin> source teamAdminUtils.jacl
	wsadmin> dumpTeamServer
Look for a variable called "ccrcTempDir". IBM has a detailed document on MBean attributes.

Table of Contents





Add a file to source control.
Updated: 04/20/12
Version: 7.0.1

There is no way to drag and drop a view-private file into a folder or create one directly there. When the CCRC view was created, CC asked where on your local drive you wanted to store data. In your Windows Explorer, go to that location and create the view-private file there.
Back in the CCRC interface, with the view selected, click the Refresh button on the toolbar (two yellow opposing arrows). The view-private file should now show up in the directory where you put it in the Windows Explorer. Right-click on the file and select Basic -> Add to Source Control.
Also, within CCRC you can right-click on a directory and select New -> File. However, while I've seen that work, there are times when it's ghosted out. I don't know why you can sometimes and other times you can't.

Table of Contents





View VOB contents without specifying a load rule.
Updated: 06/04/12
Version: 7.1.2

The only way to view VOB contents without a load rule specifying the directory tree you're interested in is to use the Edit Configuration tool to surf around.
If you don't want to load up a whole VOB, but don't know which file(s) you'll need on a given day, you'll need to go through the motions of editing the load rules to surf around inside the VOB and then only load the file you're interest in.
Right-click on the view and select "Show ClearCase View Configuration", then in the white space right-click and select "Edit Configuration".

Table of Contents





CLI
Updated: 01/08/13
Version: 7.1.2

CCRC has the abililty to run basic CLI (command line interface) commands that allow users to perform some very basic tasks, such as checkin and checkout. While these can be used in a script to do things programmatically, this interface doesn't come anywhere near the CC command line and CAL. UCM is not currently supported.
Note that prior to 8.0.0.3, CCRC CLI is a separate install from the client where the client must be installed first. To install, download CCRCCLI.zip from IBM Rational. See http://www-01.ibm.com/support/docview.wss?uid=swg24021929 for instructions on the new interface. The zip file is listed at the bottom of the page.

Table of Contents





Apply a baseline.
Updated: 03/19/14
Version: 7.1.2

It doesn't appear to be possible to generate baselines using the CCRC interface.

Table of Contents





Write the .Rational\CCRC71\workspace\.metadata folder to a custom location.
Updated: 05/23/14
Version: 7.1.2

Execute CCRC with the -data parameter. Whatever folder is specified with then contain the ".metadata" folder. For example: "C:\Program Files\IBM\RationalSDLC\clearcase\RemoteClient\ccrc.exe" -data C:\CCRC_stuff
Metadata such as previously used CCRC servers, the last used view root folder, the ClearCase Primary Group, etc.. are stored in ".metadata\.plugins\com.ibm.rational.clearcase\dialog_settings.xml".

Table of Contents





Determine the location where CCRC writes .ccase_wvreg, .keystore_clearcase, and .ccase_wvreg_lockfile
Updated: 06/03/14
Version: 7.1.2

When you log into a CCRC server for the first time, it may prompt for a security certificate, which is then stored in .keystore_clearcase.
When a view is created, the view root folder is written to .ccase_wvreg. While CC is editing that file, it sets a temporary .ccase_wvreg_lockfile.
The location of those and other files is the parent folder of the value set in the registry key "HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\Desktop".

Table of Contents





Derived objects (general).
Derived objects (DOs) have three distinct parts; the DO, its data container a configuration record:
1) The DO appears as a view-private file in the directory in which it was created. This is just a pointer to the data container and not the actual object file.
2) The data container when initially created (unshared) is located in the view's storage area. If another view winks in the object, the data container is copied to a more permanent storage area within the VOB's storage area (shared). In either case the data container is not a VOB object or versioned. It is only a versioned object when a checkin is explicitly run on the DO. Note, a mkelem is not necessary on the DO, as the DO is already in the VOB database, just not versioned.
3) Configuration records (CRs) are created each time clearmake executes a build in which one or more DOs are created.

Derived objects can be referenced different ways:
1) simple name (if already local to view) -- ex: hello.o
2) view-extended naming -- ex: /view/view-tag/hello.o
3) VOB-extended naming -- ex: hello@@21-Dec.16:18.397
The unmbers at the end of the VOB-extended naming are the date and an ID unique to that date.

Table of Contents





List derived objects.
The default is to list all DOs at a given pathname regardless of what view was used.
  # ct lsdo [derived-object]
A couple of the more useful options include:
-r.ecurse List recursively.
-me Restrict listing to DOs under your control.
-zer.o List unshared DOs with a reference count of 0.
-l.ong Show reference counts and the views that reference them as well.
The describe subcommand can be used to list DO versions that the lsdo cannot.

Table of Contents





Remove derived objects (DO).
DOs and their data containers can be deleted independently, because a view may no longer need to reference a DO, but other views still need to get at that data container. Deleting a DO without rmdo decrements its reference count. The reference count of a DO can be determined with "ct describe". Shared is defined as being in a VOB storage area. Unshared is defined as only being in a view's private storage area. To ensure that all references to a DO are deleted, you need to combine an rmdo with a UNIX rm (or Windows del) command.
1) Using UNIX mv (or Windows move) or ct mv on a shared or unshared DO has no affect on the DO being a candidate for winkin or not. That is, the name seen in the view can be changed and the DO retains its CR and can still be winked in to another view under the original name.
2) Using UNIX rm (or Windows del) will delete an unshared DO in the normal way along with its data container and CR.
3) Using UNIX rm (or Windows del) on a shared DO will have no affect on the data container that has been promoted to the VOB.
4) A build that overwrites an unshared DO acts just like the rm (del) command in (2).
5) Using rmdo on a shared DO will delete the VOB data container and CR. Any version of the DO still in a view will become a simple view-private file.
6) Using rmdo on an unshared DO will not delete it or the container in a view's private storage area; only the CR. A subsequent ct ls command will list the DO as [removed with white out]. If this is the case, "touch" the DO and then "rm" it.
7) The CC "scrubber" command will delete shared DOs and data containers from the VOB's pool that have a reference count of 0. See the mkpool command for information on setting the pool scrubbing parameters.
8) See the view_scrubber command for the scrubbing of DOs from a view.

Removal of DOs can only happen on the command-line for both UNIX and Windows. By default, the rmdo command only deletes one DO version for a given name. That is, there may be many DO versions of a DO, but rmdo will only remove the one that is in the current view.
  # ct rmdo DO(s)
Some useful options:
-a.ll Remove all versions of the DO regardless of reference count.
-zer.o Similar to -all, but only delete those DO versions with zero reference counts.
-bef.ore   date-time New in CC 2003.06.00. Delete DOs dated prior to a certain date-time.
-sin.ce   date-time New in CC 2003.06.00. Delete DOs dated since a certain date-time.

Date-time strings for the -before and -since options must adhere to 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.)

Table of Contents





Configuration records (general).
A configruatoin record (CR) is a bill of materials generated by the clearmake, omake and clearaudit commands. Any time a DO is created a CR is written to that view's database. The CR is copied to the VOB database when/if the DO is winkedin or promoted. If the DOs span many VOBs, then each VOB will have a copy of the CR. A CR contains several sections (only the first two apply to clearaudit).
Header target, host info, time, view and initial working dir
MVFS objects each MVFS file read during the build (versioned & view-private)
Non-MVFS files explicitly mentioned by the makefile but not in CC
Variables and options values of make macros referenced by the build
Build script script executed by clearmake
Typically a makefile has a hierarchical structure. An invocation of clearmake on a makefile can cause multiple build scripts to be executed, thus creating multiple CRs. That is, a CR is associated with a build target, not a makefile. Moreover, when running a command such as "catcr", the output pertains only to the DO at hand. Be sure to use the -recurse option to get the full source tree.
Initially, the DO and associated CR are view-private. To speed up referencing the CR in the currrent view during subsequent builds, a compressed file called .cmake.state is stored in the directory in which the build was started. A subsequent winkin or CC versioning of the DO will cause the DO and CR to be promoted to the VOB.
NOTE:The CR of a DO does not contain environment information that may be relative to a successful rebuild of the object later in time, such operating system patches and packages.
WARNING!   The dependency checking that occurs to determine if an object can be winked into another view does not take into account other vital factors, such as the operating system that originally build the object. For example, if an object is built on Solaris and a subsequent build of the identical source files is conducted on HP, clearmake could errantly winkin the DO. To avoid this potential issue, add the following to your Makefile. In the example, target.o is dependent on OSVERSION, even though it's send to /dev/null. The example is decidedly UNIX, but the theory can be applied to any OS.
OSVERSION: sh=uname -r

target.o:
	echo $(OSVERSION) > /dev/null
	$(CC) $(CFLAGS) target.c
Table of Contents



Winkin a derived object.
Normally a DO is winked-in via a clearmake build. However, DOs can be winked-in at any time via the winkin command. This is useful to access another view's DOs, in that DOs cannot be accessed via the normal version-extended pathname. Once the DO is winked-in, it is accessible locally using that view.
  # ct winkin derived-object
See the derived object general discussion for DO naming conventions.
Some useful options:
-pri.nt Only list what would have been winked-in.
-sib.lings Wink-in DOs created by the same build script that created the named DO.
-r.ecurse Walk the DO's configuration record, winking-in subtargets of the named DO.
-out Specify a new local name for the DO (mandatory for view-extended name wink-ins).
-nov.erwrite Override the default of overwriting any existing unshared DOs.

If you specify a shared DO while working in the view where it was originally built and there is still a view-resident data container for the DO in that view, the view-resident data container is scrubbed and your view will access the shared data container in VOB storage. This is equivalent to executing a view_scrubber command.
If you specify an unshared DO in your view, it is promoted to the VOB and then winked-in. The view-resident data container is scrubbed and your view will access the shared data container in VOB storage. This is equivalent to executing a view_scrubber -p command.
Note that view_scrubber is more efficient when a large number of DOs are to be processed in this way.

Table of Contents





Use clearaudit.
The clearaudit command can be used to create an audit record of any executable that outputs into a VOB context. That is, it creates DOs out of any files that the executable generated. This can be useful for creating a CR of a UNIX make that uses CC objects. However, those new DOs, though available to most DO related commands, cannot be winked-in by a clearmake unless an explicit winkin command is run.
  # clearaudit -c "make [options]"
The clearaudit can also be used to audit the backup of VOB elements. The output of the tar will have a CR associated with it listing the versions of the saved elements.
  # clearaudit -c "tar cvf tarfile file(s)"

Table of Contents





View a configuration record.
See configuration records for a description of CRs.
In UNIX clearcase, Building -> Display config rec.
In Windows GUI, unknown if it's possible.
On the command-line:
  # ct catcr DO
Some useful options:
-r.ecurse Display the CRs of DO subtargets as well.
-fla.t Similar to -recurse, but consolidates into a list of unique versions.
-uni.on Similar to -flat, but one report for all DOs listed on the command line.
-mak.efile Similar to -recurse, but display output in makefile format.
-wd List pathnames relative to the current directory.
-typ.e { f | d | l } Specify the version types to report: files, directories or links.
-l.ong Include kinds of objects and their comments in the listing.
-s.hort Restrict output to file system objects only.
-fol.low New in CC 5.0/2002. List the targets of symbolic links, not the links themselves.
-scr.ipts_only New in CC 5.0/2002. Restrict the listing to the header and build script.

Table of Contents





Diff configuration records.
See configuration records for a description of CRs. Don't know if it's possible to diff CRs in UNIX xclearcase or a Windows GUI.
On the command-line:
  # ct diffcr DO-1 DO-2
Some useful options:
-r.ecurse Compares the DOs and their commom subtargets.
-fla.t Consolidate subtargets into a single unique listing.
-wd List pathnames relative to the current directory.
-typ.e { f | d | l } Specify the version types to report: files, directories or links.
-l.ong Include kinds of objects and their comments in the listing.
-s.hort Restrict output to file system objects only.
-nxn.ame Do not include version extensions when listing MVFS objects.
-fol.low New in CC 5.0/2002, list the targets of links and not the links themselves.

Table of Contents





Create non-shareable derived objects.
New in CC 4.0, one has the ability to create derived objects that cannot be shared (winked-in) by any other view. Simply, it doesn't create the VOB database entry that other views would need to know if a derived object has been built in another view.
A view (dynamic only) can be configured to create non-shareable DOs at time of creation. The default for a new view is shareable unless overridden by sitewide defaults. Make a view's DOs non-shareable during creation:
From the Windows GUI, the option is tucked away in the Advanced Options button on one of the pages in the creation wizard.
From UNIX xclearcase, the option is prompted for during view creation.
From the CLI, Windows or UNIX, use one of the following options:
  # ct mkview [ -sha.erable_dos | -nsh.areable_dos ] ...

Make a view's DOs shareable after creation:

From the Windows GUI, see the view properties sheet, Advanced tab.
From UNIX xclearcase, unknown if it's possible.
From the CLI:
  # ct chview { -sha.reable_dos | -nsh.areable_dos } view-tag

Toggling whether a view's DOs can be shared or not only affects DOs created in the future. Non-shared DOs can be subsequently shared by doing a "winkin" on them or by using "view_scrubber -p". Once a DO has been shared, it cannot be unshared.

Table of Contents





CC/CQ non-UCM integration.
It doesn't matter if the VOB being integrated is being served from Windows or UNIX. The integration tool described below will handle both. For either case, you need to be logged into the Windows box as the owner of the VOB to be integrated. Only the VOB owner or higher can create triggers, which is what this integration does. CC must be installed on the CQ server to utilize this integration. CQ does not need to be installed on the CC VOB server. Any client workstation that will use the integration needs CC and CQ installed.

On the CQ side:
Create a new schema. Add the ClearCase package to your schema. Also be sure to add any ClearCase package updates, such as "Upgrade 1.0". Note, if using CC prior to 4.0, this portion is completed via the CQ tab on the CC side. See below.

On the CC side (Windows only):
Go to Start -> Programs -> ClearCase Administration -> ClearQuest Integration Configuration. In the ClearCase tab, choose the VOB to be integrated and determine the integration properties. In the ClearQuest tab (prior to CC 4.0), choose the schema with which to integrate and select Update ClearQuest Schema.
Even though the CQ integration is bundled with CC, you need to tell CC that you want that functionality during install. If you don't see the CQ Integration Configuration in the ClearCase Administration menu, you need to update your CC release area and reinstall CC.

NOTE: Out of the box, CQ does not require a password. However, the CC integration tool does not allow a null string as the password.

Table of Contents





Remove the CC/CQ non-UCM integration.
Start the ClearQuest Integration Configuration wizard via the ClearCase Administration startup menu. Select the VOB to be de-integrated and simply set the Checkout Policy and Checkin Policy to "Never Prompt...". The trigger(s) that were created in the VOB during the integration are dynamically removed.

Table of Contents





Set CC/CQ non-UCM integration policy.
See CC/CQ non-UCM integration. The integration page sets the policy.
NOTE: The checkout policy is post-op. That is, there is no way to capture the CQ-record-id and do something with or to it prior to checkout. The unco and checkin policies are pre-op triggers.

Table of Contents





CM API overview
Updated: 01/09/13
Version: 7.1.2
The Rational CM API extends the WVCM (Workspace Versioning and Configuration Management) API, which is a standard Java API for configuration management (see http://www.jcp.org/en/jsr/detail?id=147). The Rational CM API supports web views but does not currently support dynamic or snapshot views, which implies CCRC. See http://publib.boulder.ibm.com/infocenter/cqhelp/v7r1m2/index.jsp?topic=%2Fcom.ibm.rational.team_api.doc%2Ftopics%2Fc_introduction.htm for an introduction.

Table of Contents





Create an element.
Updated: 10/08/12
Version: 7.1.2
Before creating an element, there needs to be a proper element type already in existence. See "Set up/modify a trigger script" for a discussion on element types and supertypes. To work with elements, the parent directory needs to be in a checked-out state first. As a default, the new element is created in the checked-out state. When creating elements stored on a UNIX machine, make sure the names adhere to the standard UNIX naming conventions. If creating an element from a pre-existing file, it is necessary to copy the file into the VOB directory first, thus creating a view-private file. That is, the pre-existing file must be copied local before making it into a CC element.
For pre-existing files:

In xclearcase, File -> VOB object -> Create element from file.

In Windows, right-click on the the view-private file and select "Add to Source Control...".

From the CLI:
  # ct mkelem filename
For non-existent files:
In UNIX xclearcase, checkout the parent directory, deselect the parent directory, File -> VOB object -> Create element...
In Windows Explorer, File -> New -> kind, right-click on the new view-private file and select "Add to Source Control...".
From CCRC, add the file to snapshot view path in the Windows Explorer, then in CCRC hit F5 to refresh the screen, right-click on the file and select add to source.

CLI:
 	# ct mkelem filename
CAL:
	$checkedout_o = $CC->CreateElement("$file_path");
In general, the supertype of a file will be assigned based on the rules in the default.magic file located in "atria-home/conf/magic" on Unix or "ClearCase-home\config\magic" on Windows. However, that can be overridden with the mkelem -eltype element-type option. Unfortunately, automatic eltype assignment cannot be overridden when using either a UNIX or Windows GUI.

(Windows only) Prior to CC 4.1, your primary group must be listed in the VOB's group list. As of CC 4.1, if any group you are a member of is in the VOB's group list, you have permission to mkelem.

NOTE: For the mkelem -ci option, the file must already exist. If the new element is empty, CC will complain about it being identical to predecessor (/main/0). If the new element is not empty, /main/1 will be created and checked in.

NOTE: While copying a file in Windows or UNIX into a VOB directory as a view-private file, it's simple to preserve the original creation/modification date. However, there is no way preserve that date in CC. Once the element is created, a new time-stamp is applied and the old is lost forever. If absolutely needed, the new element could possibly be given an attribute with the original time-stamp for record keeping purposes. Yes, the -ptime option preserves the modification date, but only until the file is overwritten with a new version. Inspection of the element using describe, lshistory and other CC commands will not show a preserved original date :-(.

NOTE: The mkelem subcommand has no   -recurse   option. That is, if you want to check into CC a whole directory structure all at once, mkelem is not the command to use. Instead, use a "clearexport_ffile -r directory" out in the non-CC system to create a cvt_data file. Cd to the VOB directory where you want the new directory to go and run "clearimport -v" on it there.

WARNING: If you add a file to source control while it's still empty, CC may assign an incorrect element type to it. For example, if you add an empty Word file to source, CC will not be able to detect that it's a Word file based on its embedded magic number, so will assign element type "text_file". The file will be added to source control successfully, but will have trouble when you make the first edit to the file. A file's element type can be changed using the chtype command, or by just getting in the habit of not adding empty files to source control.

Table of Contents





Remove an element.
There is no way to delete an element from a GUI.
To remove an element forever, use the rmelem command. If the element being deleted is a directory, elements inside the directory will wind up in lost+found. No need to checkout the parent directory first, as rmelem removes the element from all versions of the parent. As of CC 5.0/2002, only the VOB owner or a privileged user can remove and element if there is any metadata attached.
  # ct rmelem element
The rmelem command removes directory history of the element and creates a history entry about itself. This means that comments can be attached to the rmelem itself via the   -c   option. The confirmation prompt can be bypassed via the   -force   option. However, as recommended by the CC Admin Manual, it is much better to just use the rmname command. The rmname command removes the reference to the element from the directory element. That is, it still exists for previous versions of this directory, but will not for versions thereafter. A rmname of a CC directory will obviously cause all of its subdirectories to be dereferenced as well.
NOTE: If using UCM, rmelem will remove the element's name from the activity change sets to which it belonged.

WARNING!   While base CC elements can be recovered from backups, there is no way to recover a UCM element and have it installed back into the UCM heirarchy.

  # ct rmname element-name
Use the &nbps; -nco   option if you don't want to check-out the parent directory first; which would need to be done. To restore an element that has be de-referenced using the rmname subcommand, use the "ln" subcommand. That is, if code.c has been removed from the current version of the local directory.
  # ct  ln  .@@/main/older-version/code.c  code.c
The older-version is that last version of the current directory in which the file "code.c" existed. An lsvtree of the current directory for different versions will tell you in which version of the directory the element was last present.
  # ct  lsvtree  .@@/main/version
See also "Remove a version of an element."

WARNING!   If running rmname in a UCM environment, ensure the element is not part of any activities not yet delivered or you will get "file not visible in view" and the deliver will fail. Open the element's version tree browser and look for versions on development branches that do not a Merge hyperlink to an integration branch.

Table of Contents





Change an object's permissions.
Need to be at least the object's owner to change its permissions. Use the corresponding protectvob command when changing permsissions on a VOB. There is no way to change permissions on a view without recreating it.
On Unix xclearcase, Admin -> Element -> Change ? --or-- Report -> Describe -> ClearCase Object
On Windows, context menu option Properties of Element -> Protection
On the command-line:
  # ct protect options element(s)
-or-
  # ct protect options type:selector(s)
Options:
-cho.wn new-owner Change the owner of the object.
-chm.od permissions Change the permissions.
-chg.rp new-group Change the group of the object.
-r.ecurse Change protections recursively.
-fil.e | -d.irectory Restrict the recursive protection change.
NOTE: In Unix, initial permissions are set be the user's umask unless the element was created from a view-private file, in which case the permissions are base on those inherited permissions. On Windows, the permissions are set to 444 for files and 777 for directories.
NOTE: On Windows, there is no way to remove group read permissions on an element.

Table of Contents





Rename an element.
Updated: 04/24/13
Version: 7.1.2
Renaming an element is as simple as the UNIX mv command. But, only use it in a CC context or errors will occur. This command only works within a single VOB. If you want to move an element to a different VOB, use the relocate subcommand.
  # ct mv oldname newname
From the CLI, the parent directory must be checked out prior to changing the name of a file or moving it somewhere else. Once the parent directory is checked back in, the element will still show up as the old name in previous versions of that directory.
From the CC Explorer, right-click on the element and select Rename. CC will automatically check the parent out and back in as part of the rename. If the parent folder is already checked out, the rename will not check it back in. If using UCM, you must already have an activity set in the current view, as it won't prompt for which one to use.
NOTE: If the element is currently checkedout to a view, CC will send a warning message that view private may need to be renamed as well, but will continue with the element rename anyway. However, I don't know what the warning is for. If the element is checkedout to the current view, the view private file is automatically renamed as well as the element itself. If the checkout is another view on a different branch, the other view will only see your element rename when the branches are merged. If the checkout is to a view on the same branch, the view private file doesn't get the rename, but the subsequent checkin proceeds without issue.
WARNING: Unfortunately, there is no easy way to know if an element has been renamed. This is a problem from a verification and audit stand point. The parent folder versions merely state that a file was Uncatalogued and that another was Added. That is from the parent folder information, you can't determine if the file is the same one. The history of the file element itself shows the new name for all versions back to creation.

Table of Contents





Link to another element.
If there is code common to several areas in CC, create an original and then create a hard-link to that one from other areas. The directory containing the linked element must be checked out prior to creating the link. Entire directory elements can be soft-linked (-slink option) in a similar way. It is recommended that relative paths be used, vice absolute, to avoid invalid links if one or another VOB mount point gets changed. Links can only be applied from the command-line, both in UNIX and Windows.
  # ct ln path/original-name linked-name
-or-
  # ct ln -slink /another-vob/directory directory
When a hard-linked element is checked-out, all other names for that element will appear as "[checked out but removed]". I.E. There is only one view-private file no matter how names there are for it.
The   -slink   option can be used to create a soft-link to the original, but there are many restrictions on what can be done WRT check-outs, labels, etc...
NOTE: Cannot use hard-links across VOBs or on directory elements; must use a soft-link (-slink) in those cases.
NOTE: Once a hard-link is created, there is no way to tell the "original" from the newly created name for that element. I.E. There are truly the same element in all respects. The only way to determine if two names in a VOB are really the same element is to use the mvfsstorage or dump command.
NOTE: Unlike UNIX, if the other end of the link does not exist, DOS will not list the link via "dir". However, a "ct ls" will show the invalid link in both UNIX and Windows.
NOTE: In UNIX, if you cd to a soft-linked directory and then immediately "cd ..", you will not be where you were before, but rather you will then be in the directory above the other end of the soft-link. This is not true for Windows. If you cd to a CC soft-linked directory in Windows, the route you took to get there remains part of your path and can be traversed backwards.
NOTE: Most ct commands as well as config specs DO NOT follow softlinks. A few exceptions, such as find, have -follow options.
NOTE: In the Windows CC Explorer, double-clicking on a symbolic link correctly invokes the correct executable only if the symbolic link end has the same extension as the original file. That is, the CC Explorer is using the native system to set the icons next to the file names. However, this isn't true for directories. Symbolic links to directories have the "unknown" file type icon next to them. If you double-click on it, CC Explorer will launch the Windows Explorer and take you to the correct directory. Since it doesn't leave you in the CC Explorer, this can be a sore point for developers.
NOTE: As of CC 5.0, there is no way to run a query to find symbolic links.

Table of Contents





Remove a reference to an element or symbolic link.
This command is useful if you want to remove the reference to an element in the current version of a directory element. This avoids having to rmelem, which deletes all versions of the element. It is also useful for deleting symbolic links to other elements without removing the original. The rmname can be abbreviated to "rm". As of CC 4.0, the parent directory does not need to be checked out first.
  # ct rmname element
-or-
  # ct rm softlink
Table of Contents



Remove references to view related elements from a VOB.
Uncheckout an element that belongs to a missing view.

If an element is checked out in a view and that view is subsequently deleted without checking the element back in, the element becomes "stranded". That is, CC will tell you that the file is checked out to a certain view, but you see that the view no longer exists. Use the following commands to undo the checkout. Obviously, any changes made to that element are already lost. You will need the view-uuid of the the deleted view. The describe subcommand will list any objects in a checked-out state in the VOB and give the uuid of the view that owned the checkout. Alternatively, if the missing view still has a tag and that tag name is known, the lsview -l command will also give you the UUID.
  # ct describe -long vob:vobtag
-or-
  # ct lsview -long viewtag

  # ct rmview -all -uuid view-uuid
There is another way that is a longer way to accomplish this, but requires that the view be a snapshot and that only the loaded files are gone (the vws directory still exists somewhere). If these conditions are true, run the following commands to uncheckout the elements. In fact, doing this will essentially recreate the view, but without any view-private files (including the checkouts) that were in the now missing view root. The following are the Windows version of the command set.

This will place the missing "view.dat" file in the view's vws directory.
  # ccperl ccase-home\etc\utils\regen_view_dot_dat.pl

Create a dummy directory somewhere and place the regenerated view.dat there.
  # mkdir C:\temp\tempview
  # copy vws-path\view.dat  C:\temp\tempview

Update the view and then perform the uncheckouts in the normal way.
  # cd \temp\tempview
  # ct update
Table of Contents



Merge elements.
Updated: 09/19/06
Note: binary elements can be merged, sort of. If an element is of a type, such as "file" or "compressed_file", that cannot be diffed nor merged like an ASCII file, the "from" version will simply overwrite the destination version. However, that's only true if it's a trivial merge. If both versions have changed since the base contributor, the operation will complain that the files cannot be merged automatically. If given the option, skip the file and merge manually later. That is, don't try to merge binary files. Complete the merge by skipping those types of files. Then, checkout the binary in the destination view and copy the "from" version over the top of the checkedout version. If desired, an element type can be created using the "-mergetype never" option that states that these files are never to be merged, which makes the merge operation smoother, knowing that you're going to merge those files manually later.
However, new in CC 7.0, an element type can be created with "-mergetype copy", but it only works for UCM deliver and rebase merges.

Findmerge
The findmerge subcommand can be used to just look for files that may need merging. If it finds any, it will create a file in the local directory called findmerge.log.date. The contents of which will be the correct command(s) to use if merging is desired.
NOTE: If the commands in the findmerge.log.date-time file are used to perform the merge, because the versions to be merged are listed explicitly, another search will not be performed even though the commands are written as "findmerge".
  # ct findmerge element -fversion version -print
ex: ct findmerge word.doc -fversion /main/working_branch/LATEST -print
Some useful options:
-fta.g view-tag Look at the version selected by another view.
-fve.rsion version-selector To select a version marked by a tag.
-fla.test Select the LATEST version on the current branch. Useful if the checkedout version was checked out unreserved.
-fcs.ets activities (UCM only) Consider versions in the listed activities.

Merge If the versions to merged are known, the merge command can be used explicitly. For both types, the element "from" version is that selected by your view.
  # ct merge -to element -version version(s)
Some useful options:
------  
-query Start merge automatically and query to resolve conflicts.
-abo.rt Start merge automatically. Abort and roll-back if conflicts arise.
-qal.l Query on every merge.
------  
-nda.ta Create merge hyperlink, but don't actually merge.
-nar.rows Do merge without creating the merge arrow.
------  
-g.raphical Perform merge graphically. Merge result is editable on the fly.
------  
-out view-private-file Merge to a file other than the "to" version. No merge arrow recorded.
-opt.ions   "pass-through-options" Merge can pass through options, such as -blank_ignore, to the merge tool See cleardiff for a list.
See below on how to do selective and subtractive merges. If interested in customizing the GUI, see the man page or CC Ref Manual page cc.icon for matching file types to bitmaps.
In UNIX, merges can also be initiated by selecting an element in xclearcase, going to its Vtree Browser and then clicking on the Merge button (second from right in CC 3.2.1) or by going to the Version -> Merge menu.
In Windows, merges can also be initiated by right-clicking on an element in the Version Tree Browser and selecting "Merge to...". When the target cursor appears, click on the "to" version. If similar merges are to be done regularly, time can be saved by setting up a Merge Manager session. The Merge Manager can be started via ClearCase Home Base -> Branches. Once the "findmerge" is complete, File -> Save As... the session. Next time you start Merge Manager, simply Merge -> Refresh Elements List, or hit F5.

Merge types:
Trivial - Nothing at all happened to one contributor.
Automatic - Only one contributor has changed for any given chunk of text.
Non-automatic - Cannot resolve conflict without human intervention.

Some shops choose to disallow automatic merges, because while the merge algorithm is very sophisticated, it isn't infallible.
Merging does not end a branch and can be in either direction. To "undo" a merge, simply uncheckout the "to" version. Therefor, it is always a good idea to test the merge results before checking in. A successful merge will leave a view-private file in the current directory called element.contrib. Checkin is not performed automatically and there is no .contrib file for directory merges. If it was a directory merge, check the directory in immediately so that only changes due to the merge are part of the changes to that directory version.

WARNING!   If doing a directory merge and separate branches have files of the same name but are actually different elements, the merge will rename the -from version to element.uuid.

Merges can be done in a selective or subtractive manner. These type merges can only be done from the command-line (with the exception of a single version selective merge) and merge arrows are not recorded, as a merge arrow implies a cumulative merge. Examples:

Select a single version.
  # ct merge -to element -insert -version version-selector
ex: ct merge -to foo.c -insert -version /main/bug_fix2/4
Select a range of versions.
  # ct merge -to element -insert -version from-version-selector to-version-selector
ex: ct merge -to foo.c -insert -version /main/bug_fix2/2 /main/bug_fix2/6
  If you want the range from versions 2 to 6, but not version 3, you must do two merges.
Exclude a single version.
  # ct merge -to element -delete -version version-selector
ex: ct merge -to foo.c -delete -version /main/bug_fix2/4
Exclude a range of versions.
  # ct merge -to element -delete -version from-version-selector to-version-selector
ex: ct merge -to foo.c -delete -version /main/bug_fix2/2 /main/bug_fix2/6
To determine the changes that took place for any given merge destination, use the annotate command. It writes a view-private file called element.ann.
  # ct annotate element

Merge Manager
CC Windows has a GUI called the Merge Manager that will conduct a findmerge type operation. As of CC 5.0/2002, clearmrgman is available from the CLI on both UNIX and Windows. It can be used for UCM deliver and rebase as well as base CC merges. It will start the Merge Manager GUI.
  # clearmrgman options
The base CC clearmrgman has many of the same options as "merge" and "findmerge".
-del.iver   [ -to target-view-tag | -tar.get stream-selector ] Deliver to the specified view or stream.
-reb.ase   -str.eam stream-selector Rebase the specified stream.

XML merge
New in CC 5.0/2002, xmldiffmrg facilitates the comparing and merging of XML elements.
  # xmldiffmrg operation
Options:
-xvi.ew | -xco.mpare | -xme.rge Must specify an operation for xmldiffmrg to perform.
-visible_blank White-space characters are made visible by alternate glyphs representing the white space.
-blank_ignore Ignores white-space in white-space-only nodes. Can be used with -visible_blank.
-hst.ack Stack the panes horizontally. (default)
-vst.ack Stack the panes vertically.
-out   filename Specify an output file for the merge result.
-to   to-version Specify the version extended file that is both a contributor and merge result.
-q.uery Prompts you to proceed with every change. Changes in the to-version are still automatically accepted.
-abo.rt Merge only if completely automatic.
-qal.l Query the user for every change including those in the to-version.
-enc.oding   { utf-16 | utf-8 | iso-8859-1 | ascii } If an output file is generated, use the specified encoding type.
-bas.e   version-selector Specify a base selector other than the one that would have been chosen automatically.

Table of Contents





Change an element's type.
The element type to which it is being changing must already exist.
  # ct lstype -eltype
  # ct chtype -nc new-element-type element
This command can take awhile. For intsance, if you change from text_file to compressed_text_file and you have many text files, the system will immediately go through and compress all the data containers. Conversely, if changing from a type, such as text_file, to a user-defined type based on the supertype text_file, the command will complete instantly.

Table of Contents





Move an element between VOBs.
This includes entire directory trees as well. Do not use this to move elements within a VOB; use "ct mv" instead. You cannot move UCM elements between VOBs.
  # ct relocate element(s) /target_vob-tag/path
Options:
-f.orce Suppress the default confirmation step.
-quall Ask for confirmation for every relocated borderline element (such as linked elements).
-upd.ate Run in update mode. Does not remove originals.
-log   logfile Record the transaction in a file other than the default relocate.log.date-time

*** Must be VOB owner or root of both VOBs.
*** Relocate will do the checkout of the target directory for you. However, you will get an error if the destination directory is already checked out to another view.
*** The ownership and permissions do not change during relocate, regardless of the username and umask of the user executing the relocate.
*** This command will not overwrite existing elements of the same name in the target VOB; you will get the error "already exists in the target-dir". If you want to create new versions of the target elements and/or leave the original elements in the original VOB, use the -update option.
*** If there is a collision with Metadata, relocate will rename the new Metadata type with a numbered extension. For example, if the label type BUG_FIX_1 already exists in the target VOB, the newly transferred label type will get named BUG_FIX_1.1, which may cause confusion.
*** Disable any triggers from both VOBs that might impede the checkout/in of the elements.
*** Ensure the elements to be relocated are not locked.
*** The relocate command does not handle view-private files. Of the three types: a) ensure all elements are checkedin (from any view) otherwise relocate will fail, b) generic view-private files need to be moved or removed and c) DOs are quietly deleted (unless they are versioned). Search for view-private files in every view via:
  # ct lsprivate -tag view-tag -invob /vob-tag/path
If view-private files become stranded during the relocate, they can be recovered. The recovered view-private files are placed in the view's lost+found directory in the view-storage area .s subdirectory. A view's lost+found directory doesn't exist until it's needed.
  # ct recoverview -synchronize view-tag -vob vob-tag
*** Relocate has the following affect on symbolic links. The "in" and "out" refer to whether an end of a link is in or out of the relocate selection set. View-private UNIX links are simply ignored. Any UNIX links pointing into the selection set will now be invalid. Any UNIX links pointing out of the selection set will be lost.
Link type original/linked-end notes
hard in/in The hardlink will be recreated as expected.
hard in/out The hardlink will be split, one data-container in each VOB. Each element will still point to each other via a new HyperSlink hyperlink.
soft in/in The softlink will be recreated as expected.
soft in/out The data-container is moved. The end in the original VOB now points to the wrong place.
soft out/in The data-container is not moved. The end in the new VOB now points to the wrong place.
*** Relocate will fail if the original VOB is attached to an AdminVOB in which Metadata types are locked.
*** Relocate will fail if the original VOB's types are CCMS mastered elsewhere. If the relocated elements are to be replicated as well, the target VOB will have to be created manually at the other site(s). If the relocated elements are NOT to be replicated, when the relocate command is complete, delete the RelocationVOB hyperlink from the originial VOB. It will also fail if the target VOB is a replica whose main branch type is mastered elsewhere.
*** If a relocate command aborts for some reason and you never get around to actually completing the relocate, the original VOB will still have a RelocationVOB hyperlink erroneously attached to it.
*** Relocate can be stopped and restarted, provided that you: DO NOT release the locks set automatically by the relocate command, DO NOT modify elements in the relocation set, and DO NOT record your answers to -quall the first time through. The final phase, removing elements from the original VOB, is not restartable.
*** Relocate can be run in an update mode (-update). Update mode does not lock the originals, does not remove the originals, does not create a symbolic link from the originals, will relocate non-locally mastered elements and does not checkout or modify the source directory. Also, update mode will not update the copies if objects have been removed from the original since the last update; I.E. rmver, rmbranch, rmelem. Update only creates objects, it does not remove them. If the removal on the original was actually a replacement, update will fail. For instance, if a branch is removed from the original and then rebranched from a different point, the relocate will fail to create the new branch because the old one still exists on the destination element. To get around this, simply remove the destination element in entirety and let relocate recreate it. One cannot switch from using update mode to a regular relocate. If after running updates one wants to now totally move the elements, delete the destination elements and run relocate as if for the first time. Finally, one cannot make changes to the desintation elements until you've stopped using the originals.
*** The relocate command will remove the originals if not run in update mode. It will create a soft symbolic link from the original to the new VOB to preserve the namespace in the original VOB.
*** The relocate command will preserve the relationship of bi-directional hyperlinks. It will not update uni-directional hyperlinks whose target is inside the selection set. It will update uni-directional hyperlinks that originate inside the selection set.

MultiSite
*** Running relocate in a CCMS environment takes a few more steps than just relocating the elements. The following is an un-tested set of steps that would most likely need to occur to preserve mastership across the relocate. The mastership of elements is irrelevant. The mastership of metadata can probably be cleaned up later on an as needed basis, but could be included in the scripts mentioned below if desired. The most important part of mastership that needs to be transferred is branch mastership.
1) Have all remote sites send out last minute, manual sync packets and then have them lock the VOB to be split.
2) At the local site, after importing any last minute sync packets, run a script that makes a list of the masterships of all branch types and branch instances throughout the directory tree to be relocated.
3) At the local site, create a new empty VOB and run the relocate in the normal way.
4) Create replicas of the new VOB for all sites involved.
5) At the local site, run a script that resets the masterships to the way they used to be.
6) At the local site, generate sync packets that contain the changes.
6) Send the replicas and sync packets of both the old and new VOBs to all sites.
7) Have all remote admins import the new replica VOB, unlock their old VOBs and perform a manual import of the sync packets for both VOBs.

Table of Contents





Diff two text elements.
In UNIX xclearcase, hightlight an element and go to Versions -> Diff.
In Windows you can run a graphical compare by right-clicking on an element and choosing either "Compare with Previous Version" or "Compare...".
From the CLI: ct diff
The diff subcommand can diff between text or directory elements in the same view or in different views. The following are a few of the permutations. See the CC Reference Manual for a full listing.
  # ct diff element element@@/main/branch/LATEST
  # ct diff -predecessor element
  # ct diff -graphical element /view/view-tag/element
Note that diff can only be used in a VOB context.

cleardiff
A cleardiff will give the same output as a simple diff command, but it has more formatting options. It cannot diff directory elements and does not have a -graphical option. The two files being diff'ed do not have to be in CC.

  # cleardiff element-version1 element-version2
xcleardiff
The UNIX only, stand-alone command xcleardiff utilizes xcompare and xmerge. It can be invoked by itself or via a "diff -graphical", "merge -graphical" or "findmerge -graphical". The font and colors can be customized. See "schemes" in the CC Reference Manual.
  # xcleardiff element-version1 element-version2
Some useful options:
-b.lank_ignore (diff) Do not display differences in blank lines when diff'ing.
-col.umns   n Divide n by 2. Default n is 80; 40 chars per column.
-tin.y (diff or merge) Use smaller fonts.
-vst.ack (diff or merge) Display the diff'ed files stacked vertically (default is horizontal).
-out (merge) Specify a checkedout version or system file (required).
-f.orce (merge) Overwrite the output file, if it already exists.
-bas.e   base-pname (merge) By default, xcleardiff does not calculate a base contributor.
-q.uery (merge) No automatic merging for non-trivial merges.
-qal.l (merge) No automatic merging at all. Automatically set if base not specified.
-abo.rt (merge) Abort if conflict arises. Used when called from a script.
-pause (merge) Do automatic merges, but pause for confirmation after each change.
-win.dow New in CC 2003.06.00. Disply the output in a separate difference window.

See also cleardlg on Windows.

Table of Contents





Remove a merge arrow from an element's version tree.
The following subcommand will remove the merge arrow that appears in an element's version tree. It does not affect either version of the element that was merged.
  # ct rmmerge from-version to-version
Table of Contents



Remove a version of an element.
Updated: 11/17/11
The rmver command destroys information irretrievably. It cannot remove a previous version of a file that is currently checked out, nor can it remove an interesting version: labeled, branch point, merge point, etc...; unless the appropriate option is used.
If the element uses an element type such as "File" that has a separate container for each version, the rmver command will physically delete that container from the VOB. However, if the element is using a type that relies on z_text_file_delta or text_file_delta, the version removal is only logical. That is, the information in the removed version still exists in the data container in the VOB. This can be an issue if the version was removed, say, to comply with export restrictions on the VOB.
Delete uninteresting versions.
  # ct rmver element-name
Delete a specific version.
  # ct rmver -version /main/bugfix/5 element-name
Other useful options:
-f.orce don't ask for confirmation
-xbr.anch remove even if branch point, all version on the branch are removed also
-xla.bel remove even if labelled
-xat.tr remove even if attribute attached -xhl.ink remove even if hyperlink attached
-dat.a only delete the data container leaving the database intact, explicitly invokes the above listed -x options
-vra.nge specify a range of versions
NOTE: The rmver subcommand does not actually recover disk space, but merely marks that version as removed. This is not true for whole copy types though. History information is removed in both cases.

Table of Contents





Create a directory element.
Updated: 10/08/12
Version: 7.1.2
In Windows, right-click on the parent directory and choose Open. Use File -> New -> Folder to create a view-private directory. Then right-click on the new directory and "Add to Source Control...".
In xclearcase, click on the Shell button and use the command-line.
On the CLI, simply use the CC equivalent of the UNIX mkdir command. The directory will be created in a checkedout state unless the   -nco   option is used.
 	# ct mkdir directory-element
or
 	# ct mkelem -eltype directory directory-element
or CAL
	$checkedout_o = $CC->CreateElement("$directory_path","Auto-created folder","1","directory");
For each method, the parent directory must be checked-out first. Unlike UNIX, there is no associated "rmdir" command. Must use the rmelem to delete a directory element. Any contents of a deleted directory element will end up in the lost+found directory.
Options:
-master New in CC 2003.06.00. The replica in which element is created will explicitly master the main branch.

NOTE: Creating a directory element from an existing view-private directory only works in a Windows GUI. I.E. You will get the following error message from the CLI: Can't create directory element because ... already exists. If you need to create a directory element from the command-line and it already exists as a view-private directory or is out in the system somewhere, use the clearexport_ffile and clearimport commands. See "Import large amounts of data" for more information on that process.

Table of Contents





List details about the contents of an element version.
Output is written to a view-private file element.ann.
  # ct annotate -long -ndata element
Some useful options:
-nda.ta Use when dealing with element types other than text.
-nhe.ader Suppress the header and output only annotated text lines.
-out Use to send output to a file other than element.ann. Use a dash "-" as the output filename to send to standard out.
-rm Show deleted lines.
-a.ll Show changes no matter what branch. That is, changes made to branches that don't affect the current version.
-fmt   format-string Format the output. See fmt_ccase in the CC Reference Manual.
-rmf.mt   rm-format-string New in CC 2003.06.00. Specify a format for deletion annotations. The default format is "DEL %Sd %-8.8u | ".

Table of Contents





Checkout an element.
Updated: 01/06/12
Version: 7.0.1.8
In Windows, right-click on the file.
In xclearcase, left-click on the file to highlight it then go to the Versions menu.
CAL: If the "file" path is passed to the call to Version, it will use the version selected by the current view. The "0" parameter means check it out reserved. See the CAL documentation for many parameters that can be used with Checkin.
	$version_o	= $CC->Version("$file_path");
	$checkedout_o	= $version_o->Checkout(0);
	$checkedout_o->Checkin;
From the CLI checkout can be abbreviated to co. This will checkout the version of the element selected by the current view.
  # ct co element
Checkouts are recorded both in the view and VOB databases.
Some options:
-ver.sion Checkout a specific version not necessarily selected by the current view.
-bra.nch branch Checkout the LATEST version on the specified branch.
-out file Checkout an element under a different name.
-unr.eserved Checkout an element allowing others to check it out also.
-unr.eserved   -nma.ster Checkout even if the local site doesn't master the branch.

WARNING!   When merging in the changes from the checkout from a previous version, the Merge hyperlink will erroneously point to the version just prior to LATEST.

NOTE: A single view can have only one checked out version of an element at a time. Files can only be checked out if you have write permission to the view's storage directory. At most, there can be only one reserved checkout of an element.

WARNING!   While only the checkout owner can check an element back in, if two users are using the same view, they can modify any element checked out to that view (file permissions permitting).

  # ct co -nc -unreserved element
  # ct co -version element@@/main/version
  # ct co -branch /main/bug_fixes element
  # ct co -out element_test element
Files are normally checked out reserved. That is, only the person who checks it out can check it back in. The element can also be checked out unreserved, which means that someone else can check it out too. However, if more than one person has it checked out unreserved, only one person can check it back in and create a successor version. However, any unreserved checkout can be checked in via a merge.
If checking out a derived object, CC will attempt to perform a winkin to your view. If the winkin fails, for various reasons, it will just copy it in as a local view-private file. Permissions on the checkedout file are determined by the following:
1) Start with the permissions on the element itself.
2) Add write permission wherever the element has read permission.
3) Subtract read, write and/or execute based on your personal umask.
Permissions on a checkedout file can be changed at will. However, only use the ct protect command to change permissions on a checked in element or derived object.

See also cleardlg on Windows.

Table of Contents





Checkin an element.
In Windows, right-click on the file.
In xclearcase, left-click on the file to highlight it, then go to the Versions menu. On the command-line, checkout can be abbreviated to ci.
From the CLI:
  # ct ci element
Common options:
-nc No checkin comment. If checkout comment exists, it uses that.
-ide.ntical Checkin even identical to predecessor. (not available in xclearcase)
-kee.p Keep a view-private file called element.keep as well as the checkedin version.
  This is automatically prompted for each Windows checkin. Not applicable to directories.
-fro.m Use the specified file as the checkin version instead of the view-private file.
  The option -keep is invoked.
-ptime Preserve the modification date/time. This is important if the file date outside CC denotes version.
If the predecessor of the version checked out is not the LATEST version on the branch, CC will not let you check it back in. This can happen if the checkout was unreserved or the   -version   option was used. If this happens and you don't want to do an uncheckout, you will need to merge with the LATEST. For that, make the LATEST version the "from" version and merge it to your checked out version. Then a checkin should be possible.
If the element is "[checkedout but removed]", it means the checkedout version is missing for some reason. Use an uncheckout if the checkedout version cannot be located.

See also cleardlg on Windows.

Table of Contents





Uncheckout an element.
In Windows, right-click on the element.
In xclearcase, left-lick on the element and go to the Versions menu.
From the CLI, uncheckout can be abbreviated as unco. Use the   -keep   option to keep a copy of the checkedout version. File checkouts are cancelled via the uncheckout command. This destroys the the checkedout view-private version and erases any record of the checkout. I.E. There is no such thing as an uncheckout event record. An element in another view can be unchecked out by using a view-extended pathname. However, if the other view's storage area isn't accessible, that won't work. Unfortunately there is no way to suppress the prompt for the saving of a private copy without using the -keep option with a subsequent removal of the .keep file.
  # ct unco element
UNIX
  # ct unco /view/view-tag/path/element
Windows
  # ct unco X:\vob-tag\path\element

WARNING!   If an element is unchecked out immediately after creation and you don't save a private copy when prompted, the file contents will be lost. CC creates the 0th version as an empty place holder. An unco of version 1 will result in an empty file. Note that the 0th version on branches will only be empty if the version from which they branched were also empty.

Table of Contents





List/find CHECKEDOUT elements.
Updated: 04/07/16
Version: 7.1.2.14

In Unix xclearcase, Report -> List checkouts.
In the Windows, right-click on any element and select Find Checkouts.
On both Unix and Windows, the GUI can be invoked from the CLI via clearfindco.

NOTE: There is no way to use the "ct find" command to find checkouts.
NOTE: There is no way to find checkouts for a view other than the current one.

From the CLI:
lsco
The lsco command must be run while already in a view context. That is, there's no way to specify the viewtag of another view, which makes it difficult to use in utility type scripts.
  # ct lsco [pname]
There are many options to control the scope; which elements and/or directories are searched for checkedout elements. The default is to search the current directory only for elements checkedout under any view.
If you want to find all checkouts NOT by me (exclusion). The following example will find all reserved checkouts from the main branch by a user other than "user1". The fmt option lists "reserved/unreserved,view-tag,user.group,element". The egrep command only works on Unix. Windows has a findstr command similar to grep, but no equivalent to egrep.
  # ct lsco -recurse -brtype main -fmt "%Rf %Tf %Lu %En\n" | egrep -v '(unreserved|user1)'

lsprivate
The lsprivate command can also be used to find checkouts. Use its -co option. The lsprivate command doesn't work in snapshot views. Also, it won't report on checkedout directories, as there is no view-private version of a checkedout directory. Also, it doesn't have the useful -avobs option that lsco does.

ls Another way to find checkouts is the "ct ls -view_only". But with this method there is no way to differentiate between checkouts and other types of view-private files.

NOTE: If you remove a load rule from a snapshot view, the files are normally completely removed from the view root. However, if there were any view-private files there, including checkouts, the unloaded files/directories will be officially unloaded from the view but not removed from the view-root. They will simply be renamed as "<element>.unloaded". If you run lsco in a snapshot view, the command will not find checkedout elements that have been unloaded.

Table of Contents





Find all elements with a given characteristic.
In UNIX xclearcase, Report -> Find query.
On Windows, the "find" command is only available on the command-line.
From the CLI:
Branches with a specified attibute with a specific value on one of its versions:
  # ct find . -branch 'attr_sub(attribute,operator,value)' -print
Elements with a specified label on one of its versions:
  # ct find . -element "lbtype_sub(label)" -print
The LATEST version on a specified branch:
  # ct find . -ver 'version(/branch-path/LATEST)' -print
Instead of using a dot "." to start the search in the current directory, a path, or list of paths can be supplied to the search directory(s), such as:
  # ct find /vobs/vob1 /vobs/vob2/src ...
Alternatively, you can have CC search all mounted VOBs by using "-avobs" instead of a search path. The "-avobs" option has the added benefit that it will find elements, etc.. even if your current view doesn't see them. See the warning below. Also, when running a find, if there are hardlinked elements, the find will report what is essentially the same element multiple times. If the "-avobs" option is used, the reported elements will be unique.
Find does not work on view-private files. Instead, use lsprivate.

WARNING!   Even though find will search through all versions of an element, the element itself must be visible to the current view. For example, if an element has a label that you are searcing for on one of its versions, but the element itself is not selected by your view (perhaps on a different branch of a directory), then find will not even begin to search that element. I.E. It will not find that particular version with that label.

Table of Contents





Modify element attributes en masse.
The example below will attach a trigger to all elements with a specified label at or below the current directory.
  # ct find . -ver "lbtype(label)" -exec 'cleartool mktrigger trigger $CLEARCASE_XPN'
For Windows, use "%CLEARCASE_XPN%" as the variable name.

Table of Contents





Refer to an element.
When inside a VOB, the elements will appear to be normal files when doing an ls (or dir). However, being that they are CC elements, they can be referenced several different ways. The @@ designation can be set to anything unique in the Windows ClearCase Home Base -> Administration -> Control Panel -> MVFS; though highly unrecommended.
The version selected by the current view:
  foo.c
The latest version on the main branch:
  foo.c@@/main/LATEST
The element itself (not any particular version):
  foo.c@@
A version other than the one selected by the current view:
  foo.c@@/main/2
A version on a branch not selected by the current view:
  foo.c@@/main/branch/3
The version selected by a different view:
  /view/view-tag/VOB-tag/foo.c  (UNIX)
  M:\view-tag\VOB-tag\foo.c     (Windows)
Table of Contents



Recursively checkin/uncheckout all checkouts.
If all the checkouts are to you in your current view, simply create the list of elements to be checked in using the lsco command. On Windows, it's easy to run "Find Checkouts" from any of the different GUI interfaces. From the CLI:
On Unix:
  # ct ci -nc -identical `ct lsco -s -r -me -cview`
On Windows:
  # FOR /F "%i" in (`cleartool lsco -s -r -me -cview`) DO cleartool ci -nc "%i"
However, if it is needed to checkin all elements by all users in any view, such as cleaning up the lost+found, two steps are necessary. For the following steps, one must be the VOB owner to have the ability to checkin another's checkouts. The following steps are written for UNIX on the CLI. However, the procedure is the same if writing a script (such as ccperl on Windows).
1) Change to the appropriate directory. Ensure the views involved are started.
  # ct startview `cleartool lsco -r -fmt "%Tf\n" | sort -u`
If a view comes up <no-tag-in-region>, other arrangements will have to be made.
2) Do the checkin en masse.
  # ct ci -nc -identical `cleartool lsco -r -fmt "/view/%Tf$PWD/%n\n"`
Table of Contents



Determine what pools are assigned to an element.
The describe must be run on the element itself, not on one of its versions; hence the @@ without a follow-on version.
  # ct describe element@@
Table of Contents



Assign different storage pools to an element.
Use the describe command on the element itself to determine current pools assigned. Use the lspool command to determine what pools are available. The chpool command is only available from the command-line on both UNIX & Windows.
  # ct chpool pool:pool-name element
A useful option when working in conjunction with a find command is -f; suppress the confirmation step.
  # ct find . -element 'pool(pool-name)' -exec 'cleartool chpool -f new-pool $CLEARCASE_PN'
For Windows, use %CLEARCASE_PN%.
Changing the cleartext pool will only affect the location of future cleartext versions. The old ones will be scrubbed from the old location in time. Changing the source pool immediately moves all data containers to the new location.
Directories have pool assignments as well, but only for inheritance purposes. That is, new file elements inherit their pool assignments from the directory in which they are created.
NOTE: Since file elements inherit their pool assignments simply from the directory in which they were created and not from their element type, one would need to write a trigger on mkelem that does an automatic chpool for all future elements.

Table of Contents





Change the checkout status to unreserved/reserved.
In UNIX xclearcase, Versions -> Change checkout.
In Windows CC Explorer, Tools -> Unreserve.
From the CLI:
  # ct unreserve element
 -or-
  # ct reserve element
This command might be used if you need access to someone else's checkedout element, but they aren't around to check it back in.
A useful option:
-view viewstore Specify a different view, if the other vws is available.
  # ct unreserve -view machine:vws-local-path element

ex: ct unreserve -view ntpt002:C:\ClearCase_Storage\views\yourview.vws file.doc
See also cleardlg on Windows.

Table of Contents





Create an element type.
Updated: 09/16/06
Though CC populates a new VOB with predefined element types based on predefined type managers, the VOB administrator can create new element types based on them. The type managers handle version storage and manipulation. While one could in theory write their own type manager, it is best just to base a new element type on a predefined "supertype" and use the type manager that came with CC. The following table gives the relationship between predefined element types and their type managers:
ELEMENT TYPE TYPE MANAGER
binary_delta_file binary_delta
compressed_file z_whole_copy
compressed_text_file z_text_file_delta
directory directory
file whole_copy
file_system_object no associated type manager
text_file text_file_delta
As an example, one might create a new element type to give a grouping to all shell script elements. Since shell scripts are simply ascii text, an appropriate supertype would be text_file or compressed_text_file. That way, even though shell elements have varied extensions such .ksh, .sh, .csh, etc.. they can all be found using a "find" command that looks for the new element type name.
In xclearcase, Admin -> Element -> Type -> Create...
In Windows Type Explorer, enter the "element type" folder and select Type -> Create...
From the CLI:
  # ct mkeltype -supertype supertype new-element-type
Options:
-rep.lace Change the parameters of an existing element type. Cannot change supertype parameters.
-glo.bal Allow this element type to be used by other VOBs.
-mer.getype   { auto | user | never | copy } This option is only active for UCM deliver and rebase merges. "auto" will attempt a merge (default), "user" will auto merge trivial only, and "never" means never merge this type at all. New in CC 7.0, for binaries, the "copy" argument will make a simple copy of the version and set the hyperlink as if there were a real merge. Note that the copy argument is not support in CCRC.
-pti.me By default, a version is give a new timestamp when it's checked in. This sets "checkin -ptime" for the elements of this type, which uses the timestamp currently on the view-private checkout as the checkin timestamp.

Table of Contents





Checkin all elements from all views.
The following is applicable to a UNIX CLI, but could be adapted to Windows via a ccperl script.
Using any view:
  # cd vob-tag    
  # csh
  # foreach view (`cleartool lsco -fmt '%Tf\n' -all | sort -u`)
  ? ct startview $view
  ? cd /view/$view/vob-tag
  ? ct ci -nc -identical `cleartool lsco -recurse -short -cview`
  ? end
In the Windows Perl script, one would use \\view\$view\vob-tag for view-extended naming or from the regedt32 GUI, HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Mvfs\Parameters.

Table of Contents





Find ALL elements in a VOB.
A normal find command will only search elements that are currently selected by your view. Even if the view has a default config_spec, there can be elements that exist only on branches that are not selected by your view. Those elements won't be searched even if they contain information for which you are looking. The following command will simply list all elements in a VOB, regardless of branches, if you run it in the root directory of the VOB.
  # ct find -all -print
Table of Contents



Create a symbolic link.
There are two types of symbolic links, hard and soft. Both are created with the same command.
Hardlinks create another pointer to an existing file element storage container in the VOB storage area. For example, if a file already exists as an official CC element, you can create a hardlink to it from another directory. The link's name in the other directory does not have to be the same. Note, however, that the hardlink just created is indistinguishable from the "original". Since both are pointers to exactly the same data container, any test you perform in an attempt to distinguish the two will produce the exact same answer. They are truly two names for the same element. A different way of thinking about it is that all element names in a VOB are hardlinks to their respective data containers in the VOB's storage area. Directories cannot be hardlinked. Cannot hardlink across VOBs.
NOTE: The only way to tell if an element is an alternative name (hardlink) for another element is to run the stand-alone "mvfsstorage" command on it. All elements in a VOB will give a different answer for that command. But the two that are hardlinks of each other will give the same answer. It's a bit of a reverse way of finding out, but it's the only way.

WARNING!   If an element has hardlinks elsewhere in a VOB and the element is checkedout, the view-private file will only be written to the directory where the checkout was actually performed, even though the other hardlink will report that the file is checkedout. In fact, a "ct ls" in the other directory will report [checkedout but removed]. This can be a problem if the element is checkedout but both element names need to be there at the same time, such as for a build.

Softlinks are simply pointers to another element's name and not an alternative pointer to the actual data container. As such, you can access the data the softlink points to, but you cannot perform any element modifications on the softlink end, such as checkout, chmod, etc... Directories can be softlinked together. Softlinks can cross VOBs. In fact, this is how one makes many small VOBs (for performance reasons) look like one big VOB (for ease of use).
NOTE: Solaris has the quirk that if you traverse (cd) a softlink to get to another directory and then immediately do a (cd ..) to go back up one level, you find that you did not go back to where you started, but are now above the other end (where softlinked pointed to). If you cd to a directory on HP or Windows that is actually a softlink and then immediately "cd ..", you will return from whence you came.
NOTE: Windows will not show a CC softlink in the Windows Explorer or DOS prompt if the softlink points to a non-existent element. A "ct ls" or the CC Explorer will show the defunct link as it really exists.

New in CC 5.0/2002, symbolic links can be created from the Windows CC Explorer shortcut menu.
From the CLI:
  # ct ln [-soft] path\original link-name
NOTE: When creating CC symbolic links, it's wise to make the paths relative. If the path is made absolute (starts with a slash), it's very difficult to move directories or VOBs around later.

Table of Contents





Retrieve element versions not loaded in a snapshot view.
In a snapshot view, one has the ability to get a copy of versions of elements that are not seen by the view either because there is no load rule for them or the config_spec selects a different version. The following command will copy the designated element version into the view as a view-private file. There is no GUI equivalent for this command.
  # ct get -to view-private-name element-version

ex:
  # ct get -to foo.c.temp foo.c@@\main\otherbranch\LATEST

Table of Contents





Restore a single element from backup.
If an element is inadvertantly deleted (rmelem), the single element can be restored from a backup tape. The following procedure is convoluted because a VOB with same UUID and replica name cannot be mounted on the same system at the same time.
To restore a single element. The following procedure doesn't require the original VOB to be offline at any time. 1) Set up another machine as its own registry server. 2) Restore the VOB backup to that alternate machine, including register and mktag. 3) Create a new, temporary VOB on the alternate machine. 4) Use "ct relocate" to move the element from the restored VOB to the temporary VOB. 5) Register and create a tag for the temporary VOB on the primary registry server. 6) Relocate the restored element from the temporary VOB to its final destination. 7) Rmvob the temporary VOB and the restored VOB.

As of CC 2003, UCM elements cannot be restored individually. The entire PVOB and ALL associated components must be restored to the state when the element last existed.
However, if it's impractical to restore the entire PVOB and all components, the internal contents of a file element can still be recovered. In a stream in the "live" VOB, simply create a new element. Restore the PVOB and components to a separate server. Create a view on that other server for the stream in which the removed element last appeared. With those restored VOBs and the new view, you can read the contents of the file element. Simply copy the contents into (on top of) the element now checkedout in the "live" VOB.

Table of Contents





Recover a previous version of an element.
The restoration of a previous version of a directory or file element implies a merge forward along the same branch.
If a rmname is performed on an element, it can no longer be seen in any subsequent versions of that directory, or if a file element is modified and a previous version needs to be restored, a merge forward along the same branch can be performed. In both the GUI and CLI procedures, ensure you use a view that selects the LATEST version on the designated branch.
In a Windows GUI environment, open the parent directory's Version Tree Browser. Select the version along that branch that last catalogued the element to be recoved. Select "Merge to" and select the LATEST version on that branch. Perform the merge graphically. In the merge tool, ensure the element to be brought forward shows up in the merge result pane. Close the window, save the results, inspect the LATEST version on the branch and check it in if all is ok.
This cannot be accomplished in a Unix GUI.
From the CLI, perform the lsvtree so that it's easy to cut and paste the needed version.
  # cd directory

Recover an element removed with rmname:

  # ct lsvtree .
  # ct co -nc .
  # ct merge -to . -graphical -ver older-version-of-the-directory

Ex: ct merge -to . -graphical -ver \main\eostrand_project2_dev\1


Recover an older file element version:

  # ct lsvtree file
  # ct co -nc file
  # ct merge -to file -graphical -ver older-version-of-the-file

Ex: ct merge -to links.cpp -graphical -ver /main/mybranch/10


In either case, ensure all is ok after the merge before checking anything back in.

In the CLI cases, the -graphical option was used so that you could inspect and choose what information is to be recovered. To simply have the older version overwrite the LATEST version, use the -base option. The -base option needs an argument that is a version-extended name. In this case, since you want the older version to overwrite the LATEST version, set the -base version-extended argument to be the same as the LATEST version. This will trick CC into thinking the only changes to be merged are from the older version. Extending the file element example above, the -base might look like the following. If desired, the -graphical option can be used as well. See the merge man page for more info on the -base option.

  # ct merge -to links.cpp -base links.cpp@@/main/mybranch/LATEST -ver /main/mybranch/10

Table of Contents



Find symbolic links.
While a "find" command can find symbolic links there are no query language options that can isolate certain ones, such as lbtype(REL1) would isolate just the REL1 labels. A -name option can help though.
  # ct find . -type l -print
Table of Contents



Find the LATEST version.
The following command will find the LATEST version on the specified branch.
  # ct find . -version 'version(/branch-path/LATEST)' -print
Table of Contents



Remove elements from the lost+found directory.
1) Do a recursive search for checkouts by anyone is any view and uncheckout them.
2) These next steps are looped, so could probably be put in a script.
2a) Do a rmname on everything in the top directory. If the name actually disappears, it means that it probably was a hard-link and has a real sibling elsewhere, which means you didn't want to rmelem it.
2b) Once the rmname is complete, run a rmelem on everything in the top directory of the lost+found. If there are directories there, new elements will surface.
Repeat (2a) and (2b) until the lost+found is empty.

Table of Contents





Unreserve a snapshot checkout even if the loaded files are offline.
One has the ability to toggle the reserved/unreserved status of a checkout. To do so requires the view-storage directory to be accessible for both dynamic and snapshot views. However, if the loaded files of a snapshot view aren't accessible (offline), the unreserve command will fail even if the view-storage is accessible.
However, in an unsupported manuever, you can fake the system long enough to change the checkout status. If the loaded files belonging to a snapshot view are ever inadvertently deleted, the loaded files directory can be restored by running the supported cc-home/etc/utils/regen_view_dot_dat.pl tool. Simply run that tool in a directory. The system will now be faked into thinking the loaded files are still online so that the unreserve command will pass. Be sure to remove the ersatz loaded directory when done.

Table of Contents





Find all elements that have a particular branch.
One way to this is to use to construct your own find command.
  # ct find path -element "brtype(branch-name)" -print
This can also be done via the CC Report Builder, which produces a much nicer output, that can be saved in html or xml format for a slick looking report. Note that independent of which method you choose, the element search is dependent on the view you're in. Some elements may not be visible in every view.

Table of Contents





Determine an element's name given its data container.
All file elements live in data containers in the VOB's source pool(s). A typical path (on Unix) might be "/net/niobium/usr2/vobstorage/cag.vbs/s/sdft/38/23/0-6ba0a5418ad411d78a8a000180c4d544-4p". Run the following command to find the element name associated with a particular data container.
  # ct dump oid:OID
Example (note that the info before and after the dashes is omitted):
  # ct dump oid:6ba0a5418ad411d78a8a000180c4d544
Table of Contents



Recursively checkout all elements in a tree.

From the CLI:
On Unix:   
  # ct find . -exec 'cleartool co -nc $CLEARCASE_PN' 
On Windows:
  # ct find . -exec "cleartool co -nc \"%CLEARCASE_PN%\""
From a Windows GUI:
1) In Windows Explorer, navigate to the folder where the desired elements are located.
2) Right click the directory and choose Search.
3) When prompted, type * as the file name and click Search.
4) Select all files and directories in the list.
5) Right click and choose ClearCase->Check Out. Be sure to select "Apply to All".

Table of Contents





Preserve the modification time during mkelem or checkin.
When a file is placed under source control, or checkedin, the modification time recorded on the file is the time when the checkin is done. However, it's possible to force CC to use the modification time already on the file when checking it in or adding it to source control. This is useful for things like dll's where the version of the dll is known by its modification date/time.
In Windows, to permanently set this behaviour, go to the CC Explorer under Tools->Options->ClearCase Options.
From the CLI, use the -ptime option during checkin or mkelem.

Table of Contents





Recursively import large numbers of elements.
Updated: 06/16/11
The following simple example imports an entire source tree to populate an existing new CC VOB. The commands are located in atria-home\bin on Windows and /usr/atria/bin on UNIX. The   -r   option tells clearexport to descend subdirectories recursively.
NOTE: The clearexport_ccase command will not export view-private files. If there are view-private files present, they will each generate an error message. Simply ignore the message, as it will not hurt the export.
  # cd top-of-source-tree
  # clearexport_type  (see below for types)
Some useful options:
-r Run clearexport recursively.
-o   filename Send the output to file other than the default cvt_data.
-b   branch-name Clearimport will place import elements on the branch; to avoid directory branching, have them checkedout first; clearimport will create the branch-name type.
-b   branch   -v   version Have the branch sprout from a version other than /main/LATEST.
The following are the clearexport_* types supported by CC. See the "ClearCase Reference Manual" for clearexport options specific to the types:
ccase ClearCase
cvs Concurrent Versioning System (new in CC 4.1)
dsee Domain Software Engineering Environment
ffile Flat files (single file or entire directory tree, also see clearfsimport below)
pvcs Professional Version Control System
rcs Revision Control System
sccs Source Code Control System
ssafe SourceSafe (Windows only)

WARNING!   A clearexport_* will only create a cvt_data file with information about the layout of the originals. That is, the cvt_data file is a mere pointer to the originals. DO NOT CHANGE the path or contents of the originals from which the cvt_data file was built or the CC element created with that name will be empty. The cvt_data file can be moved from its original creation location as long as the path, ExportFromDir (at the top of the cvt_data file), is still valid from the new location. If the path is not valid from the clearimport location, it's ok to edit the ExportFromDir path so that it is valid. For example, on Windows, if the export was done on one machine, the path might be written as C:\mystuff. If the import is to be done on a separate machine, turn the directory called "mystuff" into a share and mount it on the remote machine. Copy the cvt_data file to the import location and modify the ExportFromDir line to be a UNC path; in this case \\machine\mystuff. Note that doing the opposite way won't work. That is, if you copy the cvt_data file to the import location and run the import as "clearimport \\machine\mystuff", it will fail because the path listed in the cvt_data file still says C:\mystuff, which is an invalid path from the remote machine.

This all implies that you have some sort of direct electronic connection between the exported data and the VOB. That is, you cannot run clearexport on one system, ftp the cvt_data over to another system and run clearimport. The clearimport command has to be able to see the originals to work correctly.

Clearimport ignores any -mkbranch rule modifiers in the config_spec. Because clearimport will import data onto, at most, one branch deep (using -b), use clearfsimport (CC 4.2+).
If not intending to import onto branches, ensure the view you set uses a default config spec. Use the catcs subcommand to determine if this is true. Start a view and mount the destination VOB.
Cannot run clearexport and clearimport on different architectures. That is, if the clearexport was done on Windows, the clearimport must be done on Windows as well, even if the VOB actually lives on a UNIX server. Use mounted drives in that case.
NOTE: If running clearexport_ccase to copy data from one VOB to another, note that it doesn't copy over any directory history. All file element history is copied, including MD, but only the directory version currently selected by your view is taken.
  # cd target-vob
  # ct catcs
  # clearimport -verbose /path/cvt_data
Notes on clearexport/clearimport:
- clearimport needs to be done by the VOB owner or an admin unless   -nsetevent   is used.
- However, if the   -nsetevent   option is used, there can be no restart.
- If clearimport is done on an Windows, be sure to use the   -pcase   option to preserve case.
- CC will handle the checkout of the import VOB's directory automatically.
- Any elements created will be in a checked-in state when complete.
- clearimport will not overwrite existing files of the same name.
- The clearexport/clearimport pair doesn't work in UCM, use clearfsimport instead. - Beware, it will do an uncheckout if the file exists and is checkedout in the target VOB.
- If an error occurs, fix the problem and simply invoke clearimport again.
- While clearexport_ccase will export all versions on all branches of a file element, it will only export the directory version currently selected by your view.
- CC handles symbolic links in differnet ways when running a clearimport from a clearexport_ccase. The "in" and "out" refer to whether one or the other end of the link was in the set being exported. Because clearexport does not work on view-private files, simple UNIX symbolic links are bypassed with a Warning.
Link type original/linked-end notes
hard in/in The link is split. Two independent elements are created in the new VOB.
hard in/out Both VOBs now contain a data-container each.
soft in/in The link is recreated as expected.
soft in/out The new object now has its own data-container. The old link is still intact.
soft out/in The new object is an invalid link. The old link is still intact.

New in CC 4.2, one can use clearfsimport as an alternative to clearexport_ffile/clearimport. This command will work in a UCM environment, where as clearexport/import does not. It is a one-step process and supports many new options. You must be root (UNIX), have Administrative privileges (Windows) or be VOB owner unless the   -nsetevent option is used. If it encounters a lock during import, it will wait 60 seconds before retrying until it succeeds. Simply unlock the offending object and wait for it to continue on its own. Unlike clearimport, this import is view-context sensitive. That is, clearfsimport supports any branching strategy in your config_spec.
  # clearfsimport   source   target-VOB-directory

ex: clearfsimport   -recurse   -mklabel INITIAL_IMPORT   *   M:\myview\myvob
NOTE: On Windows, if a file or directory that is to be imported by simply stating "*" contains any spaces, those files/directories will need to be imported explicitly. The star will be expanded and those files/directories will have their names misread by clearfsimport. Enclose their names in single-quotes. And no, placing single-quotes around the star doesn't work.
However, in CC 7.1.2, I've seen it throw the error about "Pathname not found" and yet do the import correctly ... go figure.
NOTE: The clearfsimport command doesn't work in a CCRC (web) view. However, CCRC does have a "recursive" mode. Simply copy the directory tree into the VOB as view-private files, then right-click on the parent directory and Add To Source Control. Click the Show Details button and select "Include descendant artifacts ...".

Some useful options:
-preview Only report what would have be imported.
-follow Process the object to which a UNIX (only) link points and not the link itself.
-recurse Recursively descend the source directory.
-rmname Performs a rmname on VOB elements not in the source tree.
-mklabel   label Attaches the specified label to each new version. Will create the label type if needed.
-nsetevent For newly created elements, record the user and current time instead of using information from the original.
-identical Create a new version even if there are no changes.
-master In CCMS, assign explicit mastership of the main branch to the local replica.
-unco If the target element is checkedout, perform an uncheckout first. Automatically generates a .keep file.
-downcase Convert to lowercase all newly imported files (Windows only).

Table of Contents





Force the merge tool to appear even if a merge isn't necessary.
If a merge or findmerge is conducted on a "to" version that is a direct decendent of the "from" version, CC will tell you that a merge isn't necessary. However, you may desire the merge tool to appear so that you can, say, recover some lines that were deleted.
You need to fool CC into making the merge tool appear. To do this you need to reset what it thinks the "base" contributor is. That is, you can't let it automatically pick the base contributor. The base contributor is the last version in the tree where the two versions (contributors) being merged diverged from each other. In this scenario, one version is a direct decendent of the other, so the base contributor is, by definition, the "from" version. Resetting the base contributor can only be done with the "merge" command. The findmerge command doesn't have that capability.
As an example, say that you want to recover lines from the LATEST version of file.cpp on the integration branch and restore them to the LATEST version on your current branch, called "mybranch". The following command will force the base contributor to be equal to the "to" version, thus fooling CC into thinking that a merge of changes is necessary. This assumes that your view is already picking mybranch/LATEST, thus making -to and -base equal to each other.
  # ct merge -graphical -to file.cpp -base file.cpp@@/main/integration/mybranch/LATEST -version /main/integration/LATEST
Table of Contents



Recover a removed element.

The element was removed using rmelem.
The rmelem command completely removes the element and its history from the VOB. As of CC 2002, that command can only be run by the VOB owner. The only way to recover an element using rmelem is from a backup. See Restore a single element from backup.

The element was removed using rmname or from the ClearCase Explorer (Windows).
The rmname command simply uncatalogues the name of the element from the current version of the parent directory. The "Delete" shortcut menu option in the ClearCase Explorer runs rmname. Its history and the history of the parent directory are preserved. If that element is ever needed again, it can be retrieved from a previous version of the parent directory (merged forward). See Recover a previous version of an element. In this case, you are retrieving a previous version of the file's parent directory.

The element is missing from a dynamic view.
In a dynamic view, if the element is checkedout and the resulting view-private file is removed, it will show up in a ct listing as [checkedout but removed]. Since the checkedout contents of the file are missing, there is no choice but to uncheckout the element.

The element is missing from a snapshot view.
In a snapshot view, the element can either be [checkedout but removed] or [loaded but missing]. If the is checkedout but removed, there is no choice but to perform an uncheckout. If the element is loaded but missing, simply perform a "ct update" on that single file.

Table of Contents





Find all elements modified since a certain date-time.
See the qyuery_language man page for details on what strings are acceptable for <date-time>. Note that if that <time> is omitted, 12 noon is assumed.
  # ct find <path> -version "created_since(<date-time>)" -print

Example:
  # ct find . -version "created_since(10-May-2004)" -print
Table of Contents



Increase the maximum size allowed for an element.
Updated: 09/19/06
CC 7.0 introduced support for VOBs that allow certain types of elements to grow beyond the previous limit of 2 GB. After a VOB has had its feature level raised to feature level 5, version and container size restrictions are relaxed for the following types of elements: This feature is available on all platforms. However, not all platforms have a default configuration that supports files this large. On hosts running the Unix system or Linux, use the ulimit command to get or set the maximum file size.

Table of Contents





Find objects created by a certain user.
The "ct find" command can search for elements, branches, or versions created by a certain user. As of CC 5.0, there's no way to find other types of objects without a script that loops through each instance of that type looking for the owner.
  # ct find -all -element "created_by(username)" -print
Table of Contents



Find objects created since a certain date.
The "ct find" command can search for elements, branches, or versions created since a certain date. As of CC 5.0, there's no way to find other types of objects without a script that loops through each instance of that type looking for the creation date.
  # ct find -all -element "created_since(date)" -print
Table of Contents



Count the number of elements in a VOB.
To find the number of elements in a VOB, one could set to a default view and simply run find on all files with a "main" branch. However, the vob_scrubber has already done that for you. Each night, the vob_scrubber runs and logs everything it finds. One could inspect the vob_scrubber.log file or simply run the command again from the CLI without logging anything. The vob_scrubber is one of those commands that lives in the <ccase-home-dir>/etc directory.
  # vob_scrubber -stats_only -nlog vob-storage-area
See the leftmost column; "Number of objects".

Table of Contents





Describe an element that has spaces in its name.
Updated: 10/10/11
Version: 7.1.0.8
If an element name has spaces in it and you attempt to describe it, you'll get an error like.
	cleartool describe my element.txt@@
	cleartool: Error: Unable to access "my": No such file or directory.
	cleartool: Error: Unable to access "element.txt@@": No such file or directory.
To get around, simply enclose the whole selector string in double quotes.
	cleartool describe "my element.txt@@"
Table of Contents



Print all files and the latest version number chosen by the view.
Updated: 01/05/12
Version: 7.1.0.8
	ct find vobtag -type f -version version(branch-path\LATEST) -exec "ccperl -e \"if ( '%CLEARCASE_XPN%' =~ /.+\\(.+)\@\@.+\\(.+)$/ ) { print \\\"$1 $2\n\\\"; }\""
Table of Contents



Programmatically determine a version's predecessor on a different branch.
Updated: 02/06/12
Version: 7.1.0.8
If an element is checked out from version "0", it's very difficult (impossible) to use cleartool commands to determine information about the version it was branched from. This is one occasion where CAL does better than cleartool. For example, if looking to see if the previous version has a certain label, the following code will work in a trigger.
	$version_o = $CC->Version($ENV{CLEARCASE_XPN});
	if ( Win32::OLE->LastError ) {
		print STDERR "Cannot get version object\n".Win32::OLE->LastError);
		exit 1;
	}
	$version_number = $version_o->VersionNumber;

	if ( "$version_number" eq "0" ) {
		$predecessor_o = $version_o->Predecessor;
		if ( Win32::OLE->LastError ) {
			print STDERR "Cannot get the predecessor version object.\n".Win32::OLE->LastError);
			exit 1;
		}
	} else {
		$predecessor_o = $version_o;
	}

	$labels_co	= $predecessor_o->Labels;
	$n_labels	= $labels_co->Count;
	for ( $l = 1; $l <= $n_labels; $l++ ) {
		$label = $labels_co->Item($l)->Type->Name;
		if ( "$label" eq "MY_LABEL" ) {
	...
Table of Contents



View the contents of a previous version of a file.
Updated: 03/31/16
Version: 7.1.2
Unfortunately, there is no direct way to view the contents of an older version of a file.

Method 1: (This is quicker, but only works for files that can be diffed)
1) Right-click on the file and select Version Tree.
2) Right-click on the latest version and select Compare -> with Another Version.
3) Your mouse will turn into a target scope. Click on the desired older version.
4) This will bring up a diff tool. Simply view the older version and ignore the latest version.

Method 2:
1) Right-click on the file and select Version Tree.
2) Right-click on the desired version and select Send To -> My Documents.
3) In the Windows Explorer, go to your My Documents folder.
4) You will see a file there that is simply named for the version number from step (2). It’s unfortunate, but it doesn’t carry the original file name. Also, it won’t have an extension. For example, if I extracted version 2 of a “MyFile.docx”, in the My Documents folder rename the file called “2” to be “MyFile_ver2.docx”. I recommend including “ver2” in the new name so that there is no ambiguity about where it came from.

Method 3: (This will only work if the virtual drive reduces the path length enough)
1) In the Version Tree Browser, right-click on the version you want to view and select Properties.
2) Copy the parent path into the following command on the CLI (where Y: is an unused drive letter):
	Syntax:		subst  unused-drive	parent-path
	Example:	subst  Y:  X:\p29462_MUOSD00300619_GD_dev\GTSDistribution\MASrelease\MAS_Application_Server\doc
  
3) Launch the executable to view the version you want:
	Syntax:		executable	version-extended-path
	Example:	"C:\Program Files (x86)\Microsoft Office\Office14\winword.exe"  "MAS_SVD_98-P52180E.doc@@\main\GTSMASDev Build2_Integration\GTSMASDevBuild3_Integration\GTSMASDevBuild3-1_Int\icm_gts_03_01_04_190_0208232414_integration\1"
  
4) When done with the virtual drive (can’t be removed from Windows Explorer):
	Syntax:		subst  drive-letter  /D
	Example:	subst  Y:  /D
  
Table of Contents



View the contents of file logically removed with rmname.
Updated: 03/28/12
Version: 7.1.0.8
Unfortunately, there is no direct way to view the contents of a file removed with rmname.
However, there is a workaround, though a bit kludgy. In the Version Tree of the parent directory, locate the version where that file was last cataloged. Perform a merge from that directory version to the latest version. Complete the merge, but don't check in the directory. Simply view the contents of the file, or even copy it out of CC. Then, uncheckout the parent directory to cancel the merge.
If the above solution isn't possible, the long way around will be necessary.
1) Right-click on the folder that once held the file in question and select Version Tree.
2) Hover over each previous version and determine the version of the parent folder in which the file was last available.
3) Inspect the version tree and note the branch path to the version in question. For example “\main\System_Int”. This is the branch path.
4) Right-click on that version and select Compare -> with Previous Version.
5) In the resulting window, locate the file, right-click on it and select Properties. Note the full path of the lower-numbered version. This is the parent path.
6) On the command line, run the appropriate executable along with the path information discovered above. For example, if the document is a Word doc:
	Windword.exe  parent path\file name@@branch path\LATEST
For example, the following will show the latest version of that file on the “System_Int” branch. The parent path determined in step (5) is in red. The file name is assumed to be known. The branch path in green was determined in step (3).

Windword.exe M:\EJO_System_int\System\Tools@@\main\System_Int\23\System_tools.docx@@\main\System_Int\LATEST

Note that the above command will show you the latest version of the element on the such-and-such branch. If you want to view a version other than latest, simply substitute the version number where it says “LATEST”. If you want to view all versions on any possible branch, it would be a long tedious process, or need to be done programmatically.

Table of Contents





List all branches of an element.
Updated: 04/20/12
Version: 7.1.0.8
The following command will produce a listing of branches of an element. It's kludgy to use a search for a non-existent attribute called "dummyname", but there isn't any more efficient way to do it. There's no CAL equivalent of this.
	ct find element -branch \"!attype(dummyname)\" -print

	# Don't recurse if the element is a directory:
	ct find element -dir -branch \"!attype(dummyname)\" -print
Table of Contents



List all versions of all branches of an element.
Updated: 04/20/12
Version: 7.1.0.8
The lsvtree command produces the desired output. There's no CAL equivalent of this.
	ct lsvtree -all -s element
Table of Contents



Determine if an element was renamed.
Updated: 04/24/12
Version: 7.1.2
Unfortunately, there is no easy way to know if an element has been renamed. This is a problem from a verification and audit stand point. The parent folder versions merely state that a file was Uncatalogued and that another was Added. That is from the parent folder information, you can't determine if the file is the same one. The history of the file element itself shows the new name for all versions back to creation.
One solution is to create a postop rename trigger that performs a chevent on the current parent version, such as:
	ct chevent -append -c "Renamed A.doc to B.doc" .
Table of Contents



Create a hyperlink type.
WARNING!   Most references to objects in CC use the OID. However, hyperlinks merely point to another string. For instance, if you hyperlink to VOBs together and then change the tag of one of those VOBs, the hyperlink will have to updated.
In xclearcase, Metadata -> Hyperlink -> Hyperlink type ... -> Type -> Create...
In Windows CC Type Explorer: right-click on mounted VOB in Windows Explorer and go to ClearCase -> Explore Types, double-click on hyperlink type and go to Type -> Create...
From the CLI:
  # ct mkhltype hyperlink-name
Some common options:
-glo.bal The type definition can be used by other VOBs once the AdminVOB hyperlink has been connected between them.
-rep.lace Change the properties of an existing hyperlink type; such as rename.
-sha.red Hyperlinks of this type can be created in any MultiSite replica.

Table of Contents





Rename a hyperlink type.
All occurences of the hyperlink in the VOB will be changed to the new name automatically; because the hyperlink doesn't actually reside with the object, but is rather a link to the original hyperlink type.
  # ct rename hltype:old_hyperlink-name hltype:new_hyperlink-name
-- or--
  # ct mkhltype -replace hltype:old_hyperlink-name hltype:new_hyperlink-name
NOTE: If the "mkhltype -replace" is used, all options used during original creation need to be restated during the replace or their values will return to default. So, if simply renaming a hyperlink type, it's safer to use the rename command.

Table of Contents





Attach a hyperlink.
Updated: 10/19/11
Version: 7.1.0.8
You must create a hyperlink type prior to attaching a link of that name to an element. Hyperlinks can be connected between any two CC objects except for other hyperlinks; this includes hyperlinks to objects in other VOBs or to other VOBs themselves. If connected to another an element in another VOB, only the "to" side is recorded so that the other VOB does not need to have the hlink type defined. If linking to another VOB, note that a link to vob:/tag is a link the VOB itself and a link to /tag is a link to that VOB's top directory. Note that hyperlinks are not to be confused with soft and hard links, which actually link data or hypertext. Hyperlinks are simply annotations that represent a relationship between two objects. There can be more than one hyperlink pointing to or from an element version.
In UNIX xclearcase, select the element and then go to Metadata -> Hyperlink
In Windows, it's not possible to attach hyperlinks using the GUI.
From the CLI:
  # ct mkhlink hyperlink-name from-object to-object
Some useful options:
-uni.dir Make no notation on the "to" object (only applicable when crossing VOBs).
-fpn.ame   from-hlink-name If crossing VOBs, specifies "from" link if different than "to" name.
-tpn.ame   to-hlink-name If crossing VOBs, specifies "to" link if different than "from" name.
-tte.xt   text Link to a text string vice another object. Used for simple annotations.

Hyperlinks can also be attached automatically via triggers. When creating the trigger type, use the   -mkhlink   option. Hyperlinks have direction associated with them. The default is to create a bidirectional hyperlink. That is, the link can be seen from both ends. The end at which you are currently looking is denoted by directional arrows as seen in the "describe" command.
<-   current object is being pointed to
->   current object is the from side
NOTE: For some reason, if applying the hyperlink from the CLI or a trigger using the -ttext or -ftext options, if the text contains backslashes, no amount of creative quoting will prevent it from throwing an error. The workaround is to convert the backslashes to forward slashes.

Table of Contents





Remove a hyperlink.
In UNIX xclearcase, select the element and go to Metadata -> Hyperlink -> Show Inherited Hyperlinks, select the link to be removed and go to Hyperlink -> Remove.
In Windows, unknown if it's possible to remove hyperlinks from the Windows GUI.
From the CLI:
  # ct describe -long -ahlink hyperlink object    (note hyperlink-selector)
  # ct rmhlink hyperlink-selector

ex:
  # ct describe -long -ahlink Testlink foo.c
        Testlink@295@/vobs/admin -> /vobs/admin/notes@@/main/1
  # ct rmhlink Testlink@295
If the hyperlink is corrupt for some reason, the checkvob command can be used to remove it.
  # ct checkvob -hlink -hltype hyperlink object

ex:
  # ct checkvob -hlink -hltype AdminVOB vob:\vobtag
Table of Contents



Use predefined hyperlinks: AdminVOB, Merge, etc...
A brand new VOB comes loaded with the following predefined hyperlinks:
AdminVOB Manually attached between two VOBs when you want to use globally defined types from another VOB.
Change ClearGuide only.
GlobalDefinition Automatically attached between a local type definition and the global type definition in an administrative VOB.
IndependentGuard ClearGuide only.
Merge Automatically attached between two element versions when they are merged independent of whether changes were actually accepted from the merge contributor.
RelocationVOB Automatically attached to VOBs between which elements were relocated. Also creates a new hyperlink type called "HyperSlink" attached to the relocated element pointing to the new location.

Table of Contents





Determine a hyperlink ID
Unlike labels and attributes, the same hyperlink can be attached to a version of an element many times. To distinguish between the separate instances of that hyperlink, CC associates a hyperlink ID with each.
In UNIX xclearcase, Versions -> Show version tree... -> Report -> List history -> Element -> Minor
In Windows Explorer, ClearCase -> History -> select the Include Minor Events button (far right)
From the CLI:
  # ct describe -long -ahlink hyperlink object
-or-
  # ct lshistory -minor object
Table of Contents



View hyperlinks.
In xclearcase, select an element and Metadata->Hyperlink->Show Inherited Hyperlinks. Or, Report->Describe->ClearCase Object.
In Windows, see the "Properties of Version" dialog. There is no Htree browser on Windows.
From the CLI:
  # ct describe -l element
Table of Contents



Stop 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.
You can only see an inherited hyperlink from the CLI.
  # ct describe -ihlink hlink-name file-name
Table of Contents



Connect Windows to Unix (interop).
There must be an NFS connection between Unix and Windows. That connection can be established with a client-side solution, such as Hummingbird NFS Maestro, Diskaccess, or Windows Service for Unix (WSFU). Or, the connection can be handled from the server side with Totalnet Advanced Server (TAS) or Samba.
Client-side solutions are generally cheaper for small work groups, but must be installed on each client machine. However, Samba is freeware, but Rational only supports a limited number of Samba versions. The server-side solutions have the advantage that usernames and groups can be mapped from Windows to Unix. While it isn't mandatory that the usernames match, it is mandatory that your Windows primary group match a group on the VOB's group list by name.
If the VOB is located on Unix, the view storage can be located on either the Unix or Windows side and can be either dynamic or snapshot. If the VOB is on the Windows side, as of CC 5.0, a Unix snapshot view can access it.
NOTE: If you experience slow access times to the Unix VOB when using a client-side solution, enter the CC Control Panel applet and under the MVFS tab, change "View Network Name" entry from "view" to "127.0.0.1".

Table of Contents





Converting end-of-line characters.
UNIX and Windows environments handle end-of-line termination characters differently in text files. UNIX uses <NL> (or <LF>) and Windows uses <CR><NL> (or <CR><LF>). Default UNIX views always use UNIX sytle line terminations and Windows views always Windows style line terminations. However, since UNIX views can be used on the Windows side in an interop environment, they can be made to automatically handle the Windows line terminations.
A UNIX view can be placed in msdos mode at creation:
  # ct mkview -tmode msdos ...     (CC 3.x)
  # ct mkview -tmode insert_cr ... (CC 4.x)
To determine what mode a view is in, as of CC 4.0, look for "Text mode:" in:
  # ct lsview -properties -full view-tag
NOTE: With view modes, you cannot have it both ways. That is, as of CC 4.1, there is no way to have a view that can be used on UNIX and Windows and have the line terminations automatically appropriate for the OS at hand. It's one or the other.
To make sure all new views automatically get placed in interop mode, use the setsite command and set "view_interop_text_mode=TRUE". Use "ct lssite -inquire" to get current settings.

If using that Windows mode UNIX view to access a UNIX VOB, the VOB must also be placed in interop mode. Even though the UNIX VOB may be placed in interop mode, it always stores the files internally with UNIX style terminations. That is, the file is not converted until an Windows view or UNIX view in Windows mode reads a file, and only then the view-private and cleartext copies are converted. Because msdostext_mode is used so that local views can read files properly, it isn't recorded as a CCMS oplog entry and therefor you do not have to have other replicas in the same family in interop mode as well. If you recieve a packet from a non-enabled replica, see the -c option below. This command lives in ccase-home/etc/utils.
To place a VOB in interop mode:
  # msdostext_mode vob-storage-pname
Options:
-c Converts the VOB, but does not enable text mode support. Basically, this option will go through and convert any files not already in interop mode; such as those added from a non-enabled CCMS replica.
-d Disable interop text mode support.
-f   (undocumented) Occasionally MSDOS mode views can experience problems accessing file versions. Run this "fix" mode to correct. Then, you must run msdostext_mode without options to re-enable interop mode.
-r   (undocumented) If files are chtype'ed from "text_file" to "file" or vice-versa, the pc_line_count can become out of sync. This option resets the line count so that there is no file version truncation.
You can determine if a VOB is already in interop mode. Look for a switch called "pc_line_count" on the line called "flags:".
  # ct dump vob:vob-tag
To determine if a given file has been converted, look for "stored fstat" and "returned fstat". If they are set to anything other than null or "00", it's converted.
  # ct dump file
NOTE: Even though a UNIX VOB in interop mode stores files with UNIX style terminations, if a file is placed there by a regular Windows view, that file will retain its Windows style terminations and be unreadable by a UNIX view. However, on the UNIX side, files can always be migrated back and forth between the two modes via one of the following:
  # dos2unix file > newfile
  # unix2dos file > newfile
Table of Contents



Install hclnfsd/pcnfsd.
If hclnfd (or pcnfsd) isn't already running and this is a new install on a VOB server exporting to PC clients, complete the following. The daemon, hclnfsd (provided by Hummingbird Software if using NFS Maestro) must be running on a UNIX server that will have its drives exported to PC clients. Note: an alternative to hclnfsd is a daemon called pcnfsd that may also be setup in the same way. If it exists, pcnfsd would come bundled with the server OS. Set up the server so that the daemon gets started automatically upon reboot. Obtain hclnfsd directly from Hummingbird and install it in /usr/local/bin. So that hclnfsd gets started at reboot, create a file called /etc/init.d/hclnfsd and place something similar to the following in it:
#!/bin/sh

# PC NFS daemon; so that PCs can map exported UNIX drives via NFS Maestro.
hclnfsd_home=/usr/local/bin
case "$1" in
  'start') if [ -f $hclnfsd_home/hclnfsd ]; then
             echo "PC nfs daemon (hclnfsd) starting"
             $hclnfsd_home/hclnfsd -A -X
           else
             /usr/bin/echo "\n /etc/init.d/hclnfsd ERROR: cannot find PC nfs daemon $hclnfsd_home/hclnfsd \n"
           fi;;
   'stop') PID=`/usr/bin/ps -efl | grep hclnfsd | grep -v grep | awk '{ print $4 }'`
           [ ! -z "$PID" ] && /usr/bin/kill ${PID} 1> /dev/null 2>&1;;
        *) echo "Usage: /etc/init.d/hclnfsd { start | stop }";;
esac
Change permissions on the new hclnfsd file to make it executable and setup the run control links to it.
  # cd /etc
  # chmod 744 init.d/hclnfsd
  # ln -s /etc/init.d/hclnfsd rc3.d/S99hclnfsd
  # ln -s /etc/init.d/hclnfsd rc2.d/K00hclnfsd
Start the hclnfsd daemon.
  # /etc/init.d/hclnfsd start
Table of Contents



ClearCase File Server (CCFS)
ClearCase File Server (CCFS) is a TCP/IP based mechanism for file transfers between UNIX VOB servers and CC clients running Windows NT/95/98 (CC 3.2.1 or later). Starting in CC 4.1, one can use a UNIX snapshot view to access an Windows/Win2K VOB with CCFS. If using CCFS, one is limited to snapshot views. Dynamic views on Windows still need a supported NFS client or SMB server product to access UNIX VOBs. Windows 95/98 clients can only run snapshot views and cannot run view servers. Hence, even though files are downloaded to and accessed from 95/98, the view storage area and view server process still need to be on Windows.
1) Open the ClearCase Control Panel.
2) In the Options tab, select "Use CCFS to access UNIX VOBs". Click OK.
3) Shutdown and retart the whole computer to ensure the settings take affect.

Table of Contents





MicroSoft Service for UNIX (MS-SFU)
SFU versio 1.0 is support by Rational. However, the much enhanced version 2.0 is not as of CC 4.1. MS-SFU gives you the ability to access NFS resources from a Windows system. Once it is fully supported, it will be an alternative to other packages, such as NFS Maestro and DiskAccess. It also has many neat features, such as Password Synchronization and Username Mapping. See Microsoft Service for UNIX 2.0.
At this time (8-17-00), Rational tech support cannot answer the question as to whether using an installed SFU 2.0 to take advantage of its utilities will enhance or interfere with other concurrently running supported packages, such as Maestro.

Table of Contents





File access between operating systems.
The following is a matrix of UNIX/NT connection possibilities.
TAS = TotalNet Advanced Server
SMB = Server Message Block
CIFS = Common Internet File System
NFS = Network File System
Rational supported, third-party NFS solutions include Intergraph DiskAccess, Hummingbird NFS Maestro, and Microsoft Service for UNIX. Samba has been used to connect Windows to UNIX, but as of 10/09/00 is not supported by Rational.
Platform NT/Win2k views & VOBs UNIX VOBs UNIX views
Windows 95/98 Native SMB CCFS Unsupported
NT/Win2k using dynamic views Native SMB 3rd party NFS or TAS/CIFS 3rd party NFS or TAS/CIFS
NT/Win2k using snapshot views Native SMB CCFS, 3rd party NFS or TAS/CIFS 3rd party NFS or TAS/CIFS
UNIX using dynamic views Unsupported Native NFS Native NFS
UNIX using snapshot views CCFS Native NFS Native NFS

Table of Contents





Nothing yet.

Table of Contents





Access a Windows VOB from a Unix client.
To access a Windows VOB from a Unix client, you can only use a snapshot view using the builtin CC CCFS.
You must specify a Windows domain to authenticate Unix users. If your VOB, view, registry, or license server hosts will be accessed by Unix clients, you must specify the Windows domain that will be used to map the credentials of Unix users. Specify the Windows domain for credential mapping:
1) Click Start > Settings > Control Panel.
2) Double-click ClearCase and click the Options tab.
3) In the Use this domain to map Unix user and group names area, select a Windows domain in which user and group identities have been defined for all Unix users who access these services on this server.

Table of Contents





Create a label type.
The label type must exist in the VOB before it can be attached to an element. Simply put, the label type IS the label. Must be in a VOB to run this command.
In UNIX xclearcase, Metadata -> Label -> Label type... -> Type -> Create...
In Windows CC Type Explorer, right-click on mounted VOB in Windows Explorer and go to ClearCase -> Explore Types, double-click on "label type" and go to Type -> Create...
From the CLI:
  # ct mklbtype label
Some useful options:
-rep.lace Change the parameters of an existing label type.
-glo.bal Allow other VOBs to access this label.
-ord.inary Limit use of this type to the local VOB.
-sha.red CCMS VOB replicas can create/remove instances of this type.
-pbr.anch The label can be applied to more than one branch in an element.
Shared label types can only be applied to versions on a branch if the -pbranch option is also used and that branch is mastered by the local replica. If the -pbranch option was not also used, the shared label can only be applied to a locally mastered branch if the element itself is locally mastered.

Labels must conform to the following syntax:
- Must contain only letters, digits or the special characters "_", "." and "-".
- First character cannot be a dash or digit.
The general convention is that labels are all uppercase letters; to avoid confusion with all lowercase letter branch names.

The default is that a label can only be attached to one version on any branch. Use the   -pbranch   option to allow attaching of the label once per branch.

Table of Contents





Attach a label.
Updated: 01/02/12
Version: 7.0.1.8
A label type must be created before attempting to attach it to an element. That is, you must create the label type first, then create instances of it. Labels can be attached recursively using the -recurse option on the CLI or by employing the Apply Label wizard. The wizard can be invoked from the CLI via clearapplywizard.

In UNIX xclearcase, highlight the element and go to MetaData -> Label -> Attach...

In Windows, in the Version Tree Browser -> Tools -> Attach label... (or simply right-click on the version).

CAL: The extra Apply parameters shown are "no comment" and "replace if previously applied".
	$vob_o		= $CC->VOB($vobtag);
	$version_o	= $CC->Version("$extended_version_path");
	$lbtype_o	= $vob_o->LabelType("My_Label_Type");
	$lbtype_o->Apply($version_o,"",1);

	$label_o	= $version_o->Label("My_Label_Type");
	$label_o->Remove;
On the CLI:
  # ct mklabel label element
The element can be a version extended name such as those seen in "ct ls" if you don't want to attach it to the version currently selected by your view.
Some useful options:
-r.ecurse Recursively attach label if element is a directory.
-rep.lace Move an existing label to another version.
-con.fig config-record Attach the label to those elements that went into a build.
-name tail-pattern used with -config, limits labeling to elements ending in tail-pattern
-fol.low New in CC 5.0/2002, follow any symbolic link encountered and label the target.

Example: Attach a label to a specific set of files.
	ct find . -nr -name "clock*.c" -exec "cleartool mklabel -replace Approved \"%CLEARCASE_PN%\""
NOTE: Labels can only be attached to element versions. That is, they cannot be attached to the element itself or a branch.
NOTE: The regular application of labels across tens of thousands of elements, perhaps to record daily builds, can take an inordinate amount of time and resources. As one workaround, a timestamped config-spec can be created that corresponds to where the label would have been applied. That is, a view is needed to apply a label across a VOB. For each rule in that view's config-spec, place a "-time datetime" at the end of the line. Save the actual config_spec file to a location and name that file after the date-time stamp that would have been the label, had it been applied. Make that file read-only. Keep it under version control. Any user needing access to the version set can merely set to that config spec:
  # ct setcs /path/filename
However, labels MUST be applied for very stable/tested builds and certainly for released software. Many customers lock down (trigger) commands such as rmver and rmelem to fail if the element being worked on has any baseline labels applied.

Table of Contents





Remove a label.
Updated: 01/06/12
Vesion: 7.0.1.8
Must be element group member, element owner, root or vobadm.

In UNIX xclearcase, Metadata -> Label -> Remove...

In Windows Type Explorer, enter "label type" folder, right-click on the label and choose Delete.

CAL: The extra Apply parameters shown are "no comment" and "replace if previously applied".
	$vob_o		= $CC->VOB($vobtag);
	$version_o	= $CC->Version("$extended_version_path");
	$label_o	= $version_o->Label("My_Label_Type");
	$label_o->Remove;
CLI:
  # ct rmlabel LABEL element
-- or --
  # ct rmlabel -version /main/5 LABEL element
To remove a label en masse at and below the current directory:
  # ct find . -ver 'lbtype(LABEL)' -exec 'cleartool rmlabel LABEL $CLEARCASE_XPN'
Use "%CLEARCASE_XPN%" for Windows command-line. See "Delete a type" if you want to remove the label from the VOB entirely.

Table of Contents





Rename a label type.
All occurences of the label in the VOB will be changed to the new name automatically; because the label doesn't actually reside with the object, but is rather a link to the original label type.
  # ct rename lbtype:old_label-name lbtype:new_label-name
-- or--
  # ct mklbtype -replace lbtype:old_label-name lbtype:new_label-name
NOTE: If the "mklbtype -replace" is used, all options used during original creation need to be restated during the replace or their values will return to default. So, if simply renaming a label type, it's safer to use the rename command.

Table of Contents





Find instances a label.
In UNIX xclearcase, Report -> Find query.
The find command is only available on the command-line in Windows.
  # ct find path object-type lbtype(LABEL) -print
The path is the directory in which you want the search to begin.
The object-type is one of the following:
-version list the specific version with the label
-element just list the element name if it contains any instances of the label
-branch list the branch on which the version with the label lives
NOTE: For -element and -branch, you must use lbtype_sub instead of lbtype. The lbtype_sub designator tells find to look at sub objects for the label. This is necessary because branches and elements themselves cannot have labels attached. If lbtype is used with either of those two, find will return nothing and no error.

Table of Contents





Find all label types that begin with a specified string.
Updated: 05/02/13
Version: 7.1.2

The Windows findstr command isn't as flexible as regular expressions in grep, but doesn't require any extra installs, such as Cygwin, on a Windows computer. See the findstr man page.
	ct lstype -s -kind lbtype -invob VOB-tag | findstr /b string
Table of Contents



Types.
Everything in CC belongs to a "type" (a class of object). A CC VOB is automatically populated with types called supertypes that tell CC how to handle the CC object internally.
  # ct lstype -kind type
-or-
  # ct lstype -type  (up to CC 3.2.1)
However, there may not be one that you want to use. In fact, it is probably wise to create your own to keep it separate. Each of the supertypes is associated with a type manager. The type manager tells CC how to store the data. See the "CC Concepts Manual" for an explanation of the type manager catagories.
ex: ct mkeltype -supertype text_file -c "ISSPD SCM documents" myeltype
Each of the "type" or "type_object" commands used depends on what type is being worked with. The following are CC types:
-attype   attribute type
-brtype   branch type
-eltype   element type
-hltype   hyperlink type
-lbtype   label type
-trtype   trigger type
-actype   activity type
-sttype   state type
Types can be referenced as a group, by name, or by name in a specific VOB. Examples in order:
-eltype
-eltype:my_element_type
-eltype:my_element_type@myVOB
List the entries for a given type:
  # ct lstype -kind type
The Windows install of CC has a Type Explorer that can be accessed via ClearCase Home Base -> Administration -> Type Explorer.
The term type-selector refers to the following construct:
     type:type-name
ex:  lbtype:BUG_FIX1.0
NOTE: A single VOB cannot have a branch type and label type of the same name.

Table of Contents





Create a type.
The subcommand used depends on the type being created. Below are a few examples of the mk commands:
  # ct lstype -kind type
  #
  # ct mklbtype -ordinary label_type-name
  # ct mktrtype -element -execunix command trigger_type-name
  # ct mkeltype -ordinary -supertype supertype element_type-name
Table of Contents



Remove a type.
Updated: 01/06/12
Version: 7.0.1.8
In UNIX xclearcase, Metadata -> type -> Type -> Destroy type.

In Windows Type Explorer, enter "type type" folder, right-click on the type and choose Delete.

CLI:
  # ct rmtype type-selector

ex: ct rmtype lbtype:VER_1.0
Options:
-rma.ll remove all instances of the type as well
-for.ce do not ask for confirmation
-ign.ore (trigger types only) Removes a trigger type even if a previously defined preop trigger would prevent rmtype.
If the type has instances of it in the VOB, you will not be able to delete it. For instance, if a certain trigger is attached to elements, you will not be able to delete the trigger type. To find all elements that have a certain type attached, see Find all elements with a certain attribute. To remove all the instances of a type from elements, see Modify element attributes en masse or use -rmall. Once these conditions are satisfied, the type can be deleted.
Cannot remove an element type from a replicated VOB.
Cannot remove predefined types.
NOTE: Rational Software recommends obsoleting a type rather than removing it. This is especially true if the type was previously applied to an element version that was part of a build or something. That is, if a label was applied to an element at one time but is no longer needed, instead of removing the label and deleting the label type, simply lock the label using the   -obsolete   option. This will make the label "disappear" for most common commands, but will still be a part of that object's history; which is important for proper CM.

CAL
The RemoveType parameters shown are "remove all instances", "remove even if a preop trigger would prevent the removal", and a history comment.
	$triggertype_o = $vob_o->TriggerType("trigger_name");
	if ( "$triggertype_o" ne "" ) {
		print "Removing $remove_trigger ...\n";
		$triggertype_o->RemoveType(1,1,"");
		if ( Win32::OLE->LastError ) {
			print STDERR "\n$script ERROR: Unable to remove trigger_name.\n".Win32::OLE->LastError;
			exit 1;
		}
	}
Table of Contents



Set a default element type. (magic files)
Each time an element gets created (added to source control), it is assigned an element type based on the rules layed out in the ccase-home-dir/config/magic/default.magic file. However, not all file extensions are recognized, or you may add to source control a file with no extension at all. In those cases, you can either add the file to source control from the CLI using "mkelem -eltype" or place custom rules in your own magic file.
For example, if you create a new element type in a VOB called "word_doc" based on the "file" supertype, you would place a line like the following in a magic file so that anytime a .doc file is added to source control, its default type is automatically set to word_doc. Your custom magic file must have the extension ".magic" and be placed in a common, permanent location. In this case it would contain the line:
word_doc binary_delta_file: -name "*.doc" ;
NOTE: As of CC 4.0, there is a predefined element type called ms_word.
There are many combinations for rules to determine which default type to assign. See cc.magic/default.magic in the "CC Reference Manual".

NOTE: Even though Windows is case insensitive, if CC is connected to a UNIX server, the element type assignment IS case sensitive. It is safer to write the above example as or a variant of:
word_doc binary_delta_file: (-name "*.doc" | -name "*.DOC") ;
NOTE: The space before the trailing semicolon is required.

It is also possible to have it choose between a list of types, depending on which VOB you are in at the moment. For instance, one VOB may contain the word_doc type for word documents and another worddocs, also for word documents. However, the list should end in one of the pre-defined elements types that the others are based on as a catch-all.
word_doc worddocs binary_delta_file: (-name "*.doc" | -name "*.DOC") ;
NOTE: Above, Microsoft Word files were used in the example and their custom type "word_doc" was based on the whole copy type "file". In the past, I've had success placing them under the "binary_delta_file" type. This saves space and allows branching and merging (though not graphically). However, CC 4.0 comes with a predefined element type called "ms_word" that does allow graphical merges of Microsoft Word documents.

To get CC to read your magic file first, it must placed first in an environment variable called MAGIC_PATH. That environment variable probably does not exist yet, as CC assumes the default path without it. On Windows, environment variables are semicolon separated lists and are set via the Control Panel -> System icon. On UNIX, they are colon separated and set via a commonly sourced file, such as a .global_cshrc. On both platforms, the variable MUST be set so that ALL users working in that VOB can see it; otherwise your custom rules won't be seen. Even though it would be much simpler to just place your custom rules in the default magic file, those customizations would be lost during the next upgrade.

NOTE: If altering the default magic file or creating a centralized custom magic file are unacceptable, an alternative is to reset the element's type upon creation. That is, create a mkelem trigger that resets the type (chtype). For example, if you want to ensure zip files are copy-only:
	# Create the custom element type.
	ct mkeltype –supertype file –mergetype copy COPY_ONLY_FILES

	# Convert existing files to the new type.
	ct find . –element –name *.zip  –exec `cleartool chtype –nc COPY_ONLY_FILES $CLEARCASE_PN`

	# Account for newly created elements.
	ct mktrtype –element –all –postop mkelem –exec “ccperl …” Copy_Only_Element_Type

Table of Contents





Rename a type.
In UNIX xclearcase, Metadata -> type -> type type... -> select the type -> Type -> Rename...
In Windows Type Explorer, enter the "type type" folder, right-click on the type and choose Rename...
On the command-line:
  # ct rename old-type-selector new-name

ex: ct rename lbtype:BUG_FIX lbtype:BUG_FIXES
-or-
ex: ct rename lbtype:BUG_FIX BUG_FIXES
All occurences of the type in the VOB will be changed to the new name automatically. The instance of the type doesn't actually reside with the object, but is rather a link to the original type object.

Table of Contents





Global types. (Administrative VOBs)
Updated: 04/02/14
Version: 7.1.2
Administrative VOBs keep global definitions of types: label, branch, etc... An admin VOB is created the normal way and only when metadata is created with the global option in the AdminVOB does the AdminVOB truly become the "admin" VOB.

Global MetaData created in the admin VOB is fully connected to the children. That is, when a child VOB attempts to create an instance of MetaData that is globally defined in the admin VOB, the MetaData type is created locally and linked to the original MetaData definition in the admin VOB. Any and all modifications made to the original MetaData type in the admin VOB are automatically propogated to the children.
MetaData is created as global in an admin VOB, the MetaData type is immediately created and listable in the children. However, it is only listable in the CLI and not via the Apply Label wizard.
A PVOB is an AdminVOB for its component VOBs. All metadata is initially created in both of those as "global".
You can perform "rmtype -rmall" on globally defined metadata in an admin VOB and it will remove all instances from all child VOBs (after a confirmation).

When a child VOB uses an admin VOB's globally defined MetaData type, a GlobalDefinition hyperlink is attached between the newly created type in the child VOB and the globally defined one in the admin VOB. That hyperlink is the one traversed when a lock is placed on the type in the admin VOB. However, if the admin VOB's global type is subsequently redesignated as local, that hyperlink goes away and there is then absolutely no connection between the type definitions in the client and admin VOBs.
A client VOB can have more than one admin VOB, but if the type being worked with is defined in multiple admin VOBs, the VOB listed alpha-numerically first will be the admin VOB for that type. VOBs cannot be admin VOBs of each other. That is, you cannot have circular AdminVOB hyperlinks.
The following commands show how to access globally defined metadata from a child VOB. The AdminVOB hyperlink is predefined by CC.
Create a globally defined type in a VOB:
  # ct mk??type -global type-name@/admin-vob-tag

Link the two VOBs together:
  # ct mkhlink AdminVOB vob:/client-vob-tag vob:/admin-vob-tag

The type is automatically created in the client VOB:
  # ct mkmetadata type-name element
A ct lstype of the type in the admin VOB will show the scope as being global.
A ct lstype of the type in the client VOB will show the type as "Automatically created type type from global ...". It will also show that the type is linked to the administrative VOB via a GlobalDefinition hyperlink. That is, the AdminVOB link was only used when a copy of the globally defined type was made in the local VOB. NOTE: On UNIX only, unlike the AdminVOB hyperlink and other hyperlinks, the GlobalDefinition hyperlink cannot be removed without removing the type completely from the client VOB. The GlobalDefinition hyperlink can be removed at will on Windows.

WARNING!   As of CC 4.1, UCM cannot import globally defined labels. If implementing UCM, simply change the globally defined MetaData type in the admin VOB to be "ordinary" (local) and the link to the children will be broken allowing import.
WARNING!   Most references to objects in CC use OIDs. However, hyperlinks merely point to another string. For instance, if you hyperlink to VOBs together and then change the tag of one of those VOBs, the hyperlink will have to updated.

Table of Contents





Copy a type.
Creates a new type object with the same characteristics as the original. They can have the same name if the copy is in a different VOB. There is no connection between the two after the copy is made.
  # ct cptype existing-type-selector new-type-selector
Table of Contents



Lock and/or obsolete a type.
Rational recommends obsoleting a type rather than removing it. This is especially true if the type was previously applied to an element version that was part of an important process, such as a build. That is, if a label was applied to an element at one time but is no longer needed, instead of removing the label and deleting the label type, simply lock the label using the   -obsolete   option. This will make the label "disappear" for most common commands, but will still be a part of that object's history; which is important for proper CM and ISO 9000 compliance.
In UNIX xclearcase, Metadata -> Type -> type type... -> select the type to be locked -> Locks -> Lock (or Obsolete).
In Windows Type Explorer, enter the "type type" folder, right-click and select Properties -> Lock
On the command-line:
  # ct lock -obsolete type:name
See "Lock and unlock objects" for more information.

Table of Contents





List all MetaData types in a VOB.
There is no single CC command to gather up all the MetaData types that exist in a VOB. You can write a simple Perl script to gather and report that information. Or, with a canned (Windows-only) SoDA report, it's possible to get a listing of all labels, attributes, triggers, etc that are in a VOB.
If a Rational Suite is installed, go to Rational-home\SoDAWOrd\template\ClearCase and double-click on vob.doc.

Table of Contents





Change the scope of a type.
Updated: 06/08/12
Version: 7.0.1.8
It's possible to convert the scope of a type from global to ordinary or ordinary to global. See the following document for details: https://publib.boulder.ibm.com/infocenter/cchelp/v7r1m0/index.jsp?topic=/com.ibm.rational.clearcase.cc_admin.doc/topics/t_typeadm_acquire.htm

Table of Contents





cleartool command
Most operations in CC performed on command line (CLI) are accomplished with the cleartool command, one of its subcommands and associated options, such as "cleartool lsvob -s". Cleartool is most often aliased (abbreviated) to "ct". The cleartool command has two modes, interactive and non-interactive. The example just given is non-interactive. However, if cleartool is typed with no subcommand or options, it will spawn a subshell that is cleartool specific. In interactive mode, the user can type commands without prefacing them with ct each time. Any non-CC shell commands executed while in interactive mode must be prepended with "!". In interactive mode lines can be continued with a backslash "\" on UNIX or a caret "^" on Windows.
  # cleartool
  cleartool> lsvob -s
  ...
  cleartool> !dir
  ...
  cleartool> lsview \
  -s
  ...
  cleartool> quit
  #
The cleartool command has a couple useful options independent of any subcommand.
-ver.sion Display the CC version and any applied patches.
-VerAll Long listing of -version.
-e Interactive mode: cleartool will quit automatically if an error is encountered.
-status New in CC 5.0/2002. Interactive mode: give the exit status (1 or 0) of the last CC command.

NOTE: There is no way to deinstall a patch. One must deinstall CC and reinstall it from a site release area that doesn't have the offending patch.
For patches, go to the customer only site http://clearcase.rational.com/cgi/patchfinder.
For a description of installing patches, see hostname" for each unique host listed in an "ct lsclients" list.

Table of Contents





CC tutorial.
The best way to start to learn the CC system is to run the tutorial.
UNIX:
Prior to running CC, you should add atria-home/bin to your path variable.
For ksh users this is in the .profile in your home directory. If running the CDE on Solaris, ensure the DTSOURCEPROFILE line in the .dtprofile file is uncommented so that the .profile is picked up appropriately.
For csh users this in the .cshrc file in your home directory.
Windows:
At the begining of the CC tutorial it will attempt to test the environment. Creat a HOME environment variable to "C:\winnt\profiles\badge-number" or an appropriate substitute. Set the HOMEPATH variable to the same thing, except without the prepended "C:". Environment variables are set in Settings -> Control Panel -> System -> Environment. If you get an error of "%HOME%\\.test <Invalid Argument>", it means that you do not have permission to build the tutorial VOBs/Views in the shared area (prompted for in the CC environment test).

Table of Contents





clearcase_albd
On Windows machines there needs to be a special user called "clearcase_albd". This user needs to be set up prior to installation and given the standard clearcase_albd/vobadm password. The password will be prompted for during the install (which cannot be blank). The CC albd services are run by the clearcase_albd user on behalf of the CC user. The clearcase_albd user should belong to one group only (called clearcase) whose only member is the clearcase_albd user.
If the password needs to be changed anytime after the install, for the Windows side use Programs -> Adminstrative Tools -> User Manager and for the CC side use Settings -> Control Panel -> Services -> Atria Location Broker. The passwords need to match so that CC can run the albd services for you.
NOTE: The Windows user used as for the albd service doesn't have to actually be called clearcase_albd. It can actually have any name you want. For example, if many projects share a single Windows domain and the projects have separate CC Admins, each admin would know the password to all other projects if they all shared the same albd account. For that reason, if projects have tight security requirements, they should use separate albd accounts -- something like "ProjectX_albd". Same is true for the "clearcase" group. As long as the Atria Location Broker daemon has a valid logon, that's all that's needed.

WARNING! DO NOT use a regular user's account in place of the albd account. If that person leaves and IT needs to deactivate the account, you'll have a devil of a time trying fix your VOBs.

On Unix, albd information is logged in /var/adm/atria/log/albd_log and on Windows in Start -> Programs -> Administrative Tools (Common) -> Event Viewer -> Log -> Application which can be accessed via the ClearCase Home Base -> Administration -> Log Browser -> albd. See cleargetlog on either platform.

Table of Contents





Lock and unlock objects.
Updated: 01/10/12
Locks can be placed on most any type of CC object: VOBs, types, elements, storage pools, etc ... The examples below give just a few of the possibilies. Locked objects can still be viewed, just not modified. Cannot lock views.
  # ct lock element
  # ct lock vob:vob-tag
  # ct lock lbtype:label-name
Some useful options:
-obs.olete Locked object no longer appears in any listings, but can still be unlocked.
-nus.ers   login-id(s) List users that the lock does not apply to.
-rep.lace Move the lock from one version to another.

Unlock
To unlock an object, simply use the following. If the object isn't locked, cleartool will throw an error. To avoid the error message, first test the lock status.
	$status = `cleartool describe -fmt "%[locked]p" object-selector`;
	if ( "$status" eq "locked" ) {
		`cleartool unlock object-selector`;
	}
NOTE: Locks are not recursive. That is, if you lock a directory, only the modification of that specific directory element and none of its subdirectories will be affected. View private files are not affected by locks, only CC elements.
NOTE: Locks don't always the effect you intend. For example, if you lock a UCM project, it only locks the project definition itself. Users can still join and use the project.

Listing locks
  # ct lslock [pname]
Some useful options:
-local List the lock state of the local copy of a global type.
-l.ong Expands the listing to include times and users.
-s.hort Only list the names of the locked object(s).
-fmt   format-string See fmt_ccase in the CC Reference Manual for output formatting options.
-obs.olete Include obsoleted objects in the listing.
-a.ll List all objects containing pname.

Lock and unlock with CAL
Note that to unlock something, you need to get the lock object applied to it. To lock something, you need to get the object being locked.
	$lock_o = $vob_o->TriggerType("TriggerName")->Lock;
	if ( "$lock_o" ne "" ) {
		print "\tUnlocking\n";
		$lock_o->Remove;
		if ( Win32::OLE->LastError ) {
			print STDERR "\n$script ERROR: Unable to unlock the \"TriggerName\" trigger type.\n".Win32::OLE->LastError;
			exit 1;
		}
	}

	print "\tLocking\n";
	@exclusion_list = ("Me","Myself","I");
	$trtype_o = $vob_o->TriggerType("TriggerName");
	$trtype_o->CreateLock("",0,\@exclusion_list);
	if ( Win32::OLE->LastError ) {
		print STDERR "\n$script ERROR: Unable to lock the \"TriggerName\" trigger type.\n".Win32::OLE->LastError;
		exit 1;
	}
Table of Contents



Change event record comments.
If there is an error or omission in the comments tied to an event, they can be changed using the chevent subcommand. That is, the comment prompted for during file creation, checkout/in, etc ... can be modified at any time. This command does not create event history about itself. This command is not ISO9000 compliant.
  # ct chevent -option object-selector

ex: ct chevent -insert -c "This eltype is for Word docs." eltype:word_doc
The options are -replace, -append (default) and -insert (at beginning of text). If the object is given as element@@ or as an object-selector (as in the example above), then the object's creation event record is modified.
You can also refer to an object by event-id. Event IDs can be determined via the lshistory subcommand. For example, to remove the comment from a particular version based on its event-id:
  # ct lshistory -eventid element
  # ct chevent -replace -nc -event event-id
Table of Contents



View CC logs.
Use the subcommand getlog and its associated options to view selected portions of the CC logs. The following are just a few of the possible uses for getlog.
What logs are available?  The log name is the leftmost column.
  # ct getlog -inquire
"vob" log entries since Wednesday for the admin vob.
  # ct getlog -vob admin -since Wed vob
Last 100 lines of the "view" log.
  # ct getlog -last 100 view
The subcommand "cleargetlog" will execute "getlog" with a   -graphical   option. The UNIX logs are located in /var/adm/atria/log. This has been obsoleted as of CC 4.1.
The Windows install has a Log Browser that can be accessed via ClearCase Home Base -> Administration -> Log Browser, which essentially runs cleargetlog.
General MVFS information is logged in a location called "Logging Path:"; default is "C:\mvfslogs".
The license file -audit option writes to /var/adm/atria/log/albd_log on UNIX and on Windows, Start -> Programs -> Administrative Tools (Common) -> Event Viewer -> Log -> Application.

Table of Contents





Collect info for Rational support.

clearbug

The clearbug command lives in /usr/atria/bin on UNIX. On Windows, the executable is cc-home\etc\utils\clearbugnt.exe.
On UNIX, execute it with a view already set and inside the vob having the errors. Output is sent to standard out and to a file called clearbug.log.date.time, so there's no need to explicitly redirect the output.
On Windows, once it has been run, in the dialog that pops up, save the output to a file. Send the .nfo file to Rational Support.
  # clearbug | clearbugnt
On both UNIX and Windows, use the -help option to get usage information.

ClearCase Doctor

Run the Windows only ClearCase Doctor and select Analysis->Save As. The GUI can also be invoked from the CLI via ccdoctor.exe.

memory dump

For any system, remember that the drive that %SystemRoot% is on needs at least a pagefile that is equal to physical memory in the machine to successfully write the .dmp file. This section is only necessary if you're having very serious problems, such a system crash when using CC.
On Windows, right-click on My Computer and choose Properties. Select the page STARTUP/SHUTDOWN. On that page there is a RECOVERY section that enables the user to do the following:
A>* Write and event record entry to the system log upon crash
B> Send an administartive alert(if needed) Especially helpful on a DC
C>*** Specify the location of where the .dmp file will be writen (default= %SystemRoot%\MEMORY.DMP)
D> Overwrite that file on subsequent crashes
E> Automatically reboot
Note that Windows Server 4.0 is set to write event log messages by default and Windows Workstation is not.
On Windows 2000, right-click on My Computer and go to Properties. Select the Advanced Tab and go to the STARTUP and Recovery... button. On this page enable the following:
A>* Write an event to the system log
B> Send an administartive alert(if needed) Especially helpful on a Domain Controller
C> Automatically reboot
D> Select "Complete Memory Dump" in the "Write Debugging Information drop down menu while noting the location of where the .dmp file will be writen (default= %SystemRoot%\MEMORY.DMP)
E> Overwrite any existing file
Submit Data contained in the event log message to Rational Support. The description and format of the event log differs from the format displayed when the computer is writing the Memory.dmp file, but the majority of the information is the same.

winmsd

Table of Contents





Get information about CC objects.
In UNIX xclearcase, select an element and go to Report -> Describe.
In Windows, right-click on an element and go to ClearCase -> ClearCase Explorer.
From the CLI:
The describe subcommand:
These are just a few of the describe options available.
Describe the current VOB:
  # ct describe -long vob:.
Describe a label type using a type selector:
  # ct describe -type lbtype:label-name
-or-
  # ct describe -type label-name
Describe a particular version of an element:
  # ct describe -long -version /branch/version-number element
Retrieve the unique database identifier for this object:
  # ct describe -fmt "%Dn" object
The   -fmt   option gives you the ability to request many different specific pieces of information about objects: unique database identifier, leaf name (version), user name, group name, age, host, predecessor, etc... You can use the "cleardescribe" command in place of "describe -graphical".
  # cleardescribe object
The describe subcommand will work on view-private files but cleardescribe will not.
NOTE: As of CC 4.0, the describe command will work on non-CC files.

The cleardetails command:

On Windows you can run "cleardetails" from the command-line. It will bring up a GUI that looks like the Windows Explorer but has buttons and menu options specific to CC. The CC Details can also be accessed by right-clicking on an element in the Windows Explorer and choosing the ClearCase -> ClearCase Details option. This GUI gives information similar to a "ct ls" from the CLI. NOTE: This is obsolete as of CC 5.0/2002.

The mvfsstorage command:

This will return the view or VOB storage location (container) for an element. The command is located in the atria-home/etc directory. If you need to find the actual data container location, use dump. In a view context, mvfsstorage most often only reports the cleartext location.
  # mvfsstorage element
The dump subcommand:
This command gives details about inodes, creation times, data containers, etc ... It doesn't have a man page. However, "ct help dump" will give you the syntax. You will get "Error: Not a vob object:" if the element is view-private.
Note that OIDs will be different for the element object and its versions. Each version has its own oid too.
  # ct dump element
The ls subcommand:
The ls command will tell you which version of an element is currently being selected by the view and which rule was used to select it.
  # ct ls element
Use the   -vob_only   option to show only those files in VOB storage. Use the   -view_only   option to show only those files in view storage. CHECKEDOUT files will show up with both options.
  # ct ls -vob_only             foo.c@@ [eclipsed by checkout]
  # ct ls -view_only            foo.c@@
The "ct ls -recurse" command will not follow symbolic links.

The lshistory subcommand:

In xclearcase, select the object, Report -> List history.
In Windows CC Explorer, select the object, Tools -> History.
The GUI can be invoked from the CLI via stand-alone clearhistory command.
From the CLI:
  # ct lshistory object-selector
Some useful options:
-g.raphical Generate a display that would have been shown through a GUI.
-min.or List minor events.
-eve.ntid Show the event IDs of each event.
-sin.ce   date-time List events since a certain date-time
-use.r   username List events by a certain user.
-bra.nch   branch-name Restrict the listing to events pertaining to a certain branch.
-l.ong Expand the listing to include event details.
-s.hort Restrict the listing to just version names.
-fmt   format-string Format the output to taste.   See fmt_ccase in the CC Reference Manual.
-r.ecurse Process the entire sub-tree.
-d.irectory List information on a directory itself, not its contents.
-nco Exclude checkout events from the listing.

The annotate subcommand:
See List details about the contents of an element version.

The lsvtree subcommand:

This subcommand will display all the interesting versions of an element. Interesting is defined as branch points, labeled versions, LATEST, etc... Use the   -all   option to display all versions, interesting or not.
  # ct lsvtree element
The graphical version of lsvtree that can be accessed by right-clicking on an element and choosing Version Tree. The Version Tree Browser can then be used to manipulate the element. The little flashlight (Locate) lets you get information about any version, labels or attributes of an element. The Browser will even let you print the version tree.
A similar interface is available on UNIX from the CLI using the -graphical option or from xclearcase by clicking on the toolbar button that looks like a tree.

The file subcommand:

The "file" subcommand, which is new in CC 4.0, is similar to the standard UNIX "file" command. It will return either the element type that would be assigned if added to source control or the element type currently assigned if already under source control.
  # ct file { element | view-private-file }
Options:
-invob   vob-tag Compare potential element types with those in vob-tag. Default uses current VOB.
-all Skip the comparison with the available types in the VOB and list all matched in the magic file.

Table of Contents





Get information about the a CC host.
Updated: 02/15/16
Version: 7.1.2.14

This subcommand gives limited information about the current CC host (not necessarily the server). The hostname given can be ANY computer running CC that can be seen by the current computer. The default is the current computer.
  # ct hostinfo -long
  # ct hostinfo hostname
NOTE: The "hostinfo -l" command will tell what version of CC is installed, but don't confuse that with the ALBD service running on that host. That ALBD service does not need to be running for that command to return information.

Table of Contents





Get information about CC commands/man pages.
In Unix xclearcase, Help -> Apropos...
In Windows CC Explorer, Help -> Help Topics -> Find
On the command-line (UNIX only):
  # ct apropos string
Though running the same command, the GUI and a -glossary option on the command-line give a subject listing vice a command listing. As of CC 2003.06.00, the -glossary option is no longer supported.
If the command is known:
  # ct man command   (UNIX or Windows)
-or-
  # man ct+command   (UNIX only)
Table of Contents



Create command aliases.
In UNIX, simply add lines similar to the following line to your login files:
.cshrc
  alias ct cleartool
.profile
  alias mt=multitool
In Windows:
NOTE: Do not simply copy cleartool.exe to ct.exe because ct.exe will not get upgraded if there is ever a reinstall or upgrade done. Instead, create an alias file akin to UNIX's .cshrc file called alias.bat in a common directory; most likely C:\bin. Place the following line in it:
  doskey ct=cleartool $*
  doskey mt=multitool $*
Also in the same directory, create a cmd.bat file called cmd.exe with the alias file's customizations:
  cmd.exe /q /k C:\bin\alias.bat
-- or --
  cmd.exe /q /k alias.bat    (if C:\bin is in your path)
Next, create a shortcut to the cmd.bat file on your desktop and use it to invoke any command prompts you may need. Rename the shortcut to something like "my-DOS". You can now use the alias.bat file to see all your command-line aliases, not just the cleartool one.
To get CC-invoked command-lines to see the same aliases, go to ClearCase Home Base -> Options -> User Preferences -> Explorer and change Command Prompt to C:\bin\cmd.bat (or simply cmd.bat if C:\bin is in your path). Alternatively, one can invoke "cleardlg /options" from the command-line to get to the same preferences GUI.

Table of Contents





.clearcase_profile
This file is placed in a user's home directory by the user to make common ct subcommand comment options (-c, -cfile, -cq, -cqe and -nc) their personal defaults. This file, much like a config_spec, is a set of ordered rules. That is, it goes down the list in order until a rule satisfies the operation and then it exits. Unlike a config_spec, there is no compiled version of the .clearcase_profile. Because of the ordered aspect of the profile, care should be taken in placing lines.
For instance, if one never wants to be prompted for a comment except at the initial creation of an element, the following order of rules would need to be adhered to:
mkelem  -cqe
*       -nc
NOTE: This file will not override a trigger.

Table of Contents





Customize a Windows context menu.
Updated: 09/12/12
Version: 7.1.2
On Windows, you can customize the "right-click" (context) menu for CC objects in the Windows Explorer and/or CC Explorer.
The editor can be launched from the ClearCase start menu as "Context Menu Editor", or from the CLI as the standalone "clearmenuadmin" command.

1) To edit a menu, select the application from the Application menu up top, select an object in the "Object Type" pane, select that object's state in the "Object State" pane, and then click the New button midway down the page. The "Menu Text", "Command Type", and "Command" are mandatory fields.
Menu Text The text that shows up when you right-click on the object.
Help Text This text shows up in the lower-left corner of the CC Explorer when the mouse is over that menu item.
Command Type See the builtin "Using Context Menu Editor" help.
Initial Directory Set the initial directory where the command is run. Note that $dir doesn't get set in the CC Explorer. The initial directory defaults to the parent directory of a snapshot view root and M:\ for dynamic.
Command Something like "ccperl" or other executable. The actual script it runs is set in Arguments.
Arguments Anything that is passed to Command as if you were running it from the CLI. Note that any builtin arguments, such as $viewtag must be listed after any others that you may place there. Example: "\\box\share\bin\script.pl default $viewtag". The selection for $dir is for the parent directory of the element. The selection for $file will work for any element, file or directory.
Comment Administrative comment that doesn't show up anywhere for a user, but the "Menu Text" followed by this Comment show up at the bottom of the main editor window.

2) Once the parameters are set, test the customization. Select your new menu option in the "Available Menu Choices", use the Browse button at the bottom to select an appropriate object, and then click Test.

3) Once you're satisfied with the execution, select the new menu item and Add it to the menu in the "This Menu Contents" pane.
4) Once you're satisfied, select Apply under the Configuration menu up top.

NOTES:
1) The "Available Menu Choice" just created was only customized for the Application selected in step (1). To make that choice available in the other application, you'll have repeat all the steps after selecting the other application from the Application menu up top. Basically you have to do it from scratch for each application.
2) The customizations can be saved to a file by selecting "Save to File" under the Configuration menu. That file can be referred to during an installation site prep so that the customizations show up for all users that install from that release area. Each application needs to be saved in its own registry file.
3) When the Apply button was selected, registry entries were created on the local box. The definitions for the customizations are in HKEY_LOCAL_MACHINE\Software\Atria\ClearCase\CurrentVersion\ContextMenus. Note that the information is for the whole machine. However, to make the customization available to any particular user on that machine, while the user is logged in, open the Context Menu Editor, Configuration->Load from File. Once loaded, select Configuration->Apply. Do this for each application file and then close the Menu Editor.
4) If a custom shortcut menu option is added to a dynamic view itself, that new customization will only show up when you right-click on the view under the MVFS drive (usually M:), and not if the view is mapped to its own drive letter. Unknown reason why.
5) When a customization is applied using the Context Menu Editor, identical registry entries are added to HKEY_LOCAL_USER and HKEY_LOCAL_MACHINE. If you want to adjust the parameters, the change must be made through the tool and then click Configuration -> Apply. The system will pick up the HKEY_LOCAL_USER entry first and then possibly HKEY_LOCAL_MACHINE. If HKEY_LOCAL_USER entries exist, changes to HKEY_LOCAL_MACHINE have no affect. If you make manual changes to HKEY_LOCAL_USER, be sure to add them to HKEY_LOCAL_MACHINE as well, but note that other users on the same machine will continue to use old parameters from their HKEY_LOCAL_USER entries. The best thing to do is to make parameter changes in the Context Menu Editor, export to a file, and distribute the new registry file to users. Note that both the ClearCase Explorer and Windows Explorer registry files can be combined into one and renamed for convenience.
6) If the registry entry for either interface is updated manually (not from the Context Menu Editor), then the tool needs to be restarted. If the change is pushed from the Context Menu Editor, the tool does not need to be restarted.
7) If you manually update the registry file that has the context menu definitions, and if you add a path to something, on Windows be sure to include double (escaped) back-slashes.
8) WARNING: As of CC 7.1.2 there is a bug in the $filelist parameter that passes the list of chosen files into your script. The list will be truncated if there are any spaces in the path or file name. For example, if the user attempts to add "New Folder" to source control, that variable will contain "M:\myview\myvob\New".
9) When saving the configuration, if you choose the "Multiple Selection" option, be sure to also set up the new menu choice for "Single Selection" as well. Mutiple selection does not imply that single selection is included; they're two distinct configurations and context menus.

Table of Contents





Performance tuning.
In general, the CC Admin Manual has a section called Tuning for Performance.

Performance Assistant

This tool is an undocumented, unbundled, unsupported tool for monitoring system and CC performance. The onboard help describes its usage. System administration knowledge of the system being tested is essential.
On UNIX, untar the ha* file as the root user in the / directory of any machine to be monitored. This is the data gathering portion and will place files in /usr/atria and /var/adm/atria. Then, create a directory called java in the home directory of any user on a client machine in the same region as the machines to be monitored. Untar the client* there and run perfasst.sh. Do not run the Performance Assistant client from a machine being monitored, as it places a CPU overhead on the machine on which it is running.
On Windows, execute the self-extracting executables in the following order: ha*, jre*, client*. If the default install locations were used, ignore the Notepad that comes up to edit the hostagent.bat and perfasst.bat files.
The executables need be obtained via your local Rational Tech Rep and/or Rational Tech Support. However, the executables are not being updated by the Rational engineers and will only work on CC up to 4.0.

top

The UNIX only "top" command will show a listing of the top running commands on a system along with CPU usage statistics. It doesn't come bundled with UNIX operating systems, so must be downloaded from the web.

Data gathering with SCS.

Run the UNIX-only SCS from any directory on a machine being monitored. This is an unsupported, unbundled clearcase tool. It will gather system information for Tech Support. You can also look inside it to find useful commands to run yourself.
  # SCS | tee SCS.log.`date +"%d-%b-%y.%H:%M"`
See SCS.html for more info.

Look at timing.

Run the standard "ping" command. Ping times between clients and server must be <10ms for optimal performance. CC is still workable when ping times average 30-50ms per ping, but anything higher than that will probably be too slow, especially for UCM.
Run mvfstime (lives in atria-home\etc). When analyzing a given command's performance, run the following sequence:
  # mvfstime CC-command
  # mvfstime creds
  # mvfstime clearlicense
  # mvfstime nslookup VOB-server

ping

The standard "ping" command is available on all operating systems. However, when used alone it doesn't give an accurate picture of performance in a CC network. While the round-trip ping time is important for good response times, there are VOB, view, registry, license, DNS, DHCP, domain controller, etc... servers all being queried for information. Any one of those could be a bottle-neck for some reason.
So, while ping will let you know if the network itself is responding, don't rely on it solely as an indicator of the CC network's health. Ping times of around 10ms are desirable. Base CC can tolerate higher round-trip times than CC UCM, which tolerate higher round-trip times than CC/CQ UCM. Raise a red flag if ping times exceed 30ms.
Your best ping type of performance check for the purpose of metrics is to run an innocuous checkout/uncheckout pair every 10 mins or so from a script. Record the amount of time to complete the checkout. Run the script for a couple weeks.
You can also run a tool, such as Ping Plotter to monitor ping times over a long period of time.

clearping

Run the UNIX-only clearping both on the machine that owns the view-storage and then again on the machine that owns the VOB (if they aren't the same machine). It will gather data about the interaction between the view and VOB being used to do a build (that is presumably slow). This is an unsupported, unbundled clearcase tool.
  # clearping -view view-tag -vob VOB-tag | tee clearping.log.`date +"%d-%b-%y.%H:%M"`
Some useful options:
-count   n How many times should the ping run?   (default 10)
-name Only give the names of the host servers.
-verbose When pinging, don't filter the output.

clearbug

Run the UNIX only clearbug command to gather general information about a system on which clearcase is installed. It needs to be executed with a view set inside a VOB that presumably is having the errors or is running slow builds. Output is sent to standard out and simultaneously to a file called clearbug.log.date.time. This is a standard, bundled clearcase command in /usr/atria/bin.
  # clearbug
Some useful options:
-short Suppress the instructions if you've been there, done that.
-l   logfile Send output to logfile instead of clearbug.log.date.time.

lockmgr (Lock Manager)

If you have a large number of VOBs on your server, adjusting lockmgr parameters is probably a good idea. Each VOB server runs one database lock manager that arbitrates data requests from clients. Unlike most other CC processes, the lockmgr is not started by albd. The lockmgr communicates with other processes; namely db_server & vobrpc_server. On Unix, that is accomplished through the shared-memory file /var/adm/atria/almd, which should be owned by root. Using the "top" command on UNIX or the "performance monitor" on Windows, determine if the lockmgr process is using in excess of 50% of the CPU at any moment. If so, lock manager startup parameters can be changed to improve performance. If these parameters are adjusted, stop and restart CC afterward. The command arguments (UNIX) or registry key string value (Windows) is of the form "-a almd -u <value> -f <value> -q <value>". On UNIX, lock manager startup parameters are defined in the startup script, /usr/atria/etc/atria_start. To change these values, look for and edit the line containing ${ATRIA}/etc/locklmgr. Save that file in a CC VOB somewhere, as it will most likely be overwritten when CC is next upgraded. On Windows, lock manager options are set in the registry. In HKEY_LOCAL_MACHINE\SOFTWARE\Atria\ClearCase\CurrentVersion, edit LockMgrCmdLine. If it doesn't already exist, create a new string key with that name.
As an alternative to adjusting these parameters, consider moving some VOBs to a different server, as too many VOBs on one server can have other performance affects aside from lockmgr parameters.

-u <value>
This specifies the concurrent number of db_server and vobrpc_server processes that can request locks. Each active view requires one vobrpc_server process for each VOB that the view accesses. Any operation that requires a change in VOB metadata requires a db_server process. The defaults are 128 (Windows) and 256 (UNIX). The absolute worst case scenario value can be computed as V*(N/4+5), where V is the number of VOBs on the server and N is the number of users accessing those VOBs. However, setting that value too high will cause the lockmgr to comsume unnecessary amounts of memory. Set your -u value at approx 30% (1/3) of the worst case value just calculated. On hosts, such as Windows, that do not employ a shared-memory lock manager, this value should not exceed 1018. On other hosts, it's limited only by the available virtual memory.

-f <value>
This specifies the number of database files that can be concurrently open. The defaults are 128 (Windows) and 256 (UNIX), which is enough for 18 VOBs on Windows and 36 VOBs on UNIX. Set the value to 7*V, where V is the number of VOBs on the server.

-q <value>
This specifies the number of lock requests for locks to be queued. The lock manager will not queue lock requests in excess of this value. It should be set to approx 3-4 times the -u value, but not to exceed 5 times.

As of 2012, simply set the parameters to "-a almd -f 1018 -u 1024 -q 2048" as a standard setup for a VOB server.

Change the PATH environment variable.

Ensure the bin directory (/usr/atria/bin on UNIX or %ATRIAHOME%\bin on Windows) is near the front the path definition. Also, on Windows, make sure there aren't two semicolons together ";;", this will cause the path to be read twice.

Network considerations.

If possible, have all CC servers and clients on the same subnet. Going through routers takes a bit of time per transaction. On Windows, if running one subnet, place NetBEUI before WINS Client (TCP/IP). On UNIX or Windows, if more than one subnet, add them to the routing table to ensure direct routing. For example, if 123.446.78 is one of the other subnets,
  # route add -p 123.446.78. mask 255.255.255.0 your-hostname
If possible, have view and VOB servers electronically next to each other.
If there is more than one DNS server in your lookup list, make sure they both can be reached in a timely manner. That is, even though DNS will try the next one in the list if the first one listed is defunct, that action takes time.
Add the hostname and IP address of known servers, such as VOB, view, license, and registry, to the client's "hosts" file (/etc/hosts on UNIX and C:\WINNT\system32\drivers\etc on Windows). This will circumvent the need for DNS.
If using multiple domains, read Rational's white paper entitled "Windows Domains and ClearCase" for details.
Turn off "bus mastering" for PCI cards. Increase the cache size of other cards to at least 64k.
Make sure no CC servers are running screen savers or other unnecessary programs that eat up resources.

UNIX mvfs_largeinit

On Windows, the MVFS scaling factor is set in the CC Control Panel applet, but the discussion below is largely the same. See the Adjusting the MVFS Memory Initialization Factor in the CC Admin Manual.
This MVFS cache tuning is mostly a view-server consideration.
The resource that affects the value of mvfs_largeinit is the amount of memory on the system. The number of CPUs isn't relevant. One general rule of thumb is to set the value of mvfs_largeinit to be equal to the number of GBs of memory on the server.
Setting a value too high can result in a degradation in performance instead of an increase. Various caches, tables, and other data structures in the MVFS get initialized and sized based upon the value of mvfs_largeinit. Setting a value too high can increase the time it takes to search hash tables and linked lists and results in a single process grabbing the lock to search the list and other processes then queuing up behind that process while it searches the list.
The setting for mvfs_largeinit drives the default settings for:
- size of the mnode table
- high and low water marks for the mnode freelist
- high and low water marks for the cleartext (Cltxt) freelist
- size of 3 directory name caches (DNC)
- size of the RPC client handle pool and for ClearCase 5.0 and beyond
- sizes of hash tables used in managing some of the above structures
The algorithms for sizing the various MVFS data structures increase quickly with small increases in mvfs_largeinit.
On single-CPU systems the cost is mainly in dedicating memory to the MVFS that might have been better used by another portion of the system.
On multi-CPU systems, when tables and lists are searched or modified they are locked to prevent changes by another kernel thread running on another CPU. Time spent searching large tables and lists with locks held can significantly impact throughput. On multi-CPU systems, the cost of larger size tables and lists becomes too great when the contention for the locks begins to interfere with throughput.
How to pick an initial value for mvfs_largeinit:
The initial value for mvfs_largeinit should be based largely on the amount of memory available on the system so that CC will be dedicating a reasonable amount of memory to our data structures. Starting in CC 5.0/2002, mvfs_largeinit is set automatically based on the size of system memory. The algorithm is (max value mvfs_largeinit will be automatically scaled to is 24):
mvfs_largeinit setting for available memory
0 < 24 MB
1 > 24 MB & < 2GB
2 >= 2 GB
For systems running pre-5.0 versions of ClearCase, the recommendation is starting with about 1/2 of the above algorithm. So, for systems with 4 GB memory or more, mvfs_largeinit = (# GB)/2. MFVS performance improvements in CC 5.0/2002 allow for greater values.
Resetting mvfs_largeinit
Simply edit the file. Many sites would want to manage all their machines with the same value for mvfs_largeinit. This is unwise. A system with 12 CPUs may have half the memory of a 24 CPU machine and so is likely to work best with about 1/2 the value for mvfs_largeinit. Remember to restart ClearCase for the new value of mvfs_largeinit to take effect. Note that some UNIX computers require a kernel rebuild for the new value to take effect. See the Platform Specific Guide for details.
One other key area of MVFS tuning is ensuring enough client RPC handles. Once you have set mvfs_largeinit as above and have run the system for a while under its normal ClearCase load, run:
  # cleartool getcache -mvfs
and check the number of RPC handles. This number is reported as max_used_from_pool/pool_size. If the max_used_from_pool is equal to pool_size you should increase the pool_size so that it is a few larger than the pool_size. (The directions for how to do this will be listed in the output of getcache.) Use setcache to reset the parameters. A new option called -persistent in CC 2003.06.00 will ensure cache settings are persistent across reboots.

Block buffer cache size.

For optimal performance on UNIX and Windows, a VOB host should have enough memory to buffer 50% of all VOB databases. If you add up all the db directory (vob-stg-dir/db) sizes of every VOB on a given host and divide by 2, there should be more memory than that value on the VOB server.
To view the performance of the block buffer cache activity on UNIX, the following command will run a check every 60 seconds for 5 times.
  # sar -b 60 5
If your block buffer caches are sized correctly, cache reads (%rcache) are in the 90% to 95% range and cache writes (%wcache) are 75% or above. See also the Platform Specific Guide for UNIX platform specific buffer cache monitoring tools.
The block buffer cache is flushed periodically, which degrades performance. HP-UX has a utility called syncer that can be used to set the periodicity. Larger cache sizes should be flushed less often.

Windows heap size

The Windows operating system reserves a small amount of memory for itself regardless of demand for memory by active applications. If the OS needs more memory than the heap, it will simply use more. However, if memory is fully utilized and the OS can't expand into the shared memory, it's forced to swap memory pages to disk just like the rest of the applications running on the system. If the OS is swapping pages to disk, it can significantly reduce performance. The default heap size on NT 4.0 is 1024 and on Win2K is 512k. However, if the reason you need to increase the heap size is lack of memory, there will be other performance hits on the system other than the heap size. So, in that case, it's time to buy more memory.
Edit the registry to change the heap size. This change requires a reboot of the server. Go to HKEY_LOCAL_MACHINE->SYSTEM->CurrentControlSet->Control->Session Manager->SubSystems. Change "SharedSection=1024,3072,512" to "SharedSection=1024,3072,2048". Do not change any other value than the last one. Reboot.

setcache

The "ct 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.
Increasing dynamic view cache size is marginally useful for normal view user. However, if a particular view is used for large builds, there is a noticeable performance improvement if that view's cache is increased. As of CC 2003.06.00, the default is 400K. Increasing a view's cache beyond 4MB is rarely helpful.
Increasing, or attempting to tune, MVFS cache parameters is tricky. However, most often, first-order performance gains can almost always be made elsewhere, such as defragmenting server disks, etc... That is, put MVFS tuning at the bottom of the list.
See the setcache man page for details.

Windows shortcut menus

One might be able to improve performance by using simpler shortcut menus when right-clicking on an object in the Windows Explorer. To get simpler shortcut menus, go to the CC Explorer->Tools->Options->ClearCase Options->Explorer. The simpler shortcut menu doesn't give the user any useful CC options, but does improve performance when simply right-clicking on an object.

map Windows dynamic views to their own drive letters

Under certain conditions, having a Windows dynamic view mapped to its own drive letter can improve performance when attempting to access that view.

dynamic view storage on local machine

There is a known small performance improvement if the dynamic view storage for a view (Windows and Unix) is created on the machine where the view will be started and used.

lock and obsolete unused objects

Unfortunately, locking and obsoleting unused objects does not improve CC performance itself. Locking an object just prevents somebody from modifying it. Obsoleting an object stops it from showing up in lists and interfaces, such as version tree, baseline explorer, project explorer, etc...

Table of Contents





Invoke the UNIX CC GUI.
The CC GUI is a stand-alone executable that lives in /usr/atria/bin.
  # xclearcase &
If a view is already set when invoked, it will use that one, otherwise it will prompt for one. It will initially display the directory in which it was invoked, even if not inside a VOB. Simply edit the bar containing the path to the current directory to change directories, or double-click on the ../ icon (or text) to surf around one directory at a time.
To switch between the icon and text based displays, File -> Preferences... -> Graphic format

Table of Contents





CC group permissions.
Updated: 08/15/16
Determine/modify group permissions on a view:
Unfortunately, there are no straight forward commands that can change the group permissions for a view. One must create a new view to get different group permissions. If absolutely needed, call Rational Tech Support for a procedure on how to change permissions without creating a new view. In UNIX, the group permissions on a view are determined by your primary group (id) and the value of your umask. In Windows, group permissions are set by the CLEARCASE_PRIMARY_GROUP enviroment variable with Full Control given to that group and read/execute to others. However, on Win2k PDCs, a primary group can be set at the domain level, alleviating the need for that environment variable. For UNIX/NT views, read/write access can be changed via chview.

Determine the groups allowed to create objects in a VOB:

In Unix xclearcase, Report -> Describe -> VOB.
In Unix/Windows clearvobadmin, Start -> Programs -> ClearCase Administration -> VOB Administration Browser -> select-VOB -> Edit -> VOB Properties... -> Permissions (obsoleted as of CC 4.1).
In CC Administration Console (ccadminconsole Windows only, new in CC 5.0/2002), unknown if it's possible.
From the CLI:
  # ct describe vob:VOB-tag
Determine your CC primary group:
On UNIX
  # id
On Windows
  # echo %CLEARCASE_PRIMARY_GROUP%
  -or-
  # %ATRIAHOME%\etc\utils\creds
  -or-
  # gpresult /r
On Windows, the creds command picks up on the CLEARCASE_PRIMARY_GROUP environment variable or the group assigned as primary at the domain level (Windows). A primary group can be assigned at the domain level in later Windows server operating systems. To get a deeper listing, add a "-A" option. The creds man page doesn't list the available options, but "creds -?" will at least list them.
WARNING! The creds command will take a username argument as well. However, up to at least CC 5.0/2002, the primary group will incorrectly show up as "None". Therefor, only use creds to verify the user that is currently logged in. This has been reported to Rational as a bug.
To verify that your Windows primary group maps correctly to a valid Unix group in an interop environment:
  # %ATRIAHOME%\etc\utils\credmap UNIX-server
On UNIX, credmap information is logged in /var/adm/atria/log/credmap_log and on Windows in Start -> Programs -> Administrative Tools (Common) -> Event Viewer -> Log -> Application which can be accessed via the ClearCase Home Base -> Administration -> Log Browser -> credmap. See cleargetlog on either platform.
NOTE: If CLEARCASE_PRIMARY_GROUP is a newly set environment variable and you aren't seeing it correctly in the creds or credmap command, try starting a new DOS window. If you can't see it still, try flushing the CC cache and starting a new window:
  # %ATRIAHOME%\etc\utils\phash -f
If you STILL don't see the environment variable set, try logging out and then back in.

To change your primary group:

In UNIX:
  # newgrp group
To permanently change your primary group in UNIX, the 4th field of your login in the /etc/passwd file must be changed to the new group's GID. NOTE: be sure to place your login name in the old group's list in the /etc/group file to ensure you remain a member of the old group even if it's no longer your primary group.
In Windows, Start -> Settings -> Control Panel -> System -> Environment
Set/modify the CLEARCASE_PRIMARY_GROUP environment variable. In Windows 95/98, set CLEARCASE_PRIMARY_GROUP in AUTOEXEC.BAT.

To modify the group of an element:

  # ct protect -chgrp element
If modifying the group of an element, the group to which you are changing the element must be in the VOB's group list and it must be your primary group.

To modify a VOB's group list you must have root/Administrator privileges or be a member of the special Windows "clearcase" group:

  # ct protectvob  -add_group group-name  vob-storage-dir
-or-
  # ct protectvob  -delete_group group-name  vob-storage-dir
-or-
  # ct protectvob  -chgrp group-name  vob-storage-dir
NOTE: There are limits to the number of additional groups that can be added to a VOB's list. On most UNIX systems the limit is 16. However, on some systems that limit can be increased by changing the NGROUPS_MAX kernel variable. The limit on NT is hardwired at 32. If a user belongs to more than 32 groups, only the first 32 will be recognized. In CC 4.2, one can use the CLEARCASE_GROUPS environment variable to set which 32 groups are recognized. See https://www-304.ibm.com/support/docview.wss?uid=swg21124574 for additional information.

Change the server process group.

CC runs under a specific group. That group is more than just the primary group assigned to newly created VOBs and views. Unfortunately, that group name gets imbedded in view and VOB storage areas upon creation. If needs to be changed, the following steps must be performed. Yes, this needs to be run locally on EVERY machine that has a view or VOB storage.
1) Update the following registry key.
HKEY_LOCAL_MACHINE\SOFTWARE\Atria\ClearCase\CurrentVersion\ClearCaseGroupName
-or-
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Atria\ClearCase\CurrentVersion\ClearCaseGroupName
2) Reboot.
3) Run the following on EVERY view and VOB storage. Apparently it picks up on the registry entry so that you don't have to specify the group name on the CLI.
	<ccase-home>\etc\utils\fix_prot -replace_server_process_group   <storage-area> 
4) Run the scrubber on the VOB cleartext pools.
	<ccase-home>\bin\scrubber  -e  -k cltxt  <vob-storage-area> 

Table of Contents





Schedule jobs.

at, winat

The "at" command can be used to schedule jobs on both UNIX and Windows. However, the UNIX "at" command only runs once, whereas the Windows "at" is used to schedule repetitive jobs. See "cron" below for scheduling repetitive jobs on UNIX.
On Windows, you must have administrator privileges to run at or winat and the Windows Schedule service needs to be running. The "winat" command is the GUI equivalent of "at" and is only available if the Windows Resource Kit is installed.
From the CLI:
  # at 8:00PM /every:m,w,f C:\bin\MyBatchFile
On UNIX, "at" jobs can be scheduled by anyone.
  # at 0730 tomorrow
  at> MyScript
<CTRL-D>
Until they are run, "at" jobs are stored in /var/spool/cron/atjobs.

crontab

On UNIX, repetitive jobs can be scheduled by anyone via the "crontab" command. Simply invoke "crontab" from the CLI with one of the following options:
-e Edit your crontab file.
-l Simply view your crontab entries.
-r Delete your entire crontab file.
The crontab files are stored in /var/spool/cron/crontabs under your user name. You are not allowed to even look at crontab entries there; readable only by root. Crontab entries are similar to the following, which is an example of the weekly ClearCase cron job run by root (see the crontab man page for details):
30 0 * * 0 /bin/sh /usr/atria/config/cron/ccase_cron.wk

disprun (obsolete as of CC 5.0/2002)

On UNIX, who runs a certain command is controlled by whose crontab file owns the entry. On Windows, if one needs to run a job and have it run as the special user called clearcase_albd, it needs to be invoked via "disprun". The disprun utility simply runs the specified command as clearcase_albd.
  C:\> at 8:00PM /every:m,w,f <ccase-home-dir>\bin\disprun C:\bin\MyClearCaseBatchFile

Windows Scheduled Tasks

On Windows, you can schedule any executable to run at specified times. For example, to automatically import CCMS packets from a custom folder (instead of using a special shipping class), add a line similar to the following to a .bat file.
	@echo off
	multitool syncreplica -import "C:\project_folder\incoming"
Then create a task that calls the batch file using Programs -> Accessories -> System Tools -> Scheduled Tasks (Windows XP).

schedule

CC 4.x has a job scheduler utility that eliminates CC's dependence on "at" and "crontab". It is available on any Windows or Unix box running ClearCase 4.0+. The scheduler relies on two data repositories. One is a database of available tasks and the other is actually scheduled jobs. Jobs must be entered into the tasks database before they can be scheduled. The task database is in scheduler/tasks/task_registy in /var/adm/atria on Unix and <ccase-home-dir>\var on Windows. This is also where ccase_local_day and ccase_local_wk now live. The task database can be edited using any standard editor. Once in the database, they are available to be scheduled. The standard tasks that CC runs live in <ccase-home-dir>/config/scheduler/tasks on both Unix and Windows. Don't edit them! The actual scheduled jobs live in scheduler/db in /var/adm/atria on Unix and <ccase-home-dir>\var on Windows. This is a binary file that can only be viewed and edited using the schedule command.
The schedule command maintains a single ACL regarding the read/write aspect of job scheduling and of read/write to the ACL itself. The default ACL entry is "Everyone: Read". Use the schedule command itself to set its ACL. Initially, the ACL can only be changed by root on Unix or a member of the "clearcase" group on Windows.
  # ct schedule -get -acl
  # ct schedule -edit -acl
The first column can be one of the following. There can't be any spaces between a Group or User entry and its arguments. For example, "Group: acme.com\users" is invalid. It won't complain about the syntax, but it won't recognize Group either.
Identity Qualifier Example
Everyone   Everyone:
Domain Domain-name Domian:acme.com
Group Domain-name\group-name Group:acme.com\users
User Domain-name\user-name User:acme.com\fred
The second column can be one of the following:
Access Type Access to "schedule" Access to ACL
Read read only read only
Change read/write; can start jobs read only
Full read/write; can start jobs read/write

Entries in the editable (any editor) task registry take the form:
Task.Begin
    Task.Id:       <task-id>
    Task.Name:     <name-string>
    Task.Pathname: <pathname>
    Task.UIInfo:   <ui-info>
Task.End
The Task.Id is any integer unique among the task IDs. Tasks that you create must have a Task.Id or 100 or more. All Task.Ids 99 or below are reserved. The Task.Name can be any unique string. The Task.Pathname is the full path to your task. If the full path is not given, it is assumed to live with the common CC tasks (<ccase-home-dir>/config/scheduler/tasks). Both the Task.Name and Task.Pathname can contain spaces as long as they are double quoted. The Task.UIInfo line is a string describing the task's CLI and is used exclusively by the pre-defined CC tasks. That is, don't use it for custom tasks. Entries in this file must occupy a single line and are case-sensitive. Comments with "#" are allowed.

The schedule command has several uses depending on the arguments. All of the forms have the following two options in common:
-f.orce Suppress any change confirmation.
-hos.t   hostname Specify a host other than the current.
1) Display information about jobs, tasks, or protection (ACL):
  # ct schedule -get
The following four options are mutually exclusive:
-sch.edule Default: show jobs using the the job definition language.
-job   job-id-or-name List only the job specified by its Job.Id or Job.Name.
-tas.ks List the tasks in the task registry.
-acl Display the scheduler's ACL.
To have the scheduler send notifications, in "ct schedule -edit", reset the "Job.NotifyInfo.Recipients" entry to have a comma-separated list of email addresses.

2) Edit a schedule or ACL. Optionally, the schedule or ACL can be set from a file. Note that when adding a new schedule, the scheduler will automatically give it a new Job.Id when you exit. That is, don't place a Job.Id line in your new scheduled job. See the CC Reference Manual "schedule" page for details about the syntax.
  # ct schedule -edit { -sched | -acl }
-sch.edule   [filename] Default: open for edit the database of currently scheduled jobs.
-acl   [filename] Open for edit the scheduler's ACL.
3) Test the scheduled task or other operation.
  # ct schedule -run job-id
-del.ete   job-id-or-name Delete a specified scheduled job.
-run   job-id-or-name Immediately run the specified scheduled job.
-wai.t   job-id-or-name Wait for the specified running job to complete and then report the status.
-sta.tus   job-id-or-name Display the status of the specified job.

Table of Contents





Stop and start CC services.

CC albd

On UNIX, as root:
  # /etc/init.d/atria { stop | start }
-or-
  # /usr/atria/etc/atria_start { stop | start }
Note that a patch in CC 2002 and 2003 changed the name of the startup file to /etc/init.d/clearcase.
On Windows, as any user, ClearCase Home Base -> Administration -> Control Panel -> Services Startup, Shutdown ClearCase & Startup ClearCase. From the CLI:
  # net { stop | start } albd

Lock Manager

On UNIX, the lockmgr is stopped by atria_start.
On Windows, from the CLI:
  # net { stop | start } lockmgr

Cred Manager

Not applicable to UNIX.
On Windows, from the CLI:
  # net { stop | start } cccredmgr
NOTE: If recovering from a crashed server and are having problems getting VOBs mounted and services restarted, if you get an MVFS error message saying something about "can't unload the module: Device busy", there is no alternative to reinstalling CC. In this case, a simple reinstall over the old system isn't sufficient. It requires a deinstall followed by a reinstall. If this is on a server, be careful about the registry.
NOTE: On Unix, if you want to stop CC, but MVFS won't let you for some reason, there is an unsupported way to shutdown CC even if MVFS isn't working.

Table of Contents





Enable checksums on SunOS 4.1.x, HP-UX 9.0.x and UnixWare 2.1.x.
Systems running the title operating systems do not enable UDP checksums by default for NFS traffic. To ensure NFS reads and writes are not at risk, follow the steps below:

SunOS 4.1.x
As root, edit the /usr/sys/netinet/in_proto.c. Change the following line
from:
  int udp_cksum = 0;
to:
  int udp_cksum = 1;
After editing, rebuild the kernel and reboot the system. The file must be changed on both the clients and server to ensure proper protection.

HP-UX 9.0.x
As root, patch the kernel image file and the running kernel with the adb utility.
  # adb -k -w /hp-ux

kudp_ckecksumming/W 2
kudp_checksumming?W 2
$q
This must be done everytime the kernel is rebuilt.

UnixWare 2.1.x
As root, set the UDPCKSUM parameter with idtune utility.
  # /etc/conf/bin/idtune -f UDPCKSUM 1
  # /etc/conf/bin/idbuild
Reboot the system after making the change.

Table of Contents





cleardlg
On Windows, when one executes CC commands from a GUI interface, additional boxes pop up giving or asking for information. However, from the command-line, the execution of the ct command to accomplish the same things does not pop any GUIs (unless something like -graphical is used). CC comes with a command-line, stand-alone executable called cleardlg that pops up the same dialogue boxes that the GUI interfaces do.
  # cleardlg /?
The options:
/addtosrc   [/nocheckin][/comment string]   filename Add filename to source control.
/checkin   [/identical][/comment string]   element Check element back in.
/checkout   [/reserved|/unreserved][/comment string]   element Checkout element.
/uncheckout   [/keep|/remove]   element Uncheckout element.
{/reserve|/unreserve}   element Change the reserve status of the checkedout element.
{/mount|/unmount}   vob-tag Mount or unmount vob-tag.
{/starview|/stopview}   view-tag Start or stop view-tag.
/viewprop   view-tag Display the view properties sheet for view-tag.
/removeview   view-tag Delete the view-tag view.
{/diffother|/diffpred}   element1 element2 Diff two elements.
/options Display CC user preferences.

Table of Contents





Patch CC.
Updated: 06/13/11
For patches, go to the customer only site https://www-304.ibm.com/support/docview.wss?rs=0&uid=swg21265307&wv=1. On both Windows and Unix, applying patches and updating CC will not affect VOBs, views, license or registry information.
On Unix, as root, create a "patches" subdirectory inside the CC release area at the same level as the install subdirectory. CC Unix patches cannot be applied directly to the install, they must be applied to a release area from a sub-directory within that release area. The release area was created when the tarfile from the install cdrom was extracted, and shouldn't be confused with /usr/atria, which is the CC home directory. Download the compressed patches that the patchfinder has selected. You will need gzip. Once the patches have been extracted, cd to their respective install subdirectories and run "./apply_patch". It will update the necessary files. Once the patches have been applied to the release area, simply run "./install_release" from the release area's install directory; the one at the same level as the patches directory you created. No reboot is necessary.
On Windows, as Administrator, create a "patches" subdirectory at the same level as the CC release area. If there is no release area, patches can be applied directly to the local system.
msiexec /a  /p   /lv* 

Ex:
msiexec /a \\machine\share\ClearCase\v7.0.1\Setup\1033_ClearCase.msi /p \\machine\share\ClearCase\Patches_7.0.1\7.0.1.11-RATL-RCC-WIN-en-US-FP11.msp /qb /lv* \\machine\share\ClearCase\v7.0.1\install.log
After running the update, run "ct -ver" to see the applied patches.

Rational Download Manager

You can apply service releases using the Rational Download Manager. The executable is not installed as part of a normal CC install and lives in the "extras" folder on the cdrom.
You must be a registered member of the Customer Only site to download service releases.

Table of Contents





Get help.
In UNIX xclearcase, Help -> Usage... and Manual page...
In Windows Explorer, right-click on any CC entity from the view on down and select ClearCase -> Help.
From the CLI:
  # ct help | more
  # ct command -help
  # ct man command
  # ct man -graphical command
  # man ct+command                            (UNIX only)
  # ct apropos search-string                  (UNIX only)
  # hyperhelp /usr/atria/doc/hlp/subject.hlp  (UNIX only)
If your service contract is up to date, call Rational support at 800-433-5444 or see one of the many CC webpages.

Table of Contents





Build in CC.
Simply run "clearmake" or "omake" inside a dynamic view. The stand-alone clearmake command will work inside snapshot views, but will not produce configuration records, which implies that the object produced is not a derived object (DO) and cannot be share between developers. The CC options and behavior are identical for clearmake and omake. The decision to run one or the other depends on what flavor of makefile is be used. Omake generally runs on PC based make systems and clearmake on UNIX. Clearmake and omake will run on your existing make files.
  # clearmake
Clearmake supports all the make options, which are in lower-case and documented in the make man page. The upper-case letter options are CC specific. Some useful options:
-f   makefile Clearmake will use the existing "Makefile" file if not overridden by -f.
-u Unconditionally build all targets.
-U Unconditionally build goal targets. Sub-targets undergo build avoidance.
-N Overrides the default behaviour of reading build options specification (BOS) file, if one exists.
-J   integer Enable clearmake's distributed and parallel build capabilities. See below for more info.
-V Restrict configuration lookup to the current view. Disable winkin.
-M Restrict dependency checking to explicitly declared dependencies in the makefile. Disable winkin.
-A   BOS Also read from the designated build options specification file. Can be used with -N. Can designate multiple -A options.
-version Print the clearmake version.
-c Checkout DOs before rebuilding or winking in. Does not check back in. (new in CC 4.2)
Some useful environment variables:
CCASE_BLD_UMASK The umask value to use for newly created DOs.
CCASE_HOST_TYPE Gives the name of the build hosts file (.bldhost.$CCASE_HOST_TYPE) when working with distributed builds.

Distruted and parallel builds.
The clearmake system allows one to build several targets simultaneously on one machine and optionally run the build simultaneously across several machines, thus greatly improving performance. As of CC 4.2-, parallel and distributed builds could only be performed on UNIX systems. As of CC 5.0/2002, you can conduct parallel, but not distributed, builds on Windows.
To invoke parallel builds, simply used the "-J integer" option. The integer tells clearmake the maximum of targets to build simultaneously. It's been my experience that even on very healthy servers, a value of J=4 is about maximum without getting into diminishing returns. Using the -J option will also cause clearmake to look for a .bldhost.architecture file in your personal home directory. The build host file contains the names of other machines that you would like to employ during the build. The machines listed in the build host file (one per line) should all be of identical architecture. This is to ensure that all machines utilized in the build are creating compatible derived objects. For instance, if conducting a build whose target architecture is Sun, the CCASE_HOST_TYPE encironment variable would be set to something like "sun" and the machines listed in the build hosts file are Sun boxes. If you want to then run the same build on, say HP, you would have a like build hosts file for HP boxes in you shop. Just prior to running the build, set CCASE_HOST_TYPE to something like "hp" that would corrrespond to a .bldhost.hp file in your home directory. For more information, see "clearmake Makefiles and BOS Files" in the manual called "Building Software with ClearCase".
NOTES:
The -J option will attempt to execute only that many concurrent compiles no matter how many hosts you have specified in your bldhost file. The bldhost file is simply for load balancing. That is, if -J 2 and you have four hosts listed in the bldhost file, it's not 2*4=8 simultaneous jobs.
The current host is NOT implicit. You must include your own host in the bldhost file if you want to use it too.
The bldhost file is read dynamically. It checks to see if the other machine can support a compile for every job that it sends it.
ClearCase must be installed on the remote machine. The remote machine must be in a region that has the target VOB and working view tagged in it. That is, the remote machine must be able to use the view to select the versions in the VOB as if you initiated the build from the machine.

Table of Contents





Customize ClearCase Explorer tools.
Updated: 08/16/12
Version: 7.0.1.8
Windows only. In the ClearCase Explorer, select the Toolbox in the left pane. Right-click and select Add Tool Shortcut. The CC Explorer can also be invoked from the CLI via clearexplorer.

When setting a custom tool, the executable is just "ccperl.exe" and the argument is the full path to the Perl script. If the path contains spaces, enclose it in double quotes.

To make the customized tool set available to all users, once the customizations are complete on one machine, right-click in the Toolbox pane and select Export. Save the file to the site release area or to another network accessible directory. This will create a file that can be imported during the siteprep phase of an install. Rerun the siteprep. When it asks to supply tool shortcut definitions, point to the file just exported. In the Save Site Defaults step, save the new defaults. When users run an install using this release area they will automatically pick up the customized tool set.

If you create an export .xml file for the purpose of sharing a custom tools page with colleagues without going through the siteprep and install, the user's registry will need to be updated with the following lines to set their environment. Place the following in a .reg file. This will set it up so that the custom tools page gets automatically loaded when they launch the CC Explorer.
REGEDIT4

[HKEY_CURRENT_USER\Software\Atria\ClearCase\CurrentVersion\ClearCase Explorer\General]
"ImportingSiteToolShortcuts"=dword:00000001
"SiteToolShortcutPath"="your path\\your filename.xml"

[-HKEY_CURRENT_USER\Software\Atria\ClearCase\CurrentVersion\ClearCase Explorer\ToolsPage\your custom page name]
If you create an export .xml file and then make manual changes to the file, be careful what editor you use. Text editors, such as Notepad and Wordpad, will replace the line terminations and make the file unreadable by CC when it attempts to load the file at startup. You can use a program like Word, but it's difficult to manipulate custom XML tags outside of a template. The best option I've found is to use Notepad++, which is freeware.
To make the customized tool set available only to a select group, simply modify the ACL on the exported file.

The tool set can also be imported after installation. Right-click in the gray area of the Toolbox tab and select Options. Click the radio button called "Import tool shortcuts ...". Browse to the location of the XML file containing the tool shortcut definitions. Then, each time the Explorer is started, the custom tools are automatically imported to the specified page.

More information can be found online at: http://publib.boulder.ibm.com/infocenter/cchelp/v7r0m1/index.jsp?topic=/com.ibm.rational.clearcase.dev.doc/topics/clearexplorer/c_abt_cstmz_ccexpl.htm

WARNING: CC 7.1.2: If you are testing tool shortcut imports and "Remove Page" to test the import of an .xml shortcuts file, the page and tools will not load. This is identified as a bug, but will not be fixed by Rational. See http://www-01.ibm.com/support/docview.wss?uid=swg21243654. As a workaround, in the registry, go to "HKEY_CURRENT_USER/Software/Atria/ClearCase/CurrentVersion/ClearCase Explorer/ToolsPage/<your-custom-page>" and for each custom tool definition, reset the Removed key back to "0".

Table of Contents





Prompt users with/for information.
In CC automation scripts it is often necessary to prompt the user for additional information, especially in triggers. The clearprompt command will pop up a GUI dialog if the user is in a GUI environment or will prompt text on the CLI.
New in CC 5.0/2002, if the "-newline" option is used, the "\n" (newline) character can be used in the prompt_string to better control of the prompt's format.
  o 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 ] 

  o 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 ] 

  o UNIX only--Prompt for list:

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

  o 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 ] 

  o 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 ] 

  o Windows only--Prompt for text:

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

  o 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 

  o Windows only--Prompt for list:

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

  o Windows only--Prompt for continue-processing choice:

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

  o 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 
Table of Contents



Disconnect CC from the network.
On Windows only, the CC environment on a workstation can be disconnected from the rest of the CC network. This is usually done when a user has downloaded needed files from the VOB via a snapshot view. The disconnect is a logical one as opposed to the physical one (removing the ethernet cable). When disconnected, the user cannot run any CC commands. To disconnect from the network from the GUI, enter the CC Control Panel applet. Under the Options tab deselect the box "Connected to network for ClearCase operations".
If the disconnect is needed from a script, the corresponding Windows registry entry can be altered at will. I don't know if there's an easy way to make registry modifications without creating a .reg file with the appropriate registry setting. Open regedit and save to a file the registry key "HKEY_CURRENT_USER\Software\Atria\ClearCase\CurrentVersion". Cut out all the unecessary junk and save the file as disconnect_CC.reg with the following information:
Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Atria\ClearCase\CurrentVersion]

"Connected"=dword:00000000
and another as connect_CC.reg:
Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Atria\ClearCase\CurrentVersion]

"Connected"=dword:00000001
To connect or disconnect from a script, simply execute the appropriate .reg file.

Table of Contents





Determine what ports CC uses.
On UNIX, the albd server uses port 371, all others are dynamically assigned.
On MultiSite, specific ports can be assigned to the shipping_server via the environment variables CLEARCASE_MIN_PORT=min-port and CLEARCASE_MAX_PORT=max-port.

Table of Contents





Web Authoring Integration Wizard
See the section in the Administration Manual called "Configuring Integrations with Microsoft Web Authoring Tools" for details.
Snapshot views created for use with ASP must be created using the Authoring Wizard. IDE tools that modify ASP change the modification times on files that haven't actually changed. Snapshot views created using the Wizard have a special algorithm that isn't fooled into thinking that those hijacked files need to be updated in the VOB.

Table of Contents





Determine where CC is installed.
Updated: 04/27/12
Version: 7.0.1.8
On some machines, an environment variable called ATRIAHOME might be set.
On Unix, CC can always be found at /usr/atria. Even if you specify an alternate install directory, CC will automatically create a softlink from /usr/atria to the real location. As of 2003.06.00, CC is installed in /opt/rational by default, but there is still a softlink at /usr/atria for backward compatibility.
On Windows, the CC install root directory can be anywhere. One way to find it is to look at:
  # regedit /E tempfile HKEY_LOCAL_MACHINE\SOFTWARE\Atria\ClearCase\CurrentVersion
The output is written to "tempfile". Look for a key called "HostData" or "ProductHome". The information can be found programmatically as well:
	use Win32::Registry;

	$key = "SOFTWARE\\Atria\\ClearCase\\CurrentVersion";
	$::HKEY_LOCAL_MACHINE->Open($key,$parameters_o);
	if ( "$parameters_o" eq "" ) {
		print STDERR "ERROR: Unable to open \"HKEY_LOCAL_MACHINE\\$key\" using Win32::Registry.\n";
		exit 1;
	}
	$parameters_o->QueryValueEx("ProductHome",$type,$cc_home);
	if ( "$cc_home" eq "" ) {
		print STDERR "ERROR: Unable to determine ClearCase product home.\n";
		exit 1;
	}
	print "CC home: $cc_home\n";

Table of Contents



Determine the MVFS drive letter. (Windows only)
Updated: 04/06/12
On Windows, any dynamic view will show up under the MVFS drive letter independent of whether or not it's mapped to its own drive letter as well.
A couple simple ways to find the MVFS drive letter are to 1) simply open the Windows Exporer and inspect the drive letters for one containing the label "view on ..." or 2) open the ClearCase Contol Panel applet and look under the tab called "MVFS".
However, if you need to find the MVFS drive letter inside a script, use the following. Win32::Registry works with ccperl.
	use Win32::Registry;
	$key = "SYSTEM\\CurrentControlSet\\Services\\Mvfs\\Parameters";
	$::HKEY_LOCAL_MACHINE->Open($key,$parameters_o);
	if ( "$parameters_o" eq "" ) {
		print "ERROR: Unable to open \"HKEY_LOCAL_MACHINE\\$key\" using Win32::Registry.\n";
		exit 1;
	}
	$parameters_o->QueryValueEx("drive",$type,$mvfs_drive);
	if ( "$mvfs_drive" eq "" ) {
		print "ERROR: Unable to determine the MVFS drive letter for an unknown reason.\n";
		exit 1;
	}
	print "MVFS drive letter: $mvfs_drive\n";
The following will work as well, but isn't as efficient. Moreover, on a Windows 7 box it may produce errors about accessing the registry, even though isn't writing anything there.
  # regedit /E tempfile HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Mvfs\Parameters
You'll need to parse the data for a key called "drive". Warning: In an editor like notepad, that line looks like "drive"="M", but in Perl is looks like " d r i v e " = " M ".
# In a Perl script.
`regedit /E MVFS_tempfile.txt HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Services\\Mvfs\\Parameters`;
if ( ! open(TEMPFILE,"MVFS_tempfile.txt") ) {
	print STDERR "$script ERROR: Unable to determine the MVFS drive letter.\n";
	exit 1;
}
close(TEMPFILE);

foreach $row (<TEMPFILE>) {
	$row =~ s/\W//g;
	next if ( "$row" !~ /^drive/ );
	$mvfs_drive = substr($row,-1,1);
	last;
}
print "MVFS drive letter: $mvfs_drive\n";

unlink("MVFS_tempfile.txt");
Table of Contents



Remotely/automatically reset a Windows albd service password.
CC on Windows needs an account to log into as a service upon startup. That account is password protected. The most simple solution for that password is to have it never expire. However, if your site doesn't allow that option, the periodic changing of the password can be automated. However, the solution is a Rational Tech Support internal solution. That is, if there is a demonstrable need, you can escalate the problem within Rational Tech Support and request the albd_pw_util.exe. For reference, the install instructions are in Rational internal Tech Note 14623.
As an alternative, the following script requires you to have Admin rights on the remote computer. The "print" statements regarding the service's status aren't necessary.
use Win32::OLE;
use strict;

##########
# Set these:
my $password = "XXXXXXXX";
my $computername = "computername";
##########

my @service_status = ("Unknown","Stopped","Start Pending","Stop Pending","Running","Continue Pending","Pause Pending","Paused");

my $computer = Win32::OLE->GetObject("WinNT://${computername},computer");
$computer->{Filter} = [ "Service" ];

foreach my $service (in $computer) {
    if ($service->{DisplayName} =~ "Atria Location Broker") {
	print "Display Name: ", $service->{DisplayName}, "\n";
	print "Name: ", $service->{Name}, "\n";
	print "Path: ", $service->{Path}, "\n";
	print "Account Name: ", $service->{ServiceAccountName}, "\n";
	my $status = $service_status[$service->Status()];
	print "Status: $status\n";
	$service->SetPassword("$password");
	print "LastError ", Win32::OLE->LastError(), "\n";
    }
}
Table of Contents



Get the status of a remote albd service.
See Remotely reset a Windows albd service password. Simply comment out the last two lines in the "if" statement inside the "foreach" loop.

Table of Contents





Change the "clearcase" group on Windows.
Version: 7.1.2
Updated: 03/30/16

Unlike the "clearcase_albd" user, the clearcase group can only be easily defined at time of install. However, you can change it by modifying the registy key. Be sure to stop CC before making the change, as there are cached references to the old group name.
Possible registry locations:
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Atria\ClearCase\CurrentVersion\ClearCaseGroupName
HKEY_LOCAL_MACHINE\SOFTWARE\Atria\ClearCase\CurrentVersion\ClearCaseGroupName

You also need to give the new group Full Control of the cc-home\var directory. In addition, every VOB on the VOB server must be give Full Control to the new clearcase group. However, do not use Windows tools to recursively change permissions. You must use the cc-home\etc\fix_prot command.

As an alternative, you can simply change the group in the CC release area site prep and have everyone resinstall, which is what I would recommend. However, you still need to change the protections on the VOBs.

Table of Contents





ClearCase File System (CCFS)
CCFS is always enabled on Unix.
On Windows, CCFS can enabled or disabled via the CC Control Panel under the Options tab.
Dynamic views must use a third-party, NFS solution to go between Unix and Windows, such as Samba, NFS Maestro, TAS, or DiskAccess.
As of CC 2002/5.0, Unix snapshot views can access Windows VOBs via CCFS.

Table of Contents





Merge non-CC files.
Using CC tools, it's possible to merge files that are non under source control.
  # ct merge -out outputfile  file1  file2
Table of Contents



Create separate "site defaults" files for installation.
As of CC 2003.06.00, the CC install requires different site defaults files for client and server installs. You can also have different site defaults files for install configurations appropriate to different projects as well.
1) Create the release area in the normal way.
2) Run siteprep.exe (Windows) or site_prep (Unix) and save the file. Use the "Save As" option to give the defaults file a unique and appropriate name. A shortcut (link) will be created with the same name in the release area (excluding the filename suffix on Windows). You can then execute the shortcut to install CC from the release area with your selected site defaults. The default name for one of these files is "sitedefs.dat".
3) To create alternate site defaults files, simply repeat step (2).

Table of Contents





Perform a silent un/install.
Silent install is a method of installing Rational products on computers without intervention from users. It greatly reduces the work of an administrator during a rollout of Rational ClearCase. It also ensures that a consistent software configuration is installed on each target system. The silent install requires an existing sitedefs.dat file that was created during the site prep.
Run the silent install from the client machine. The silent install feature should not be confuse with the ability to "push" and installation out to clients from a central server.
Windows:
  # path\setup.exe /g path\sitedefs.dat
The appropriate sitedefs.dat file may have a different name. See Create separate site defaults files.
Run the silent install on a test computer first and monitor it for errors. You cannot directly monitor the installation process -- hence the term "silent". To view the installation results, see the "rational_install.log" file in your temp directory. On Windows it will be a hidden system file. In later versions of CC, the log file is simply called "install.log" and isn't a hidden file.
If desired on Windows, the CCDoctor can be run on a computer before installing CC. Run release_area\Setup\program files\Rational\ClearCase\bin\ccdoctor.exe.

Silent Uninstall
As of CC 2003.06.00 you can run a silent uninstall. On the machine being unistalled, run the Microsoft installer. The /X indicates uninstall, the /qn means no user interaction.
Windows:
  # msiexec.exe /X path/clearcase.msi /qn
Note: If you want this uninstall to be silent, you can place this in a text file, rename it .bat and have the user run it.

Table of Contents





Uninstall CC even if MVFS isn't working on Unix.
When you uninstall (deinstall on Unix), it attempts to shutdown MVFS gracefully. If MVFS isn't working for some reason (perhaps that's why you want to uninstall), the uninstall will fail stating that it can't shut MVFS down. So, what you need is a way to tell it to uninstall unconditionally.
This is an unsupprted solution. Touch a file called /var/adm/atria/no_mvfs_tag. If that file exists during deinstall, atria_start will not try to unload MVFS. Table of Contents



Recompile MVFS on Red Hat Linux
ClearCase MVFS (dynamic views and some GUIs) doesn't always compile and link the first time with some RedHat kernel versions. The symptom is usually a series of "unresolved symbol" error messages, either during compile of mvfs.o or when the atria daemon is restarted. The following discusses workarounds to get MVFS to work. The steps listed below need to be run as root.
The exact config file copied into place depends on the kernel version being run. Sometimes there are different choices for the same kernel. You may have to try different ones to get MVFS to work.
The following sets of steps assume that /usr/src/linux exists or is linked to an appropriate directory. When atria is stopped for the restart, ignore errors about "The MVFS file system is not installed or not loaded".

RedHat 7.2

cd   /usr/src/linux/configs
cp   kernel-2.4.7-i686-smp.config   ../.config
cd   /var/adm/atria/mvfs
make   clean
make
/etc/init.d/atria   stop
/etc/init.d/atria   start
RedHat 9 before CC 2002 patch 34
cd   /usr/src/linux
make   mrproper
cp   configs/kernel-2.4.20-i686-smp.config   .config
make   oldconfig
make   dep
cd   /var/adm/atria/mvfs/linux*
make   clean
make
/etc/init.d/atria   stop
/etc/init.d/atria   start
NOTE: If compiling CC 2002 for RedHat 9, it may be necessary to edit the Makfile in /var/adm/atria/mvfs/linux*. If when you make mvfs you get an error about "p_pptr", edit the Makefile. Ensure the variable VER_DIR is the same as your uname, if possible. Also, ensure the RATIONAL parameters list RedHat9 and not 7.

RedHat 9 starting with CC 2002 patch 34

cd   /usr/src/linux
make   mrproper
cp   /boot/config-2.4.20-30.9smp   .config
make   oldconfig
make   dep
cd   /var/adm/atria/mvfs/vnode_src
make   clean
make   vnode_param.mk.config
make   install
/etc/init.d/clearcase   stop
/etc/init.d/clearcase   start
When atria is restarted, you can ignore warnings like:
Warning: kernel-module version mismatch
        /lib/modules/fs/mvfs.o was compiled for kernel version 2.4.20-8
        while this kernel is version 2.4.20-30.9smp
Warning: loading /lib/modules/fs/mvfs.o will taint the kernel: non-GPL license - Proprietary
  See http://www.tux.org/lkml/#export-tainted for information about tainted modules
Warning: loading /lib/modules/fs/mvfs.o will taint the kernel: forced load
Table of Contents



Determine the version of CC for a host or client.
Updated: 09/07/12
Version: 7.0.1.8
	ct lsclients -host registry server

	ct hostinfo -long -properties hostname

Programmatically:
	use Win32::Registry;

	$key = "SOFTWARE\\Rational Software\\ClearCase";
	eval {
		$::HKEY_LOCAL_MACHINE->Open($key,$parameters_o);
	};
	if ( "$parameters_o" ne "" ) {
		$parameters_o->QueryValueEx("ProductVersion",$type,$current_cc_version);
		$parameters_o->Close;
	}

	print "$current_cc_version\n";
Table of Contents



Execute heavy commands in the background on Windows.
Updated: 01/18/12
Some triggers or utilities can run tasks that take a long time to return control to the user. For example, if an approval label gets applied and the approved version must be copied to some other place for some reason, if the label is applied to dozens of files, the user would have to wait for all the copies to complete before regaining control.
In the following trigger code example, the actual copy command is run in the background. Note that doing it this way removes the possibility of ensuring the file was copied properly. That is, there is no error trapping.
	# Inside trigger script.
	use Win32::OLE;
	$sh = Win32::OLE->new("WScript.Shell");
	$sh->run("copy \"$ENV{CLEARCASE_XPN}\" \"$destination\\".basename($ENV{CLEARCASE_PN})."\"",0,0);
	$sh->Nothing;
Table of Contents



Send scripted emails.
Updated: 05/08/12
sub send_mail {

	# This will send email to the listed addresses.
	# If a list of addresses is provided, they must be separated by semi-colons.


	# Usage:
	# send_mail("This is the subject","This is the email body","Eric.Ostrander\@company.com;Bob.Johnson\@company.com");


	use Net::SMTP;

	my $smtp_server	= "smtp.company.com;
	my $subject	= $_[0];
	my $body	= $_[1];
	my $addressees	= $_[2];

	my $host		= `hostname`;
	chomp($host);
	my $current_user	= $ENV{CLEARCASE_USER} || $ENV{USERNAME} || $ENV{LOGNAME};

	my $smtp = Net::SMTP->new($smtp_server);
	if ( "$smtp" eq "" ) {
		print STDERR "$script ERROR: Unable to contact the $smtp_server SMTP server.\n";
		return;
	}

	$smtp->mail("$current_user\@company.com");
	foreach $address (split(/\;/,$addressees) {
		$address =~ s/\s+//g;
		$smtp->to($address);
	}
	$smtp->data();
	$smtp->datasend("To: $addressees\n");
	$smtp->datasend("Subject: $subject\n");
	$smtp->datasend("Content-type: text/html\n\n");
	$smtp->datasend("\n");
	$smtp->datasend("\n$body\n");
	$smtp->dataend();
	$smtp->quit;

	return;
}
Table of Contents



Programmatically create an Excel spreadsheet using Perl.
Updated: 05/29/12
Version: 7.0.1.8
Information gathered from CC can be formatted for easy readability by placing the output in an Excel spreadsheet. The following example works with CC perl.
Many more things can be done than just the bare-bones example below. See http://www.perlmonks.org/?node_id=153486 for useful information.
	use Win32::OLE qw(in with);
	use Win32::OLE::Const "Microsoft Excel";
	use Win32::OLE::Variant;
	use Win32::OLE::NLS qw(:LOCALE :DATE);

	$Win32::OLE::Warn = 3; # Die on Errors.

	$excelfile = ".\\myfile.xlsx";

	$Excel = Win32::OLE->new('Excel.Application');
	if ( Win32::OLE->LastError ) {
		print "Unable to open an Excel spreadsheet.\n".Win32::OLE->LastError;
		exit 1;
	}
	$Excel->{DisplayAlerts}=0;

	$Book = $Excel->Workbooks->Add();
	if ( Win32::OLE->LastError ) {
		print "Unable to add workbook.\n".Win32::OLE->LastError;
		exit 1;
	}

	$Sheet = $Book->Worksheets("Sheet1");
	$Sheet->Activate();       
	$Sheet->{Name} = "Stale ClearQuest records in CQ";
	if ( Win32::OLE->LastError ) {
		print "Unable to activate a sheet.\n".Win32::OLE->LastError;
		exit 1;
	}

	$Sheet->Range("a1")->{Value} = "My text";   

	$Book->SaveAs($excelfile);
	$Book = $Excel->Workbooks->Close();
Table of Contents



Reset CC credentials on Windows.
Updated: 11/06/12
Version: 7.1.2
If all configuration items appear to be ok, such as the CLEARCASE_PRIMARY_GROUP etc..., and still cannot get into a VOB, the Windows workstation's credentials can be refreshed using the following command. This is an IBM Rational command, but it lives in the Program Files\System32 folder. This will allow registration of user credentials within the MVFS.
	nplogon
Also see Rational's "ntlogin_util" command. While nplogon should already be in your path, the ntlogin_util.exe lives in CC-home\etc\utils, which is generally not in your path. See http://www-01.ibm.com/support/docview.wss?uid=swg21149989 for some more information.

Table of Contents





Work with object names that start with a dash/hyphen.
Updated: 09/22/15
Version: 8.1
Attempts to work with object names that start with a dash result in the error "unknown option". Putting quotes around the object doesn't help. Just precede the offending object name with two dashes, as in:
	ct lsview -l -- -view_tag
	cleartool rmelem -- -t1.txt
Table of Contents



Create a region.
Regions are used to group together computers that can see the VOB server via the same absolute path. If two sets of computers do not see the path in the same way, a region will need to be created for them, such as Windows clients of a UNIX server.
  # ct mkregion -tag region -tcomment "region comment"
NOTE: One server cannot simultaneously be the primary registry server for one region and the backup for another.
Clients will have to be moved to the new region manually:
1) Login as root/administrator on the client.
2) Shutdown CC.
3) Modify the registry/rgy_region.conf file.
4) If the region is on another registry server, modify rgy_region.con as well.
5) Restart CC.
On Windows the region will then have to be sync'ed with the UNIX region. In Windows, Control Panel -> ClearCase -> Administration -> Region Synchronizer. Ensure the "Windows:" and "UNIX:" regions are set appropriately. Select "VOB Tags", select each VOB in turn, and import each one. You will need the registry password to import public VOBs. Do the same thing for views.

Table of Contents





Remove a region.
The region to be removed cannot contain any view or VOB tags. They'll have to be removed or moved to a different region first.
  # ct rmregion -tag region
If you are not renaming the region and want to clean out the registry at the same time, use the   -rmall   option. The -rmall option only removes the tags from the region and doesn't delete the actual views and VOBs. If the region contains any public VOBs, you'll need to supply the registry password.

Table of Contents





Rename a region.
Unfortunately, there is no way to directly rename a region on a server. You will have to rmregion on the old one and then mkregion. This is only true for registry host (server). All views and VOBs tagged in the old region will have to be tagged in the new region and untagged in the old region before the region can be removed. In addition, you will need to manually repoint all clients to the new region.

Table of Contents





List the regions.
List one or more CC regions. This is simply a listing of the information in the /var/adm/atria/rgy/regions (UNIX) or atria-home/var/rgy/regions (Windows).
  # ct lsregion -long
Table of Contents


License information.
Updated: 08/08/13
Version: 7.1.2.4
The standard location for the license information on UNIX is /var/adm/atria/license.db and on Windows the licenses are stored in the Windows registry under "HKEY_LOCAL_MACHINE\SOFTWARE\FLEXlm License Manager\RATIONAL_LICENSE_FILE" and can be viewed via in the Control Panel in the ClearCase applet, if the IBM Rational License Manager is installed. Usually you will need to have root/administrative privileges to modify the license information. For Unix, the license server is specified in the site_prep phase of the install or can be changed later by editing the /var/adm/atria/config/license_host file. On Windows, the license server is specified during install, or after the install in the Control Panel in the ClearCase applet.
Licensing and can be changed dynamically at any time; no restart needed.
A client can only point to one license server at a time.
Licenses are node-locked to the server, but are floating for user access.
License servers must have CC installed.
You must create your own backup license server.
A license is taken by any work done in the MVFS system, including just entering the ClearCase Explorer or using commands such as cd and ls on the CLI.
Unix and Windows can access license on the opposite OS without additional configuration.
A custom script must be written to monitor license usage over time.
To determine the current number of licenses available/in use:
  # clearcase-home/bin/clearlicense
To get the hostid of the license server:
  # clearlicense -hostid
- or if CC isn't installed yet
  # getconf CS_PARTITION_IDENT	(HP-UX)
  # cdrom\cpf\nt_i386\hostid	(Windows)
  # hostid	(Solaris)
On Windows, the hostid is just the physical address of your ethernet adapter without the dashes, which can be determined by running "ipconfig /all". Licenses are encoded with that hostid. If you change a computer's name, it isn't necessary to reencode the licenses. However, if the ethernet card is replaced or you simply want to move the licenses to another server, you must contact Rational.

A user can manually release a license for themselves, or optionally another user.

  # clearlicense
Some useful options:
-rel.ease   [username | UID] Release your own license or that of another user.
-pro-duct   product-name Specify a single product on which to report.
-host.id Returns the hostid of the current machine.
To avoid "license release wars", the number of releases is limited to 24 or twice the number of licenses you have in a 24 hour period, whichever is greater. For example, if you have 25 CC licenses and 8 CCMS, you could run the release 50 times in a day for CC and 16 for CCMS. It ensures compliance with the Rational license agreement.

A license isn't retrieved for absolutely every command run in CC. Once a license has been obtained, the client won't check to see if the user still has a license for another 15 minutes. It caches the name of the user on the local box:
Unix - /var/adm/atria/cache/ClearCase_check
Windows - $ATRIAHOME\var\cache\ClearCase_check
If the creation time of the cache file for the user exceeds 15 minutes, it will go back to the license server to ensure the user still has a license.

A license file can be customized beyond just having the license string. Simply place any of the following option along with their arguments on separate lines in the license file.
-user   loginid Specify priority users allowed to obtain a license (space separated list, see below).
-timeout   minutes Reset the timeout of the license (default is 60 mins, minimum is 30 mins).
-audit License usage can be audited (see below).
-nuser   login Disallow specific users (space separated list).
The -audit option writes to /var/adm/atria/log/albd_log on Unix. On Windows, the information is logged in the regular Windows Event Viewer.

NOTE: Users specified using the   -user   line are given a higher priority than others that are not. That is, the first user listed there has the highest priority possible and will get a license even if they are all being used. Each additional user on that line has a descending order of priority. A hierarchy of who has license rights can be set up this way. All users not explicitly listed on that line share the lowest priority, which is the default behaviour.

Just remove line(s) from the license file and/or add new lines. The license file is read dynamically when a ct command is run. However, for performance reasons, CC doesn't recheck a particular user's license for another 10-15 minutes. In other words, once you've obtained a license, CC won't check to see if you still have that license for about 10 mins.
Licenses are redeemed by giving a Purchase Order number and server hostid to Rational via the website http://www.rational.com/products/clearcase/support/license.jtmpl. If this is a license transfer from another server, use the website http://www.rational.com/products/clearcase/support/move.jtmpl.

NOTE: The "root" user on Unix and "Administrator" on Windows do not take a license.

Table of Contents





Check the consistency of a registry.
Over time, the registry can become cluttered with views and/or VOBs that are only half removed. The following command lives in atria-home/etc and can check for them.
  # rgy_check {-views | -vobs}
Other useful options:
-region   region Check the registry in another region.
-storage For a more thorough check, look at storage areas as well.
See also registry_ccase in the CC Reference Manual for more information.

Table of Contents





Switch to the backup registry server.
There is only one active registry for any given region. But, a backup of that registry can be designated during CC installation. If the server on which the primary registry resides is unavailable for some reason, you can switch over to the backup registry server. This command lives in /usr/atria/etc on UNIX and atria-home/etc on Windows.
NOTE: One server cannot simultaneously be the primary registry server for one region and the backup for another.
  # rgy_switchover old-reg-server new-reg-server
Some useful options:
-backup   hostname Designate a new backup registry server at the same time.
-time   timestamp Use backup registry files other than the most recent on new-reg-server.
This command gets run on the new-reg-server and completes the following actions. The registry lives in /var/adm/atria/rgy on UNIX and atria-home/var/rgy on Windows. See registry_ccase in the CC Admin Manual for more information.
1) copies registry/backup files to the registry
2) notifies the albd_server that it is now the primary registry server
3) informs clients of the change (client_list.db)
If there are any clients unavailable when rgy_switchover is run, you'll need to manually edit their rgy_hosts.conf file when they return. There can be only one registry server at a time. If the primary server is still up, or when it returns, on that machine:
1) stop CC
2) edit the rgy_srv.conf file to remove the word "master"
3) edit the rgy_hosts.conf file to specify the new primary server
4) restart CC
Stop and start CC on UNIX via "/usr/atria/etc/atria_start {start|stop}" and ClearCase Home Base -> Administration -> Control Panel -> Services Startup on Windows.

Table of Contents





List the clients of a registry/license server.
If renaming a region or need to know all the clients using a particular server:
  # ct lsclients -host hostname
Some useful options:
-type [ registry | license | all ] Restrict list to registry OR license clients only. Default is all.
-l.ong Expand list to include names of client's servers and date/time of last access.
-s.hort Client names only.
The actual listing is kept in client_list.db in /var/adm/atria on UNIX and in atria-home\var on Windows.

Table of Contents





List the registry/license servers of a client.
The basic command gives information about the current host, or hostname if specified. The -long option gives the added information about the license and registry server(s).
  # ct hostinfo [ -long ] [ hostname ]
Table of Contents



Move a client to a new region.
Updated: 04/21/16
Version: 7.1.2.14

On both platforms, CC needs to be restarted. On Windows, stop and restart CC after the change. On UNIX, stop CC before the change. On UNIX, need to be root to make the changes.

On Windows:
ClearCase Home Base -> Administration -> Control Panel -> Registry
If the new region is on a different registry server, be sure to change "Use Registry Server on host:" as well.
ClearCase Home Base -> Administration -> Control Panel -> Services Startup (Shutdown ClearCase & Startup ClearCase)

On UNIX:
New path: /var/adm/rational/clearcase/config
Old path: /var/adm/atria/rgy
Shutdown:
  # /usr/atria/etc/atria_start stop
Modify the region:
  # echo new-region > rgy_region.conf
If the region is defined on a different registry server:
  # echo new-server > rgy_hosts.conf
Restart:
  # /usr/atria/etc/atria_start start
Table of Contents



Determine a computer's current region.
On Windows, ClearCase Home Base -> Administration -> Control Panel -> Registry.
On UNIX, "cat /var/adm/atria/rgy/rgy_region.conf".
On Windows or UNIX:
  # ct hostinfo -l [ hostname ]
Table of Contents



Designate a backup registry server.
On UNIX or Windows, during install you can designate a backup registry server then.
On UNIX after install, on both the primary and backup servers, add the hostname of the backup registry server as the second line in /var/adm/atria/rgy/rgy_hosts.conf.
On Windows after install, open the ClearCase Control Panel applet and add the backup registry server hostname under the Registry tab. Do this on both the primary and backup servers.
NOTE: If you need to immediately use the backup registry server because the primary is going away, you can run the registry backup command manually. The command must be run from the backup registry host. It doesn't backup the registry password.
  # rgy_backup
Table of Contents



Set the registry password.
Updated: 04/29/16
Version: 7.1.2.14

The registry password is needed if creating any VOBs or modifying a VOB tag. You don't have to know the original registry password if resetting it. You do need to have root privileges on UNIX and Administratvie privileges on Windows though. Unknown if it's possible to re/set the registry password from a UNIX GUI.
On Windows, open the CC Administration Console and right-click on the ClearCase Registry to bring up its Properties. Near the bottom of the Site Config tab, click Modify.
From the CLI:
  # /usr/atria/etc/rgy_passwd [-password password]
Table of Contents



Set up a backup license server.
Unfortunately, CC license servers do not have a semi-automatic backup system like the registry does (rgy_switchover).
However, you can, via a Redundant License Agreement. Have your local Rational respresentative get it for you from http://corp-it03.rational.com/groupfolders/Contracts/public/GENERICS/RedundantLicenseAgreement-ClearCase.doc Have a duplicate set of licenses on a separate server. Create a network alias that points to the primary server, such as cc_licenses that points to the real server name. Point all the clients at the network alias instead of the real server name. If the primary server goes down, simply have a network admin point the network alias to the secondary server and the clients are never the wiser. Depending on the availability of the network admin, you can have clients pointed to a different server in a very short time.

Table of Contents





Generate a CC report.
On Windows, reports can be generated from within the Reporting Wizard in the ClearCase Explorer, from within ClearCase Report Builder in the Start menu, or from the CLI with ccreportbuild.exe. Note that the .exe lives under ccase-home\reports and probably isn't in any user's PATH. They all start the same GUI. Most reports have parameters that need to be filled in before the report can be run.
In the Report Viewer you can sort the columns up or down by double-clicking on the column header. You can filter the results by typing a single or string of characters in the Filter Results box. The tool will look for a match for that string in any of the columns. Reports can be saved as htm, xml, or csv.
The equivalent report generator doesn't exist on UNIX. At most you can get a simple report of checkouts, history, describe, or derived objects from within xclearcase.

Table of Contents





Create a custom CC report.
The default set of reports is stored in clearcase-home\reports. Information on customizing reports can be found in the online manual "Managing Software Projects". Use existing scripts as models for writing your own.
Unfortunately, the Report Builder can only see one scripts directory tree at a time. The documentation recommends copying all the files under clearcase-home\reports\* to a location outside the clearcase-home directory and repointing the Report Builder to that new location. This is to protect your customizations if CC is ever uninstalled and reinstalled. It has the added benefit that all clients can be pointed to that custom area. Note that each install of CC points to its own set of default report scripts. Copying them to a central (possibly shared) location is desired if you intend on customizing the scripts. However, it has the downside that if CC is ever upgraded, you need to manually copy the default set of scripts to your custom location again to ensure enhancements and fixes are picked up.
Copy all the files under clearcase-home\reports\* to a network share. If you decide to modify the directory stucture under which the report scripts live, don't modify the script_tools or script_rightclick directories. In the Report Builder, the root directory will always be named "Reports".
Reset the scripts directory. Go into the Report Builder and select Report->Set Scripts Location. This needs to be done on every machine that needs to see the custom scripts.
Create a customized script. Only the following extensions are recognized.
.exe   A compiled executable.
.pl   Exectued using perl.exe found in the user's PATH environment variable.
.prl   Executed using ccperl in ccase-home\bin.
.js   JavaScript, run under Windows Scripting Host, cscript.exe.
.vbs   VBScript, run under Windows Scripting Host, cscript.exe.
When creating your custom report, there are several points to remember.
For a report script to appear in the list of report choices in the Report Builder, the script must answer with a set of interface specifications when executed with a "-i". One of the interface specifications is an id help number. If you use an unused id number, such as 2222, the help in the Report Builder will report "No Help topic is associated with this item". If you don't supply any number to id, the generic "Getting Started with ClearCase Reports" help page will pop up. Also, the "helpfile" interface specification hasn't been implemented yet. So, as yet, there is no way to associate help text with your custom report. Note that if your run your script on the CLI to test the interface specification numbers and you've reused a bunch of the code in an existing report, the path to the script must given even if you're in the same directory as the script. For example, proper execution is somehting like: ccperl "full-path\script.prl" -i.
The next time the script is called is when the report is selected by a user, any required parameters have been filled in, and the "Run Report" button is pushed. The Report Builder will pass the user supplied information to your script via the CLI in the form of a space separated list of parameters and their values. For example; INTEGER="5" ISTREAM="mystream.1234". It's up to your script to check the consistency and accuracy of the input data. If bad data is encountered, your script can output to STDERR a text string that can be read by the user.
Output from your script is sent back to the Report Results via simple "print" statements. The output data must match the field definitions used for the "-i" output. For example:
...
	print "fields : ";
		print "\"View Tag\"(view_tag, rightclick, initial_width 30) ";
		print "\"View Owner\"(user_dq) ";
		print "\"Last Access Time\"(cctime) ";
		print "\"Creation Time\"(cctime) ";
		print "\"View Host\"(Host) ";
		print "\n";
...

	print "$viewtag;$owner;$last_accessed;$create_on;$hostname;\n";

...
Table of Contents



Create a CC report using SoDA for Word.
SoDA is Rational's Software Documentation Automation tool. It comes bundled with the Rational Suites. But, that implies that you must have one of the Rational Suites installed to use SoDA. It's not a stand-alone product. The fact that the reports are generated in Word implies that this is a Windows-only solution. You can run one of the canned reports located in Rational-home\SoDAWord\template\ClearCase or create one of your own by following these steps:
1) Start SoDA for Word: Start->Programs->Rational Software->Rational SoDA for Word. A blank Word doc will appear. This is the SoDA report template.
2) Select SoDA->Template View. A separate dialog will appear.
3) Select a domain class from the right-hand pane. If an object you want does not appear in the list, that list can be customized. See the SoDA documention for information on Source Domains. When you click on a particular domain, a dialog will appear asking for specifics about the object. For example, if you want a list of the latest baselines, you would need to choose the stream to which those baselines are applied. Yes, it's possible to create a report that has the latest baselines for all streams. Note: If you want special formatting in the report, such as verbose dialog, tables, special fonts, colors, etc..., that part must be done using the standard Word doc editing tools in the SoDA template Word doc. Use existing templates in Rational-home\SoDAWord\template for examples. If you're going to use Word tables, put the table in the template before adding any REPEAT or DISPLAY commands. Once the table is in, place the REPEAT command so that it spans the whole row, but not beyond the row itself. Place DISPLAY commands inside the cells as appropriate. If you want to customize the listed domains, see "Extend SoDA source domains".
4) Once you've chosen all the CC parameters that you want in the report, simply close the Template View window. You can open it at any time to add, modify, or delete any of the commands (OPEN,REPEAT,DISPLAY,LIMIT).
5) Under File->Properties, change the Title to something appropriate.
6) Under File->Save As, place the file in an appropriate location with an appropriate name. Note that when users run this report, they will have to have SoDA and CC installed for the report to generate properly.
To run a given report, double-click on it to open the SoDA template. Select SoDA->Generate Report. Save the report to a different location to avoid confusion. If you want to make the report generic (not specific to a given instance of an object), before saving and closing the SoDA template Word doc, go back to SoDA->Template View, right-click on the OPEN command and select Modify. Blank-out any parameter values that are there. If those values are blank, the user will be prompted for them at run time. However, be sure not to save the SoDA template after you run the report. The values you were prompted for will be hard-coded back into the template's OPEN command. One unfortunate feature of making a report generic is that when the user is prompted for information, most of the time it has to be typed in. That is, there aren't always pull-down lists.

Table of Contents





Extend SoDA source domains.
THIS DESCRIPTION IS INCOMPLETE!
When creating a SoDA report template you can choose from a list of objects (source domains) on which you'd like to report. If an object, or class of objects, isn't listed in the Template View, you can extend that list via a "domain extension file". The file must be called "domain.ext" and must live in "Rational-home\SoDAWord\domains". Because this area may get deleted if you ever un/reinstall Suites, keep a copy of the file under source control somewhere. For the official documentation, see "file://Rational-home/SoDAWord/help/soda.htm"
A domain.ext file has the following syntax, where words in "<>" brackets are to filled in by the author. The elipses "..." mean that the item can be repeated. All other words are literal, such as END_CLASS. Parsed attributes define additional structure within existing attributes.
EXISTING_CLASS <Domain>.<Class>
  <Parsed Attribute>
  ...
  <Script Attribute>
  ...
  <Unary Relationship>
  ...
  <N-ary Relationship>
  ...
 END_CLASS
 ...
The following is an example of adding a new class called "AllBaselines" to the ClearCase_Stream domain.

Table of Contents





Set up a trigger.
Updated: 01/06/12
Version: 7.0.1.8
Note that trigger types cannot be viewed in CCRC.
Trigger scripts can be as simple or complicated as you want and can be attached before or after several different CC operations, such as checkin, checkout, etc...   Each of the ct commands below are fully explained in the "CC Reference Manual". Alternatively, one can use the third-party tool ClearTrigger.
1) Create the trigger script:
If the trigger is applied as   -preop  , a non-zero exit status from the script will cause the CC-command to abort. If applied   -postop  , a message will be sent to standard out stating that the script has failed. Trigger scripts have many environment variables available to them, listed in the "CC Reference Manual" under mktrtype. Note that even though the default exit should be "exit 0", you should explicitly state exit 0 to avoid any possible ambiguity. The debugging of a trigger script can be aided by the use of the CLEARCASE_TRACE_TRIGGERS environment variable. If set to a non-null value at the time of firing, the trigger script will send messages to standard out. A   -print   option on the mktrtype command will accomplish the same thing. CC ships with Perl 5.002. If using that version of Perl, your trigger script will run on UNIX as well as Windows. It lives in ccase-home-dir/bin. In CC 3.2.1, it was called ccperl, in 4.0 it's known as Perl and Perl4.
2) Create a trigger type.
In UNIX xclearcase, Admin -> Trigger -> Trigger type... -> Type -> Create.
Cannot create trigger types from a Windows GUI. Even after the trigger type has been created, it can only be viewed from the Explore Types folder.
On the command-line:
  # ct mktrtype type before-after CC-command exec /path/trigger-script trigger-name
  # ct lstype -kind trtype
-ele.ment Allow element type to be attached to element types using mktrigger.
-typ.e Allow type trigger type to be attached to MetaData types.
-pre.op | -pos.top CC-command Run trigger-script before or after CC-command.
-exe.c | -execu.nix | -execw.in /path/trigger-script Executes the script "/path/trigger-script".
-rep.lace Replace the definition of an existing trigger type. Replace does not change the comment on the original definition (use chevent). Be sure to include every original parameter in the replacement, with the exception of those being replaced.
Type trigger types can only be applied to mktype, rmtype, rntype, lock, unlock, chevent and chmaster, which look similar to CC commands but are mktrtype specific. Element trigger types can be applied to numerous CC commands. See mktrtype in the Reference Manual for a listing.
NOTE: As of CC 4.2, triggers can be applied to UCM commands. However, those triggers will not fire for client installs running < 4.2.
NOTE: There is no way to create a "-element -all" trigger and then selectively remove that trigger from individual elements. Since those types of triggers are simply implied to be on all elements in the VOB, they do not show up on an element's attached list. So, an attempt at rmtrigger on a single element will result in an error.
NOTE: The mktype operation applies to all individual objects of a given type. For example, one MUST specify: -eltype -all. That is, one cannot specify "-eltype file" when using mktype.
Other useful options:

WARNING!   If the trigger is preop, references or modifications to the element will happen to/on the element version previous to the checkout. For instance, if one applies a label via a preop checkout trigger, the label will be applied to the version prior to the checkout and not the checkout itself, which in turn becomes the next version.

-mkl.abel label Attach labels without actually writing a trigger script.
-mka.ttr attribut=value Attach an attribute without actually writing a trigger script.
-mkh.link hlink,to=element Attach a "to" hyperlink without actually writing a trigger script.
-mkh.link hlink,from=element Attach a "from" hyperlink without actually writing a trigger script.
-nus.ers user1,user2,... Exempt the list of users from the trigger.
-pri.nt Send trigger info to stdout regardless of whether CLEARCASE_TRACE_TRIGGERS is set.

Inclusion and restriction lists:
In general, an "element" trigger type can be applied to any element. However, it can be restricted to a specific element, branch, label, attribute, etc..., such as "-element -brtype -all". Restrictions can be comma separated lists, such as "-element -brtype main,fix1.0"; no wildcards allowed. The comma can be considered an "or" statement.
Similar to element trigger types, "type" trigger types MUST have an inclusion list. That is, you must tell with which type the "type" trigger is to be associated, such as "-type -lbtype -all". Inclusions can be comma separated lists, such as "-type -lbtype REL1,REL2"; no wildcards allowed. The comma can be considered an "and" statement.
You cannot associate a trigger type with more than one operation. That is, if you want to attach the same trigger script to, say -preop rmelem & -preop rmver, you will need to create two separate trigger types. The list of commands to which triggers can be attached is in the CC Reference Manual under "mktrtype". Note that in general the CC-command will be the same as the command-line command, except for mktype (unique to mktrtype) and rntype (same as rename). Be sure that the path used in setting up the trtype can be seen from both the server and from any clients accessing that VOB.
3) If the   -all   option isn't used, it is necessary to manually attach the trigger to an element via mktrigger. Now, each time CC-command runs, the trigger will fire.
NOTE: If multiple triggers are associated with the same operation, their firing order is indeterminate. If one trigger fails, none of the others will even execute. Moreover, if one trigger completes ok and a subsequent one fails, there is no way to "rollback" the first one. If you need to control the firing order and/or monitor the success of each, the solution is to create a envelope trigger that calls the other trigger scripts and can control the order, monitor success, etc...

Using CAL.
	$name		= "trigger_name";
	$path		= "\\\\machine\\share";
	$vobtag		= "\\My_VOB";
	$vob_o		= $CC->VOB($vobtag);

	$builder_o	= $vob_o->CreateTriggerTypeBuilder;
	$lbtype_o	= $vob_o->LabelType("Approved");
	if ( "$lbtype_o" eq "" ) {
		print "\n$script ERROR: Unable to find a label type called Approved in $vobtag.\n";
		exit 1;
	}
	if ( ! -e "$path\\$name.pl" ) {
		print STDERR "\n$script ERROR: Unable to locate $path\\$name.pl.\n";
		exit 1;
	}

	$builder_o->SetName($name);
	$builder_o->SetKindOfTrigger(2);		# All element
	$builder_o->SetFiring(1);			# Preop
	$builder_o->SetOperationKindsArray(19);		# mklabel
	$builder_o->SetRestrictionsArray([$lbtype_o]);	# Only on Approved label
	$builder_o->AddExecAction("ccperl $path\\$name.pl");

	$trtype_o = $vob_o->TriggerType($name);
	if ( "$trtype_o" eq "" ) {
		$trtype_o->Create;
	} else {
		$trtype_o->Replace;
	}
	if ( Win32::OLE->LastError ) {
		print STDERR "\n$script ERROR: Unable to create/replace the trigger.\n".Win32::OLE->LastError;
		exit 1;
	}
Table of Contents



Remove a trigger from an element.
When applying the rmtrigger subcommand to a directory, it automatically removes the trigger from created elements unless the   -ninherit   option is used. That is, the trigger is removed from the directory, but not its inheritance list. Under normal conditions, elements created in a directory will inherit any triggers applied to the directory itself. That is, they inherit the trigger from the parent directory.
  # ct rmtrigger -nc trigger-name element
Table of Contents



Find all elements with a certain trigger attached.
In UNIX xclearcase, Report -> Find query.
The find command is only available on the command-line in Windows.
This will find all the elements at or below the current directory that have the specified trigger attached.
  # ct find . -ver "trtype(trigger)" -print

Find all triggers attached to an element.

Unfortunately, on UNIX there is no way to answer this question without writing a script.
On Windows, in the context-menu, Properties of Element -> Triggers tab.

Table of Contents





Attach a trigger to a specific element.
Generally, when a trigger type is created, it is defined as "-element -all". That is, it is automatically attached to all elements in the VOB without using the mktrigger command. However, it may be necessary to attach a trigger to a specific element. In those cases, do no use the "-all" option in the mktrtype.
  # ct mktrigger trigger-name element
Some useful options:
-recurse process the directory's entire subtree
-ninherit attach a trigger to the dir and its contents, but not future elements
-nattach attach to elements in the dir, but not the dir itself
NOTE: Inheritance only happens at the time of mkelem. A new trigger applied to a dir will not automatically apply to its elements unless the -recurse option is used.

Table of Contents





Ensure duplicate element names are not used (evil twin).
Updated: 01/03/13
Version: 7.1.2

In any parallel development environment, not just CC, it's possible to add an element to source control on one branch, while another user adds an element to source control with the same name on another branch of the same parent directory. Both will succeed in adding the files to source control, but will have problems when it comes time to merge the branches. This problem is affectionately known as the evil twin scenario.
The following trigger script will detect and warn against that condition.

NOTE: The trigger is associated with the lnname operation because it covers all four commands that could result in an evil twin. However, even though the trigger type is created as preop, the lnname occurs after the file has been copied to .mkelem, which doesn't get renamed back just because the command failed. That is, during an operation, such as mkelem, the original file is renamed to file.mkelem. Once an empty file of the same name is under source control, the contents of the original are copied on top of the new element and checkedin under the file's original name. For that reason, the script below will rename the file back if there is a problem.

################################################################################  
#  
# File:         EvilTwin.pl  
# Description:  This trigger checks for evil twins. An evil twin can occur when  
#               a user checks in an element which matches an element name on  
#               some other branch of the directory that is invisible in the  
#               current view.  This script works with dynamic and snapshot views
#		on Windows and Unix.
# Trigger Type: All element  
# Operation:    Preop lnname
# OS:		Windows and Unix

# Author:       Eric J Ostrander  
# Created:      May 09, 2012
#  
################################################################################  


#####################
# Ensure that the view-private file will get named back on rejection.  
BEGIN {  
	END {  
		rename "$ENV{CLEARCASE_PN}.mkelem", "$ENV{CLEARCASE_PN}"  
		if $? && ! -e "ENV{CLEARCASE_PN}" && -e "$ENV{CLEARCASE_PN}.mkelem";  
	}
}



#####################
# Initialize some stuff.

$os = $^O;

if ( "$os" eq "MSWin32" ) {
	use Win32::OLE;
	$slash			= "\\";
	$protected_slash	= "\\\\";
	$windows		= 1;
} else {
	$slash			= "/";
	$protected_slash	= "/";
	$windows		= 0;
}

$script		= (split(/$protected_slash/,$0))[-1];
$pname		= $ENV{CLEARCASE_PN};
$view_kind	= $ENV{CLEARCASE_VIEW_KIND};


#####
# Debug values.  These should remain commented out, unless actively debugging.
#$debug		= 1;
#$pname		= "M:\\E559055_generic_view\\deleteme\\file2.txt";
#$view_kind	= "dynamic";
#####

if ( $debug ) { print "OS: $os\nPname: $pname\nView kind: $view_kind\n"; }


if ( "$pname" =~ /(.+)$protected_slash(.+)$/ ) {
	$element_parent	= $1;
	$element_name	= $2;
}
if ( $debug ) { print "Element name: $element_name\nElement parent: $element_parent\n"; }

if ( "$view_kind" eq "dynamic" ) {
	$dynamic = 1;
} else {
	$dynamic = 0;
}



#####################
if ( $windows ) {
	if ( $debug ) { print "Starting CAL ...\n"; }

	$ct = Win32::OLE->new("ClearCase.ClearTool");
	if ( "$ct" eq "" ) {
		print STDERR "$script ERROR: Can't create cleartool application object via call to Win32::OLE->new(\"ClearCase.ClearTool\")\n".Win32::OLE->LastError;
	}
}



#####################
if ( $debug ) { print "Running lsvtree command ...\n"; }
@return = `cleartool lsvtree -s $element_parent`;
foreach $line (@return) {

	chomp($line);
	chop($line) if ( "$line" =~ /\r$/ );

	if ( "$line" !~ /\d+$/ ) {
		next;
	}
	if ( "$line" =~ /^(.+)$protected_slash(\d+)$/ ) {
		$branch_path	= $1;
		$latest_version = $2;
	}

	for ( $x = $latest_version; $x >= 1; $x-- ) {
		$path = "$branch_path$slash$x$slash$element_name";

		if ( $dynamic ) {
			$evil_twin = ( -e "$path" );
		} else {
			if ( $windows ) {
				$ct->CmdExec("ls -s \"$path\"");
				next if ( Win32::OLE->LastError );
			} else {
				$return = `cleartool ls -s \"$path\" 2>&1`;
				next if ( "$return" =~ /error/i );
			}
			$evil_twin = 1;
		}

		if ( $evil_twin ) {
			$prompt .= "\nERROR: the element ($element_name) already exists in another version of the current directory:\n";
			$prompt .= "$path\n\n";
			$prompt .= "You can either merge the parent directory versions or create a ClearCase hardlink to that element.\n\n";
			$prompt .= "If you feel you really need to perform this action, please ";
			$prompt .= "contact your ClearCase administrator.\n";
			print STDERR "$prompt\n";
			exit 1;
		}
	}
}


if ( $debug ) { exit 1; }
exit 0;
Table of Contents



Triggers and multisite syncs.
Updated: 12/14/11
Version: 7.0.1.8
Triggers and trigger types are not replicated, so must be recreated at the remote site.
Triggers don't fire when an incoming sync packet is applied.

Table of Contents





CCRC triggers.
Updated: 05/16/13
Version: 7.1.2

CCRC triggers fire on the server side, so it is the server that must be able to see the path to the trigger script. Moreover, environment variables are derived from the server, not the user's client workstation. Clearprompt is supported.
See http://www-01.ibm.com/support/docview.wss?uid=swg21207634.

Table of Contents





Create a dynamic view.
In UNIX xclearcase, View -> Create...
On Windows, (CC 4.1-) ClearCase Home Base -> Views -> Create View
In Windows (CC 4.1+) ccadminconsole.msc, select My Host -> Views. Action -> New -> View.
In Windows ClearCase Explorer (CC 4.1+), Toolbox -> Base ClearCase -> Create View.
From the CLI:
  # ct mkview -tag view-tag view-storage-area

ex:
On UNIX,
  # ct mkview -tag ejo_view /disk1/clearcase/views/ejo_view.vws
On Windows,
  # ct mkview -tag ejo_view \\hostname\share\ejo_view.vws
The directory ending in .vws will be created for you by CC. The view-storage area doesn't need to have the same name as the view-tag, but should for clarity. The view-storage directory does not need to end in .vws, but should to distinguish it from other files and directories in the same location.
Some useful options:
-tco.mment   "comment" Attach a comment to the view.
-region   region Specify a region other then the current.
-ln   remote-location Specify a remote storage location for the view-storage .s directory. (UNIX only)
-cachesize   size Set the view cache size. (default 200k).
-hos.t   hostname   -hpa.th   hostpath   -gpa.th   globalpath Override how the path is registered. All three are a set.
-sha.reable_dos | -nsh.areable_dos New in CC 4.0. Designate whether DOs created with this view can be shared (winked-in) by other views. The default is shareable unless overridden by sitewide defaults.
-str.eam   stream-name New in CC 4.0. Specify a UCM stream with which this view will be associated.
-sna.pshot New in CC 4.0. Create a snapshot view from the Windows or UNIX CLI.
-stg.loc   {   storage-name   |   -aut.o   } New in CC 4.1. Place the vws directory in the registered storage-name location or take a default location.
-col.ocated_server New in CC 4.1. Place the view-storage area in with the loaded file view-root.
-tmo.de   transparent New in CC 4.1. Formerly "-tmo.de unix". The view does not change line terminators in any way.
-tmo.de   insert_cr New in CC 4.1. Formerly "-tmo.de msdos". The view converts to ; UNIX VOB -> Windows view.
-tmo.de   strip_cr New in CC 4.1. The view converts to ; Windows VOB -> UNIX view.

NOTE: View text modes (-tmode) are only applicable to text_file based documents. You cannot change a view's text mode after creation. See setsite to set setwide textmode view creation defaults. The -tmode options override the default setting. Pre CC 4.1 VOBs accessed with view set to take advantage of text modes must be configured for such. See msdostext_mode for more information. VOBs created using CC 4.1 automatically handle all text modes. To determine a VOBs current text mode, see msdostext_mode. If creating an Windows view from the View Creation Wizard, see Advanced for the insert_cr option. Cannot create strip_cr views from any GUI. A "ct lsview -properties -full viewtag" will tell you the text mode of an existing view (modes are still listed as "unix" and "ms_dos").

NOTE: When allowing "-stgloc -auto" to pick a storage location for you, keep these points in mind:
For dynamic views, automatic server storage selection proceeds as follows:
1) Server storage locations that have no global path (-ngpath) are disqualified.
2) Server storage locations on heterogenous hosts are disqualified.
3) Local server storage locations are preferred over remote ones.
4) A server storage location is selected at random from the remaining candidates.
Default for snapshot views: An automatically selected server storage location, if any can be found; else -colocated_server. For snapshot views, automatic server storage selection proceeds as follows:
1) Server storage locations with global paths (-gpath) that reside on heterogeneous hosts are disqualified.
2) Local server storage locations are preferred over remote ones.
3) A server storage location is selected at random from the remaining candidates.

NOTE: Windows: There is no way to create view on the CLI and at the same time associate it with a view profile.
On UNIX, ensure your umask is set to a value appropriate to the work to be done in that view. For example, if this view is to be used a "build" view and will accessed by more than one person in a group, ensure the umask is at least 007. The 0 in the second slot allows anyone in your primary group (id command) to write to the view-storage area.
On Windows, views can only be created in shared directories. Windows Client will allow up to 10 simultaneous users to access a share. If the share is acting as a view server, one will probably need to install Windows Server. View write access is controlled by the CLEARCASE_PRIMARY_GROUP environment variable.
On UNIX, view information is logged in /var/adm/atria/log/view_log and on Windows in Start -> Programs -> Administrative Tools (Common) -> Event Viewer -> Log -> Application which can be accessed via the ClearCase Home Base -> Administration -> Log Browser -> view. See cleargetlog on either platform.

Table of Contents





Remove a view.
In UNIX xclearcase, Admin -> View..., select viewtag, View -> Destroy ? view...
On Windows, (CC 4.1-) ClearCase Home Base -> Views -> Delete View.
In Windows (CC 4.1+) ccadminconsole.msc, select My Host -> Views, select a view, Action -> All Tasks -> Remove View.
In Windows ClearCase Explorer (CC 4.1+), Toolbox -> Base ClearCase -> Remove View.
From the CLI:
This procedure is described in the CC Admin Manual (page 161). You cannot be inside the the view-storage directory. Also, you must own the view or have administrative privileges. All that is needed is to run the rmview command.
  # ct rmview -tag view_tag
However, if a view's directory was inadvertenly removed using the UNIX "rm -r" command, use the following to clean up the mess: cleanout the removed view's checkouts, remove view storage area from the view object registry, remove the view from the view tag registry and kill the view_server process; which runs with the uuid of the view owner.

Note the view's "View uuid".

  # ct lsview -long view_tag
Deactivate the view_server daemon.
  # ct endview -server view_tag
Remove the view tag from the tags registry.
  # ct rmtag -all -view view_tag
Remove the view storage area from the objects registry.
  # ct unregister -view -uuid View_uuid
Remove any references to the view from VOBs. Determine if any VOBs have references to the view by looking at checked-out elements.
  # ct lsco -avobs -long
  # ct rmview -vob vob_tag -uuid View_uuid
See also cleardlg on Windows.

Table of Contents





Modify a view's rules (config_spec).
The edcs subcommand will invoke the editor specified by the WINEDITOR environment variable. If it isn't set, the default is vi on UNIX and Notepad on Windows. The following are some of the more common rules found in config_specs; not in the order of a real config_spec. While comments are allowed in a config_spec, they must begin with a pound sign and be on a separate line.
  # Every file in the current directory checkedout to my view.
    element * CHECKEDOUT
  # The latest version of each element on the main branch.
    element /vobs/myvob/.../* /main/LATEST
  # The latest version of on the "bugfix" branch of only those files ending in .c.
    element *.c /main/bugfix/LATEST
  # The version on any branch with the REL1 label attached, but prevent checkouts.
    element * REL1 -nocheckout
  # The version on the bug1 branch that has the attribute QA
  # with a value of "yes", where the bug1 branch can be attached anywhere.
    element * .../bug1/{QA="yes"}
  # Any element with a REL1 label attached.  Create the branch "br1"
  # from that version if someone checks it out.
    element * REL1 -mkbranch br1
  # Chose the latest version up to a certain time.  The -time option is only
  # used with the LATEST label.  If the time given is variable, such as the
  # word "yesterday", that time is frozen when the config_spec is modified.
    element * /main/LATEST -time 5-Dec.13:00
NOTE: When writing rules for a Windows view, you are allowed to use either forward "/" or back "\" slashes interchangeably. UNIX views can only have forward slashes.
See "config_spec" in the CC Reference Manual for a full listing of what can go into a config_spec file. See also the query_language man page.

To edit a config_spec:

In UNIX xclearcase, View -> Config spec -> Edit.
On Windows, (CC 4.1-) ClearCase Home Base, not possible.
In Windows (CC 4.1+) ccadminconsole.msc, select My Host -> Views, select a view, Action -> Properties -> Config Spec -> Edit.
In Windows ClearCase Explorer (CC 4.1+), Toolbox -> Base ClearCase -> Edit View Properties, select a view, OK -> Config Spec -> Edit.
From the CLI:
  # ct edcs                (modify current view)
  -- or --
  # ct edcs -tag view-tag  (specify another view's config_spec)
  -- or --
  # ct edcs -tag view-tag  /path/some_another_config_spec_file
When it exits, the edcs command will ask you if you want to use (set) the newly modified config_spec. If you answer no to that question, your changes will be lost. Do not use a regular editor to edit the config_spec file, as the edcs command creates a .compiled_spec in the view storage area; which is the version actually used by the view_server daemon. Note that setview and startview do not recompile the .config_spec, only edcs and setcs.

WARNING!   If, after editing the config_spec, more than one version of an element matches a rule, there will be an error of the sort "Trouble looking up element ..." or "I/O error".

Rules that you want all users to have in their config_specs can be placed in a global rules file. To include those rules, add the following line to each view's config_spec:

include /path/global_rules_file
If the rules in the global file are updated, each view's config_spec will need to be recompiled with the   -current   option. This can also be used to reset the config_spec if variable time rules are used.
  # ct setcs -current
NOTE: A config_spec for a view located on a UNIX server that uses forward slashes will also work on an Windows.
NOTE: The rules in the config_spec have no affect on view-private files.
NOTE: Using edcs and setcs are final. You cannot go back to the previous config_spec.
NOTE: A single config_spec line cannot exceed 1024 characters, including spaces.
NOTE: The setcs command copies the config_spec to config_spec.bak, so you need appropriate permissions to do that.

WARNING!   See the section View profiles. for important caveats about config_specs and view profiles.

To just look at the config_spec.

  # ct catcs
To make a specified file a view's config_spec.
  # ct setcs filename
To reset a view's config_spec to the default.
  # ct setcs -default
Update the view's config_spec in a UCM environment. This is used if there are multiple views associated with one UCM stream and one of the other views has conducted a rebase.
  # ct setcs -stream
All the setcs options work on the currently set view unless the "-tag viewtag" option is given. The -tag option can only be used for dynamic views.
NOTE: A view cannot be used to strictly look at files with a certain label. That is, if there are elements in a directory that have labels mixed in with those that don't, there is no clean way to just look at the labeled ones alone. The reason is, if the parent directory has no label on it, the view attempting to look for elements with that label will not see that directory because no version of it has the label, hence no elements inside the directory will be seen either. However, if you place the label on a version of the directory, you will see all files in the directory independent of whether they have a label or not because they are all part of that directory version. However, the elements that do not have the label will not be available at all for checkout/in or viewing of any kind; they are just names in the directory at that point and have no content. This assumes you have a "/main/LATEST" line in the config_spec after the "/main/label" line. If there is only the label line and no line about CHECHEDOUT or LATEST, you will get errors such as "No such file or directory" for the elements without the label.

Table of Contents





Rename a view tag.
Unfortunately, you cannot rename a viewtag in place. It must be removed and recreated with the new name. Be sure to remove the tag from the ClearCase Explorer first.
In UNIX xclearcase, View -> List, select a view, Admin -> Registry -> Remove/Create tag.
On Windows, (CC 4.1-) ClearCase Home Base, not possible.
On Windows (CC 4.1+) ccadminconsole.msc. The ccadminconsole executable can be found in the installation bin directory.
- ClearCase Registry -> Regions; select a region
- View Tags; select a view
- Action - >Properties; make a note of the Global Path
- Action -> All Tasks -> Remove View Tag
- Right-click on View Tags and Action -> New -> View Tag

From the CLI:
  # ct rmtag -view view-tag
  # ct mktag -view -tag new-view-tag viewstore/new-view-tag.vws

ex: ct mktag -view -tag admin_view /admin/clearcase/views/admin_view.vws
If doing the mktag on Windows connected to a UNIX server, it may be necessary to give extended path information.
  # ct mktag -view -tag new-view-tag
       -host server-name
       -gpath UNC-pathname
       -hpath path-on-server
       UNC-pathname

ex: ct mktag -view -tag admin_view
       -host scm
       -gpath \\scm\viewstore\admin_view.vws
       -hpath /viewstore/admin_view.vws
       \\scm\viewstore\admin_view.vws
Table of Contents



View profiles.
View profiles are only relevant to Windows views. The VOB can live on either Windows or UNIX, but the view must be Windows. If one wants to create a "private branch", a view profile will have to be created first. First, tell CC where to store view profiles in Start -> Settings -> Control Panel -> ClearCase -> Administration -> Options -> View Profile Tree. Give the UNC path to a share where profiles can be stored; most likely the same as where the viewstore and vobstores are. Next, create a view profile via Start -> Programs -> Rational ClearCase Administration -> ClearCase View Profiles -> File -> New -> View Profile.
1) Give a name and comments for the profile.
2) Add the names of VOBs that will need this view profile.
3) Yes. (most likely this view profile will be used for private branches)
4) Give the name of a checkpoint label. The label type for it will have to be, or has been created separately. The version of the element with this label will be the only one allowed to be branched from.
5) Create new branch type. Give it a name like "working_branch". Cannot use "main" as the name.
6) Next and Finish. The config spec will be the default unless you used another view profile as a model for this one.
The new view profile now shows up in "Exploring ClearCase View Profiles" windwon. To modify any of the parameters set down in the steps above, double-click on the view profile's icon to restart the setup wizard from the beginning, or right-click on it and select properties. Note that views associated with the view profile are not automatically updated. Each user must access their view's properties and Synchronize with the profile.
Once a view is associated with a profile, the user can create private branches off of the branch set up by the profile. Starting and ending a private branch automatically reconfigures the associated view's config spec. When a private branch is ended, the user has the choice of leaving their work on that branch or merging it with the integration branch. If the user restarts the private branch, the exact same one as before is used. For this reason, private branches in view profiles are not task based, but instead live forever.

WARNING!   The default view-profile config spec has an error in it that prevents you from seeing the latest contents of a directory. The config spec will have three lines at the bottom. Change the last line as follows:
old: element * \main\0 -mkbranch branch-name
new: element * \main\LATEST

The whole idea of creating a view-profile such as this is to automatically create a branch to work on a file off of \main\LATEST. However, before you can checkout an element in the directory, you need to checkout \main. The way "old" is written, it would create a branch off of \main\0, which probably isn't the version of the directory from which you intended on branching. I also removed the   -mkbranch   from it as well, as it isn't necessary.
NOTE: The config spec editor on Windows won't allow you to edit those last three lines in their current position. That is, you can only edit lines in the middle portion of the config spec. But, since the last line has to remain last, it is necessary to copy the 2nd and 3rd to last lines to the middle section and add the "new" line after them. This leaves the original three at the bottom of the config spec, but this is innocuous, as those rules will never be reached now anyway.

WARNING!   Even after a view has been disassociated from a view-profile, its config spec is still configured with the view-profile rules. This can cause undesired results. Edit the config spec by hand to return it to the default.

Table of Contents





Find/list view-private files.
Updated: 10/11/12
Version: 7.1.2
The lsprivate cmd only applies to dynamic views. See below for snapshot views.
In UNIX xclearcase, Report -> List checkouts/derived objects. There is no way to find simple, view-private files in this GUI.
In Windows ClearCase Explorer, right-click on the view and select Find Checkouts. There is no way to find simple, view-private files or derived objects in this GUI.
From the CLI: The default of this subcommand is to list all view-private files belonging to the current view in all VOBs:
  # ct lsprivate
For snapshot views, use the following while sitting in a snapshot view. Unlike lsprivate, this command cannot distinguish between checkouts, derived objects, or simple view-private files without you parsing the output.
Unfortunately, this command cannot be used to search inside the folders of a CCRC snapshot view. For CCRC, view-private files can only be found using the GUI.
  # ct ls -r -view_only
Table of Contents



Start and stop a view.
Under normal circumstances a view does not need to be started or stopped explicitly. That is, mkview, mktag and setview will all start the view_server process if necessary. However, a system glitch may cause the view_server to stop. If you just want to use a view, use the setview subcommand or cd to another view via the view-root directory.
  # ct startview view-tag
-or-
  # cd /view/view-tag/VOB-tag
The same is basically true for stopping a view. If you don't want to use a particular view anymore, just "exit" the view. However, it may be necessary to end the view manually, if say the .vws directory was deleted without rmview. If you want the view stopped everywhere, use the   -server   option.
  # ct endview view-tag
Both the startview and endview subcommands affect the view_server process for that view.

See also cleardlg on Windows.

Table of Contents





Snapshot views. (general)
The following discussion is applicable to Windows only in CC 3.x and UNIX/NT for CC 4.0+. Snapshot views allow one to load the files from a VOB onto the local machine and work on them in their current state until an update (see below) is done.

NOTE: As of CC 4.1, one can access Windows VOBs from a UNIX client via a UNIX snapshot view. Moreover, one can have the UNIX snapshot view's storage directory located on a Windows server if that server is also running CC 4.1 and has had it's storage locations upgraded via mkstgloc or SvrStor.exe.
To determine the location of the downloaded files if you forgot where you put them, see "Determine the location of snapshot view loaded files."

In Unix xclearcase, can only create dynamic views in CC 3.x and 4.x.
In the Windows GUI, ClearCase Home Base -> Views -> Create View.
From the CLI. If you don't want the view-storage to be located in the same directory as snapshot-view-path, use the -vws option. However, on UNIX, once you've plit the two, there is no way to determine the location of the loaded files. So, on UNIX, remember where you put them :-).
  # ct mkview -tag view-tag -snapshot snapshot-view-path
Also, if you don't use the -vws option and the CC Admin has designated a site-wide storage location, CC will put the view's .stg directory in that share and NOT colocate it wherever the snapshot-view-path is. When creating a snapshot view from the CLI, the only way to override a site default view storage location is to the -vws option. The path specified in the -vws option must be in a shared directory. If you don't like that fact that you have put the view's .stg directory in a share, create the share, but lock it down so that only you have access to it.
The directory structure of the VOB is loaded directly onto the local drive (if there is enough space). That is, the answer to the question "Where would you like it located?" is not referring to the view storage, but rather where the loaded VOB files will be located on the local machine. On Windows, to designate where the view storage is to be located, go to "Advanced Options ..." on the same page. However, if the Advanced Options are left with the defaults, the view-storage area will be placed in the same directory as you selection for the loaded files. When prompted, it isn't necessary to load the entire VOB, subdirectories or single elements can be loaded just the same.

Modify the load rules.
If one needs to load other directories or VOBs in the future, right-click on the snapshot view directory and go to ClearCase -> Properties of View -> Load Rules -> Edit Load Rules (be sure to click on "Show All VOBs" if the VOB you are seeking is not visible). If previously loaded files are removed from the load list, those files will be removed from the local snapshot directory. CC will check for hijacked files first though.

Remove
To delete a snapshot view, see rmview. If the view's view root is missing, see "Remove a snapshot view whose view root is missing".

Update.
To update a view, right-click on the snapshot view (the top level where the files are loaded) and Update view ..., or from the CLI.
  # ct update view-tag
Note that no matter what the permissions are on an element in a VOB, the element's permissions when it's loaded to a user's local drive are the username performing the update and that user's primary group.
Hijacked files.
If one is going to disconnect from the network, first checkout all the files to worked on. However, if necessary, files loaded from the VOB are editable without checking them out first. Simply change their access mode to allow write access and edit the file. When you reconnect to the network and update the snapshot view, CC will alert you to the fact that it has detected "hijacked" files. You can treat hijacked files in one of the following manners: 1) Ignore that it was hijacked and the VOB will not be updated with those changes. 2) Checkout the file. If there is already a reserved checkout of that file, you can check it out unreserved. You will then need to wait until the other user checks their version in and then merge your changes with theirs. Or, you can change their checkout status to unreserved and then simply check yours in. 3) If there are versions of the file beyond the version from which you made your hijacked changes, you will be required to merge your changes with those.

NOTE: Even though permissions in the VOBs and views happen at the group level, the update view doesn't seem to work unless the world has read/execute permissions on the elements being updated. Run a "ct protect -chmod 444" on the element if getting a permission denied during update. This can be caused by somebody creating an element with a umask of 007.

Table of Contents





Recover "stranded" view-private files from an unavailable VOB.
When trying to access a "stranded" file, you'll most likely get an error message such as "Warning: VOB is unavailable". View-private files can become stranded if the VOB they are associated with is unavailable for some reason. To recover these, run recoverview. This command will recover them to the view's storage area in the .s/lost+found directory. It writes to the /var/adm/atria/log/view_log on UNIX and Start -> Programs -> Administrative Tools (Common) -> Event Viewer -> Log -> Application which can be accessed via the ClearCase Home Base -> Administration -> Log Browser -> view.
  # ct recoverview -vob vob-UUID -tag view-tag
Another reason view-private files can become stranded is if the directory in which they used to live inside a VOB has been relocated to a different VOB.
  # ct recoverview -synchronize -vob vob-tag -tag view-tag
From the view's lost+found directory, the files can be simply copied to a new location in a VOB.
Some useful options:
-f.orce Performs a view database recovery whether one is needed or not.
-synchronize Synchronizes the view with all VOBs in which the view has view-private files.
-vob   path-in-VOB With -synchronize, moves stranded files view-storage/.s/lost+found from a directory that is no longer in that VOB.
-vob   VOB-UUID Used without -synchronize, moves stranded files view-storage/.s/lost+found from a VOB that is no longer available.
-tag   view-tag | view-storage Specify a view other than the current one.

Table of Contents





Remove derived objects from view storage.

WARNING!   This command modifies the relationship between the view storage and VOB storage. Ensure no tools or applications are using the view DOs when this command is executed. The view_scrubber command lives in atria-home/etc.

Derived object removal is accomplished via the view_scrubber command. You can only use view_scrubber after the DOs have been promoted to the VOB, either by some other view winking them in or by self-promotion via the -p option (below). That is, with the -p option, the view_scrubber doesn't actually delete any derived objects, it merely cleans out any copies that are in your view storage. In that case, DOs scrubbed from the view storage are automatically winked back in. Optionally you can scrub just named DOs.
NOTE: The view_scrubber command releases disk space taken by view-private files and DO containers, but no DO CRs. That is, the view's database grows in size as derived objects are created, but does not shrink if the associated DO is removed. See the recoverview command for information on releasing view database space back to the system.
  # view_scrubber [DO-name]
Some useful options:
-p Promote the DOs to the VOB first (self promotion).
-k Keep going even if a DO cannot be processed (default is to abort).
-n Do not actually perform the scrub, but merely report what would have been done.

The view_scrubber.sh script can be used to invoke it as well, which simply mimics

  # find . -type f -print | atria-home/etc/view_scrubber
See "Remove derived objects" for more information on deleting derived objects.

Table of Contents





List views or view properties.
In Unix xclearcase, View -> List...
In Windows, in the CC Administration Console, surf to the host that houses the view storage (perhaps My Host or under ClearCase Network) and expand the Views folder. Right-click on a view to bring up its Properties.
From the CLI:
  # ct lsview [view-tag]
Some useful options:
-s.hort Limit the output to just the view-tags.
-l.ong List registry information about each view.
-pro.perties List when and by whom the view was created plus permissions.
-pro.perties   -ful.l Give all properties possible.
-age When and by whom was the view last accessed.
-reg.ion   region List views in a different region.
-hos.t   hostname List the view whose storage directories reside on hostname or any alias of hostname.
-sto.rage   view-strorage Specify a view by its storage area vice view-tag.
-uui.d   view-uuid Specify a view by its uuid vice view-tag.
To select a pattern subset of the view list:
On Unix,
  # ct lsview '*pattern*'
On Windows,
  # ct lsview "*pattern*"
To modify the properties of a view, see "Modify view properties".

Table of Contents





Set to a dynamic view.
In Windows Explorer, right-click on the MVFS drive (defaults to M) -> ClearCase -> Start View ... -or- ClearCase Home Base -> Views -> Start View.
On UNIX, a view will be requested if starting xclearcase without a view already set.
From the CLI:
  # ct setview view-tag
On Windows, the view can be root-mapped to a drive letter and the view is only set when inside that drive letter. On UNIX, after the view is set from the CLI, you are set into a sub-shell and the view is carried with you no matter where you cd.
NOTE: setview is only available from the Windows CLI for CC versions prior to 4.0.

Table of Contents





Modify a view's properties/permissions.

Cache size.
Increasing a view's cache size generally improves performance, especially during builds. The default size up to CC 3.2.1 is 200k for 32 bit systems and 400k for 64 bit. Starting in CC 4.0, the cache size is 500k on 32 bit systems and 1m on 64 bit. Rational recommends not setting a view's cache to a value larger than about 4m, as larger values probably won't help much. When the view's cache size is increased, it doesn't immediately take up that much memory, but merely sets an upper limit to the amount of memory that can be taken.
Though increasing a view's cache size is recommended, one needs to pay closer attention in those cases. As an example, if a view server is hosting views for approx 30 developers and over time each developer conservatively has 4 views each and each view's cache has been bumped to 4MB and these view's have been around awhile without a reboot of the server, simple math will show you that the views are probably needlessly holding onto about 500MB of memory. So, one needs to either do an "endview -server" when not using a view or manually flush its cache periodically; merely exiting the view on UNIX or stopping the view on Windows still leaves the view_server process running. The setcs command is normally used to set to a new config_spec, but can also be used to flush the view's cache without modifying the config_spec.
  # ct setcs -current
To set the view's cache size:
1) The chview command is new in CC 4.0.
  # ct chview -cachesize size view-tag
2) Neither the chview nor setcache require a stop and restart of the view_server process, and update the cache immediately.
  # ct setcache -view -cachesize size view-tag
3) You can add a   -cache   line to the .view file in the view-storarge-area (see .vws on right side of lsview). However, the view_server process for that view will have to be killed and restarted (endview -server). A new line in the .view file for the new cache size of 1m would be:
  -cache 100000000
4) The view's cache can be set from the outset in the mkview from the CLI.
  -cachesize 1m
To get the current cache status.
  # ct getcache -view view-tag
Note that a new option called -persistent in CC 2003.06.00 will ensure cache settings are persistent across reboots.

Release view database disk space back to the system.
As data is collected in a view, the view's database increases in size. Commands such as view_scrubber that remove DOs from a view merely release logical space inside the view's database. That is, the disk space taken by the database does not shrink. This is true for the view-storage/db/* files and the view-storage/.s/view_db.crs_file file (which contains the derived object configuration records). To actually release that space back to the system, one needs to run recoverview twice on that view. Normally recoverview is only needed when a VOB is no longer available and the view's view-private files that once belonged to the VOB are now stranded. However, it has the added benefit that it calls reformatview, which in turn cleans up the database.
The recoverview must be run twice. The first pass releases any unused space in the database back to the system and cleans up CRs no longer attached to a DO. The second pass releases the now newly unused space (freed up in the first pass) back to the system. A third run has no affect.
An attempt to run reformatview by itself (which is actually the only part that is really needed) will result in the message "reformat not needed for view". Unfortunately, reformatview does not have a -force option, but recoverview does.
  # ct recoverview -force -tag view-tag
  # ct recoverview -force -tag view-tag
NOTE: Running recoverview does not affect view-private files.

WARNING!   Rational recommends not being anywhere in the view-storage area during the recoverview/reformatview (reason unknown).

Control whether DOs are shareable.
New in CC 4.0, you are allowed to control whether DOs created in a view are shareable; whether they can be winked in. This is applicable to dynamic views only. The shareability of a DO is determined by whether there is an entry for it in the VOB's database. So, unshareable DOs simply do not have that VOB database entry. The shareability of DOs can be changed on the fly during a build and will take affect after completing the current target. This property can be toggled on Windows via CC Home Base.
  # ct chview { -sha.reable | -nsh.areable } view-tag
This property can also be set during the mkview command using identical options. The default is shareable.

Permissions.
A view's permissions are important if the view is to be shared or DOs created using it are to be shared. For instance, if a build is done in view1 that has 755 permissions, DOs created using it will have 755 permissions. When view2 does a build and winks-in the DO, it will get copied to the VOB and winked-in to view2 with 755 permissions. Now, if view2 modifies a source file that causes those DOs to be rebuilt, view2 will get a permission denied when it tries to overwrite the winked-in DO. So, if sharing binaries in a group project environment, it's important to ensure DOs created in a view can be overwritten by other views when necessary. However, it may not be desirable to give the group write permission for the entire view. In that case, use the CCASE_BLD_UMASK environment variable to temporarily override the view's umask during builds.
A view's permissions are set during mkview. On UNIX a view's permissions are derived from the creator's umask. On Windows, a view's permissions are hard-wired at 775. There is no analogous "protectview" like the "protectvob" command. However, those can be overridden after creation by placing a line such as "-vmode 0777" (use the chmod numbering, not the umask convention) in the .view file in the view-storage area. If the .view file is modified, you need to shutdown and restart the view's view_server process. To avoid error messages, make sure nobody is using the view at the time of shutdown. Unfortunately, there is no direct way of asking whether any users are currently set to that view.
  # ct endview -server view-tag
New in CC 4.0, a dynamic view can be set to be read-only. The default is read-write. That is, even if the permissions on the view storage area are wide open, the view can be configured such that not even the view's owner can write to it. This property can be set at time of creation (mkview) or after the fact (chview) using the following options.
  # ct chview { -reado.nly | -readw.rite } view-tag
NOTE: The "chview -readonly" command DOES NOT prevent changes to the view's config_spec. To do that as well, you must change the permissions on the actual "config_spec" file that lives in the view's storage area.

Table of Contents





Set or list sitewide view properties.
As of CC 4.0, one has the ability to set sitewide (per registry server) defaults for some view properties. These view properties are picked up as defaults when creating new views. If a value has been customized, it will have an asterisk next to it. It will then also show up in the registry area in a file called site_config. That entry and asterisk remain even if the value is returned to the default setting.
To list the current settings:
  # ct lssite { -inquire | setting-name ]
To set a value:
  # ct setsite setting-name=value
The setsite command will prompt for the registry password unless the "-password password" option is given. You can also set a value to null via "setting-name=". As of CC 4.0, the values that can be altered are:
view_cache_size In bytes. Ex: 512000, 2m.
view_shareable_dos Are derived objects shareable? TRUE or FALSE.
view_interop_text_mode TRUE = -tmode msdos, FALSE = -tmode unix

Table of Contents





Determine the currently set view.
If one needs to answer the question, "What view am I set to?", then pwv is the answer. Except for the -root option, pwv is relevant only to dynamic views.
In UNIX xclearcase, View -> Describe.
In Windows Explorer, the view tag name is either the directory name directly under the MVFS drive (most often M:) or is the drive name itself if root mapped to a drive letter.
From the CLI:
  # ct pwv
Options:
-s.hort Limit the display to the set view name.
-wdv.iew Limit the display to the working directory view. (see UNIX note below)
-set.view Limit the display to the set view. (see UNIX note below)
-root Display the absolute path portion that precedes the vob-tag for a snapshot element. (CC 4.x)
In UNIX, once "set" to a view, you are in a subshell that you carry around with you no matter where you go on the system, even outside a VOB context. If you execute a pwv outside a VOB it will list the working directory as NONE and show the currently Set view. If you execute pwv inside a VOB is will tell you which view's config_spec is governing the version selection as well as the currently Set view. These are often the same view, but don't need to be.
When you install CC on UNIX, it automatically creates a directory called /view. Any views on the system that are started (not necessarily set by anyone), the view-tag will show up in that directory. If one changes directory in the following manner
  # cd /view/view-tag/vob-tag
you will be using the config_spec of view-tag, independent of the view you have set. In this scenario, if one was to then execute pwv, the working view would reflect the view-tag and the Set view the view you are set to. While in the VOB after cd'ing via the above mechanism, anything you do is subject to that view-tag. For instance, if you execute edcs, you will be editing the view-tag's config_spec, not your set view's. This construct is useful for using the rules of a particular view without setting to it. Remember, when you set to a view, it places you in a subshell in which previously set variables and such are lost. Using the /view directory is handy inside shell scripts where you don't want to lose variable definitions.

WARNING!   Because the /view directory lists view tags that in turn give you access to the system's root directory (VOB tags), be careful with recursive commands. For instance, a find command on the system's root directory will hit infinite recursion when traversing the /view directory. For that reason, one would NEVER execute "rm -rf" in /view as root to clean out that directory. Also, ensure that /view is not in your backup plan.

On Windows, to get functionality similar to the UNIX /view directory, use the net access
  # cd \\view\view-tag\vob-tag
Table of Contents



Determine view and VOB server processes.
On both Unix and Windows, one can gather information about currently running view and VOB server processes. This is an undocumented command that lives in <ccase-home>/etc/utils on both Unix and Windows.
  # albd_list [ hostname ]
The above command will give you a complete listing of all view and VOB related processes running on the local or specified remote host. To get information on a specific VOB or view, use the -s option:
  # albd_list -s local-storage-path

ex: albd_list -s C:\ClearCase_Storage\vobs\test.vbs
Table of Contents



Designate view and VOB storage locations.
Updated: 02/10/16
Version: 7.1.2.14

Designating (registering) a location (directory) for view or VOB storage simply gives users the global storage location information they need when creating those objects.

New in CC 4.0, one can use "ct register -viewstorage or -vobstorage" on Windows.

New in CC 4.1 one can designate "named" locations on both Windows or UNIX using the mkstgloc command. Not available in xclearcase yet. If pathname doesn't exist, mkstgloc will create it for you. On Windows, one can also run ccase-home\etc\SvrStor.exe, which runs automatically after the reboot of a server install or upgrade.
  # ct mkstgloc { -view | -vob } storare-area-name global-pathname

Ex: ct mkstgloc -vob vobstorage /net/cx849509-e/vobstorage
NOTE: Unfortunately, it doesn't do a validity check of the storage area you are registering. Nor does it require something like the registry password. Anyone can register a totally bogus area :-(.

NOTE: If you get the error "cleartool: Error: Must be run on server storage location's host", it can mean a couple of things. 1) If the storage area (-gpath) is on a NAS, the -host must be a server that is running CC and not the NAS server. That is, the view_server and vob_server process are run on -host. 2) The specified -host may not be reachable. Try "cleartool hostinfo -l " to see if you can reach that host from your current location and that the host is running CC.

Table of Contents





List registered view and VOB storage locations.
New in CC 4.1. The lsstgloc command lists registry information about server storage locations for views and/or VOBs.
  # ct lsstgloc
Options:
-vie.w   |   -vob List only view or VOB locations. Default lists both.
-s.hort   |   -l.ong List the location names only or an expanded information listing.
-hos.t   hostname Only list locations on the specified host.
-reg.ion   region Specify a region other than the current one.
`pattern`   |   -sto.rage   pathname Filter the listing using a pattern or by designating the location by pathname.

Table of Contents





Remove registered view and VOB storage locations.
New in CC 4.1. Removes registry entries for server storage locations. It DOES NOT remove the actual directory. The specified location cannot contain any currently registered views or VOBs.
  # ct rmstgloc { name | -sto.rage pathname }
Options:
-all Unregister ALL storage locations.
-reg.ion   region Specify a region other than the current one.

Table of Contents





Add an existing view or VOB to a new region.
Creates a view-tag or public/private VOB tag in a specified region. For a given registry server, views and VOBs only need to be registered once: usually happens when they are first created. If not already registered, use the register command. However, a view or VOB must tagged once in every region in which you would like it to appear. The public and private nature of a VOB is a function of its tag. VOBs can be public in one region and private in another.
  # ct mktag { -vie.w | -vob } -tag tagname storage-area

ex: ct mktag -vob -tag /vobs/myvob /vobstorage/myvob.vbs
    ct mktag -view -tag myview -region nt_reg \\machine\share\myview.vws
Options:
-tco.mment   "comment" Apply a comment to the tag.
-rep.lace Replace the definition of an existing tag.
-reg.ion   region Work with a region other than the current one.
-hos.t   hostname   -hpa.th   hostpath   -gpa.th   globalpath Override how the path is registered. All three are a set.
-ngp.ath New in CC 4.1. Specify that there is no global-path in the region: -host & -hpath are then optional without -gpath.
-pub.lic   [ -pas.sword   password ] VOB only. Create a public tag. Will prompt for the registry password unless specified on the CLI.
-opt.ions   mount-options VOB only. See the mount man page.

Table of Contents





Dynamic view .specdev file.
The .specdev file is a character special device file. It is for all client communication, like cleartool, clearmake, clearaudit, etc. If this file is not present, errors such as the following may arise: "cleartool: error: Unable to create directory <viewtag>: not a clearcase object". To recreate a missing .specdev file, cd to the /view directory as root and issue the following commands as root:
  # mknod c 0 0x000000 .specdev
  # chmod 444 .specdev
  # chown root:root .specdev
More information on special devices can be found by running "man IOCTL". For information on the Windows .specdev file, contact Rational Software Technical Support.

Table of Contents





Determine the location of snapshot view loaded files
Updated: 04/23/14
Version: 7.1.2.10

Full client snapshot views
Once files in a snapshot view are "loaded" to a desired location, the properties of the view do not indicate that location. So, in time the files can become misplaced.
On Windows, there are a couple ways to determine where the loaded files were put.
1) Information is stored in the registry. The output is placed in a designated output.txt file.
  # regedit /E output.txt HKEY_CURRENT_USER\Software\Atria\ClearCase\CurrentVersion\Workspaces
2) In the CC Explorer, simply move your mouse pointer over the name of the snapshot in the center pane, an information box will automatically pop up with that information.
On UNIX, look in the file called ~/.ccase_svreg. Or, you can always run a "find" on the system and look for a file called view.dat.

CCRC snapshot views
When a view is created in CCRC the view storage area is automatically placed on the server. The loaded files are placed in a local location of your choosing. On Windows 7+ that location is written to "C:\users\username\.ccase_wvreg".

Table of Contents





Automatically have views restart after reboot.

In order for view to be restarted automatically after reboot, the view must either be mapped to its own drive letter in the Windows Explorer or have view shortcut in the ClearCase Explorer. In the Windows Explorer, after reboot, Windows will automatically remap the view to the previous drive letter and start the view for you. In ClearCase Explorer, if there's view shortcut for the view, the view will start automatically if you click on it.
For Windows Explorer, that drive mapping is stored in: HKEY_CURRENT_USER\Network\drive-letter. Windows also keeps a list of previously mapped drive information in HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\Map Network Drive MRU.
For ClearCase Explorer, the shortcut is stored in HKEY_CURRENT_USER\Software\Atria\ClearCase\CurrentVersion\ClearCase Explorer\ViewsPage either under General or the name of a UCM project. CC keeps a list of previously started views in HKEY_CURRENT_USER\Software\Atria\ClearCase\CurrentVersion\RecentlyUsedViews.

Table of Contents





Determine when a view was last accessed.
Updated: 11/18/15
Version: 7.1.2

Starting with CC 5.0/2002, a view's "Last accessed" date/time is recorded as part of its properties.
In Windows, in the CC Administration Console, surf to the host that houses the view storage (perhaps My Host or under ClearCase Network) and expand the Views folder. Right-click on a view to bring up its Properties and go to the Access tab.

From the CLI:
  # ct lsview -age viewtag
--or--
  # ct lsview -properties -full viewtag
The "Last accessed" time is updated every 60 seconds.
It appears that the last access date/time is the same as that of the ".access_info" file in the view's storage area, which means even if the above CLI commands fail for some reason, but you can get to the storage area, you can still determine the last access date.
In PERL you can get the .access_info date/time using:
	use File::stat;
	use Time::localtime;
	$view_access_date = ctime(stat("$view_storage\\.access_info")->mtime);
Starting in CC 2003.06.00 there is a report built into the Reporting Wizard called "Views by Last Access Time".

Table of Contents





Set what shell is used when setting into a view. (Unix only)
Bourne shell is the default (/bin/sh). If you want a definite shell, one of the following can be done:
1) Set the shell in the /etc/passwd file.
2) Set the "SHELL" environment variable.
3) Place the following at the end of your .cshrc:
if ($?CLEARCASE_ROOT) then
	exec /usr/bin/bash
endif
Table of Contents



Load snapshot view files to multiple locations.
This is an unsupported solution. Normally when you create a snapshot view you download the files to a single specified location. However, it's possible to have those files download to other locations as well so that they can be seen and accessed from multiple locations.
First, create the snapshot view in the normal way and download the files to one of the desired locations. In the top level directory of that location you'll see a file called "view.dat" on Windows and ".view.dat" on Unix. That file tells CC that that directory is associated with a particular view -- the view's UUID is inside that file.
Copy the view.dat file to some other directory, or system. Change directory that new directory, where you just placed the view.dat file and run "cleartool update". It will load the files there based on that view's config_spec as if normal.
You can checkout, edit, and checkin files from both locations :-). In the Version Tree Browser, the file will appear to be checkedout Reserved under the original name of the view regardless of which location the file was actually checkedout. The contents of an edited file won't be visible in the opposite location until you run and Update on the opposite location. Read the following NOTE.

NOTE: When an element is checkedout, edited, and checked back in at one location, it will now appear to CC as a hijacked file in the other location. This is because CC knows that you have the LATEST version loaded at the other location, but the actual contents of the file do not match the contents of the LATEST version in the VOB. Therefore, even though you didn't actually hijack it at the other location, CC assumes that the file was hijacked and marks it as such. When you Update the view at the other location, it will flag elements changed at the opposite location as hijacked. To resolve them, let the update complete and then "Undo Hijacked File" on all the hijacked files. This will tell CC to load the LATEST version from the VOB. The one that was there will be set aside with a .keep extension.

Table of Contents





Access elements from non-CC hosts.
If you need to access files stored in a VOB from a host that doesn't have CC installed, there are a couple of choices.
First choice, you can create a snapshot view whose loaded files are placed on the non-CC host instead of where the view's storage directory lives. The snapshot view's storage directory (.view.stg or .vws directory) must still live on a machine that has CC installed. But the loaded files can be dumped on a non-CC host via native network connections. Once loaded, the files can be edited and accessed in the normal way. However, there is no way to perform a CC checkout on the remote, non-CC host. You must deal with them as hijacked files.
Second (Unix only) choice is to export the dynamic view and VOB with the -ncaexported option during mkview or mktag. A dynamic view to be used for NFS export must be marked in the registry as an export view. Each export view is assigned an export ID, which ensures that NFS-exported view/VOB combinations have stable NFS file handles across server reboots or shutdown and restart of CC. If the dynamic view is registered in multiple regions, the export marking must be on the view-tag in the server host's default region. See the export_mvfs (which the counterpart of the Unix exportfs and share commands) and exports_ccase man pages. Once the view and VOB are CC marked for export, you still need to actually share an NFS export of the /view directory.

Table of Contents





Remove a snapshot view whose view root is missing.
To properly remove a view, simply do a "cleartool rmview" on the view's view root directory (where the view's loaded files are). However, that isn't possible if the view root was previously removed.
To remove a view under these circumstances, you must trick CC into thinking the view root is still there. To do so, you must regenerate the critical missing piece, namely the view root's view.dat file. The following steps will remove a view whose view root was deleted. The viewtag listed here is the tag of the view to be removed. The perl script lives in cc-home/etc/utils on both Unix and Windows.

  # mkdir   viewtag
  # cd   viewtag
  # perl   regen_view_dot_dat.pl   -tag viewtag   .
  # cd   ..
  # ct   rmview   viewtag

Table of Contents



Add/remove a view shortcut or page to/from the ClearCase Explorer.
Version: 7.1.2
Updated: 12/12/12
To add a view shortcut, right-click in the grey area of the Views tab and select Add View Shortcut. Follow the prompts.
To add a shortcut programmatically, add the following code to your script. Note that the parameters in the registry entry need to be tailored to your environment.
	$view    = "My_View";
	$project = "Our_UCM_PRoject";

	$temp_regfile = "C:\\temp\\view_shorcut.reg";
	if ( ! open(REGFILE,"> $temp_regfile") ) {
		print STDERR "Unable to open \"$temp_regfile\" for write.\n";
		exit 1;
	}

	print REGFILE "Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\\Software\\Atria\\ClearCase\\CurrentVersion\\ClearCase Explorer\\ViewsPage\\$project\\$view]
\"Tooltip\"=\"$view\"
\"AccessString\"=\"\"
\"IconKey\"=dword:00000020
\"Default\"=dword:00000000
\"Visible\"=dword:00000001
\"Redefined\"=dword:00000000
\"Dependency\"=\"\"
\"Version\"=dword:00000001
\"Removed\"=dword:00000000
\"Type\"=\"view\"
\"SnapshotView\"=dword:00000000
\"IntegrationView\"=dword:00000000
\"UcmView\"=dword:00000001
\"ProjectName\"=\"$project\"
\"LastFolder\"=\"\"
\"UsesDriveMapping\"=dword:00000000
";

	close(REGFILE);

	$return = `regedit /s \"$temp_regfile\" 2>&1`;
	if ( "$return" ne "" ) {
		print STDERR "Unable to update the registry.\n";
		exit 1;
	}

	unlink("$temp_regfile");
To remove a view shortcut, simply right-click on it and select "Remove View Shortcut". DO NOT choose "Remove View", as that will actually, permanently remove the entire view. If that is the last shortcut in that views page, the page will go away automatically.
If the view shortcut is to a view whose view-storage is no longer available, the view shortcut must be removed manually from the Windows registry. Close any open CC Explorers and open regedt32: HKEY_CURRENT_USER\Software\Atria\ClearCase\CurrentVersion\ClearCase Explorer\ViewsPage. In that key you will find the CC Explorer views pages. Enter the desired page and left-click on the offending view shortcut, then select the menu option Edit->Delete. If that is the last shortcut in that views page, remove that page from the registry as well.

Table of Contents





Determine if a view is dynamic or snapshot.
Updated: 03/27/06
A view's tag alone does not tell you what view type it is.
If the view has a shortcut in the Windows CC Explorer, right-click on the view and select View Properties.
In the CLI, run the following command:
  # ct   lsview   -properties -full viewtag
Table of Contents



Add/remove a view shortcut page from the CC Explorer
Windows only. When you create view shortcut in the CC Explorer, it will either be found under the page called General, or one that corresponds to a UCM project, or a user-defined one.
The page called General cannot be removed or renamed. To remove one of the UCM-specific pages, you need to remove all the view shortcuts first. When there are no more view shortcuts under that page, the page will disappear on its own.
To create a another page, right-click in the grey area of an existing page and select Add Page. When a user joins a UCM project, it will automatically prompt them to create a page named for the UCM project he/she just joined.
If a page other than General is empty, but still exists, if you want to get rid of it, add a view (any view) to that tab and then remove the view shortcut. It will then disappear on its own. Or, if a page is empty, it will simply disappear the next time the CC Explorer is started.

Table of Contents





Delete a view-private file or directory.
Version: 7.0.1.8
Updated: 05/15/12
Deleting a file is as simple as right-clicking on it and selecting Delete.

WARNING: If a file is deleted from within the CC Explorer, a copy is not placed in the Recycle Bin.

Table of Contents





Update a snapshot view.
Version: 7.0.1.8
Updated: 06/28/12
Snapshot views have a set of “load rules” that define what folders and directories are loaded (copied) to the View Root directory. The load rules can be altered at any time. Altering the load rules will start an update of the view.
ClearCase Explore:
1) Open the ClearCase Explorer.
2) Assuming the snapshot view has a shortcut in the Shortcut Pane, right-click on the view and select View Properties.
3) Under the Load Rules tab, click the “Edit load rules…” button.
4) Add and remove folders and files as needed. Click OK.
5) Click OK.
6) Follow the prompts to update the view.

Command Line:
Open a command prompt. Go to Start -> Run and type in “cmd”. Type in the following command with the variable information filled in appropriately and hit enter. Even though the View Root directory might be a destination on a computer that doesn’t have CC installed, this command must be run from a computer that does. Unfortunately, there isn’t a way to remove load rules using the CLI. You can only add load rules. This command works for CCRC web snapshot views too.
	cleartool update –add “load rule”

	# If needed, see the man page.
	cleartool man update
The load rule parameter is an absolute path through the View Root to the element(s) to be loaded. For example: “C:\ClearCase\E559055_C919_FC_Phx_snapshot\Hardware\Deliverables”. If more than one rule is added, separate them with a space. The double quotes around new rules only need to be there if there are spaces in the path.

Table of Contents





Access a dynamic view without a drive letter.
Version: 7.1.2
Updated: 03/12/13
Views can be accessed through the Windows drive letter assigned to the MVFS subsystem. Dynamic views can also be accessed on the local computer in a generic, driveless way: \\view\viewtag. The view needs to be started on the local computer first.

Table of Contents





Programmatically map a dynamic view to its own drive letter.
Version: 7.1.2
Updated: 03/12/13
Dynamic views that are started on a local computer, will always show up under the Windows drive letter associated with the MVFS subsystem. A dynamic view can also be mapped to its own drive letter. That step is usually done to shorten the absolute path to elements. A drive letter can be assigned programmatically. The path looks like generic UNC path, but can only be accessed in that manner from the local computer.
	ct startview viewtag
	net use Z: \\view\viewtag
  
Table of Contents



Find all the hijacked files in a snapshot view.
Version: 7.1.2
Updated: 04/04/16
	# Unix
	ct ls -recurse | grep "hijacked"

	# Windows
	ct ls -recurse | findstr "hijacked" 
  
Table of Contents



Create a VOB.
See the CC Reference Manual under "VOB" for a general discussion on VOBs.

WARNING!   VOBs must be created while sitting in front of the machine where the vob-storage-area is to be located. Attempting to create the VOB via an rlogin or across an NFS mount may cause an erroneous path to be assigned to the vob-storage-area that is inappropriate when seen from other machines or even from the local machine.

Criteria for determining a suitable VOB-host.
The minimum recommended RAM for a VOB-host is 128MB.

  # grep mem /var/adm/messages* | grep K | head -1
There must be enough disk-space to handle all the documents for a project. The minimum recommended is 2GB.
  # df -k vob-storage-disk
Finally, the VOB must be on a disk that is exported to the client machines, if any. See "Access denied error" in the "ClearCase How to ...". For further reading, see "Improving VOB Host Performance" (Ch. 21) and "Maximize Disk Performance" (page 232) in the CC Admin Manual. Even though you can change permissions/ownership on the VOB later on, it is easiest to ensure you are the owner and group that you want the VOB to inherit. The vob-tag-area needs to have at least 755 permission to work at all.
NOTE: On UNIX, when you create a new VOB, every group to which you belong will be added to the VOB's group list. It is up to you to pare that list as desired. On Windows, only your CLEARCASE_PRIMARY_GROUP gets added as the VOB's primary group.

Choose the vob-storage area:

  # mkdir vob-storage-area       (as root, if necessary)
  # chmod 775 vob-storage-area
  # chown vobadm:project-group-name vob-storage-area
NOTE: The final .vbs directory will be created 755 independent of the creator's umask, as the vob_server writes to the VOB storage suid to owner.
Give the new VOB a unique vob-tag name. On UNIX, a vob-tag is the full path to the VOB mount point, ex: /vobs/myvob. On Windows, a leading backslash is required, but it does not denote a mount point. On Windows, VOBs are mounted under a view, which is generally assigned its own drive letter. The mkvob command is going to prompt for a password for public VOBs. If you've forgotten the password, see the CC administrator. It can also be reset as root (or vobadm if configured) running the /usr/atria/etc/rgy_passwd command. The password is stored in the file /var/adm/atria/rgy/vob_tag.sec.

On Windows, after CC 2002/5.0, in the ClearCase Administration Console go to "My Host", right-click on VOBs and select New->VOB. Pre CC 5.0, ClearCase Home Base -> VOBs -> Create VOB.
In Unix/Windows clearvobadmin, VOB -> Create...
In Unix xclearcase, Admin -> VOB... -> VOB -> Create...
The GUI VOB Creation Wizard can be invoked with the stand-alone command clearvobtool.
From the CLI, you can either change directory to the storage location and let CC generate the global path, or you can specify the global storage path manually.
  # cd vob-storage-area
  # ct mkvob {-public} -tag vob-tag vob-storage-name.vbs

Windows:
  # ct mkvob -tag vob-tag \\machine\share\directory\vob-storage-name.vbs
Unix:
  # ct mkvob -tag vob-tag /net/machine/export/directory/vob-storage-name.vbs
NOTE: Ending a VOB storage name in .vbs is merely convention. There is no mandate that it has to have any extension at all.
Some useful options:
-nca.exported Assign an export-ID to the new VOB to ensure no "stale NFS handle" on the client side across server reboots.
-reg.ion   region Create this VOB in a region other than the current one.
-opt.ions   mount-options See the CC Reference Manual for special mount options.
-pas.sword   public-password Give the public registry password on the CLI.
-ucmproject New in CC 4.0. Make this a UCM PVOB.
-stg.loc   {   storage-name   |   -aut.o   } New in CC 4.1. Place the vws directory in the storage-name location or take a default location. See below for -auto algorithm.
-flevel   feature-level New in CC 2002/5.0, patch 3. Create a VOB at the specified feature level instead of the default. This is useful for replicating VOBs to machines running older versions of CC. This option is currently undocumented and unsupported. Do not use it in a production env.

NOTE: A VOB can be created to hold a UCM project component so that there is no need to run mkcomp. However, that option is only available in a Windows GUI.

NOTE: When allowing "-stgloc -auto" to pick a storage location for you, keep these points in mind:
1) Server storage locations that have no global path ( mkstgloc -ngpath) and that reside on remote hosts are disqualified.
2) Server storage locations on heterogenous hosts are disqualified.
3) Local server storage locations are preferred over remote ones.
4) Globally accessible server storage locations ( mkstgloc -gpath) are preferred over those that are not (mkstgloc -ngpath).
5) The server storage location with the most free space is selected.

On Windows, the VOB must be created in a shared directory. On Unix, CC sets a default global path with /net/hostname prepended to the string. In the case where this is inappropriate, use the "-host   -hpath   -gpath" option set. On another machine the command might appear as follows. This example assumes the LAN is set up so the local-host-path appears the same as the global-path. This example also assumes that you are not sitting in the vob-storage-area, which isn't mandatory as long as you give the full path to it.
  # ct mkvob -public -tag vob-tag -host hostname -hpath local-host-path \
  -gpath global-path vob-storage-area/vob-name.vbs

ex: ct mkvob -public -tag /projects/emss/software/admin -host topdog \
  -hpath /projects/emss/software/vobsstore/admin.vbs \
  -gpath /projects/emss/software/vobsstore/admin.vbs \
  /projects/emss/software/vobsstore/admin.vbs
If the local-host-path and global-path are the same, CC will print a warning message. You can ignore it if this is ok for your LAN configuration. Chapter 6 in the CC Admin Manual also goes into resetting the vob-storage-area path, setuid/setgid, permissions & groups and other related issues.
Finally, mount the vob as a test:
  # ct mount vob-tag
NOTE: To create remote storage pools after the VOB has been created, see the mkpool command. Because Windows can't follow Unix links, you can only use remote pools in interop if the pools are specified as remote during the region synchronization. On Windows, prior to CC 2002/5.0, in ClearCase Home Base -> Administration -> Region Synchronizer. On Windows, from CC 2002/5.0 on, the Region Synchronizer is started from the Start menu. Once there, select VOB -> Import... -> Show Mount Options >> -> Windows-Only Options specify all remote pools on one line similar to the following:
s\sdft\=\\hostname\path\s_poolname\|c\cdft\=\\hostname\path\c_poolname\

WARNING!   In Windows, do not place VOBs on partitions that use NTFS compression, as corruption may occur. However, NTFS is preferred over FAT, as FAT is not protected by Security Descriptors.

On Unix, VOB information is logged in /var/adm/atria/log/vob_log and on Windows in Start -> Programs -> Administrative Tools (Common) -> Event Viewer -> Log -> Application which can be accessed pre CC 2002/5.0 via the ClearCase Home Base -> Administration -> Log Browser -> vob. From CC 2002/5.0 on, ClearCase Administration Console. See cleargetlog on either platform.

Table of Contents





Remove a VOB.
This procedure is described in the CC Admin Manual (page 161). You cannot be inside the VOB storage area. You must own the VOB or have administrative privileges. NEVER use a command like Unix "rm -r" to remove the vob-storage area. Take note of the "Global path" (vob-storage_path-name). The term vob_tag implies the fully qualified path to the VOB (left side of lsvob).
  # ct lsvob
  # ct lsvob -long vob_tag
Ensure this VOB is not an administrative VOB for another. If it is, the following command will produce a line stating "AdminVOB <- vob:other-vob-tag" under the heading "Hyperlinks". If it turns out that this is indeed an adminstrative VOB for another, all the "types" that are global in the AdminVOB will have to be reproduced in another admin VOB or recreated locally in the client VOB.

WARNING! Even though the rmvob command will allow you to remove a UCM component VOB, DO NOT do it unless all UCM objects have been removed from the component VOB first. It MUST be an unused, empty VOB or you will have problems if that component was part of a project that will continue to exist with other components. If a component's VOB has been removed incorrectly, see Remove a component.

Always unmount the VOB from all hosts before removing it. If you don't, the user will have a hung mount point. On Unix, you may have to use the Unix "umount" command after the VOB has been removed to get rid of the mount point if it was still mounted when the VOB was removed.
In Unix xclearcase, Admin -> VOB... -> VOB -> Destroy
In Unix/Windows clearvobadmin, VVOB -> Remove...
From the CLI:
  # ct rmvob vob-storage_path-name
If a vob-storage_path-name has been deleted inadvertently using a non-CC command, the following need to be done to clean up the mess: unmount using the standard UNIX command, unregister the vob storage area from the registry, remove the vob-tag and kill the vob_server process.
  # ct lsvob -long vob-tag  (note the "Vob replica uuid")
  # ct unregister -vob -uuid replica-uuid
  # ct rmtag -vob vob-tag
On UNIX:
  # ps -efl | grep vob_server   (determine PID)
  # kill -9 PID
On Windows:
ClearCase Home Base -> Administration -> Log Browser -> vob -> note PID,
Task Manager -> Processes -> select PID -> End Process
Table of Contents



Rename a VOB.
A VOB can have more than one tag pointing to it as long as the tags are in different CC regions. To rename a tag in the same region, simply replace the old tag with a new one. The old tag cannot be in use by anyone.
In UNIX/NT clearvobadmin, not possible.
From the CLI:
  # ct rmtag -vob old-vob-tag
  # ct mktag -vob -tag new_vob-tag old_vob-storage
Unfortunately, "mktag -replace" will not work in this situation.
In UNIX xclearcase, Admin -> VOB... -> select a VOB -> Admin -> Registry -> Remove tag   and then   Create tag...
If you want to rename the vob-storage area itself, it will have to be completely shut down and reregistered under the new name. Any tags pointing to it will have to be redone as well.
  # cd vobstore
  # ct umount vob-tag
  # ct lsvob -long vob-tag  (note the "Vob replica uuid")
  # ct unregister -vob -uuid replica-uuid
  # ct rmtag -vob vob-tag
  # more vob-storage-path/.pid  (note vob_server PID)
  # kill PID
  # mv old-vob.vbs new-vob.vbs
  # ct mktag -vob -tag vob-tag -public new-vob-storage-path
  # ct register -vob new-vob-storage-path
  # ct mount vob-tag
NOTES: The vob-tag will have to be removed and remade to point to the new name of the VOB for other regions as well. In the above example, "register -replace" can be used in place of register & unregister if in the "register -replace" you use the -host -gpath -hpath triplet of options.

Table of Contents





List VOB history.
In UNIX xclearcase, Report -> List history.
In UNIX/NT clearvobadmin, not possible.
In Windows, ClearCase Home Base -> Elements and Versions -> History Browser -> VOB.
From the CLI:
Print the history of activity in the current VOB (must be sitting inside VOB).
  # ct lshistory
Print the history of the current VOB itself.
  # ct lshistory vob:.
Print the history of a VOB elsewhere (mounted or not) excluding checkout events.
  # ct lshistory -nco vob:vob-tag
Alternatively, you can print the version tree.
  # ct lsvtree vob-tag
Table of Contents



Mount or unmount a VOB.
In UNIX xclearcase, Admin -> VOB... -> Admin -> Mount, Mount All or Unmount
In UNIX/Windows clearvobadmin, VOB -> Mount... or Unmount
In Windows, right-click on started view -> ClearCase -> Mount/Unmount VOB...
From the CLI:
  # ct mount vob-tag
  # ct umount vob-tag
If needed, UNIX mount and umount can be used to mount VOBs. All public VOBs can be un/mounted with one command using the -all option. Private VOBs can only be mounted one at a time even by the owner. The -persistent option can also be used to ensure VOBs are automatically remounted after a system restart (not applicable to private VOBs).
There are many mount options available to the mounting of VOBs that are standards when mounting any file system. Note that the read-only (ro) option has no affect on Windows.
On UNIX: Private VOBs cannot be mounted by anyone else other than the owner. The private VOB mount-point must exist prior to mounting. Public VOBs will create their own mount-point with the name of the vob-tag. The VOB mount-points will be owned by root. This is normal, as it is the VOB's owner that matters. Only the root user can use the   -options   option.

See also cleardlg on Windows.

NOTE: Mounting a VOB on a given remote box doesn't imply that the VOB is available. You won't get an error message about the VOB being unavailable until you actually try to access it.

Table of Contents





Move a VOB.
This procedure describes moving a VOB to a machine of similar architecture. This proecure can be done as the VOB administrator unless moving to a different architecture. That is, if performing a dump and load of the VOB database, one needs to be root (or be in the clearcase group on Windows). When moving VOBs around, it isn't necessary to shutdown CC on UNIX.
If moving a VOB between domains or from UNIX to Windows, see the note below.

Things to consider before moving the vob:
- Ensure the original is backed up prior to the move.
- The user and group names need to be the same on the new server. This includes the actual user and group ID numbers. - Unmount the VOB from all hosts.
- If the VOB is replicated via CCMS, the procedure is much easier if the local replica is self-mastering. If not self-mastered (see the describe command), have the mastering site run the chmaster command. The site that does the chmaster must be the one to sync with the other replicas:

  # ct describe replica:replica-name@vob-tag
  # mt chmaster replica:replica-name@vob-tag replica:replica-name@vob-tag
(for each remote replica)
  # mt syncreplica -export -fship remote-replica-name@local-vob-tag

Moving a VOB to a new host:

1) Determine whether the VOB has any non-local storage pools. Remote storage pools do not get transferred.
  # ct lspool -long -invob vob-tag
If any remote pools are found, the path to it will have to be valid on the new host and all its clients, or will have to be moved.
2) Determine if this VOB is snapshot'ed. Disable snapshots on this VOB (not to be confused with snapshot views).
  # vob_snapshot_setup lsvob vob-tag
  # vob_snapshot_setup rmparam vob-tag   (if necessary)
3) If VOB is a CCMS replica, change the hostname.
  # mt chreplica -host new-hostname replica:replica-name@vob-tag
(for each remote replica)
  # mt syncreplica -export -fship remote-replica-name@local-vob-tag
4) If moving between architectures that are not exactly the same, dump the database to ASCII dump files. This step is necessary if moving between, say, Solaris and HP-UX, or between Solaris 2.6 32-bit and Solaris 2.7 64-bit. The refomatvob -dump will lock the the VOB for you.
  # ct reformatvob -dump vob-storage-area
If moving to the same architecture, lock the VOB yourself.
  # ct lock vob:vob-tag
5) Deactivate the old VOB.
  # ct rmtag -vob -all vob-tag
  # ct unregister -vob vob.vbs
  # more vob.vbs/.pid
  # kill -9 vob-pid   (if necessary)
If just moving to another drive on Windows, it is only necessary to unregister and then register the VOB, as the tags usually point to a UNC path that is independent of a drive letter. That is, no rmtag/mktag necessary.
6) Copy the VOB storage directory. If on Windows, shutdown CC.
  # cd vobstore
Same host, same partition:
  # mv old-vob.vbs new-vob.vbs  
Same host, different partition:
  # tar -cf - vob.vbs | (cd new-locn; tar -xBpf -)
Different host:
  # tar -cf - vob.vbs | rsh hostname 'cd new-locn; tar -xBpf -'
NOTE: For Windows, the copy of a VOB to a new partition may not (does not) preserve ownership. To preserve permissions, on Windows, use scopy that comes in the Windows Resource Kit. On Win2k, use xcopy that has scopy built in. Do not use xcopy on NT 4. See the section below if moving VOBs across untrusted Windows domains or to Active Directory. It may be necessary to run:
  # ct protectvob -chown owner VOB-storage-area
It may also necessary to log in as clearcase_albd to unlock the VOB prior to running the protectvob, as the owner won't be recognized by the system anymore.
7) If a reformatvob was done, load the database in its new location. If on Windows, restart CC.
  # ct reformatvob -load vob-storage-area
8) Activate the VOB at its new location.
  # ct register -vob /full-path/vob.vbs
  # ct mktag -vob -public -tag vob-tag /full-path/vob.vbs
  # ct mount vob-tag
  # ct unlock vob:vob-tag    (if a dump & load wasn't done)
9) Once the VOB has been tested/verified at its new location, simply delete the old VOB storage area.
10) If the VOB was snapshot'ed, need to run "vob_snapshot_setup modparam" on it.
11) If VOB is a CCMS replica, import any packets rcvd while the VOB was in transit. If /var/adm/atria/config/shipping.conf on the original host was customized, remember to transfer over that file.
  # mt syncreplica -import -recieve

NOTE: If moving a VOB on UNIX because of simple disk space issues, one can simply move the vob-storage-area to a new location and create a softlink from the old to the new. However, this doesn't work if in an interop environment. That is because a Windows box accessing a UNIX vob-storage-area CANNOT follow UNIX softlinks. You can, of course, simply reregister those VOBs in the Windows region to point to the new location, which hopefully is exported in the same manner as the old location.
NOTE: Even if moving between machines of like architecture, as in Solaris 2.6 to Solaris 2.7, one needs to do the dump and load steps if switching between a 32-bit architecture and 64-bit.

Move a VOB between Windows & UNIX or between Windows domains.
The above procedure still implies that the architectures are the same. If you need to move a VOB between a Windows and UNIX box, simply replicate it using CCMS, move mastership of everything to the new VOB, and delete the old one (after sufficient testing). If you don't have MultiSite licenses, Rational can set up very temporary licenses just long enough to get the job done.
However, as of CC 5.0/2002, vob_siddump and vob_sidwalk commands exist to facilitate that sort of migration without CCMS (schema 54 VOBs only).
Moving a VOB between environments that do not share a common security model will corrupt the permissions in the storage area. The following scenarios fall into this category:
-- Moving a VOB between untrusted Windows domains
-- Migrating a Windows domain to Active Directory
-- Moving a VOB from Windows to UNIX or vice versa
Must be VOB owner or privileged user to execute the following. These commands live in cc-home\etc\utils on Windows and /usr/atria/etc on UNIX.
  # vob_sidwalk vobtag output-file
The command will send object information to the screen but will place the SID info in an output-file that cannot already exist. See the CC Admin Manual before actually using this command for a VOB move.

Table of Contents





Modify a VOB's properties.

Change protections:
In Unix xclearcase, not possible.
In Unix/Windows clearvobadmin, select a VOB -> Edit -> VOB Properties... -> Permissions
From the CLI:
  # ct protectvob -chown        username vob-storage-path
  # ct protectvob -chgrp        group    vob-storage-path
  # ct protectvob -delete_group group    vob-storage-path
  # ct protectvob -add_group    group    vob-storage-path
Use the -force option to suppress the confirmation step. As of CC 2003.06.00 you can use a vobtag to designate a given VOB as an alternate to vob-storage-path.

Change protections on ALL objects in a VOB.
A tool called vob_sidwalk (new in CC 5.0) gives the ability to change permissions across the board, even if the original UID/GID is unknown. However, even though you may have CC 5.0+, the VOB must be at schema 54+. See the vob_sidwalk or vob_siddump man page.

Change tag properties:
In UNIX xclearcase, not possible.
In Windows, Start -> Programs -> ClearCase Administration -> VOB Administration Browser -> select a VOB -> Edit -> VOB Registry Entry... -> VOB Tags for Object -> Modify
From the command-line, modify a VOB's properties with mktag -replace. The following example changes a VOB from private to public.
  # ct mktag -vob -tag vob-tag -replace -public vob-storage_path-name
Table of Contents



Register a VOB in a new region.
For all interfaces, there is no need to register the VOB again unless this is a registry server different from the one on which it was originally registered. That is, if simply making the VOB available in another region on the same registry server, the register step is not necessary.
In UNIX xlcearcase, Admin -> VOB... -> Admin -> Registry -> Register... & Create tag...
In UNIX/NT clearvobadmin, not possible.
From the CLI:
  # ct register -vob vob-storage-path
  # ct mktag -vob -tag vob-tag -public -region region-name vob-storage-path
Table of Contents



Check a VOB's consistency.
For various reasons a VOB can have problems with versions in the database: missing, unreferenced, etc ... To check the VOB for consistency, run one of the following commands. These commands can be cpu intensive and take a long time.

checkvob
The command can be run from anywhere and will create a log subdirectory called "checkvob.date.time" in the current directory. When the check is done, look in: checkvob.date.time/poolkind_source/transcript. Must set a view before running checkvob.
Run a simple check on a VOB:
  # ct checkvob -pool -source vob-storage-path
Run on a single element:
  # ct checkvob element
Options:
-vie.w Specify a view other than setting to one.
-log   logfile Designate a log file other than the default: checkvob.date.time.
-fix Fix VOB problems as they are encountered.
-fix -f.orce Skip the confirmation when fixing things.
-fix -ign.ore Ignore element and pool locks. VOB must be locked to all but current user.
-dat.a Identifies missing data containers. Does not detect data container corruption.
-pro.tections Check data container protections.
-deb.ris Looks for data containers with no db entry. If -fix, places them in lost+found.
-set.up Prepares a newly reformatted VOB for checkvob processing. See the CC Admin manual.
-poo.l [ -sou.rce ][ -der.ived ][ -cle.artext ] vob-storage-path Inspect all pools or designated pools in vob-storage-path.
-loc.k Lock an individual element while running checkvob on it.
filename Run checkvob on a single element. Not compatible with -pool.
-hli.nks Run checkvob in hyperlink mode to cleanup corrupt hyperlinks on the VOB object.
-to | -fro.m Specify one or the other end of the hyperlink to be cleaned.
-hlt.ype   hltype-selector Specify the the hyperlink type to check when using -hlinks.
-pna.me Treats each object selector as a pathname.
object-selector Object to check in hyperlink mode.
-glo.bal Run checkvob in global types mode.
-acq.uire Lists/fixes eclipsing local metadata types.
-pro.tections Lists/fixes mismatched protections between a global metadata type and the local copy.
-loc.k | -unl.ock Lists/fixes mismatched locks between a global metadata type and the local copy.
VOB-selector In globals mode, lists/fixes all global metadata types.
object-selector In globals mode, lists/fixes the designated metadata type.
-ucm New in CC 2003.06.00. Checks PVOB, components, and optional CQ db for UCM consistency.
-com.ponent   component-selectory New in CC 2003.06.00. Restricts -vob_only check to secified component.
-pro.ject   CQ-UCMproject-name New in CC 2003.06.00. Check references to UCM project in CQ.
-act.ivity   CQ-activity-name New in CC 2003.06.00. Check references to UCM activity in CQ.
-verbose New in CC 2003.06.00. Verbose output available in -ucm -component mode only.
-crm_only New in CC 2003.06.00. Only examine between PVOB and CQ db, no components.
-vob._only New in CC 2003.06.00. Only examine between PVOB and components, no CQ db.
-crm_db.name   CQ-user-name New in CC 2003.06.00. Must specify CQ dbname in -project mode.

dbcheck
Where checkvob checks the consistency between a VOB's db and pools, dbcheck will run a deep check of the db itself. Change directory to the VOB's database folder and run the following. The VOB must be locked during the operation. The dbcheck command lives in the CC home directory under etc/utils.
  # ct lock vob:vobtag
  # dbcheck -a -k -p8192 vob_db > c:\temp\dbcheck.txt
The -p8192 option can be left out if there are memory issues.
The dbcheck command has the following options:
usage:   dbcheck [-options] dbname [dbfile(s)]
options: [-s] [-k] [-dk] [-kd] [-a] [-ts] [-r#] [-p#] [-f#] [-t] [-c]

  -s  = Perform complete set consistency check
  -k  = Perform key file structure consistency check
  -dk = Perform key access consistency check from data files
  -kd = Perform key data consisteny check from key files
  -ts = Perform time stamp checks for records and sets
  -a  = Does -s -dk -kd -ts
  -r# = Report every # percent to stderr
  -p# = Number of pages for vista to allocate to its page cache
  -f# = Number of open files vista is allowed to have
  -t  = Print a traceback of the b-tree at the first sign of disorder
  -c  = Print counts of objects scanned in the check
Table of Contents



Copy a VOB.
There is no direct way of duplicating a VOB exactly. There a few ways you can get pseudo copies. You can get pretty close using the relocate subcommand. The downsides are that it won't copy the following: lost+found, private branches, view-private files and elements not selected by the current view. To get around these, use a grep/findstr filter to ignore the lost+found directory, delete any view-private files and set a view that uses the default config_spec. The target VOB must already exist and be mounted.
  # ct relocate -update `ls | grep -v lost+found` /target-vob-tag

WARNING!  
1) In this case, do not use the relocate without the   -update   option or it will move the elements vice making copies. Also, if there were errors during the update, such as encountering a private branch, the relocate will terminate and leave the target VOB in a unusable state. If this happens, it will be necessary to remove the offending object, recreate from scratch the destination VOB and rerun relocate or use else clearexport_ccase as described in (3).
2) If the copy is to be placed in a completely different region, use Move a VOB and just don't deactivate/delete the original.
3) If you want an additional copy in the same region and aren't worried about older versions of the directories, use clearexport_ccase. The downside of using it is that it does not export the entire directory histories. It will only pick up the directory as it exists now in the current view. That is, any elements that only exist in previous versions of a directory will not get picked up. The clearexport_ccase does not export triggers, user-defined element types, checked-out versions or the lost+found directory. To get around these, ensure everything is checked-in, triggers and element-types are defined in the new VOB, and who cares about the lost+found. Be sure to lock the original during transfer. A VOB with multiple hundreds of files can take a few hours to do a clearimport. See Import from other configuration management tools for important additional info on clearexport and clearimport.

Table of Contents





Reformat a VOB.

WARNING!   Always backup a VOB's storage directory before running this command. Cannot abort a reformatvob in the middle. It must complete the dump and load phases. However, the old VOB storage area is kept with the name db.date and can be restored from there. This command is not to be taken lightly. Cannot be in a view while running reformatvob. If migrating from one database schema version to another, Rational does not support a reformat back to an older version.

This is mainly used to reformat a VOB when upgrading CC to a newer version, moving a VOB to hosts of different architectures or to compact the database deleting unecessary records. The VOB storage area must be physically located on the host where the command is executed. Cannot be at or below the VOB storage area. Do not have a view set during this operation. The sequence numbers of derived objects will be renumbered during the reformat.
  # ct reformatvob vob-storage-area
See the CC Reference Manual for options.

Table of Contents





Determine diskspace used by a VOB or view.
In UNIX xclearcase, Admin -> VOB... -> Admin -> VOB -> Space
In UNIX/NT clearvobadmin, not possible.
From the CLI:
  # ct space vob-tag  (CC 3.x)
  # ct space { -vob | -view } tag  (CC 4.x)
Some useful options:
-dir.ectory   directory Report disk usage on non-clearcase files or directories.
-vie.w | -vob   tag Report on space used by a view or VOB. Default is -vob. (CC 4.x)
-host   hostname Report on ALL VOBs or views on hostname. (CC 4.x)
-reg.ion   region Use if specifying a view or VOB tag not in the current region. (CC 4.x)
-avo.bs Expand the listing to include all mounted VOBs. (CC 3.x)
-a.ll Expand the listing to include .pid, .identity and so on.
-gen.erate Compute and cache disk space data at time of execution. No info displayed. (CC 4.x)
-upd.ate Compute and cache disk space data at time of execution, then display results. Also used to update "space" info after creating a new storage pool. (CC 4.x)
The space subcommand will give you a breakdown of disk usage for a VOB or subdirectory of a VOB. The "%Use" column in the ouput is the % amount of the entire disk-drive that the VOB occupies.
Note that the -update option to the space command requires proper ACL access. You need either Change or Full access. See the schedule command.

Table of Contents





Backup a VOB.
Backups can be handled by whatever system you choose. However, it's important that the VOB be locked during the backup. That is, it's not sufficient to capture a coincidentally idle VOB. The lock does more than merely ensure that no one modifies the VOB during a backup; it also causes the VOB to flush a database checkpoint to disk prior to backup. A VOB locked with the -nusers option does not perform this flush.
  # ct lock vob:vob-storage-area
  # dump ...
  # ct unlock vob:vob-storage-area
To reduce the amount of time a VOB needs to be locked, the database can be locked, saved off to another location on the same disk and then the VOB unlocked. This is normally accomplished via the vob_snapshot command. To set up vob_snapshot'ing, use the vob_snapshot_setup command located in ccase-home-dir/etc.
  # vob_snapshot_setup modparam -snap_to location -dbcheck yes
The vob_snapshot_setup command will tell CC where to place the copy of the database and whether a database check should be performed (recommended). An attribute called vob_snapshot_parameters containing these parameters is attached to the VOB's replica name being vob_snapshot'ed.
  # ct describe replica:replica-name@vobtag
The vob_snapshot is then called daily by the root crontab entry ccase_cron.day in CC 3.x and by the Scheduler in CC 4.x. Additionally, the UNIX only   -notify   option can be used to notify a comma separated list of users that the snapshot has occurred. See the /var/adm/atria/config/snapshot.conf file for notification parameters.
The vob_snapshot_setup command also has the following two additional uses:
  # vob_snapshot_setup lsvob              (list local VOBs being vob_snapshot'ed)
  # vob_snapshot_setup rmparam vob-tag    (remove a VOB from the above list)
NOTE: Because of the possibility of inconsistencies between the database and source pool(s), the VOB backup should occur as soon after the scheduled vob_snapshot as possible, with the VOB and vob_snapshot'ed database backed up in the same run.

See "Restore a VOB from backup".

Table of Contents





Remove a vob-tag from a region.
Simply run the rmtag subcommand specifying the region from which it is to be removed. This will not remove the VOB itself, but merely the reference to it.
In UNIX xclearcase, Admin -> VOB... Admin -> Registry -> Remove tag.
In UNIX/NT clearvobadmin, not possible.
From the CLI:
  # ct rmtag -vob -region region-name vob-tag
Table of Contents



Clean up a VOB database.
By default, the VOB databases are cleaned periodically by the vob_scrubber command; invoked weekly by the root crontab entry ccase_cron.wk. However, it can be run manually at any time.
On UNIX, vob_scrubber information is logged in /var/adm/atria/log/vob_scrubber_log and on Windows in Start -> Programs -> Administrative Tools (Common) -> Event Viewer -> Log -> Application which can be accessed via the ClearCase Home Base -> Administration -> Log Browser -> vob_scrubber. See cleargetlog on either platform.
  # vob_scrubber vob-storage-area
Some useful options:
-lvobs Scrub all local VOBs.
-nlog Send report to standard out instead.
-long Produce a more detailed report.
-stats_only Merely generate a report of the number and type of records.
The host-wide rules for what's to be cleaned from the database are controlled by the atria-home/config/vob/vob_scrubber_params file. That file contains rules on how long certain events are kept recorded in the database. In general, the most recent 1000 event records are never scrubbed and events, such as the creation records for DOs are always scrubbed. A VOB specific parameter file of the same name can be placed just inside the VOB storage area. The VOB specific parameters override the host-wide ones. See the CC Reference Manual under vob_scrubber for details on the scrubbing rules.
NOTE: Scrubbing a VOB database does not free up disk space, but merely frees up space internal to the database (logical space) to limit further growth. To truly free up disk space, a reformatvob is needed.

Table of Contents





Create/modify a storage pool.
As a default, a new VOB comes with three storage pools: s/sdft (source), c/cdft (cleartext) and d/ddft (derived objects). Additional pools can be created and elements assigned to them; perhaps to break elements into logical groupings or to create remote pools where there is more disk space. Execute the command inside a VOB unless pool-name@/vob-tag is used.
  # ct mkpool { -sou.rce | -der.ived | -cle.artext } pool-name
Some useful options:
-ln   path (UNIX only) Create the pool in a remote directory. (UNIX only)
-siz.e   max-kbytes reclaim-kbytes (c & d pools only) don't scrub until the pool reaches max-kbytes and then only scrub down to reclaim-kbytes. Defaults are 0 & 0.
-age   hours Don't scrub objects dated within hours, default is 96. This option is used with the -size option, if not doing a -update.
-ale.rt   command scrubber runs command when it fails to scrub below max-kbytes (used with -size option, if not -update)
-upd.ate Change the parameters of an existing pool.
See the scrubber command for more information on the size and age options. Updating the age to 0 resets the age to the default of 96 hours. Each element in a VOB is assigned one source and one cleartext pool. See the chpool command to the change the pool assignment. Directories are assigned one each of the pools. Directories themselves are stored in the VOB database, but objects created in that directory will inherit those pools.
NOTE: As of CC 4.0, to see a newly created pool as a part of the output of the space command, one needs to run:
  # ct space -vob -update vob-tag
NOTE: The -ln option creates a UNIX softlink between the appropriate pool subdirectory and the remote pool. Because Windows can't follow UNIX links, you can only use remote pools if they are specified as remote during the region synchronization. In ClearCase Home Base -> Administration -> Region Synchronizer -> select VOB -> Import... -> Show Mount Options >> -> Windows-Only Options, specify all remote pools on one line similar to the following:
s\sdft\=\\hostname\path\s_poolname\|c\cdft\=\\hostname\path\c_poolname\

Create remote storage pools for a VOB at initial creation.
1) After creating the VOB, create the remote pools using "mkpool -ln". The new remote pool will need to be a different name than the original pool of that type.
2) Change to the top level of the brand-new VOB and chpool on "." and "lost+found". Any elements, directory or file, created in that VOB will have their pool assignments set to the new remote pool.
3) There is no way to remove the pre-defined pool. However, after step (2), no elements will ever be assigned to it anyway. At this point, it's just an empty, dead pool. As the VOB's owner, I would lock that dead pool to stop any adventerous CC users from executing a chpool to it.
  # ct lock pool:pool-name@/vob-tag
Table of Contents



Remove a storage pool.
The rmpool command will not complete unless there are no assigned to it. The follwing find command doesn't work for derived object pools. Should be at least VOB owner to ensure all elements get transferred.
  # ct find . -all -element 'pool(pool-name)' -exec 'cleartool chpool -force new-pool $CLEARCASE_PN'
  # ct rmpool pool-name
NOTE: On Windows use %CLEARCASE_PN% as the variable.

Table of Contents





Rename a storage pool.
Simply give the pool a new name. The pool name is changed for all elements contained therein.
  # ct rename pool:old-name new-name
Table of Contents



Scrub the derived object and cleartext pools.
By default, the scrubber program (/usr/atria/etc on Unix and atria-home\bin on Windows) is run by /usr/atria/config/cron/scrubber_day.sh on UNIX and atria-home\config\cron\scrubber_day on Windows which is run one a day by the schedule command. Even though scrubber gets run daily, it can be run manually at any time.
  # scrubber [options]
The default (without options) is to run a free-space check of the partition on which the VOB resides. Information about the free space of each partition is kept in /var/adm/atria/cache/scrubber_fs_info on Unix and atria-home\cache\scrubber_fs_info on Windows.
On Unix, scrubber information is logged in /var/adm/atria/log/scrubber_log and on Windows in Start -> Programs -> Administrative Tools (Common) -> Event Viewer -> Log -> Application which can be accessed via the ClearCase Home Base -> Administration -> Log Browser -> scrubber. See cleargetlog on either platform. See the CC Reference Manual for a columnar description of the log.
Some useful options:
-f Examines all specified pools individually, using the parameter-driven algorithm.
-e Override the scrubbing parameters. Everything must go.
-o Default: Invoke the free-space analysis instead of going directly to parameters.
-p   pool Only work on pool.
-k   kind Restrict scrubbing to a certain kind (do or cltxt).

The -f option causes scrubber to examine all pools individually using a parameter-driven algorithm. The parameters can be set with the mkpool command, but are defaulted to max-kbytes and reclaim-kbytes set to 0. Generally, the scrub does not happen unless the pool has exceeded max-kbytes and stops scrubbing when it reaches the minimum size of reclaim-kbytes. However, the default of 0 for max-kbytes means to try and scrub everything, independent of what reclaim-kbytes is set to. No matter what reclaim-kbytes and max-kbytes are set to, nothing is scrubbed if it's less than age hours old (default=96). In addition, independent of what those three parameters are set to, derived objects are never scrubbed unless their reference counts are zero. However, more than just old DOs are scrubbed, see the CC Reference Manual for details. The other option, -a, used in daily scrubbing tells scrubber to work on all mounted VOBs on the local host. The mkvob command sets max-kbytes=0, reclaim-kbytes=0 and age=96. These can be modified using the mkpool command with a -replace option.

WARNING!   The scrubber considers access time and not modification time. So, programs that access files without modification, such as some backup tools, may cause files to never be scrubbed.

Table of Contents





List the pools associated with a VOB.
The default is to list all pools in the current VOB.
  # ct lspool
Some useful options:
-l.ong Expand the listing to pool parameters and pathnames.
-s.hort Restrict the listing to pool names only.
-obs.olete Also list pools rendered obsolete by "lock -pool -obsolete".
-invob   vob:vob-tag List pools in a VOB other than the current.
-fmt   format-string Customize the output format. See fmt_ccase in the CC Reference Manual.

Table of Contents





List available VOBs.
Updated: 04/26/06
In UNIX xclearcase, Admin -> VOB...
In UNIX/NT, clearvobadmin.
From the CLI (a star in the leftmost column indicates mounted):
  # ct lsvob [vob-tag]
Some useful options:
-l.ong Include info contained in the VOB registry.
-s.hort Only list the vob-tag(s).
-g.raphical Invokes clearvobadmin.
-reg.ion   region Specify a region other than the current.
-hos.t   hostname Specify a registry server other than the one serving the current region.
-hos.t   hostname   -quick Read information from the registry and don't attempt to inspect the VOB storage.
-sto.rage   vob-storage List a VOB by its storage vice its tag.
-uui.d   vob-replica-UUID List a VOB by its replica UUID vice its tag.
-fam.ily   vob-family-UUID List a VOB by its family UUID vice its tag.

Table of Contents





Change a VOB's feature level.
Starting with CC 4.0, VOBs will be assigned a "feature level". VOBs prior to 4.0 are assumed to be at feature level 1, VOBs at the 2.x level are assumed to be at feature level 0 and VOBs created after installing 4.0 have feature level 2, and those created after CC 5.0/2002 are at feature level 3, etc... The feature level gives enhanced capability to a VOB. In general, when upgrading, both servers and clients must be upgraded to the new CC version prior to raising the feature level or the clients won't be able to access the updated VOBs.
For all VOBs on the system that existed prior to the upgrade, simply run chflevel. If you don't specify -force, it will prompt you to upgrade each VOB in turn, except MultiSited VOBs. The chflevel -auto command can be run repeatedly without harm.
  # ct chflevel -force -auto
If one decides to upgrade a pre 4.0 VOB without using the -auto option, the following two command must be run on it. As with -auto, this isn't for MultiSited VOBs.
  # ct chflevel -replica 2 original@vob-tag
  # ct chflevel -family 2 vob:vob-tag
For MultiSited VOBs, they MUST be upgraded manually one at a time. For a VOB to be upgraded, it must be self-mastering. Executed at the site that owns the originally created VOB, the following command will give mastership of replica-name to that remote replica.
  # mt chmaster remote-replica-name@local-vob-tag replica:remote-replica-name@local-vob-tag
Once each VOB in the replica family is self-mastering, they can each upgrade their own replica feature level. Each site needs to then sync back with the site that will upgrade the family level. That site needs to know that all other sites are up to the same level before proceeding (below).
  # ct chflevel -replica feature-level replica-name
  # mt syncreplica -export -fship remote-replica-name@local-vob-tag
Once all VOBs in the replica family have the feature levels upgraded, the replica family level can be upgraded by site designated to do so; the site that all replicas in the family manually sync'ed back to (above). The family level cannot be higher than the lowest level member of the family.
  # ct chflevel -family feature-level vob:local-vob-tag
NOTE: See " The feature level of at least one replica is unknown", if encountering that error.

Table of Contents





Restore a VOB from backup.

Standard restore.
Use this standard restore if the VOB was locked during the entire backup. This is appropriate if you have not employed VOB database snapshot'ing.
1) Unmount the corrupted VOB from all hosts.
2) Shut down CC.
3) Move the vob-storage-area to a new location and/or name (such as .bak).
4) Restore the backed-up VOB from tape (do you have enough space?).
5) Restart CC.
6) Unlock the VOB.
7) Mount the VOB.

Semi-Live Backup restore.
Use the procedure if the VOB's database was snapshot'ed during the backup.
1) Unmount the corrupted VOB from all hosts.
2) Check for enough space.
3) Run "vob_restore vob-tag". The vob_restore command will prompt you to restore the VOB from tape, copy the snapshot'ed database and stop CC as well as other misc tasks. It will also run checkvob.
4) Restart CC.
5) With the VOB still locked, run consistency checks.
6) Unlock the VOB.
7) Mount the VOB.

NOTE: If this VOB is MultiSited, you MUST run restorereplica before using it.

Table of Contents





Set or determine a VOB's text 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. VOBs created using CC 4.1 are pre-enabled and can handle views in any text mode. To disable support for interop text modes, use the   -d   option. If in a CCMS configuration, all pre-CC 4.1 replicas must have msdostext_mode run on them individually. Must be VOB owner or higher to run this command. The msdostext_mode is stand-alone and lives in CC-home/etc/utils.
  # ct lock -nuser root vob:vob-tag
  # msdostext_mode vobstorage
  # ct unlock vob:vob-tag
To determine an existing VOB's text mode, use the dump subcommand. In the line called "flags:", determine if the flag called "pc_line_count" is listed. If so, the VOB is enabled for interop text mode.
  # ct dump vob:vob-tag

Table of Contents





Get a listing of all owners of all objects.
New in CC 5.0/2002, an output file can be generated that contains a complete listing of the object type, dbid, owner, group, access mode, and storage location of every object in a VOB. This command can only be run by a VOB owner or privileged user and can potentially create a gigantic file. The command lives in cc-home\etc\utils on Windows and /usr/atria/etc on UNIX.
  # vob_siddump -profile path\dumpfile vobtag path\sidfile
The path\dumpfile is the large output file that will contain all the desired information. The path\sidfile is a tiny output file that contains SID information about the VOB itself.

Table of Contents





Get a listing of a VOB's properties.
  # ct describe vob:vobtag
See the "describe" man page for a full listing of options. If the -long option is used, all views containing checkouts from the VOB will also be listed, plus more verbose information about metadata on the VOB object itself.

Table of Contents





Fix VOB protections.
If a VOB was moved to a new location without using a suitable copy command or a VOB was restored from backup that didn't preserve the proper ACL's, it will be necessary to run the following commands. The "fix_prot" command (Windows only) lives in cchome\etc\utils and is used to bring the VOB's storage containers to a permission level that will allow checkvob to even function. Most CC Admins have the "utils" directory in their path. The primary-group must be the primary group of the vob-owner. Even though the second fix_prot command sets the data container permissions to 775, the checkvob command will reset them to the proper 444. The checkvob command cannot reset permissions in the cleartext pool, so it's best just to clean it out.
  # fix_prot -root -chown vob-owner -chgrp primary-group vob-storage-area
  # fix_prot -r -chown vob-owner -chgrp primary-group -chmod 775 vob-storage-area
  # scrubber -e -k cltxt vob-storage-area
  # ct checkvob -fix -protections -pool vob-storage-area
The albd service should be stopped and restarted to remove any caching.

You can also fix the protections on a VOB storage area on Windows or Unix by using the vob_sidwalk command.
  # ccase-home\etc\utils\vob_sidwalk -recover_filesystem vobtag outputfile.csv
Table of Contents



Lock or unlock a VOB.
In xclearcase on Unix, go to Admin -> VOB..., select the VOB to be locked and choose Locks -> Lock. Unfortunately, for an unknown reason, if locking a VOB from the Unix GUI, it needs to be mounted first. Hunh? That isn't true from the CLI.
In CC Admin Console on Windows, under ClearCase Network, surf to the server that hosts the VOB's storage area. Under the heading of VOBs, right-click on the VOB to be locked and go to its Properties sheet. Lock and unlock the VOB from the "Lock" tab.
From the CLI:
  # ct lock vob:vobtag
Lock all VOBs:
UNIX (csh):
  # foreach vobtag (`ct lsvob -s`)
  ? cleartool lock vob:$vobtag
  ? end

Windows:
  # for /f "tokens=*" %I in ('cleartool lsvob -s') do @cleartool lock vob:%I
See also, Lock down a VOB to a couple of users.
NOTE: A locked VOB cannot be synchronized. If the VOB is MultiSited and you are going to lock the VOB, run one last syncreplica -export just before locking. The latest changes won't go out when the next automated synchronization comes around. Do the syncreplica manually so that the latest changes get sent out before the lock.

WARNING! Most sites that perform automated backups have scripts that lock all the VOBs prior to backup and then unlock all the VOBs after the backup. Those scripts are often run as root or Administrator. The problem is that if you decide you want to manually lock a VOB for some reason, the automated unlock at the end of the very next backup will most likely unlock it unwittingly. Moreover, if the VOB is locked using the -nuser option, the VOB won't be relocked when the backup occurs. That means that the backups won't force the very important flush-to-disk of the VOB's database from memory that a normal lock command performs.

Table of Contents





Determine the VOB database schema version.
Rational periodically introduces upgrades to the VOB database schema. The last update happened at CC 4.0 (schema 54). Installations of that or a later version will ask if you want to use the extended VOB format (new schema revision). Accepting the new schema version requires you to reformat existing VOBs. Any new VOBs created will automatically be at the new schema level. The schema version used is for an entire VOB server and cannot be applied on a VOB by VOB basis in the way feature level updates can.
To determine what schema version is in place currently on a given server, from the CLI you can check the version of CC or look at the properties of any VOB on that server.
  # ct -ver

-or-

  # ct describe vob:vobtag
Table of Contents



Enable/disable VOB auto-remounting after reboot.
When a VOB is mounted, a check box can be selected to remount a VOB automatically after reboot. The remount information is stored in the Windows registry at HKEY_CURRENT_USER\Software\Atria\ClearCase\CurrentVersion in the key called PersistentVOBs. The registry locations were valid as of CC 2002.
If a VOB fails to remount even when it's listed in that registry key, try placing clearcase-home\bin at the begining of your PATH environment variable.
You can also disable automounting by creating a key called "DisableAutomounting" under HKEY_LOCAL_MACHINE\Software\Atria\ClearCase\CurrentVersion of type REG_DWORD with a value of 0.

Table of Contents





Ensure nobody outside a specific group can even read a VOB's contents.
A VOB has a list of groups attached to it. The VOB group list controls who can modify objects in the VOB. However, the default permissions on a VOB allow personnel whose primary group is not in the VOB's group list to read the VOB's contents.
If you want to ensure nobody else can even read the contents of a VOB, designate a single group to access the VOB. If you need more than one group, simply create a new group made up of the other groups. Use the "protectvob" command to ensure the only group in the VOB's group list is that one newly created group. Then, use the "protect" command to recursively change the group permission on all elements starting at the very top of the VOB. Remove the permissions at the top level that allow others to read the contents. The following commands will accomplish that. You need to be the VOB owner or higher to complete the commands.
Change the VOB's primary group and remove any additional groups:
  # ct protectvob -chgrp new-group -delete_group other-group(s) VOB-storage-area
Change the group permissions on all files and directories:
  # ct protect -r -chgrp new-group vobtag
Remove the ability for others to even enter the VOB:
  # ct protect -chmod 770 vobtag
Table of Contents



Link VOBs together.
VOBs may be created separately or split afterward with the "relocate" command for different reasons, first and foremost is performance. However, once split into smaller VOBs the users still have the choice to see all the files as if they were still in one large VOB.
To link VOBs together, use the "ct ln -s" command. For example, if a VOB whose tag is "/vobs/myvob" has a directory in it called "docs", you can create another VOB called "/vobs/myvob_docs", relocate the elements in the original docs directory to the new VOB, and then link the new back into the original VOB. Don't use the relocate command on UCM components.
Because this is an internal CC softlink, it can be used on Windows or Unix. However, some Windows DOS commands from the CLI may not be able to see the softlink.
  # cd /vobs/myvob
  # ct co -nc .
  # ct ln -s ../myvob_docs docs
  # ct ci -nc .
Table of Contents



Change protections on all objects in a VOB.
It's easy to change the protections on a single element or piece of MetaData or on the VOB itself. However, before CC 2002.05.00 it was difficult to change protections on every object in a VOB, if say a user has left the project that owned many objects. This is also useful when moving a VOB across Windows domains, or Unix NIS maps, or between Windows and Unix where the users and groups\ don't match by UID/GID.

Change all ownerships to the VOB owner.
  # ccase-home\etc\utils\vob_sidwalk -unknown -execute vobtag outputfile.csv
Be careful when performing this in a UCM environment. Any activities owned by a certain user will no longer be useable by that user. That is, users must own the activities they are working on.

Change ownership of many objects to a new owner.
1) Lock the VOB.
  # ct lock vob:\vobtag
2) Generate a SID list containing all the users and groups of all objects.
  # ccase-home\etc\utils\vob_siddump vobtag output_file.csv
3) Create a map based on that output file. Using a spreadsheet for the editing will simplify the process. For each line in the csv, replace the word IGNORE with the domain\user that will replace the domain\user that is listed in the first column. Leave IGNORE for any lines that don't need to be changed. Remove the last three columns after the column that had IGNORE in it. Save the map.csv file.
4) Test the map file without the -execute option first. The test-output.csv should match the map.csv you created in step (3).
  # ccase-home\etc\utils\vob_sidwalk -map map.csv vobtag test-output.csv
5) Unlock the VOB and execute the change.
  # ct unlock vob:\vobtag
  # ccase-home\etc\utils\vob_sidwalk -execute -map map.csv vobtag sidwalk-output.csv
5) To make sure everything came out ok, run the siddump again.
  # ccase-home\etc\utils\vob_siddump vobtag after-sidwalk.csv
Table of Contents



Lock down a VOB to a couple of users.
There are several ways to lock a VOB down to a couple of users.
1) Lock the VOB using the -nuser option. This is the easiest. Unfortunately, that means that the VOB never gets a full lock when it gets backed up. A lock without the -nuser option is important in that it forces the VOB's database resident in memory to be flushed to disk.
2) Add the specific user(s) to a group of their own and make that the only group in the VOB's group list. This works only if those users remember to run "newgrp" on Unix or change the CLEARCASE_PRIMARY_GROUP environment variable on Windows, which is a burden to the users.
3) Lock all the elements in the VOB using the -nuser option. This circumvents the problems in (1) and (2), but doesn't lock down any new elements.
4) Therefore, there is only one way to do this, and that is to write a preop checkout trigger that checks the username of the checkout and balances that against a list of allowed users, perhaps in an attribute on the VOB object.

Table of Contents





Public vs. private VOBs.
When creating a VOB, the private (default) vs. public option determines whether a user can mount it or not in a Unix environment. That option makes almost no difference in a Windows environment, other than a user can't use "mount -all" from the CLI, which is pretty minor.
IBM Rational has a good summary at: https://www-304.ibm.com/support/docview.wss?uid=swg21128196

Table of Contents





Determine which VOBs are locked.
Updated: 01/03/13
Version: 7.1.2
Unfortunately, I don't of an easy way to find all the lock statuses from a GUI.
To do it from the CLI for your current region:
Verbose output:
	ct describe -l vob:\vobtag

Concise output:
	ccperl -e "foreach $vob (`cleartool lsvob -s`) { print `cleartool describe -fmt \"%[name]p: %[locked]p\\n\" vob:$vob`; }"

CAL:
	$return = $ct->CmdExec("lsvob -s");
	foreach $vob (split(/\n/,$return)) {

		chop($vob);
		print "$vob: ";

		$vob_o	= $CC->VOB($vob);
		$lock_o	= $vob_o->Lock;

		if ( "$lock_o" eq "" ) {
			print "unlocked\n";
		} else {
			if ( $lock_o->IsObsolete ) {
				print "obsolete\n";
			} else {
				print "locked\n";
			}
		}
	}
Table of Contents



Programmatically determine the current VOB's tag.
Updated: 01/06/12
Version: 7.0.1.8
Using cleartool:
	$current_vobtag = `cleartool describe -s vob:.`;

Using CAL:
	$current_vobtag = $CC->Element(".")->VOB->TagName;
Table of Contents



Programmatically determine the current VOB's owner.
Updated: 01/10/12
Version: 7.0.1.8
Using cleartool (Windows only):
	$vob_owner_login = `cleartool describe -fmt "%[owner]p\n" vob:.`;

	# For some reason, this only produces the last name of the fullname.
	$vob_owner_fullname = `cleartool describe -fmt "%[owner]Fp\n" vob:.`;

Using CAL:
	if ( $vob_o->Owner =~ /.+\\(.+)$/ ) {
		$vob_owner = $1;
	}
Table of Contents



Provide read-only access to a VOB.
Updated: 01/27/12
Version: 7.0.1.8
Set the primary group to those that you want to give write access to. Create a trigger that sets that primary group for all elements and resets the access mode to 774. Be sure to set the top level directory to 774 as well.

Table of Contents





Programmatically determine a view-private file's VOB.
Updated: 09/14/12
Version: 7.1.2
I don't know if there is a built-in way to get that information, but it can obtained with the following kludgy code.
	$vpf = "M:\\myvob\\myview\\view private file.txt";
	foreach $vob (`cleartool lsvob -s`) {
		chomp($vob);
		if ( "$vpf" =~ /\Q$vob\\/ ) {
			$vobtag = $vob;
			last;
		}
	}
	print "$vobtag\n";
Table of Contents



Determine when a VOB was last accessed.
Updated: 03/04/15
Version: 8.0
Determining when a VOB was last accessed is not the same as determining when it was last modified. Access to a VOB can happen in a read-only manner. Unfortunately, read-only access does not leave a trail. There are no commands available in CC that will provide information on when a VOB was mounted and/or accessed from a view or referenced in a build, such as a VOB that acts as a common library.
Views have a last-accessed property though.

Table of Contents





Remove a Unix VOB/view storage area across NFS.
Updated: 12/01/15
Version: 7.1.2.14
If you want to completely remove a Unix VOB/view storage area that is, say, stored on a SAN, if you run a command like "rm -rf storage-area", you'll get "rm: Unable to remove directory storage-area: File exists". By running "ls -la storage-area" you'll note that it did remove everyting except a dot file like ".nfs#####". If you manually remove that file, it will just get recreated. You need to kill its process, then remove it.
	Example:
	/usr/sbin/fuser -u /vobstore/othermachine/vobs/myVOB/.*
		/vobstore/othermachine/vobs/myVOB/..:
		/vobstore/othermachine/vobs/myVOB/.:     3532c(someuser)
		/vobstore/othermachine/vobs/myVOB/.nfs4B9C4B1:     3532o(someuser)
	kill -9 3532
	rm -rf /vobstore/othermachine/vobs/myVOB
Table of Contents

ejostrander@cox.net
Return to the home page .

This page last modified: 08/15/2016