IPnom Home • Manuals • ClearCase

 Rational ClearCase Commands Reference

ClearCase Stuff:ClearCase LinksClearCase BooksClearCase Commands ReferenceClearCase ForumsClearCase News
Keyword Live Search (10 results max):
 Type in part of a ClearCase command in the search box.
Commands Index:


ClearCase and ClearCase LT Encapsulation for SoftBench


ProductCommand type
ClearCase LTcommand



Invoked as needed by SoftBench Broadcast Message Server


The ClearCase and ClearCase LT Encapsulation for SoftBench enables integration of ClearCase and ClearCase LT with all of the SoftBench tools on the HP-UX 10.X, HP-UX 11, and Solaris platforms. ClearCase and ClearCase LT service and broadcast all the messages prescribed for CM systems in the document CASE Communique: Configuration Management Operation Specifications from the historical standard.

ClearCase and ClearCase LT add a menu to the SoftBench Development Manager, providing users with a familiar interface to the most important version control and configuration management functions. Users can customize the SoftBench environment to add items to this menu, accessing more sophisticated features. In SoftBench V6, this menu is made available during SoftBench installation; it is also accessible from the main SoftBench window.

Users can configure the SoftBench Builder to use the ClearCase build tool, clearmake. All other SoftBench tools (debugger, browser, static analyzer, and so on) work within ClearCase and ClearCase LT environments by using the transparent file access capability.

ClearCase and ClearCase LT can broadcast SoftBench messages whenever they perform a CM operation, no matter how that operation was requested: from the SoftBench or ClearCase or ClearCase LT graphical user interfaces, from the ClearCase or ClearCase LT command line interface, from the ClearCase API, from other SoftBench tools, and so on. This flexibility accommodates a variety of working styles without sacrificing tool integration.

SoftBench tools communicate with ClearCase and ClearCase LT through the SoftBench Broadcast Message Server (BMS), and two server processes:

  • clearencap_sb, the ClearCase and ClearCase LT encapsulator for SoftBench
  • sb_nf_server, the ClearCase and ClearCase LT notice forwarder for SoftBench

Note: The commands clearencap_sb –ver and sb_nf_server –ver print the version of SoftBench that is installed.

After SoftBench has been configured to work with ClearCase or ClearCase LT, certain SoftBench commands invoke CM operations. When a SoftBench tool makes a configuration management request, such as VERSION-CHECK-OUT, the BMS receives the message and passes it on to the ClearCase/ClearCase LT encapsulator. (The BMS starts the encapsulator process if it is not already running.) The encapsulator evaluates the message and invokes the appropriate tool, such as cleartool checkout.

  • If the operation succeeds, the encapsulator returns a message to the BMS.
  • If the operation fails (that is, the tool exits with a nonzero exit status), the encapsulator returns a failure message to the BMS.

In both cases, the BMS passes the final status message back to the SoftBench tool.

You can have ClearCase/ClearCase LT tools send the success messages described above, even if the operation was not initiated by a SoftBench tool. To do so:

  • Verify that the tool and the BMS have both set the environment variable DISPLAY to the same value.
  • Run the tool in an environment with CLEARCASE_MSG_PROTO set to SoftBench.

An error occurs in a ClearCase/ClearCase LT tool that has its CLEARCASE_MSG_PROTO variable set correctly, but not its DISPLAY variable.

Note: HP VUE users must add the $CLEARCASEHOME/bin directory to their search path by adding a line like the following to the file /usr/lib/X11/vue/Vuelogin/Xconfig:

Vuelogin*userPath: /usr/bin/X11:/bin:/usr/bin:/etc:/usr/contrib/bin:ccase-home-dir/bin:/usr/lib:/usr/lib/acct

Vuelogin*userPath: /usr/bin/X11:/bin:/usr/bin:/etc:/usr/contrib/bin:ccase-home-dir/bin:/usr/lib:/usr/lib/acct

Without this information, the encapsulator cannot find ClearCase/ClearCase LT utilities.


Text output produced by encapsulator operations can be placed in a file (results_file in the pseudo-syntax summaries in the next section). If a result file is not specified, output is directed to the encapsulator's dedicated transcript pad. The pad is created and appears on-screen the first time output is directed to it. The transcript pad window has a single menu, with these choices:

clear pad Removes the current contents of the pad.
cancel Interrupts the current encapsulator operation.
quit Removes the transcript pad window from the screen. The transcript pad process continues to run and to collect output text. The window reappears on the next operation that sends text to the pad, with the new output appended to the existing contents of the pad.


The clearencap_sb program handles the SoftBench messages for the CM class listed in the pseudo-code syntax summary below. These conventions apply:

  • The context parameter is replaced by the pathname currently selected in the SoftBench tool.
  • Virtually all other parameters are optional. A default action is taken if no value is supplied for a given parameter, or if it has the string value "-" (except with comments, described in the following item).
  • Many messages take optional comments. If a comment is not supplied, clearencap_sb prompts the user for a comment before acting on the message.

    Note: The comment string “-” does not indicate a default action; it is a one-character comment.

  • Braces ( { ... } ) indicate that a nondefault value from the message is substituted at that location.
  • DEFAULT indicates that the user either did not supply the parameter or specified the string “-”.

