For one or more elements, the checkout command checks out a branch (typically, the most recent version on a branch). In most cases, this creates a writable copy of that version in the current view (the checked-out version), but see the “Checking Out a DO Version ” section. An appropriate message is displayed. For example:
If you are checking out in a UCM view, the view must be set to a UCM activity (see setactivity). Checked-out elements are added to the change set of the UCM activity you set.
A checkout record is created; it can be listed with the lscheckout command:
If an existing view-private object has the same name as an element being checked out, checkout responds as follows:
To check out the element, rename or remove the view-private object with the standard operating system command and enter the checkout command again.
You must check out a directory before you use a command that changes its contents (mkelem, mkdir, rmname, ln, or mv). Each of these commands appends an appropriate line to the directory's checkout comment. For example, using mkelem to create a new element within a directory adds a line like this one:
A version can have at most one reserved checkout and any number of unreserved checkouts. Performing a reserved checkout (without using the –version option) guarantees you the right to create a successor to the version you checked out. If several users perform unreserved checkouts, any one of those users (and only one) can create a successor version.
The predecessor version of your checked-out file may not be the latest on the branch from which you checked out your version; this situation can occur if the –version option or unreserved checkouts are used. In this case, you must merge from the latest version on the branch to your checked-out version before you can check in your version.
You can change the reserved state of a checked-out version with the reserve and unreserve commands.
If the VOB containing the element is replicated, the checkout command fails if you try to check out a branch mastered by a different replica:
cleartool checkout –nc file1.txt
cleartool: Error: Unable to perform operation "checkout" in replica
"lexington" of VOB "/vobs/dev".
cleartool: Error: Master replica of branch "/main" is "london".
cleartool: Error: Unable to check out "file1.txt".
If you need to do work on a branch mastered by another replica, you have two choices:
To request mastership, ask the administrator at the master replica to transfer mastership or use the reqmaster command. Consult your ClearCase administrator to make sure mastership requests with reqmaster are enabled and that the replicas are at the correct feature level.
By default, the checkout command checks out these versions:
To modify a different version, you can either use the –version option or create a subbranch at that version. (See the mkbranch reference page). Furthermore, from a single view, you can have only one checkout per element at a time.
Note: When you work in a snapshot view, the only version of a directory element that can be checked out is the version currently loaded in the view. Therefore, the –version and –branch options do not work.
When you use the –version option, you can specify the version either by setting your config spec to use that version or by specifying a version-extended pathname as the pname argument. After you make your changes, you must merge from the latest version of the element before you can perform a checkin.
You can check out a version that your config spec does not currently specify, either by using the –branch option or by specifying a pname argument that is a branch pathname (for example, msg.c@@/main/rel4_bugfix). In such cases, a warning message appears:
(Dynamic view) If the version being checked out is a derived object (DO version), checkout attempts to winkin the DO to your view. If it cannot perform the winkin, it copies the DO's data instead. A winkin cannot be performed if you use the –out option to specify a destination in another VOB, or in a non-VOB location, such as /tmp.
For more information about the behavior of checked-out DO versions, see Building Software.
If the config spec specifies a version using a rule with a –mkbranch branch-type clause (see also config_spec), checkout works as follows:
Except for some extra messages, the behavior is no different from an ordinary checkout. The checked-out version has the expected contents, because version 0 on the new branch has the same contents as the version at the branch point.
Note: (MultiSite sites) If the VOB is replicated, the current replica must master all the branch types specified in your config spec. Otherwise, auto-make-branch fails.
A config spec can include a cascade of auto-make-branch rules, causing checkout to create multiple branching levels at once. checkout keeps performing auto-make-branch until version 0 on the newly created branch is not selected by a rule with a –mkbranch clause. For example:
element * CHECKEDOUT
element * .../br2/LATEST
element * .../br1/LATEST -mkbranch br2
element * MYLABEL -mkbranch br1
element * /main/LATEST
If you check out an element in a view that currently selects the version labeled MYLABEL:
Any checked-out file can be read, edited, and deleted like any ordinary file.
You have write permission on a checked-out file only if you have write permission on the set view's view storage directory. If you have write permission on the view storage directory for the view you are using, you have write permission on a checked-out file in that view.
The initial permissions on the checked-out file are determined by this algorithm:
You can change the permissions of the checked-out file with the standard UNIX chmod(1) command or by changing the Windows file properties, but you must use the protect command to change the permissions of the element itself.
There may be no object in the view located at the pathname of the checked-out version. This can happen if any of these conditions are true:
An OS-level listing command does not show the missing file, but the cleartool ls command displays the pathname of the checked-out version with the notation checked out but removed.
You must have one of the following identities:
Additional restrictions on UNIX:
With –nmaster, checks out the branch even if the current replica does not master the branch. Do not use this option if you cannot merge versions of the element.
For a discussion of how new versions are created from reserved and unreserved checkouts, see the checkin reference page.
Exception: (Dynamic views) If the version being checked out is a derived object, it is winked in to the view.
checkout creates a copy of each checked-out version and names it pname.
The UNIX examples in this section are written for use in csh. If you use another shell, you may need to use different quoting and escaping conventions.
The Windows examples that include wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you may need to change the wildcards and quoting to make your command interpreter process the command appropriately.
In cleartool single-command mode, cmd-context represents the UNIX shell or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.
checkin, config_spec, ln, lscheckout, merge, mkbranch, mkdir, mkelem, mv, profile_ccase, protect, reqmaster, reserve, rmname, setactivity, uncheckout, unreserve
Copyright© 2003 Rational Software. All Rights Reserved.