by Robert Perron
レベル：上級者
対象：Designer 5.0
原文の掲載：2000年1月3日
Iris Today Archivesの原文
これまでのバージョンのドミノ、およびノーツでは、外部で動作するVisual Basic等のプログラムから、OLEを通してドミノ・オブジェクトにアクセスすることが可能でした。しかし、OLEには以下の欠点があります。
- 使用するマシンに、ノーツ・クライアントが載っており、動作していなくてはなりません。もしOLEのアクセス時にノーツが動作していないのならば、それは別のプロセスとして、新たに起動されます。
- 実行時バインドのみのサポートです。オブジェクトは実行時にはじめてバインドされます。パフォーマンス向上やコンパイル時チェック、オブジェクト・メンバーのルックアップ等のために、コンパイル時バインド、すなわちあらかじめバインドしておくことができません。
ノーツ/ドミノ R5.0.2b では、ドミノ・オブジェクトのインターフェースとしてコンポーネント・オブジェクト・モデル（COM）をサポートしました。COMを利用すると以下の利点を得ることができます。
- COMは、ドミノ、あるいはノーツを必要とします。しかし、OLEと違い、ドミノ・サーバー、ドミノ・デザイナー、あるいはノーツ・クライアントでも構いません。
- ドミノ、あるいはノーツ・ソフトウェアは、動いている必要がありません。
- コンパイル時バインディング、および実行時バインディングの両方をサポートします。
COMでサポートされるドミノ・オブジェクトは、ロータス スクリプトや Javaから利用可能なバックエンドのクラスでのみ構成されています。フロントエンド・クラス－NotesTimer、NotesUIDatabase、NotesUIDocument、NotesUIView、および NotesUIWorkspace－を利用するには、やはりOLEと起動しているノーツ・クライアントが必要です。
この記事の例は、Visual Basic、およびVBScriptです。しかし、C++やワード、エクセルのVBA、ASP内のVBScriptなど、COMをサポートするどんな言語、あるいはアプリケーション・インターフェースからでもドミノ・オブジェクトにアクセスすることができます。
R5.0.3でのドミノ・デザイナー・ドキュメンテーションは、COMについてアップデートされる予定です。R5デザイナー・ヘルプ・データベースで「COMを通してドミノ、オブジェクトにアクセスする」という項目を参照してください。また、索引で「COM」を探すか、コンテンツでLotusScript/COM/OLEの話題を参照してください。
Lotus Domino and Notes ToolKit for COMは、Lotus
Developer Network Technology and Toolkits Zone（US）からダウンロード可能です。ツール・キットにはサンプル、コード、COM
サポート・ファイル、およびドキュメンテーションが含まれています。コード例は、C++、Visual Basic、エクセルやワードのVBA、ASPでの VBScriptについて記述されています。
R5.0.2bをインストールすると、オペレーティング・システム・レジストリーでは、以下のようにLotus.NotesSessionと命名されたクラスが表示されます。これは、ドミノ
COMクラスのルートです。 また、同じくレジストリーには、OLEルートである Notes.NotesSession、および Notes.NotesUIWorkspace
も存在しています。
Visual Basicでの利用
Visual Basicでドミノ COMオブジェクトを使用するには、〔プロジェクト〕-〔参照〕を選びます。
一覧されている参照可能オブジェクト・クラスをスクロールダウンし、"Lotus Domino
Objects"をチェックします。
これでドミノ・オブジェクトが、プロジェクトで利用できるようになります。オブジェクト・ブラウザーを通してそれらにアクセスすることができます。
コード・エディター画面で、オブジェクト名とピリオドをタイプすると、ドロップダウン・メニューから使用できるプロパティーやメソッドにアクセスすることができます。
ドミノ・オブジェクトのルートである NotesSessionオブジェクトは、Dim Newまたは CreateObjectで作成します。その時セッションを初期化するために、COM固有の
NotesSessionメソッドであるInitioalizeまたはInitializeUsingNotesUserNameのどちらかを使用します。COMでのNotesSessionオブジェクトは、ロータス
スクリプトの場合と異なり、明示的な初期化が必要です。
以下のサブ・プロシージャーは、ドミノ・オブジェクトにアクセスする最小限のコードを示しています。コードは、NotesSessionオブジェクトを作成するために
CreateObjectを使用しています。Dim Newを使用するにはコメント化されている行の方を使います。
このサンプル・コードには、現在のドミノもしくはノーツ・ユーザー IDを元にセッションを初期化する方法が記述されています。もしユーザーIDがパスワードを要求するのであれば、ランタイム上にパスワード入力プロンプトが現れます。または、随意に、コードでパスワードを明示することもできます:
Call session.Initialize（"UserIDPassword"）
|
|
もしマシンがサーバーおよびクライアント・ソフトウェア両方を含んでいる場合には、使用されるIDはオペレーティング・システム・レジストリーのCurrentに依存します。
もしコードがドミノ、サーバーを含むマシン上で動作している場合は、以下のコードで、ローカルのドミノ・ディレクトリーのユーザー名を基にセッションを作成することもできます。
Call session.InitializeUsingNotesUserName（"UserName"）
|
|
空の文字列は、「匿名」を意味しています。匿名アクセスが可能かどうかは、ドミノ・ディレクトリーーのサーバー文書の”サーバー・アクセス”および"Java/COM制限"に依存します。
この場合、パスワードは、ドミノ・ディレクトリーのユーザー文書のインターネット・パスワードです。もしパスワードが要求され、そして、プロンプトを表示したくなかったり、ソフトウェアがプロンプトをサポートしていないときは（例、ASP/IISの下の
VBScript等）、第2のパラメーター"InternetPasssword"を明示してください。
Call session.InitializeUsingNotesUserName（"UserName",
"InternetPassword"）
|
|
VBScriptでは実行時バインディングのみが利用できます。コンパイル時のチェックは不可能です。NotesSessionオブジェクトの作成には
CreateObjectを使用しなくてはなりません。以下の例は、Internet Explorerによって走らせられるHTMLファイルでのソース・コードを示します。
NotesSessionは、直接作り出すことができる唯一のドミノ・オブジェクトです。その他のドミノ・オブジェクトは、NotesSessionやその下位階層のプロパティーやメソッドの戻り値から取得します。NotesSessionの"Create"名称のメソッドでは、以下のようなオブジェクトを取得できます。
注意：オブジェクト・ブラウザーで表示されるCurrentAgent、CurrentDatabase、およびDocumentContextプロパティーは、実際には実行されません。
また、NotesDatabaseのUnprocessedDocumentsプロパティー、UnprocessedFTSearchメソッド、およびUnprocessedSearchメソッドも実行されません。それらは、エラーなしでコンパイルしますが、ランタイムで失敗します。現在、COMオブジェクトは、「現在の環境」の概念を持ちません。
各ドミノ・オブジェクトにアクセスするための一般的な階層表記については、Common
paths sidebarをご覧ください。一覧の情報は一般的に使用する階層表記であって、全てを包括しているわけではないことに注意してください。
NotesSessionのGetDatabase は、該当するデータベースが存在すればそれをオープンします。サーバー名（空の文字列はローカルなドミノ、あるいはローカルのノーツ・データ・ディレクトリーを意味します）とデータベース名を指定します。もしデータベースが存在していなくても、GetDatabaseはエラーを返しません。データベースの存在を確認するには、IsOpenプロパティーを使用します。これらの意味は、ロータス スクリプトと同じです。
この例は、サーバー"Snapper"上の NAMES.NSFをオープンして、データベースのタイトルを表示します。
Private Sub GetNames_Click（）
Dim session As New NotesSession
session.Initialize
Dim db As NotesDatabase
Set db = session.GetDatabase（"Snapper", "names"）
If db.IsOpen Then
MsgBox db.Title, , "Title of names.nsf"
Else
MsgBox "File does not exist",
, "Title of names.nsf"
End If
End Sub
|
|
NotesSessionのGetDbDirectoryを使用してドミノ、ノーツ・ディレクトリー、およびそれを構成しているデータベース群にアクセスすることができます。以下の例は、機能上は上記のコードと同じです。
Private Sub GetNames2_Click（）
Dim session As New NotesSession
Dim dir As NotesDbDirectory
Dim db As NotesDatabase
session.Initialize
Set dir = session.GetDbDirectory（"Snapper"）
Set db = dir.OpenDatabase（"names"）
If db.IsOpen Then
MsgBox db.Title, , "Title of names.nsf"
Else
MsgBox "File does not exist",
, "Title of names.nsf"
End If
End Sub
|
|
データベースを作成してオープンする方法は、COMとロータス スクリプトでは異なります。COMでは、NotesDbDirectoryのメソッドを使用して作成とオープンをおこないます。ロータス
スクリプトではNotesDatabaseオブジェクトを作成するためにNewを使用し、そしてオブジェクトをオープンするためには、そのNotesDatabaseオブジェクトのメソッドを使用します。もし、COMとロータス
スクリプトの間でコードを移植している場合にはこの部分を書きなおさなくてはいけません。 違いは以下のようになります。
| COM: NotesDbDirectory |
LotusScript: NotesDatabase |
| CreateDatabase |
Create |
| OpenDatabase |
Open （with parameters） |
| OpenDatabaseByReplicaID |
OpenByReplicaID |
| OpenDatabaseIfModified |
OpenIfModified |
| OpenMailDatabase |
OpenMail |
また、パラメーターのないNotesDatabase.Openは、COM、およびロータス スクリプトで同じです。
NotesDbDirectoryのナビゲーション方法は、2つの注意点を除いてCOM、およびロータス スクリプトで同じです。コンパイル時バインディングのCOMコードでは、名前の重複を避けるために、定数DATABASEを使わないでください;かわりに
NOTES_DATABASEを使用します。
実行時バインディングCOM コードでは、定数は利用できません。そのかわりそれらの整数値を明示しなくてはいけません。値は、1245（REPLICA_CANDIDATE）、1246（TEMPLATE_CANDIDATE）、1247（NOTES_DATABASE）、および
1248（TEMPLATE）です。
以下のVisual Basicコードは、ローカルなドミノ、あるいはノーツ・ディレクトリーでデータベースを取得するループです。
Private Sub LoopDbDirectory_Click（）
Dim session As New NotesSession
Dim dir As NotesDbDirectory
Dim db As NotesDatabase
session.Initialize
Set dir = session.GetDbDirectory（""）
Set db = dir.GetFirstDatabase（NOTES_DATABASE）
While Not （db Is Nothing）
MsgBox db.Title, , db.FilePath
Set db = dir.GetNextDatabase
Wend
End Sub
|
|
VBScriptでは、コーディングは以下のようになります。
<HTML>
<HEAD>
<TITLE>Initialize Session</TITLE>
<SCRIPT LANGUAGE="VBScript">
Sub Button1_OnClick
dim s, dir, db
Set s = CreateObject（"Lotus.NotesSession"）
Call s.Initialize
Set dir = s.GetDbDirectory（""）
Set db = dir.GetFirstDatabase（1247）
While Not （db Is Nothing）
Msgbox db.Title,, db.Filepath
Set db = dir.GetNextDatabase
Wend
End Sub
</SCRIPT>
</HEAD>
<BODY>
<H3>Loop through local Notes directory</H3><HR>
<FORM><INPUT NAME="Button1" TYPE="BUTTON" VALUE="Click
Here"></FORM>
</BODY>
</HTML>
|
|
ロータス スクリプトでは、アイテムの名前を NotesDocumentのプロパティーとして使用して、アイテム・オブジェクトにアクセスすることができました。COMでは、この方法は使用できません。以下のロータス
スクリプトのコードは、そのままでは COMへ移植できない例です。
Dim doc as NotesDocument
...
Msgbox doc.Subject（0）,, "Contents of Subject item"
|
|
アイテムの値にアクセスするためには、NotesDocumentオブジェクトの AppendItemValue、GetItemValue、ReplaceItemValue、あるいは
NotesItemオブジェクトのValues を使用しなくてはなりません。
以下の例は、ローカルなデータベース内でそれぞれのドキュメントの"Subject"および"Categories"アイテムの値を得ます。ロータス
スクリプトと同様に、テキスト、数値、および日付値は、配列で返されます。"Subject"といった、単一値の項目にアクセスするためには、配列の最初の要素にアクセスしてください。複数値のアイテムにアクセスするためには、全ての要素あるいはすべての要求した要素にアクセスしてください。
Private Sub
GetSubjects_Click（）
Dim session As New NotesSession
Dim db As NotesDatabase
Dim dc As NotesDocumentCollection
Dim doc As NotesDocument
session.Initialize
Set db = session.GetDatabase（"", "document
examples"）
If Not db.IsOpen Then
MsgBox "File does not exist",
, "document examples"
Exit Sub
End If
Set dc = db.AllDocuments
Set doc = dc.GetFirstDocument
While Not （doc Is Nothing）
catmsg = "Categories:"
REM Get all values in Categories item
For Each cat In doc.GetItemValue（"Categories"）
catmsg = catmsg & Chr（10） & " " & cat
Next
REM Get first （and only） value in Subject item
MsgBox catmsg, , doc.GetItemValue（"Subject"）（0）
Set doc = dc.GetNextDocument（doc）
Wend
End Sub
|
|
COMでは、ループ構造は"For Each".."Next"ですが、一方で，ロータス スクリプトはそれが"ForAll".."End
ForAll"であることに注意してください。 移植の際には、この構文は手動で変更しなくてはなりません。
次の例では、"Subject"および"Categories"のアイテムを加えるために、ドキュメントを作成して、AppendItemValueを使います。
Private Sub CreateDocument_Click（）
Dim session As New NotesSession
session.Initialize
Dim db As NotesDatabase
Set db = session.GetDatabase（"", "document examples"）
f Not db.IsOpen Then
MsgBox "File does not exist",
, "document examples"
Exit Sub
End If
Dim doc As NotesDocument
Set doc = db.CreateDocument（）
doc.AppendItemValue "Subject", "New Document"
Dim cats（2） As String
cats（0） = "Category One"
cats（1） = "Category Two"
doc.AppendItemValue "Categories", cats
doc.Save False, False
End Sub
|
|
Visual Basicでは、定数はオブジェクト・ブラウザーから取得可能です。オブジェクト・ブラウザーの左側のペインにリストされているの全て大文字のEnum構造体や左側のペインにある <globals> を通して定数にアクセスすることが出来ます。
以下は
DB _ TYPES のEnum構造体です。以前に述べたように、NOTES_DATABASE使用して、DATABASEを使用しないようにします。
エラー定数は、NOTES _ ERRORSの下に列挙されます。
以下のコードは、ドミノ・エラー ERR_SYS_FILE_NOT_FOUNDのテストです。コードは、Err（）組み込み関数によるエラー番号から、ドミノ・エラー・コードを引き出します。COMで、エラー番号は4バイトです。最初の2バイトは
16進の8004、最後の2バイトは、ドミノ・エラー・コードです。サンプル・コードは、最後の4桁のエラー番号を取って、それらを整数に変換します。
Private
Sub ErrorTest_Click（）
On Error GoTo ErrorHandler
Dim session As New NotesSession
session.Initialize
Dim db As NotesDatabase
Set db = session.GetDatabase（"", "fooey"）
db.Open
MsgBox db.Title, , "Title of fooey"
Exit Sub
ErrorHandler:
If Err（） = ERR_SYS_FILE_NOT_FOUND Then
MsgBox "File not found", , "Domino
Error"
Else
MsgBox CInt（"&H" & Right（Hex（Err（））,
4））, , "Domino Error"
End If
End Sub
|
|
ロータス スクリプトは現在 Err組み込みオブジェクトをサポートしません。もしCOM とロータス スクリプトの間の移植を考慮するのであれば、COMで
Err（）のかわりに Err.Numberを使うことができます。その例です。
If Err.Number = ERR_SYS_FILE_NOT_FOUND
Then
|
|
VBScriptではErr（）関数をサポートしないので Err.Numberを使わなくてはいけません。
VBScriptといった実行時バインディング言語では、名前付き定数の使用はできません。実際の整数値を明示しなくてはいけません。これらの値を見つけるために、以下のリソースを使ってください。
- ドミノ R5.0.3デザイナー・ヘルプで、"COM を使用してドミノにアクセスする"または"ランタイム・エラーのハンドリング"トピックを参照したり、索引で"COM2、"エラー・ハンドリング"を探します。
- ドミノ、あるいはノーツ、プログラム・ディレクトリーでLSXBEERR.LSSファイルを検出し、そこに記述されているエラー定数を参照します。
- Visual InterDevのようなツールを使って、ドミノ、あるいはノーツのプログラム・ディレクトリーでDOMOBJ.TLB
を参照します。
- ドミノ・デザイナー、あるいはVisual Basicを持っていれば、定数の値を表示したり（例えば、MsgBox を使用します）、あるいオブジェクト・ブラウザーで調べます。
以下のコードは、上記のコードのVBScriptでの実装です。コードは、チェックされるエラーの名前と値の変数を定義します。エラー値は、（もしエラー・コードが3桁なら）16進法
80040 に、（もしエラーコードが4桁なら）16進法の8004に、ドミノ・エラー・コードが加えられて8桁の16進数に結合され、それがlongに変換されます。（実際はこのサンプルでのエラー・コードは定数なので、条件分岐は不必要です。これらはデモンストレーションのために記述されています。）
<HTML>
<HEAD>
<TITLE>Initialize Session</TITLE>
<SCRIPT LANGUAGE="VBScript">
Sub Button1_OnClick
On Error Resume Next
dim s, db, ERR_SYS_FILE_NOT_FOUND
If Len（Hex（4003）） = 3 Then
ERR_SYS_FILE_NOT_FOUND = Clng（"&H80040" & Hex（4003））
Else
ERR_SYS_FILE_NOT_FOUND = Clng（"&H8004" & Hex（4003））
End If
Set s = CreateObject（"Lotus.NotesSession"）
Call s.Initialize
Set db = s.GetDatabase（"", "fooey"）
db.Open
If Err.Number = 0 Then
MsgBox db.Title,, "Title"
Else
If Err.Number = ERR_SYS_FILE_NOT_FOUND Then
MsgBox "File not found",,
_
"Domino Error"
Else
MsgBox CInt（"&H" & Right（Hex
（Err.Number）, 4））,, "Domino
Error"
End If
End If
End Sub
</SCRIPT>
</HEAD>
<BODY>
<H3>Get fooey.nsf</H3><HR>
<FORM>
<INPUT NAME="Button1" TYPE="BUTTON" VALUE="Click
Here">
</FORM>
</BODY>
</HTML>
|
|
 |
移植に関して考慮しなくてはならない項目の多くはすでに述べられました。繰り返すと、
- COMで利用できるのはバックエンド・クラスだけです。NotesUI クラス、および NotesTimerは使用できません。
- COMセッションは初期化しなくてはいけません。それにはNotesSessionメソッドのInitialize（"UserIDPasswordOptional"）または、InitializeUsingNotesUserName
（"UserName"、"InternetPasswordOptional"）を使用します。
- NotesSession以外のドミノ・オブジェクトを直接作り出すことはできません。それ以外のオブジェクトはドミノ・オブジェクト階層のプロパティーやメソッドの返り値として取得しなくてはなりません。
- COMは、現在の環境のいかなる情報も持っていません。
NotesDatabaseの UnprocessedDocuments、UnprocessedFTSearch、UnprocessedSearch、および、NotesSessionのCurrentAgent、CurrentDatabase、DocumentContext
は使用できません。
- COMは、データベースの作成とオープンのために、NotesDbDirectoryのメソッドであるCreateDatabase、OpenDatabase、OpenDatabaseByReplicaID、OpenDatabaseIfModified、およびOpenMailDatabaseを使います。
一方ロータス スクリプトでは、"New"を使用して NotesDatabaseオブジェクトを作成し、NotesDatabaseのメソッドの、Create、Open、OpenByReplicaID、OpenIfModified、および
OpenMailを使用します。
- COMでは、アイテム名をNotesDatabaseプロパティーのようにあつかうことはできません。
アイテムにアクセスするには、NotesDatabase
のAppendItemValue、GetItemValue、ReplaceItemValue、または NotesItemのValuesを使用します。
- Visual BasicではFor Each...Nextループを使用します。
ロータス スクリプトでは
ForAll...End ForAll ループを使用します。
- 長いEnum構造体をCOMで明示しないことで、定数をポーティングできます。例えば、定数 NOTES
_ DATABASE （値1247）は、COMでは DATA_TYPES.NOTES_DATABASEとして明示することもできますが、その場合、ロータス
スクリプトへそのまま移植はできません。また、DATABASEではなく、必ずNOTES _ DATABASEを使用してください。
- ロータス スクリプトはErr組み込みオブジェクトをサポートしません。
ロータス スクリプトおよび Visual
Basic は両方ともErr（ ）組込み関数はサポートします。（ VBScriptはErr（ ）組込み関数をサポートしません）
COMクラスには、ユーティリティーの目的のためにいくつかの追加のプロパティーとメソッドが含まれています。これらのプロパティーとメソッドは将来のリリースにおけるロータス
スクリプトで編入される可能性がありますが、R5.0.3 ではその計画はありません。それらCOM固有のプロパティーやメソッドは以下のとおりです:
- NotesAgent、NotesDatabase、NotesDocument、NotesForm、NotesSession、NotesViewの各オブジェクトで、アクセスしている
URLを返すためのHttpURL、および NotesURL。
- 該当オブジェクトを含んでいる親オブジェクトへのハンドルを取得するための Parentプロパティー。このプロパティーを含んでいるオブジェクトは、NotesDateRange、NotesDateTime、NotesDbDirectory、NotesForm、NotesInternational、NotesLog、NotesName、NotesNewsletter、NotesOutlineEntry、NotesRichTextStyle、およびNotesViewColumn。また、同じ目的で
NotesOutline の ParentDatabase も使用可能。
- NotesSession オブジェクトのServerName、URLDatabase、UserNameObject、CreateRegistration、Evaluate、Resolve。
- NotesView オブジェクトのCreateViewNavMaxLevel、GetColumn。
- NotesViewNavigator オブジェクトのGetCurrent、GotoChild、GotoEntry、GotoFirst、GotoFirstDocument、GotoLast、GotoLastDocument、GotoNext、GotoNextCategory、GotoNextDocument、GotoNextSibling、GotoParent、GotoPos、GotoPrev、GotoPrevCategory、GotoPrevDocument、GotoPrevSibling。
ロータス スクリプトは、ブールのデータ型をサポートしません。ロータス ドミノ・スクリプト・クラスは、booleanスタイルのパラメーターと戻り値はIntegerかVariantとしてタイプされます。これは、ロータス
スクリプトからVisual Basicへ移植する上での問題ではありません。しかし、Visual BasicでBooleanとしてタイプされたデータは、ロータス
スクリプトへの変更なしで移植はできません。
他のいくつかの重要でない違いが、COMとロータス スクリプト、クラスの間には存在します（または Visual Basic、およびロータス スクリプト言語の間で）。これらは、R5.0.3の更新されたドミノ
R5デザイナー・ヘルプに掲載される予定です。
COMをサポートするどんなソフトウェアからでも、バックエンドのドミノ、オブジェクトにアクセスすることができるようになりました。必要なのは、ドミノ サーバー、ドミノ・デザイナー、ノーツ・クライアント
R5.0.2b （またはそれ以上）を COMを利用したいマシン上にインストールすることです。ドミノ、あるいはノーツ、ソフトウェアは、動いている必要はありません。
この記事は、Visual Basic、および VBScript での例を提供しました。C++、ワードおよびエクセルのVisual BasicVBA、ASPのVBScriptでの使用についての例やドキュメンテーションは、Lotus
Developer Network Technology and Toolkits zoneから取得できます。
| IBMはIBM Corporationの商標。Lotus、Lotus
Domino、Lotus NotesはIBMの商標。その他、記載された社名および製品名は、それぞれ各社の商標または登録商標です。 |
|
|
|
|
