Working in a View, describes tasks you perform daily or weekly. You may need to perform some of these tasks less often:
You can add files or directories to source control at any time.
To add view-private files and directories to source control, or to make placeholders for nonexistent files and directories:
The version-selection rules of your view determine the branch on which the first version of the element is created. Make sure your view creates versions on an appropriate branch.
For snapshot views, the path from which you add to source control does not need to be loaded. However, it must match the VOB namespace.
cleartool mkdir directory-name
cleartool mkelem file-name
cleartool mkdir directory-element-path
cleartool mkelem file-element-path
By default, when you add an element, it remains checked out. When you finish modifying the new elements, check them in. Elements you add to a directory element are visible only in your view until you check in the directory.
For more information about the mkelem command, see Under the Hood: What Happens When You Add to Source Control and the mkelem reference page in the Command Reference.
The mkelem command always creates an element and initializes its version tree by creating a single branch (named main) and a single, empty version (version 0) on that branch. The following arguments for the mkelem command determine optional ClearCase behavior:
Using mkelem or mkdir without the –master option assigns mastership of a new branch to the VOB replica that masters the associated branch type. If this replica is not your current replica, you cannot create new versions on the branch.
Other views do not see the element until the parent directories of the element are checked in (you must do this yourself) and you check in the file or directory.
Each element is an instance of an element type. You can specify an element type with the –eltype option. (The lstype –kind eltype command lists the element types in a VOB.) The element type must already exist in the VOB in which you are creating the new element, or must exist in the administrative VOB hierarchy associated with the VOB in which you are creating the new element. A mkelem –eltype directory command is equivalent to a mkdir command.
If you do not specify an element type on the command line, mkelem uses the magic files to determine an element type with which to perform file-typing. This involves matching patterns in the name of the new element (and examining the existing view-private file with that name, if one exists; see Conversion of View-Private Files to Elements). If file-typing fails, an error occurs and no element is created:
For more information about file-typing, see cc.magic in the Command Reference.
Elements are controlled by ClearCase permissions, as described in the permissions reference page in the Command Reference, not by the access modes for files and directories that are set by the operating system. When your view selects a checked-in version of an element, all of its write permissions are turned off. When you check out an element, write permissions are added to the view-private copy. (For more information, see Under the Hood: What Happens When You Check Out a File or Directory.)
Because file elements are read-only, the mode to which your umask is applied is 444 (not 666) for a file element. When you convert a view-private file to an element (see Conversion of View-Private Files to Elements), its read and execute rights become those of the new element.
You can use the mkelem command to convert a view-private file to a file element with the same name. There are several cases:
During the element-creation process, the view-private is renamed to prevent a name collision that would affect other ClearCase tools (for example, triggers on the mkelem operation). If this renaming fails, a warning message appears. There are two renaming procedures:
Note: If mkelem does not complete correctly, your view-private file may be left under the .mkelem file name.
mkelem does not perform any special processing for a nonshareable derived object. The process is the same as for a shareable derived object, as described in Conversion of View-Private Files to Elements. However, when you check in version 1 of the new element, the checkin converts the nonshareable derived object to a shareable derived object, then checks it in.
Note: When a nonshareable derived object is converted to a shareable derived object, its derived object ID changes. For more information, see Derived Objects and Configuration Records in Building Software.
If you create a new directory element, you cannot use the same name as an existing view-private file or directory, and you cannot use mkelem to convert an existing view-private directory structure into directory and file elements. To accomplish this task, use the clearfsimport and clearimport utilities.
If your config spec has a /main/LATEST rule with a –mkbranch clause, mkelem checks out a subbranch instead of the main branch. For example, suppose your view has this config spec:
element * CHECKEDOUT element * .../gopher_port/LATEST element * V1.0.1 -mkbranch gopher_port element * /main/0 -mkbranch gopher_port
The /main/0 rule in the last line allows you to create elements. In this case, a gopher_port branch is created for the new element, and this branch is checked out instead of main:
cleartool mkelem –c "new element for Gopher porting work" base.hCreated element "base.h" (type "text_file"). Created branch "gopher_port" from "base.h" version "\main\0". Checked out "base.h" from version "\main\gopher_port\0".
The auto-make-branch facility is not invoked if you use the –nco option to suppress checkout of the new element. For more about auto-make-branch, see the checkout and config_spec reference pages in the Command Reference.
By default, when you create an element in a replicated VOB, mkelem and mkdir assign mastership of the main branch of the element to the VOB replica that masters the branch type main. If this replica is not your current replica, you cannot create versions on the main branch. (You can create versions on other branches if they are mastered by the current replica.)
To assign mastership of the main branch of a new element to the current replica, use the –master option. The –master option also allows auto-make-branch during element creation, even if the branch type specified in your config spec is not mastered by the current replica. In this case, mkelem or mkdir assigns mastership of newly created branches to the current replica. For example, suppose your view has the following config spec:
When you create a new element with mkelem –master or mkdir –master and do not use the –nco option, the command creates the branches main and gms_dev and assigns their mastership to the current replica.
Note: If you use the –nco option with –master, only the main branch is mastered by the current replica, because it is the only branch created by mkelem or mkdir.
You sometimes need to distinguish an element itself from the particular version of the element that is selected by your view. In general:
For example, msg.c@@ references an element, whereas msg.c refers to a version of that element. In many contexts (for example, checkin and lsvtree), you can ignore the distinction. But there are ambiguous contexts in which you need to be careful. For example, you can attach attributes and hyperlinks either to version objects or to element objects. Thus, these two commands are different:
cleartool mkattr BugNum 403 msg.c (attaches attribute to version) cleartool mkattr BugNum 403 msg.c@@ (attaches attribute to element)
The first command operates on the version of the element selected in your view, but the second command operates on the element itself.
Caution: Do not create elements whose names end with the extended-naming symbol. ClearCase software cannot handle such elements.
Physical storage (data containers) for the versions of an element is allocated in the storage pools that mkelem assigns. You can change pool assignments with the chpool command.
Each VOB has a group list. If your principal group is on this list, you can create an element in that VOB. For more information about group lists, see the protectvob reference page in the Command Reference. Your principal group is the first group listed when you enter the id(1) command.
If you are adding a large number of files and directories to source control, use the clearfsimport command (or clearexport commands) and clearimport command. For more information, see the clearfsimport and clearimport reference pages in the Command Reference.
This section explains how to move, remove, and rename elements.
Because directories as well as files are under ClearCase control, you can move or remove elements from specific versions of directories without affecting the element itself. Moving or removing elements creates new versions of the parent directories to record the modifications.
For example, version 4 of /gui_vob/design contains an element named prog.c. If you remove prog.c from the design directory, ClearCase creates version 5 of /gui_vob/design, which does not contain the prog.c file element. The element prog.c itself is not modified.
cd pat_v1.4_cropcircle/gui_vob cleartool ls design@@/main/4 prog.c@@/main/2 lib.c@@/main/10 cleartool checkout –nc design Checked out “design” version “/main/4” cleartool rmname prog.c Removed “prog.c” cleartool checkin –nc design Checked in “design” version “/main/5” cleartool ls design@@/main/5 lib.c@@/main/10 cleartool ls design@@/main/4 prog.c@@/main/2 lib.c@@/main/10
Before you move or remove an element name from a directory, verify with your project manager that your changes will not adversely affect other team members or break project builds.
Use the cleartool relocate command.
Warning: The relocate command makes irreversible changes to at least two VOBs and their event histories. We recommend that you not use it for minor adjustments. Furthermore, we recommend that you stop VOB update activity before and during a relocate operation. Check with your project manager and ClearCase administrator before using the relocate command.
Removing an element name from its parent directory does not affect the element itself, but two other types of a removal operation do irrevocably affect an element, and we recommend that you be very conservative in using these operations:
Renaming an element creates a new version of the parent directory to catalog the new element name. The element uses its new name in subsequent versions of its parent directory, but previous versions of the parent directory refer to the element by its previous name.
cd pat_v1.4_cropcircle/gui_vob
cleartool ls design@@/main/4
prog.c@@/main/2
lib.c@@/main/10
cleartool checkout –nc design
Checked out “design” version “/main/4”
cleartool mv prog.c msg.cat
Moved “prog.c” to “msg.cat”
cleartool checkin design
Default:
Added file element "msg.cat".
Removed file element "prog.c".
Checkin comments for ".": ("." to accept default)
.
Checked in “design” version “/main/5”
cleartool ls design@@/main/5
msg.cat@@/main/2
lib.c@@/main/10
cleartool ls design@@/main/4
prog.c@@/main/2
lib.c@@/main/10
Before you move or remove an element name from a directory, verify with your project manager that your changes will not adversely affect other team members or break project builds.
While working with source files in a snapshot view, you may need to see the contents of elements that are not loaded into the view or see ClearCase information about these nonloaded elements. For example, you may have chosen not to load a VOB that contains functional-specification documents. However, you may want to check periodically whether the functional specifications have been modified by reviewing the history of the elements.
You can use the cleartool ls command to see all elements in the VOB namespace, even if they are not loaded into your snapshot view. This command lists the names of elements cataloged in the VOB namespace that the config spec of your view selects. The output of cleartool ls includes this information:
To see all elements in a directory, enter this command:
cleartool ls path...
For more information, see the ls reference page in the Command Reference.
To access a version of a file not loaded into your view, use the cleartool get command, which copies the version you specify into your view. You can view nonloaded files or copy them into your view for build purposes, but you cannot check them out. Only file elements that are loaded into the view can be checked out.
Note: You cannot use cleartool get for directory elements.
To copy a nonloaded version of a file element into your view, type a command in this format:
For example:
This command copies prog.c@@/main/v3.1_fix/10 into your view under the name of prog.c.previous.version. For information on version-extended paths, see The Version-Extended Path.
If you need to perform ClearCase operations in a snapshot view that you did not create or have not updated, you must register that view.
When you create a snapshot view, ClearCase registers it in the file .ccase_svreg in your home directory. When ClearCase needs to access a snapshot view, it looks in that file in your home directory for the path for the snapshot view root directory. If you did not create or have not updated the view that ClearCase is trying to access, you must explicitly register the view.
If a snapshot view is not registered under your home directory and you use the snapshot view to perform ClearCase operations (for example, to check out a file), ClearCase cannot find the view. To use this view to perform ClearCase operations, register the view (see To Register a Snapshot View). If you inadvertently delete or corrupt the .ccase_svreg file, you must regenerate information in it for each snapshot view that you use (see To Regenerate .ccase_svreg).
To register a snapshot view that you did not create or have not updated, perform the following steps:
This registers the view for your use on any UNIX workstation. The preview form of the command (update -print) is quicker than update and does not change the loaded files.
Note: You cannot register a snapshot view that was created from a Windows host (see Accessing Views Across Platforms of Different Types).
For more information, see Updating a Snapshot View.
When you create a snapshot view or register a snapshot view, ClearCase creates or modifies the file .ccase_svreg in your home directory. Some ClearCase operations use information from this file. If you moved the snapshot view or the .ccase_svreg file in your home directory has been deleted or corrupted, you must regenerate the file. To regenerate information in .ccase_svreg, follow the steps in To Register a Snapshot View for each snapshot view that you use.
This section discusses the following tasks:
For information about changing a view tag, see the mktag reference page in the Command Reference.
If the snapshot view storage directory is in a storage location, you can use the standard mv command to move the directory tree of loaded elements and view-private files of the snapshot view.
Enter the following command:
cleartool lsview –long view-tag
The Global Path field displays the path for the view storage directory.
Caution: If the view storage directory is located below the root directory of the view (colocated with the view), do not use the standard mv command to move the snapshot view. Instead, see Moving a View Storage Directory.
If the snapshot view storage directory is in a storage location, you can move the view to a different workstation, but the workstation must run a UNIX operating system.
After moving a snapshot view, you must use cleartool update (or cleartool update –print) to modify .ccase_svreg in your home directory (see To Regenerate .ccase_svreg). Some ClearCase operations use information from this file and will not succeed until you use update to modify it.
Each dynamic view and snapshot view includes a view storage directory, which ClearCase uses to maintain the view. Do not use the standard mv command to move a view storage directory for the following reasons:
We suggest that you ask your ClearCase administrator to move view storage directories because it may affect other, potentially many other, ClearCase users at your site. For more information about the procedure for moving view storage directories, see the Administrator’s Guide for Rational ClearCase.
Caution: You will lose data (including view-private files in a dynamic view) if you move a view storage directory without following the procedure described in the Administrator’s Guide for Rational ClearCase.
The root directory of a snapshot view contains a hidden file, .view.dat. If you delete this file inadvertently, ClearCase no longer identifies the view as a ClearCase object, and you can no longer perform ClearCase operations on files or directories loaded in the view.
Perl ccase-home-dir/etc/utils/regen_view_dot_dat.pl \ [ –tag snapshot-view-tag ] snapshot-view-path
For example:
Perl /usr/rational/etc/utils regen_view_dot_dat.pl \ –tag pat_v1.4_cropcircle_sv \ ~/pat_v1.4_cropcircle_sv
If the view storage directory is under the root directory of the view, you do not need to use the –tag snapshot-view-tag argument.
ClearCase supports environments in which some ClearCase hosts use a Microsoft Windows operating system and others use a UNIX operating system.
This section discusses the following topics:
Your ClearCase administrator can set up storage locations on Windows and UNIX server hosts. Any snapshot view that you create can use one of these storage locations, regardless of the platform type of the server host. For more information about storage locations, see the mkstgloc reference page in the Command Reference.
For a dynamic view, the view storage directory must be located on a host of the same platform type as the host from which you create the view. If you create a dynamic view from a UNIX host, you must locate the view storage directory on a ClearCase host on UNIX; if you create a dynamic view from a Windows host, you must locate the view storage directory on a Windows NT host that is set up to store view storage directories. We recommend that you locate dynamic view storage directories on the host from which you most often use the view.
For snapshot views, the operating system type from which you create the view determines view characteristics; the operating system type that hosts the files and processes related to a snapshot view do not affect the behavior of the view.
For example, it is possible to create a snapshot view from a Windows host and locate the view directory tree and the view storage directory on a ClearCase host on UNIX (assuming that you use third-party software to access UNIX file systems from Windows computers). Although all files related to the view are on a UNIX workstation, because you created the view from a Windows host, the view behaves as if its files are located on a Windows computer:
This section describes support for accessing a view residing on a platform that differs from the platform from which it is being accessed.
ClearCase supports a set of third-party products for accessing UNIX file systems from Windows computers. If your organization uses one of these products, you can access UNIX snapshot views from Windows Explorer (or a command prompt) just as you would access any other directory tree on a UNIX workstation.
You can access snapshot views across platforms, but you cannot issue ClearCase commands across platforms. For example, you cannot check out files in UNIX snapshot views from Windows hosts nor can you create shortcuts to UNIX snapshot views from ClearCase Explorer.
If, from a Windows host, you hijack a file in a UNIX snapshot view, ClearCase detects the hijack when you update the view from a ClearCase host on UNIX.
ClearCase does not support accessing Windows file systems from UNIX workstations.
ClearCase supports a set of third-party products for accessing UNIX file systems from Windows computers. If your organization uses one of these products, you can complete the following tasks to access UNIX dynamic views from Windows computers:
ClearCase does not support products for accessing Windows file systems from UNIX workstations. You cannot access Windows views from UNIX hosts.
Your ClearCase administrator sets up VOBs on Windows or UNIX hosts and creates VOB tags in each ClearCase network region that needs to access the VOBs. (For information about registering UNIX VOB tags in a Windows network region, see the Administrator’s Guide for Rational ClearCase.) Then, from any ClearCase host on Windows or UNIX systems, you can create snapshot views to load elements from VOBs that have tags in your network region.
From a ClearCase host on Windows that supports dynamic views, you can access VOBs on Windows and UNIX from dynamic views as well as snapshot views. To access VOBs on UNIX from Windows dynamic views, you must use third-party software that provides access to UNIX file systems from Windows computers. From a ClearCase host on UNIX, you cannot access VOBs on Windows from dynamic views. Table 5 summarizes your options for accessing VOBs across platform types.
If developers check in source files from views created on both Windows and UNIX hosts, consider creating your views in interop (MS-DOS) text mode. The text modes change how a view manages line terminator sequences. For more information about view text modes, see the Administrator’s Guide for Rational ClearCase or ClearCase Help. For information about starting Help, see To Access Online Information.