Rational® ClearCase® Automation Library は、Windows が稼働するプラットフォーム上で Rational ClearCase データにアクセスしたり、これを操作したりするのに使用できる COM インターフェイスです。 CAL を使用してスクリプト、スタンドアロン プログラム、または他のアプリケーションに組み込まれるマクロを作成することができます。通常の Rational ClearCase ライセンス チェックは、CAL を使用するアプリケーションに適用されます。
CAL インターフェイスは、Rational ClearCase がインストールされたときに自動的に登録されるため、登録の必要はありません。
CAL を使用するためには、Rational ClearCase の概念と操作方法を理解している必要があります。
最上位のレベルで、CAL は様々なオブジェクトに分割されます。CAL オブジェクトの中には、Rational ClearCase バージョンを表す CCVersion オブジェクトのように、基礎的な Rational ClearCase データを表すものがあります。 また基礎的な Rational ClearCase データを直接表すのではなく、これを管理する、制御オブジェクトの CAL オブジェクトもあります。例えば、CCVersions コレクション クラスは、CCVersion オブジェクトのコレクションを管理します。また CCCheckedOutFileQuery オブジェクトでは、チェックアウト済みファイルを検出するためのクエリーを作成できます。TriggerTypeBuilder オブジェクトでは、トリガ タイプ オブジェクトを作成するためのパラメータを構築できます。
一般に、CAL オブジェクトは Rational ClearCase 用語の名前と同じ名前を持ちますが、CAL オブジェクトの名前には接頭部 CC が付きます。例えば、CAL では、CCElement オブジェクトは Rational ClearCase エレメントを表します。
1 つのオブジェクトで複数のインターフェイスをサポートすることができます。例えば、CCVersion オブジェクトは、バージョン特有の情報については ICCVersion インターフェイスをサポートし、システム特有の情報については ICCFile インターフェイスをサポートします。 また、複数のオブジェクトで同じインターフェイスをサポートすることも可能です。例えば、CCVersion オブジェクトと CCElement オブジェクトはどちらも ICCFile インターフェイスをサポートしています。どちらのインターフェイスもファイル システム オブジェクトを表しているためです。
各 CAL オブジェクトにはプライマリ インターフェイスがあり、オブジェクトによっては他にもインターフェイスを持つことがあります。CAL では、複数インターフェイスは継承によってのみサポートされます。つまり、継承の階層がわかれば、各オブジェクトがどのインターフェイスをサポートしているのかがわかります。(これは、COM インターフェイスの場合には必ずしも当てはまりませんが、CAL インターフェイスの場合には必ず当てはまります)。
オブジェクトとインターフェイスの区別は、Visual Basic のプログラマにとって明確ではありません。インターフェイスが VB プログラマの目に触れることはありません。VB プログラマはオブジェクトのみ参照します。
CAL オブジェクトのプライマリ インターフェイスは CAL オブジェクトと同じ名前を持ちますが、プライマリ インターフェイスの場合はインターフェイスを表す接頭部 I が付きます。例えば、CCLabel オブジェクトの場合は ICCLabel インターフェイス、CCVersion オブジェクトの場合は ICCVersion インターフェイスとなります。
各インターフェイスは、オブジェクトとの対話を可能にする多くのプロパティとメソッドをサポートしています。
プロパティからは、オブジェクトに関する情報の 1 つ 1 つを取得したり、ときには設定したりすることができます。例えば、ICCLabelType の Name プロパティからは、ラベル タイプ オブジェクトの名前を取得できます。
メソッドは、オブジェクトに対していくつかのアクションを呼び出します。 例えば、CheckOut は CCVersion オブジェクト上のメソッドであり、バージョンをチェックアウトすることができます。
CAL インターフェイスのデフォルト プロパティは、各インターフェイスの説明の先頭にある表にリストされています。CAL オブジェクトを参照する Visual Basic プログラマがデフォルト プロパティにアクセスする場合は、プロパティ名を省略できます。例えば、IClearTool のデフォルト プロパティは CmdExec なので、Dim CT As New ClearCase.ClearTool というコードを使用する場合は、CT("pwv") を呼び出しても CT.CmdExec("pwv") を呼び出しても結果は同じになります。
CAL ライブラリは、Microsoft Visual Basic (5.0 以降) を使用してブラウズできます。
Visual Basic オブジェクト ブラウザの下部のパネルには、ヘルプ文字列のテキストが表示されます。Visual Basic 6.0 では、任意のクラスまたはそのクラスの任意のメンバを選択した状態で F1 を押すと、そのクラスまたはクラス メンバについての資料が表示されます。
CAL との対話には、Application オブジェクトと ClearTool オブジェクトという 2 つの開始点があります。CAL API の大半は Application オブジェクトによって提供されます。CAL を使用するアプリケーションのほとんどは、ここから開始されます。ClearTool オブジェクトには 1 つだけ CmdExec というメソッドがあります。このメソッドは、cleartool サブコマンド文字列を実行するために呼び出されます。ClearTool オブジェクトは、Application オブジェクトでカバーされていない cleartool 内の機能をプログラムでアクセスできるようにするためのものです。
外部から作成できる CAL 内のオブジェクトは ClearCase.Application と ClearCase.ClearTool の 2 つだけです (このため、"CC" という名前の接頭部を必要としないオブジェクトはこの 2 つだけです)。
COM インターフェイスの場合、外部から作成可能なオブジェクトは、クライアントが直接作成可能なものだけです。Visual Basic では、New キーワードを使用してオブジェクトを作成します。C++ では、CoCreateInstance() を呼び出してオブジェクトを作成します。そしてスクリプト言語では、CreateObject() でオブジェクトを作成します。
ほとんどの CAL オブジェクトは外部からは作成できません。外部から作成できないオブジェクトは、別のオブジェクトによって作成する必要があります。この例では、両方の種類のオブジェクトを使用する方法を示しています。
Visual C++ プログラマは、適切なインターフェイスを使用してオブジェクトにアクセスする必要があります。外部から作成可能なオブジェクトへのインターフェイスは、IClearCase (ClearCase.Application の場合) と IClearTool (ClearCase.ClearTool の場合) です。
CAL インターフェイスの参照に使用する構文の表記法は、使用する言語によって変わります。同じ言語であっても、複数のバインドが定義されている場合があります。各インターフェイスについての解説ページに、Visual C++ の場合と Visual Basic の場合の両方の構文が紹介されています。
Visual C++ では、#import 指示を使用すると、コンパイラが CAL タイプ ライブラリの情報から次の 2 種類の C++ ラッパー関数を生成します。
紹介されている Visual C++ 構文は、上位レベルのラッパー用のものです。
加えて、タイプ ライブラリ ヘッダーは、各 CAL インターフェイスに「スマート ポインタ」タイプ (例えば ICCVersionPtr) を定義します。これらのポインタは参照のカウントを処理し、有効範囲外になると自動的に自身を解放します。宣言は、生成されるタイプ ライブラリ ヘッダー ファイル cauto.tlh の中にあります。
CAL はデュアル インターフェイス ("dispatch" インターフェイスと "vtbl" インターフェイスの両方をサポートする) であるため、vtbl ベースのラッパー クラスを使用する代わりに IDispatch のメソッド (例えば、GetIDsOfNames と Invoke) を使用してプロパティにアクセスすることができます。
構文では、BSTR 用 (_bstr_t) と VARIANT 用 (_variant_t) の Visual C++ ラッパー クラスが示されています。BSTR プロパティ用のメモリはすべて CAL によって割り振られますが、メモリの解放は呼び出し元から SysFreeString への呼び出しを使用して行う必要があります。
C++ では、array という語が使用される箇所はすべて SAFEARRAY でなければなりません。文字列の場合と同様、CAL によって SAFEARRAY に割り振られたメモリは呼び出し元で解放する必要があります。SAFEARRAY を解放する関数は SafeArrayDestroy です。
ClearCase.Application オブジェクトは、一度取得すれば、その後は再度「取得」しなくても、ずっとこのオブジェクトを使用して他のオブジェクトを取得することができます。CAL は、プロパティやメソッドが呼び出されたときに必要に応じてリフレッシュを行うことにより、可能な限り CAL オブジェクトが基礎の Rational ClearCase データと同期した状態を保つようにします。ただし、CAL オブジェクトを保持している状態で基礎の Rational ClearCase データが何者かによって削除されると、CAL オブジェクトは無効になることがあります。
「オプション」というマークが付いたパラメータは、Visual C++ プログラマと Visual Basic プログラマのどちらの場合でも、オプションです。ただし、Visual C++ からこれらのパラメータを呼び出す場合は、パラメータのデフォルト値を使用しても呼び出し方法は変わりません。Visual Basic のプログラマは、呼び出しの際にこれらのパラメータを省略することができますが、C++ のプログラマはできません。C++ のプログラマは、この資料やブラウザを見てデフォルト動作を行わせるために何を渡せばよいかを確認することができますが、それを自動的に行わせる方法はありません。
CAL タイプ ライブラリには、一部のスクリプト言語 (例えば VBScript) ではシンボリック フォームで使用できない列挙定数が含まれています。それでも、数値を直接使用するよりも、列挙値用に定義された定数を使用することが推奨されています。例えば、VBSscript では、
CheckOut(1)
というコーディングをするよりも、次のようにします。
const ccReserved=1 CheckOut(ccReserved)
これらの定数は OLE/COM オブジェクト ブラウザで見つけることができるので、そこから定数をカット アンド ペーストできます。VB プログラマと VC++ プログラマは、シンボリック フォームで列挙定数を使用できます。
CAL では、標準の COM エラー処理と標準の自動化エラーを使用します。Visual Basic および Visual C++ からの COM エラー処理について考察する際は、MSDN ライブラリの記事番号 Q186063 を参考にしてください。
この例は、CAL を使用して Rational ClearCase のバージョン情報を取得する方法を示しています。
Visual Basic プロジェクトで、[プロジェクト] メニューから [参照] を選択し、[ClearCase Automation Library x.x] のチェック ボックスにチェックが付いていることを確認します。
Rational ClearCase バージョン M:¥view¥vob¥file@@¥main¥3 を表す CAL オブジェクトを取得するには、ClearCase.Application オブジェクトを作成し、その後 Application オブジェクトからバージョンを取得します。
Dim CC as New ClearCase.Application Dim Ver as CCVersion Set Ver = CC.Version("M:¥view¥vob¥file@@¥main¥3")
例では、バージョンの参照に拡張パスを使用しています。これは必須ではありません。CAL では、cleartool 操作や GUI アプリケーションで機能するのと同じ Rational ClearCase コンテキストが機能します。 例えば、コードがディレクトリ M:¥view¥vob から実行された場合で、ビューで選択されたバージョンを選択することが目的であった場合、この例は次のようにコーディングされます。
Set Ver = cc.Version("file")
実行後、Ver は、M:¥view¥vob¥file@@¥main¥3 を表す CAL CCVersion オブジェクトを保持します。これで、Ver をバージョンのクエリー プロパティとして使用できるようになりました。例えば、バージョンのバージョン番号を出力する場合は、次のフォームでステートメントを使用します。
MsgBox "Version Number " & Ver.VersionNumber
CAL では、すべての Rational ClearCase 機能にアクセスすることはできません。 例えば、CAL には以下の制限があります。
加えて CAL では、cleartool または Rational ClearCase GUI からの実行が許可されていない操作は実行できません。
CAL は、DCOM アプリケーションではなく、インプロセス COM サーバーとして稼働します。