QUESTION: Scripting - examples and information for Clearcase

ANSWER: Below are some examples of accessing ClearCase via Rose scripting
and more information.

#1 Script to test if file checked out To the current view.
#2 Visual Basic code example
#3 Rose code example
#4 Add ClearCase version number to each diagram
#5 Solution 10629 - ClearCase Automation Library (CAL) FAQ

\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
#1 Script to test if file checked out To the current view.
//////////////////////////////////////////////////////////
1. add test.mdl to Clearcase.
2. check out file (from within Rose).
3. run following code:
'---------------------------------------------------------
Sub Main
      Dim CC As Object
      Dim Ver As Object
      Dim COF As Object

      Viewport.open "Fixes"
      On Error Resume Next
      Set CC = CreateObject("ClearCase.Application")
      If CC Is Nothing Then
          MsgBox "Could not start ClearCase."
          Exit Sub
      End If
      Val1 = "z:\rosetset\test.mdl"
      Ver = CC.Version(Val1)
      Print Ver
      On Error GoTo BADCall
      Set COF = CC.CheckedOutFile(Val1)
      On Error GoTo 0
      If Err.Number <> 0 Then
                Print"Its Not checked out To the current view"
      Else
                Print "It Is checked out To the current view"
      End If
      Set CC = Nothing

      BADCall:
      msgbox "not checked out"
End Sub
'---------------------------------------------------------
4. Code should return "It Is checked out To the current view"
5. right click on test in browser, Undo check out
6. run script
7. Code should now return msgbox "not checked out"

\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
#2 Visual Basic code example
//////////////////////////////////////////////////////////

Sub Main
'If using in Rose... * see next example #3
'Dim CC As New ClearCase.Application
'Dim Ver As CCVersion
'Dim CheckedOutFile As CCCheckedOutFile

'If using in Visual Basic...
Dim CC As object
Dim Ver As object
Dim CheckedOutFile As object

On Error Resume Next

Set CC = CreateObject("ClearCase.Application")
'Return message regarding ability to connect to Clearcase
If CC Is Nothing Then
      MsgBox "NOTHING"
      Exit Sub
Else
      MsgBox "CONNECTED"
End If

'Find the Version of the ClearCase File
Set Ver = CC.Version("\\view\gustaf-pc_localView\ScriptTest\testModel.mdl")
MsgBox "version = " & Ver

'Checkout file
Set CheckedOutFile = Ver.CheckOut(ccReserved, "test checkout")
If Err.Number <> 0 Then
        MsgBox "Checkout Error: " & Err.Description
Else
        MsgBox "Checkout successful"
End If

End Sub

\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
#3 Rose code example
//////////////////////////////////////////////////////////

NOTE above VB example code will fail in Rose even if you change
Dim statements, "Dim Ver As object" to "Dim Ver As CCVersion",
becaused of an undefined constant. This is explained in Solution: 
13748 - Rose scripts cannot access COM/OLE type-library constants.

Here is the above VB example code modified and including Clearcase
constants to run as a Rose script:

