The Rational® ClearCase® Automation Library is a COM interface you can use to access and manipulate Rational ClearCase data on platforms that run Windows. You can use CAL to write scripts, stand-alone programs, or macros embedded in other applications. The usual Rational ClearCase license checks apply to applications using CAL.
There is no need to register the CAL interfaces because they are automatically registered when Rational ClearCase is installed.
To use CAL, you should have an understanding of Rational ClearCase concepts and operations.
As in any COM interface, the main building blocks of CAL are objects, interfaces, methods, and properties.
At the highest level, CAL is divided into various objects. Some CAL objects are representations of underlying Rational ClearCase data; for example, the CCVersion object represents a Rational ClearCase version. Other CAL objects are control objects, which do not directly represent the underlying Rational ClearCase data, but manage it. For example, the CCVersions collection class manages a collection of CCVersion objects, the CCCheckedOutFileQuery object lets you build up a query for finding checked-out files, and the TriggerTypeBuilder object lets you construct parameters for creating a trigger type object.
In general, a CAL object has the same name as in Rational ClearCase terminology, but prefixed with the letters CC. For example, in CAL, the CCElement object represents a Rational ClearCase element.
An object can support multiple interfaces. For example, the CCVersion object supports the ICCVersion interface for version-specific information and the ICCFile interface for file system-specific information. Also, more than one object can support the same interface; for example, the CCVersion and CCElement objects both support the ICCFile interface because both interfaces represent file system objects.
Each CAL object has a primary interface, and may have other interfaces. In CAL, multiple interfaces are supported only through inheritance; in other words, if you know the inheritance hierarchy, then you know which interfaces each object supports. (This is not true of all COM interfaces, but it is true of all CAL interfaces).
The distinction between objects and interfaces is blurred for Visual Basic programmers. VB programmers don't ever see the interfaces and refer to the objects only.
The primary interface for a CAL object has the same name as the CAL object, but prefixed with an "I" for interface. For example, the CCLabel object has an ICCLabel interface and the CCVersion object has an ICCVersion interface.
Each interface supports a number of properties and methods that allow you to interact with the object.
A property allows you to get and (sometimes) set pieces of information about the object. For example, the Name property of ICCLabelType allows you to get the name of a label type object.
A method invokes some action on the object. For example, CheckOut is a method on the CCVersion object that allows you to check out a version.
Default properties for the CAL interfaces are listed in the tables at the beginning of each interface description. Visual Basic programmers referring to a CAL object can omit the property name if they want to access the default property. For example, the IClearTool default property is CmdExec, so if you use the code Dim CT As New ClearCase.ClearTool, then invoking CT("pwv") is equivalent to invoking CT.CmdExec("pwv").
You can browse the CAL library using Microsoft Visual Basic (5.0 or later).
Help string text is displayed on the bottom panel of the Visual Basic Object Browser. In Visual Basic 6.0, when you click F1 on any class or any member of that class, the documentation for that class or class member is displayed.
There are two starting points for interacting with CAL: the Application object and the ClearTool object. The Application object provides most of the CAL API. Most applications using CAL will start there. The ClearTool object contains just one method, CmdExec, which is invoked to execute a cleartool subcommand string. The ClearTool object is provided to ensure that any capabilities in cleartool not covered by the Application object are accessible programmatically.
ClearCase.Application and ClearCase.ClearTool are the only two objects in CAL that are externally creatable (and are consequently the only two objects that do not have the "CC" naming prefix).
In COM interfaces, an externally creatable object is one the client can create directly. In Visual Basic, the New keyword is used to create the object; in C++, a call to CoCreateInstance() creates the object; and in scripting languages, CreateObject() creates the object.
Most CAL objects are not externally creatable. An object that is not externally createable must be created by another object. This example shows how to use both kinds of objects.
Visual C++ programmers must access objects through the appropriate interfaces. The interfaces for the externally createable objects are IClearCase (for ClearCase.Application) and IClearTool (for ClearCase.ClearTool).
The syntactical notation used to refer to the CAL interfaces varies with the language you use. Even the same language can have multiple bindings defined. The reference pages for each interface provide the syntax for both Visual C++ and Visual Basic.
In Visual C++, the #import directive causes the compiler to generate two kinds of C++ wrapper functions from the information in the CAL type library:
The Visual C++ syntax given is for the high-level wrappers.
In addition, the type library header defines a "smart pointer" type (for example, ICCVersionPtr) for each CAL interface. These pointers handle reference counting and free themselves automatically when they go out of scope. You can find the declarations in the generated type library header file cauto.tlh.
Because CAL is a dual interface (supporting both a "dispatch" interface and a "vtbl" interface), you can access the properties using the methods of IDispatch (for example, GetIDsOfNames and Invoke) as an alternative to using the vtbl-based wrapper classes.
The Visual C++ wrapper classes for BSTR (_bstr_t) and VARIANT (_variant_t) are shown in the syntax. Memory for all BSTR properties is allocated by CAL, but must be freed by the caller with a call to SysFreeString.
Wherever the term array is used, for C++ this must be a SAFEARRAY. As with strings, the memory allocated by CAL for a SAFEARRAY must be freed by the caller. The function to free a SAFEARRAY is SafeArrayDestroy.
Once you get the ClearCase.Application object, you can continue to use it to get other objects without having to "get" it again. CAL ensures as best it can that CAL objects stay synchronized with the underlying Rational ClearCase data, refreshing as necessary when you invoke properties and methods. However, the CAL objects can become invalid if someone deletes the underlying Rational ClearCase data while you still hold the CAL object.
Parameters marked as "Optional" are optional for both Visual C++ and Visual Basic programmers. However, default values on parameters have no effect on the way you call them from Visual C++. Visual Basic programmers can omit these parameters in a call; C++ programmers cannot. C++ programmers can look at this documentation or the browser to get an idea of what to pass to get the default behavior, but there is no automatic way for this to happen.
The CAL type library contains enumeration constants that are not available in symbolic form to users of some scripting languages (for example, VBScript). However, we encourage the use of defined constants for the enumeration values, rather than using the numeric values directly. For example, in VBSscript instead of coding
CheckOut(1)
write
const ccReserved=1 CheckOut(ccReserved)
These constants appear in the OLE/COM object browser and you can cut and paste them from there. The enumeration constants are available to VB and VC++ programmers in symbolic form.
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 MSDN library article number Q186063.
This example shows how to obtain Rational ClearCase version information using CAL.
In your Visual Basic Project, from the Project menu choose References, and be sure to check the check box for ClearCase Automation Library x.x.
To get a CAL object representing Rational ClearCase version M:\view\vob\file@@\main\3, you 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")
The example uses an extended path to refer to the version. This is not a requirement. The same Rational ClearCase contexts that work for cleartool operations or in GUI applications also work in CAL. 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 a statement in the following form:
MsgBox "Version Number " & Ver.VersionNumber
CAL does not provide access to all Rational ClearCase functionality. For example, with CAL:
In addition, CAL does not allow you to perform operations that are not permitted from cleartool or through the Rational ClearCase GUIs.
CAL runs as an in-process COM server; it is not a DCOM application.