IBM Support

About the ClearCase Automation Library (CAL)

Technote (FAQ)


Where are the help files for the IBM Rational ClearCase Automation Library (CAL)?



Documentation on the Microsoft® Windows® COM API called ClearCase Automation Library (CAL) is located (by default):

Note: Depending on the version of ClearCase used, you may find an html (htm) file [cc_cal.htm] or a compiled help module (chm) file [cc_cal.chm] in the bin directory of your ClearCase installation.

Note: This is the only documentation available on CAL.

What is CAL (ClearCase Automation Library)?

The ClearCase Automation Library (CAL) (referred to as CAL) provides a set of COM interfaces to ClearCase on the Windows 32-bit platforms. These interfaces are intended both as an integration platform and also as an API that can be used to extend or customize ClearCase. CAL can also be used to develop stand alone applications, write scripts, or embed macros in other applications that interact with ClearCase on some level.

What version of ClearCase is supported with CAL?

Originally introduced in ClearCase 4.0, CAL is supported only on the currently supported ClearCase releases (refer to Rational product lifecycle dates).

Which code languages does CAL support?
  1. Visual Basic 5.0 or later Note: In a Visual Basic Project, from the Project menu choose References, and be sure to check the check box for ClearCase Automation Library 4.0
  2. Visual C++ or later 5.0 or later
  3. Win32 Perl(COM-Enabled) Note: CCPerl is not supported
  4. Java Note: JavaScript is not supported with CAL. (Java is supported via the CM API)
  5. Windows Scripting Host(VBScript)

What COM components make up CAL?

As with most COM interfaces, the typical pieces are:


There are only two (2) top-level CAL objects that can be used to execute a cleartool subcommand:

  1. ClearCase.Application object (which is rich with numerous interfaces, methods and properties)
  2. ClearCase.Cleartool object (which only has one method CMDEXE).

Note: The CAL object and interfaces are named to be descriptive of the underlying data they are to represent, for example ICCElement is an interface to ClearCase elements and ICCAttributeType is an interface to ClearCase attribute types.

Is CAL a DCOM interface?

CAL is not a DCOM interface, in other words CAL runs in-process with the client code.

Once you "GET" a ClearCase.Application object programmatically, do you need to keep getting the object in CAL?

Once the ClearCase.Application object is obtained, it can be used to get other objects
without having to create them again. CAL ensures as best it can that CAL objects stay synchronized with the underlying ClearCase data, refreshing as necessary when invoking properties and methods. However, the CAL objects can become invalid if someone deletes the underlying ClearCase data while a reference is still held by the CAL object.

What limitations does CAL have?

CAL does not provide access to all ClearCase functionality.

For example, with CAL:

CAL cannot create VOBs.
CAL cannot access build capabilities.
CAL cannot access view profiles.
CAL cannot get properties or perform operations on symbolic links or derived objects.
CAL cannot access most UCM objects in this version of CAL

Note: ClearCase 4.1 and later allows access to more UCM objects.
CAL does not allow someone to perform operations that are not permitted from cleartool or through the ClearCase graphical user interfaces or applets.

How does CAL implement "Error Handling"?

CAL uses standard COM error handling and standard automation errors. For a good discussion of COM error handling from Visual Basic and Visual C++, consult Microsoft Knowledge base article Q186063.

Examples of CAL

Additional examples of sample CAL code:


Reminder: The Win32::OLE module is required. This module is furnished in standard with the free ActiveStates Perl for Windows distribution. After installing this module, normal COM interface can be used with the Perl Object Oriented programming way.

Bellow is a simple example to demonstrate the way to do it. A cleartool object is created, used to get a list of VOB and print this list on the screen.

use Win32::OLE;

my $cal_ct = Win32::OLE->new('ClearCase.Cleartool')
or die "Could not create the ClearTool object\n";

my $cclsvob = $cal_ct->CmdExec('lsvob');

print "Here is the return of lsvob using the CAL interface in Perl:\n$cclsvob";

Visual Basic:
  1. Get a CAL object representing a ClearCase version (M:\view\vob\file@@\main\3), create the ClearCase.Application object, and then get the version from the Application object.

    Dim CC as New  ClearCase.Application
    Dim Ver as CCVersion
    Set Ver = CC.Version("M:\view\vob\file@@\main\3")

    Note that the example uses an extended path to refer to the version. This is not a requirement. The same ClearCase contexts that work for cleartool operations or in GUI applications work in CAL as well.

    For example, if the code were running from the directory M:\view\VOB, and the intention was to choose the version selected by the view, the example could have been coded as

    Set Ver = cc.Version("file")

    After execution Ver holds a CAL CCVersion object representing M:\view\VOB\file@@\main\3.

    Now Ver can be used to query properties of the version.

    For example, to print the version number of the version, use

    MsgBox "Version Number " & Ver.VersionNumber

  2. Create a pop-up of available views on a local host in VB:

    Here is an example of using CAL to connect to the ClearTool object and issue a lsview -host; capture the output of the lsview in an array and then populate a list box with the values.

    ' Connect to the top-level ClearTool object
    Dim ClearTool As New ClearCase.Cleartool
    On Error Resume Next
    ' Issue a cleartool command using the IClearTool's default property (CmdExec)
    MsgBox "Output from CmdExec:" & vbCrLf & ClearTool("lsview -host <host name>")
    If Err.Number <> 0 Then
    MsgBox "ClearTool returned error: " & Err.Description
    Err.Raise Err.Number
    End If

  3. Add an existing file to source control.

    Note: This works on view private files that exist

    'Define a new cleartool

    Dim CC As New ClearCase.Cleartool
    'For the return code
    Dim CT_error As String
    'Check out the directory to be modified
    CT_error = CC.CmdExec("co -nc Z:\VOB_tag\dir1\dir2")
    ' Add element to source control
    CT_error = CC.CmdExec("mkelem -nc -ci Z:\VOB_tag\dir1\dir2\file.txt")    
    'check in the directory
    CT_error = CC.CmdExec("ci -nc Z:\VOB_tag\dir1\dir2")

    Note: The object used is of 'cleartool' type. This means that the command to run is sent to cleartool. In this example all path- and file names are hard-coded. (No errors are trapped to keep the example as small as possible).

  4. Applying a pre-existing attribute to a branch type

    The following example applies an existing attribute to the predefined "main" branch type.

    Tip: The key is to get the attribute type from the ClearCase VOB using the AttributeType() property.

    ' Connect to the top-level ClearCase application object
    Dim CC As New  ClearCase.Application
    Dim VOB As CCVOB

    ' Get a VOB from the top-level ClearCase application object
    Set VOB = CC.VOB("\TestVOB1")

    Dim AtType As CCAttributeType
    Dim Branch As CCBranchType

    'Get an existing Attribute type. This attribute type MUST exist.
    Set AtType = VOB.AttributeType("FooBar")

    'Get an existing branch type, note lack of leading backslash
    Set Branch = VOB.BranchType("main")

    'Apply the attribute.
    AtType.Apply Branch, , "Test", True

Related information

CAL and Numeric Error Return Codes
Request for support with C# in CAL
About Win32::OLE errors and CAL
Article on Rational Java-COM Bridge (RJCB)
Java-COM bridge download and sample
Using Perl with CAL

Cross reference information
Segment Product Component Platform Version Edition
Software Development Rational ClearCase ClearCase Automation Library (CAL)

Document information

More support for: Rational ClearCase
ClearCase Automation Library (CAL)

Software version: 7.0, 7.0.1, 7.1, 7.1.1, 7.1.2

Operating system(s): Windows

Reference #: 1123249

Modified date: 28 February 2011

Translate this page: