This chapter contains basic background and usage fundamentals for the ClearCase graphical interface.
The xclearcase command line can include any of the numerous X(1) command options, but examples in this chapter are all derived from an interface invoked with:
% xclearcase & |
You can start xclearcase with or without a view context. If you are not in a view, xclearcase first prompts you for a view-tag. Figure 3-1 shows a view-tag browser.
The view-tag browser lists all registered views. You can set the current view to any on the list, whether or not it is currently “active.” (An active view already has an entry in the viewroot directory, /view.)
Click leftMouse over a view-tag to select (highlight) it, and press the Ok button.
Figure 3-2 shows the file browser, which appears once you have an active view. Think of the file browser as your “home base.” A file browser displays the current directory name and, below it, the directory contents.
Like all xclearcase browsers, a file browser includes a variety of menus — toolbar menu, pop-up menu, and pull-down menus — to do the real work. Each menu item launches an operating system command script, which typically includes some ClearCase-specific enhancements.
The file browser in Figure 3-2 is displaying the contents of a directory under a VOB mount point. To change to a VOB directory, type the desired pathname into the directory input box, and press <Return>.
 | Note: If the graphical interface has been customized at your site, your screen display may vary. See Chapter 18, “Customizing the Graphical Interface,” for more information. |
With the main file browser displayed, you are ready to work. Notice that only some of the toolbar and pull-down menu items are enabled, while others are “grayed out.” To familiarize yourself with the workings of a browser:
Scan through the various pull-down menus.
Display “pop-up help” for any enabled toolbar item by moving to it and clicking rightMouse. For pull-down menu items, click on the menu to “post” it, and press rightMouse on the desired item.
Try selecting various files, and combinations of files, and watch how the set of enabled operations changes with your selections.
Post the pop-up menu by clicking rightMouse in the browser.
Use the Admin and Metadata menus to look at other browsers.
Here are brief descriptions for the default file browser toolbar items (see also each item's “pop-up help”):
Here are brief descriptions for the default file browser toolbar items (see also each item's “pop-up help”):
Toggle Graphic Mode — Toggle between iconic and textual display modes for directory listings. See Figure 3-3.
Toggle Keyboard Input Mode — Enable or disable the file browser's keyboard input box. See “Keyboard Input” . See Figure 3-4.
Checkin — Checkin the checked-out versions of the selected elements. See Figure 3-5.
Checkout — For selected elements, checkout (reserved) the versions selected by your current view. See Figure 3-6.
Uncheckout — Uncheckout one or more checked-out versions. See Figure 3-7.
Describe — Describe each selected object (in a read-only text output window). See Figure 3-8.
Vtree — Start a vtree (version tree) browser on the selected element. See Figure 3-9.
Diff — Diff the selected version against its predecessor version. See Figure 3-10.
Merge — Merge from another version (which is prompted for) to the selected version. See Figure 3-11.
Clearmake: default — Run clearmake on the default target (using Makefile or makefile in current directory). See Figure 3-12.
Shell — Start up a shell process in a separate window. See Figure 3-13.
The basic usage model involves a simple cycle:
Select data to operate on (one or more file elements, for example). Your selection enables some subset of the available toolbar buttons and menu commands.
Invoke an enabled menu item, either on the toolbar or from a pull-down menu.
If necessary, respond to interactive prompts (by the various kinds of browsers) for more information.
At any given time, some items are active, or enabled, while others are “grayed out” (or insensitive). Many operations are defined to remain insensitive until you select one or more data objects relevant to the operation. For example, the checkout button is not enabled until you preselect at least one unchecked-out element.
While xclearcase is displaying a browser prompt, you can start another menu command. When you have completed the “interrupt”, the original prompt is still active, waiting for input. When nesting commands, you cannot cancel a browser started to collect input for a previous command. The command nesting level limit is ten.
Table 3-1 covers basic pointer actions and keystrokes for all file browsers. (In general, these actions apply to the other kinds of browsers, as well.).
Table 3-1. File Browser Pointer Actions and Keystrokes
Function | Pointer Action/Keystroke |
|---|---|
Basic |
|
Select item | Click leftMouse |
Select region | Drag leftMouse |
Extend-select (discontiguous) | control-leftMouse |
Extend-select (range) (for textual, not graphical, dir list) | shift-leftMouse |
Display “pop-up help” for an enabled menu item | Toolbar: rightMouse on button Other menus: click leftMouse to post menu, then rightMouse over item |
Change working directory | doubleClick
on directory icon, or |
List directory history | Press button. See Figure 3-14 |
Display pop-up menu | rightMouse in browser |
Exit xclearcase | Exit option on File menu |
|
|
|
|
Menu Navigation |
|
Post (“pin up”) a pull-down menu; | Click leftMouse on menu; |
Cycle through posted menu options | upArrow/downArrow |
Post submenu | mnemonicChar |
Cycle through menus left-to-right | rightArrow/leftArrow |
Invoke highlighted menu item | return |
Each browser has an optional keyboard input box as shown in Figure 3-15, which lets you type in data selections directly. Some commands enable it automatically, but you can also enable it manually with the toolbar's Keyboard input button.
You can use the keyboard input box to type in one or more items. For browsers that accept pathnames, most commands allow wildcard patterns, including *, ?, and [] (but not {}). Any selection you make by pointing replaces the current contents of the input box. The items that appear in the keyboard input box constitute the current selection. Select a menu item to operate on them.
| Note: The keyboard input box sidesteps many built-in protections against incorrect input to buttons and menu commands. When the keyboard input box is enabled, all menu items become active, whether or not they are applicable. Typed-in data is not validated until the command executes. (The number of typed-in data items is continually evaluated; if this number violates the conditions required to enable a menu item, the item becomes insensitive.) |
The File menu and the menu items in Table 3-2 are common to all browsers.
Option | Brief Description |
|---|---|
Show transcript | Display the transcript pad. By default, the transcript pad pops up automatically only to display error and warning messages. It stays up until dismissed. |
Update browsers | Manually update all browser displays. |
New file browser | Start a new file browser. |
Close window | Close current browser. |
Figure 3-16 illustrates the transcript pad, a scrolling text window that functions as xclearcase's “standard output” and “standard error” devices.
As you work in the graphical interface, the transcript pad receives error, status, and warning messages, as well as command output from menu operations. By default, the transcript pad pops up automatically only in response to error and status messages. You can manually post the transcript pad at any time with the menu item File -> Show transcript icon.
Depending on how a menu operation is defined, its text output can appear in a variety of places, including:
the transcript pad
a list browser
a read-only display window
a text editor
Although a menu operation's primary output may be redirected from the transcript pad, a Starting - “operationName” message appears in the transcript pad for each operation you execute.
The menu options for the transcript pad are detailed in Table 3-3.
Table 3-3. Transcript Menu Options
Option | Brief Description |
|---|---|
Clear transcript | Clear all text from the transcript pad. |
Scroll to Bottom | When set, the transcript pad automatically scrolls to the bottom to display new output as it arrives. Unset this toggle button when you are examining a particular section of text and don't want to be interrupted by new output. |
The xclearcase interface includes numerous browsers. File, VOB, viewtag, vtree, type, pool, and username browsers let you query and select the data objects used by ClearCase. List and string browsers facilitate string data I/O. This section provides a brief introduction to each kind of browser.
Browser interaction follows two distinct patterns:
You explicitly start browsers ( Metadata -> Label -> Label type... or Admin -> Vob..., for example) in order to view or select data objects. Bringing up a file browser with xclearcase also falls into this category. A browser started in this manner stays up until you close it
Other browsers come and go automatically as you work. When executing the scripts attached to menu items, xclearcase frequently starts browsers to prompt for additional data, and terminates them after you Ok or Cancel the prompt. For example, a button labeled Prepare vob report might start numerous browsers (with interactive prompts) to collect information about the various data objects in a particular VOB.
At any one time, your screen display may include multiple instances of both “long-lived” and “transient” browsers. If xclearcase requires data from you, the same prompt may appear in multiple browsers, if more than one is capable of satisfying the prompt.
In general, each class of browser exists to handle a particular type of data. The following Table 3-4 shows the tight correspondence between browsers and xclearcase data types.
Table 3-4. Browsers and Data Types
Data type | Browsers that Display or |
|---|---|
PNAME | File/Vtree |
HYPERLINK | Vtree |
LIST | List |
ATTYPE/BRTYPE/ELTYPE/ | Attype/Brtype/Eltype/ |
POOL | Pool |
STRING | String |
USERNAME | Username |
VIEWTAG | View-tag |
VOBTAG | VOB-tag |
See the section “File Browser”.
Each of the six type object browsers operates on the corresponding class of type object. You can start type object browsers explicitly from the file browser's Admin and Metatype menus, and with the Version -> Branch -> Branch type... menu item.
Figure 3-17 shows a label type browser.
The type object browsers share a common toolbar:
Toggle Keyboard Input Mode — Enable or disable the file browser's keyboard input box. See Figure 3-18.
Toggle Unlocked Object Display — Enable or disable the display of unlocked type objects. See Figure 3-19.
Toggle Locked Object Display — Enable or disable the display of locked type objects. See Figure 3-20
Toggle Obsolete Object Display — Enable or disable the display of obsolete type objects. See Figure 3-21.
Describe — Describe the selected object (in a read-only text output window). See Figure 3-22.
List browsers are not started directly. You encounter a list browser only when a menu command redirects output to one and prompts you to select data from it. Figure 3-23 shows a sample list browser — the one Help -> Manual page... uses to prompt you for a topic.
A list browser prompts you to select one or more items (entire lines only, no partial lines or substrings). Press Ok to submit the selection, or Cancel to cancel the prompt (and, therefore, the entire command operation). You cannot edit the contents of a list browser.
For comparison with list browsers, Figure 3-24 shows a sample text output window, and Figure 3-25 shows a terminal emulation window. Neither prompts for, or accepts, user input; they are display-only devices.
The text output window was generated by the Describe button and the terminal window by menu item Report -> Find query -> Whole VOB -> Versions with Label...
You can cancel output to a terminal emulation window with <Ctrl-C>.
Admin -> Pool...
A pool browser lists the storage pools and their locations for any registered VOB. Click the down-arrow next to the text input box to display a list of currently registered VOBs.
String browsers exist only to prompt for text strings and, therefore, are more like simple dialog boxes than browsers Figure 3-26 shows the text string browser that results when you choose Help -> Apropos...
A variety of menu command use string browsers to prompt for simple text string arguments (comments, for example) or for other data strings — any data that cannot be captured by the more specific data type browsers.
Admin -> Vob...
Browse and select VOB-tags. The VOB browser lists the VOB-tags, or mount points, for all registered VOBs.
Admin -> View... Contrast this with the Version -> Set... command, which starts a transient, prompting view-tag browser.
Browse and select view-tags. A viewtag browser lists all registered views. You can set the current view to any on the list, whether or not it is currently “active.” (An active view already has an entry in the viewroot directory, /view.)
You can start a vtree browser with the vtree toolbar button, or from the command line with either the cleartool xlsvtree or xlsvtree commands.
Use vtree browsers to scan version trees and to operate on file and directory versions, branch names, and merge arrows. (On a vtree browser, arrows show merge hyperlinks.) Figure 3-31 shows a sample vtree browser.
Vtree-specific toolbar items:
Toggle Checked-out Version Display — Enable or disable the display of checked-out versions. See Figure 3-27.
Toggle All Versions Display — Enable or disable the display of all versions in the element. If unset, only labeled versions, branch points, and merge endpoints are displayed. See Figure 3-28.
Toggle Merge Arrow Display — Enable or disable the display of merge arrows. See Figure 3-29.
Toggle All Labels Display — Enable or disable the display of all labels on all versions. If unset, up to five labels are display for any one version (followed by “...” if there are more than five). See Figure 3-30.