Standard Messages

The following messages are specified in the historical standard:

VERSION-CHECK-IN context rev options keyword comment
if (keyword == "CO-LOCK")
     cleartool checkin  -c comment options context
     cleartool checkout -nc context  
else if (keyword ==  "CANCEL")
     cleartool uncheckout { options | -keep } context   
     cleartool checkin -c comment options context

VERSION-CHECK-OUT context rev options keyword comment  
if  (keyword == "CO")
     if (context{@@rev}  not in current view)
     cleartool checkout -c comment options context{@@rev} 

VERSION-COMPARE-REVS context rev1 rev2 results_file  
if (results_file !=  DEFAULT && results_file != "*")
     if (rev1 ==  "-pred") 
            cleartool diff -pred context{@@rev2}  > results_file
            cleartool diff context{@@rev1} context{@@rev2} > results_file
     if (rev1 == "-pred")
            cleartool diff -graphical  -pred context{@@rev2}
            cleartool diff -graphical context{@@rev1} context{@@rev2}

VERSION-INITIALIZE context options comment   
cleartool mkelem -c comment options context

VERSION-LIST-DIR context results_file keyword options  
if (keyword ==  "RECURSIVE")
     cleartool ls -r options context {  > results_file }
     cleartool ls options  context { > results_file } 

Note: If results_file is DEFAULT, output is sent to the transcript pad.

VERSION-SET-MASTER context configuration options 
if (configuration == DEFAULT)
     cleartool setcs -default options  
else if (configuration  == "*")
     cleartool edcs 
     cleartool setcs options configuration

VERSION-SHOW-HISTORY context results_file options 
cleartool lshistory options context {  > results_file } 

Note: If results_file is DEFAULT, output is sent to the transcript pad.

VERSION-UPDATE-DIR context keyword options  
(no action needed with ClearCase/ClearCase LT — always succeeds)

Nonstandard Messages

The following messages are ClearCase and ClearCase LT extensions, not specified in the historical standard.

VERSION-MAKE-DIR context keyword options comment  
if (keyword ==  "QUERY")
     prompt for directory-name   
cleartool mkdir -c comment options context[/directory-name]

VERSION-MAKE-BRANCH context branch-type-name rev options comment   
cleartool mkbranch {-version rev} -c comment options branch-type-name context 

DERIVED-CAT-CONFIG-REC context do-extension results_file options  
cleartool  catcr options context{@@do-extension}  { > results_file }

Note: If results_file is DEFAULT, output is sent to the transcript pad.

DERIVED-DIFF-CONFIG-REC context do-extension1 do-extension2 results_file options   
cleartool diffcr options context{@@do-extension1}
    context{@@do-extension2}  { > results_file } 

Note: If results_file is DEFAULT, output is sent to the transcript pad.

VERSION-MAKE-ATTRIBUTE context options attribute-type attribute-value comment   
if (options include "-default")
    cleartool mkattr -c comment options -default attribute-type  context
    cleartool mkattr -c comment options attribute-type attribute-value context

VERSION-GET-ATTRIBUTE context options attribute-type results_file  
cleartool describe -short options -aattr attribute-type  context { > results_file } 

Note: If results_file is DEFAULT, output is sent to the transcript pad.

VERSION-MAKE-LABEL context options label-type comment  
cleartool mklabel -c comment options label-type context

START-VIEW context view_tag   
cleartool startview view_tag

VERSION-DESCRIBE context options results_file  
cleartool describe options context { > results_file } 

Note: If results_file is DEFAULT, output is sent to the transcript pad.

VERSION-LIST-CHECKOUTS context options results_file
cleartool lscheckout options context {  > results_file }

Note: If results_file is DEFAULT, output is sent to the transcript pad.

VERSION-SHOW-VTREE context options results_file  
if (results_file = DEFAULT )
    cleartool lsvtree  -graphical options context   
    cleartool lsvtree options context > results_file

VERSION-COMPARE-FILES context file2 result-file  
if (result-file != DEFAULT && result-file  != "*")
    cleartool diff context file2 > result-file   
    cleartool diff -graphical context file2

Note: If file2 is not supplied as part of the message, or is either or *, then clearencap_sb prompts the user for a file name (using the Motif file-selection dialog box).

VERSION-MERGE-REVS context  options rev  
cleartool merge -graphical options –to context –version rev

DO-COMMAND context keyword command  
if (command includes the string “<context>”
    first substitute context for this string,
    then execute the resulting command 
    cleartool command context

Note: If the keyword is DISPLAY, output is sent to the transcript pad.


/var/adm/rational/clearcase/log/ti_server_log Error log for notice forwarder


Release Notes for your product.



ClearCase Links • ClearCase Books • ClearCase Commands Reference • ClearCase Forums • ClearCase News