Const ccConstraint_None   As Long =   0
Const ccConstraint_PerElement   As Long =   1
Const ccConstraint_PerBranch   As Long =   2
Const ccConstraint_PerVersion   As Long =   3
Const ccKeep   As Long =   0
Const ccRemove   As Long =   1
Const ccScope_Ordinary   As Long =   0
Const ccScope_LocalCopy   As Long =   1
Const ccScope_Global   As Long =   2
Const ccOp_mktype   As Long =   5
Const ccOp_rmtype   As Long =   6
Const ccOp_rntype   As Long =   7
Const ccOp_lock   As Long =   8
Const ccOp_unlock   As Long =   9
Const ccOp_checkout   As Long =   10
Const ccOp_mkelem   As Long =   11
Const ccOp_mkbranch   As Long =   12
Const ccOp_checkin   As Long =   13
Const ccOp_rmelem   As Long =   14
Const ccOp_rmbranch   As Long =   15
Const ccOp_rmver   As Long =   16
Const ccOp_rmname   As Long =   17
Const ccOp_chtype   As Long =   18
Const ccOp_mklabel   As Long =   19
Const ccOp_mkattr   As Long =   20
Const ccOp_mkhlink   As Long =   21
Const ccOp_mktrigger   As Long =   22
Const ccOp_rmlabel   As Long =   23
Const ccOp_rmattr   As Long =   24
Const ccOp_rmhlink   As Long =   25
Const ccOp_rmtrigger   As Long =   26
Const ccOp_uncheckout   As Long =   27
Const ccOp_lnname   As Long =   32
Const ccOp_mkslink   As Long =   33
Const ccOp_reserve   As Long =   37
Const ccOp_unreserve   As Long =   41
Const ccOp_chevent   As Long =   44
Const ccOp_chmaster   As Long =   49
Const ccFiring_PreOp   As Long =   1
Const ccFiring_PostOp   As Long =   2
Const ccKind_Type   As Long =   0
Const ccKind_Element   As Long =   1
Const ccKind_AllElement   As Long =   2
Const ccReserved   As Long =   0
Const ccUnreserved   As Long =   1
Const ccTryReserved   As Long =   2
Const ccVersion_Default   As Long =   0
Const ccVersion_SpecificVersion   As Long =   1
Const ccSelection_Path   As Long =   0
Const ccSelection_SubTreeRoot   As Long =   1
Const ccSelection_Directory   As Long =   2
Const ccSelection_AllInVOB   As Long =   3
Const ccSelection_AllVOBs   As Long =   4
Const ccAction_Exec   As Long =   0
Const ccAction_ExecUNIX   As Long =   1
Const ccAction_ExecWin   As Long =   2
Const ccAction_Mklabel   As Long =   3
Const ccAction_Mkattr   As Long =   4
Const ccAction_MkhlinkTo   As Long =   5
Const ccAction_MkhlinkFrom   As Long =   6
Const ccAll_ElementTypes   As Long =   13
Const ccAll_BranchTypes   As Long =   14
Const ccAll_AttributeTypes   As Long =   15
Const ccAll_HyperlinkTypes   As Long =   16
Const ccAll_TriggerTypes   As Long =   17
Const ccAll_LabelTypes   As Long =   20
Const ccSubset_Both   As Long =   0
Const ccSubset_NotInheritance   As Long =   1
Const ccSubset_NotAttached   As Long =   2

Sub Main

'If using in Rose...
'Dim CC As New ClearCase.Application
'Dim Ver As CCVersion
'Dim CheckedOutFile As CCCheckedOutFile

'If using in Visual Basic...
Dim CC As object
Dim Ver As object
Dim CheckedOutFile As object

On Error Resume Next

Set CC = CreateObject("ClearCase.Application")
'Return message regarding ability to connect to Clearcase
If CC Is Nothing Then
      MsgBox "NOTHING"
      Exit Sub
Else
      MsgBox "CONNECTED"
End If

'Find the Version of the ClearCase File
Set Ver = CC.Version("\\view\gustaf-pc_localView\ScriptTest\testModel.mdl")
MsgBox "version = " & Ver

'Checkout file
Set CheckedOutFile = Ver.CheckOut(ccReserved, "test checkout")
If Err.Number <> 0 Then
        MsgBox "Checkout Error: " & Err.Description
Else
        MsgBox "Checkout successful"
End If

End Sub

\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
#4 Add ClearCase version number to each diagram
//////////////////////////////////////////////////////////

Example script posted to rose_forum:

' Description : Add the version number stored in ClearCase in a text field
' in each diagram on the upper left corner This is done for the model.
' !!!! File must be checked out by hand version number is not 
' exactly extracted. text "Checked out" is also put in the diagrams 
' sub packages' diagram are not yet updated to show version number
' subunits are not treated.

Sub Main
Dim theModel As New Model
Set theModel = RoseApp.CurrentModel

Viewport.Open
Viewport.Clear

Dim theModelFileName As String
theModelFileName = RoseApp.CurrentModel.GetFileName
Dim unitFileName As String
Dim unitDirectoryName As String
Dim appRunning As Boolean
Dim appName As String
Dim id As Variant

'bat command file is constructed
'the result of cleartool ls -s filename is redirected to a file result.dat
Open "AskVersionCCCmd.bat" For Output Access Write As #2
Dim command As String
command = "cleartool ls " & theModelFileName & "> result.dat"
Print #2, command
Close #2

'execute bat command file
id = Shell( "AskVersionCCCmd.bat", ebNormalFocus )

' loop : to be sure command is executed
appRunning = True
            While appRunning
                Sleep 2000
                appName = AppFind$(id)
                If appName = "" Then
                      appRunning = False
                End If
            Wend

'Read the result.dat
'format is like : z:\app_vob\test.txt@@\main\3
Dim str                             As String
Open "result.dat" For Input Access Read As #3
Input #3, str
Close #3

