IBM® DevOps Code ClearCase Automation Library (CAL)
The DevOps Code ClearCase® Automation Library is a COM interface you can use to access and manipulate DevOps Code 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 DevOps Code ClearCase license checks apply to applications using CAL.
There is no need to register the CAL interfaces because they are automatically registered when DevOps Code ClearCase is installed.
To use CAL, you should have an understanding of DevOps Code ClearCase concepts and operations.
COM overview
As in any COM interface, the main building blocks of CAL are objects, interfaces, methods, and properties.
Objects
At the highest level, CAL is divided into various objects. Some CAL objects are representations of underlying DevOps Code ClearCase data; for example, the CCVersion object represents a DevOps Code ClearCase version. Other CAL objects are control objects, which do not directly represent the underlying DevOps Code 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.
Object naming
In general, a CAL object has the same name as in DevOps Code ClearCase terminology, but prefixed with the letters CC. For example, in CAL, the CCElement object represents a DevOps Code ClearCase element.
Interfaces
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.
Interface naming
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.
Methods and properties
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
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").
Browsing the CAL Library
You can browse the CAL library using Microsoft Visual Basic (5.0 or later).
- 1. Open a Visual Basic project.
- 2. Choose Project >References and select the check box for the ClearCase Automation Libraryx.x
- 3. In Visual Basic, choose View >Object Browser. In the pull-down dialog that preselects <All libraries>, click the drop-down arrow and select ClearCase from the drop-down dialog menu.
- 4. Click any DevOps Code ClearCase Automation Library class; the right pane displays all the members of that class. All the members of inherited interfaces are also displayed by default.
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.
Working with CAL
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).
Syntax
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.
Visual C++ information
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:
- Low-level functions that invoke the CAL methods and properties directly and return an HRESULT
- High-level functions that throw exceptions for errors rather than returning HRESULT
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.
Lifetime of CAL objects
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 DevOps Code ClearCase data, refreshing as necessary when you invoke properties and methods. However, the CAL objects can become invalid if someone deletes the underlying DevOps Code ClearCase data while you still hold the CAL object.
Optional parameters
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.
Enumeration values
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.
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 MSDN library article number Q186063.
Visual Basic example
This example shows how to obtain DevOps Code 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 DevOps Code 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 DevOps Code 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
Limitations to CAL
CAL does not provide access to all DevOps Code ClearCase functionality. For example, with CAL:
- You cannot access build capabilities.
- You cannot access view profiles.
- You can only get properties or perform operations on symbolic links and
derived objects by using IClearTool.
In addition, CAL does not allow you to perform operations that are not permitted from cleartool or through the DevOps Code ClearCase GUIs.
CAL runs as an in-process COM server; it is not a DCOM application.