If Len(str) = 0 Then
      Print "No version found"
      End
End If

'the version number is the data starting from right until a \ is found
notFinished = true
        i = Len(str)
While notFinished
      car$ = Mid$(str,i,1)
              If car = "\" Then
                  notFinished = false
      End If
      i = i-1
      If i = 0 Then
                  Print "No version found"
                  End
      End If
Wend
i = i + 2 '+1 because goes out of while loop with a i=i-1
' +1 because we do not want the \
versionNbr = Mid$(str,i,Len(str))
'Print versionNbr

'Add Text Box (called NoteView in Rose REI) in Main Diagram
Dim theNoteView As NoteView
Dim theMainDiagram As Diagram

Dim theLogicalView As Category
Set theLogicalView = theModel.RootCategory
Dim     thediagrams     As ClassDiagramCollection
Set thediagrams = theLogicalView.ClassDiagrams
theNoteText = "Version" & versionNbr

For i =1 To thediagrams.count
    Set theNoteView = thediagrams.Getat(i).AddNoteView(theNoteText, 1)
    theNoteView.XPosition                             = 0
    theNoteView.YPosition                             = 0
Next i

End Sub

\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
#5 Solution 10629 - ClearCase Automation Library (CAL) FAQ
//////////////////////////////////////////////////////////
==========================================================
What is CAL (ClearCase Automation Library) ?
==========================================================
The ClearCase Automation Library (CAL) (referred to as CAL) provides a set of 
COM interfaces to ClearCase 4.0 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 versions of ClearCase are supported with CAL ?
==========================================================
ClearCase versions 4.0 and later are supported by CAL officially. Some 
customers have tried to use some of the limited components of CAL in ClearCase
3.2.1. Rational does not support the usage of CAL for versions of ClearCase 
before 4.0 ClearCase Automation Library, ccauto.dll
==========================================================
What are the languages that CAL supports ?
==========================================================
Visual Basic 5.0 or later
Visual C++ or later 5.0 or later
Win32 Perl(COM-Enabled) (CCPerl is not supported)
Visual J++
Windows Scripting Host
==========================================================
What COM pieces makes up CAL ?
==========================================================
As with most COM interfaces, the typical pieces are:OBJECTS, INTERFACES, 
METHODS and PROPERTIES There are only two (2) top-level CAL objects, the 
Clearcase.Application object(which is rich with numerous interfaces,methods and
properties) and the Clearcase.Cleartool object which only has one method 
CMDEXEC, which can be used to execute a ClearTool sub-command.
==========================================================
Where can I get more information on CAL, is there reference manual?
Where can I get examples ?
==========================================================
The CAL documentation at this time can be accessed via the cc_cal.chm online 
documentation in the bin subdirectory of the clearcase install path (ie: 
\Program Files\Rational\ClearCase\Bin\cc_cal.chm) This file has all of the 
commoly needed documnetation on the various interfaces,methods and properties 
for both CAL objects,and includes many examples.  You can also access help from 
Start...Programs...ClearCase...ClearCase Help... and click on Administrating 
ClearCase. The subsection "using clearcase automation library (CAL)"..
==========================================================
CAL Object Naming Conventions
==========================================================
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 ClearCae 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 I "GET" a ClearCase.Application object,do I have to keep getting it in 
CAL?
==========================================================
Once you create the ClearCase.Application object, you can use it 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 you invoke properties and methods. However, the CAL objects can
become invalid if someone deletes the underlying ClearCase data while you still 
hold the CAL object.
==========================================================
What limitations does CAL have ?
==========================================================
CAL does not provide access to all ClearCase functionality. For example, with 
CAL:

You cannot create VOBs.
You cannot access build capabilities.
You cannot access view profiles.
You cannot access most UCM objects in this version of CAL
You cannot get properties or perform operations on symbolic
links or derived objects.
In addition, CAL does not allow you to perform operations that
are not permitted from cleartool or through the ClearCase GUIs.
==========================================================
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 MSDN 
library article number Q186063.
==========================================================
What is a simple example of CAL use ?
==========================================================
This example shows how to obtain ClearCase version information using CAL.

In your Visual Basic Project, from the Project menu choose References, and be 
sure to check the checkbox for ClearCase Automation Library 4.0

To get a CAL object representing 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")

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

//////////////////////////////////////////////////////////
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

Rational Customer Service Policies and Information: http://www.rational.com/support/info.jsp