ソフトウェア > Lotus > Lotus Developer Domain > 製品別技術情報 > Lotus Notes/Domino >

LDD Today

Notes/Domino 5および6でのエージェントのトラブルシューティング

by ジュリー・カダシェヴィッチ
レベル：中級者
対象：Notes/Domino 5 and 6
原文の掲載：2003年1月2日

LDD Today の原文（英語）

インデックス

	エージェントについての簡単な説明
	役に立つNotes.ini設定
	ルーターおよびWebエージェントによって生成されるエラー・メッセージ
	NotesLogクラスによるデバッグ
	サーバー・コンソールでのデバッグ
	一般的なエージェントの問題
	複数のサーバーへの展開
	まとめ

1998年3月に、「Troubleshooting agents」（英語）という記事を公開しましたが、これはNotes.net/LDDがこれまでにお届けした中で最も人気の高い記事の1つで、今に至るまで読者の皆さんの高い関心を得て根強い人気を保っています。もちろん、その記事が初めて公開されてから、状況は大きく変わりました。たとえば、Notes/Domino 5とNotes/Domino 6という、2つものメジャー・リリースがその間に出荷されました。そんなことから、記事の大部分は今でも適切であるとはいえ、そろそろ最新情報で内容を更新するべきではないかと感じました。

その一方で、数字が示しているように、今もなお読者の皆さんによって頻繁に利用されている以前の記事を残しておく必要もありました。そういうわけで、元の記事はそのまま残し、Notes/Domino 5および6でのエージェントのトラブルシューティングに的を絞ったまったく新しい記事を執筆することにしました。こうすれば、Domino 4.6を使用しているユーザー（少なからず存在します）が元の記事を引き続き利用できると同時に、それより新しいリリースを使用している残りのユーザーは、包括的な最新情報をいつでも利用できるというわけです。

以前の記事と同様に、この記事では、エージェントのトラブルシューティングやエージェントが意図したようには動作しない原因の調査方法について説明します。まず、Notes.ini設定、LotusScriptのNotesLogクラス、サーバー・コンソール・コマンドなど、Notes/Domino 5および6でのエージェントのトラブルシューティングのために用意されているツールを紹介します。その後、エージェントの設計や実行、発生する可能性がある一般的な問題の一部について、考えられる原因と解決策を示しながら考察します。

この記事の対象読者は、実務経験のあるNotes/Dominoアプリケーション開発者で、システム管理についてある程度の知識を有していることが理想です。

エージェントについての簡単な説明

エージェントの問題のトラブルシューティングにあたっては、エージェントとAgent Managerの仕組みを理解することから始めるのが一番です。そこで、まずエージェントの起動方法から見ることにしましょう。サーバー上では、次の方法でエージェントを呼び出すことができます。

Agent Manager：定期エージェントを制御するサーバー・タスクです。定期エージェントには、ユーザーが指定したスケジュールで実行されるエージェント、または特定のイベント（新規メール、新規文書の作成など）の発生時に実行されるようにスケジュールされるエージェントがあります。
HTTPタスク：Webブラウザーを介して呼び出されるエージェントを実行します。
ルーター：メール配信の一環として実行されるエージェントを実行します（「新規メールの受信前」エージェント・トリガー）。
RunOnServerメソッド：クライアント上で実行されるエージェントのコードに含まれています。
サーバー・コンソール・コマンド「Tell amgr run」（これはNotes/Domino 6のみのコマンドです）＜br＞・クライアント上では、次の方法でエージェントを呼び出すことができます。
ユーザー・アクション（メニューの選択やボタンのクリック）の結果、Notesクライアントによって呼び出される対話型エージェント
Client TaskLoaderによって呼び出される定期ローカル・エージェント：Agent Managerの組み込み版（Notes/Domino 6）またはクライアント上でローカルに実行されるAgent Managerタスク（R5）によって、クライアント上の定期エージェントを実行します。

エージェントが動作しない場合にまず行わなければならないことは、問題の性質についてよく知ることです。それには、まず最初にエージェント・ログを調べます。エージェント・ログを見れば、エージェントが最後に実行された日時とエージェントの処理が完了したかどうかを確認できます。

Notes/Domino R5から、Domino Designerには、エージェントのセキュリティーやスケジュールに関する一般的な間違いを突き止めるのに役立つエキスパート・システムとして、エージェント・テストが搭載されています。エージェント・テストは、必要に応じてエージェントの設定を調整するのに役立つ診断メッセージを表示する便利なツールです。Domino Designer 6では、Notes/Domino 6のセキュリティー・モデルに対して正常に機能するように更新されています。Notes 6クライアントでエージェント・テストを使用してDomino 5サーバー上のエージェントを調べる場合、自動的にR5のセキュリティー・モデルに切り替わります。エージェント・テストを実行するには、Domino Designerを開き、データベースの［エージェント］ビューを表示し、テストするエージェントをハイライトし、［エージェント］-［テスト］を選択します。

エージェント・テスト実行のログ

サーバー・ベースのエージェントに関する詳しい情報については、サーバー・コンソールまたはNotes Log（［Miscellaneous Events］ビュー）で、誤動作しているエージェントからのメッセージを調べます。実際のサーバー・コンソールに物理的にアクセスできない場合は、［ファイル］-［ツール］-［サーバー管理］を選択し、［コンソール］ボタンをクリックすると、ライブ・コンソールにアクセスできます。サーバー・コンソールにアクセスする権限がない場合、後で説明するコマンドの発行はできませんが、エージェントを実行しようとしたときにDominoサーバー・ログ内に生成される出力を見ることはできます。

LotusScriptを使用する場合は、LotusScriptのDebugオプションを使用してクライアント・ベースのエージェントの問題を診断することができます。また、Notes/Domino 6では、リモート・デバッグを使用してサーバー・ベースの問題を診断することができます。クライアント側のデバッガーを起動するには、［ファイル］-［ツール］-［LotusScriptのデバッグ］を選択します。リモート・デバッグを起動するには、［ファイル］-［ツール］-［リモートデバッグ］を選択します。これらのデバッガーでは、コード実行中に発生する問題を診断できます。ただし、サーバー上でエージェントを実行する権限に関するセキュリティーの問題がエージェントに発生した場合や、エージェントが誤ったサーバー上で実行されるように設定されている場合には、リモート・デバッグを開始できないことに注意してください。幸い、エージェントがサイレントに失敗することはありません。問題の性質について最大限の情報を得る方法については、後で説明します。また、すべてのエージェントが対話形式でのデバッグに適しているとは限らないため、NotesLogクラスを使用してエージェントのデバッグを行う方法についても考察します。

上に戻る

役に立つNotes.ini設定

Notes.iniには、エージェントの問題の分析に使用できる設定がいくつかあります。それらの変数は、サーバー・ベースの定期エージェントをデバッグする場合はサーバーのNotes.iniファイルに、クライアント・ベースの定期エージェントをデバッグする場合はNotesクライアントのNotes.iniファイルに設定します。それらの変数は、Agent Managerによって実行される定期エージェントをデバッグする場合にのみ使用します。前述のとおり、HTTP、ルーター、コンソール、RunOnServer、および対話型クライアント・エージェントは、Agent Managerによって実行されません。したがって、このセクションで説明するNotes.ini変数は、それらのエージェントに影響しません。（Agent Manager以外のタスクによって実行されるエージェントのデバッグ方法については、後で説明します）。

Notes.ini変数「Debug_Amgr」は、Agent Managerのデバッグを有効にします。これは、定期エージェントに関する問題の診断に役立ちます（DominoサーバーとNotesクライアントのどちらにも有効です）。定期エージェントが動作しないことがわかったら、まずNotes.iniファイルに次の行を追加します。

Debug_AMgr = フラグ

フラグには、次のうちの1つまたは複数を指定できます（リストはアルファベット順になっています）。

フラグ	説明
c	エージェントの制御パラメーターを出力します。
e	Agent Managerイベントに関する情報を出力します。
l	エージェントのロード・レポートを出力します。
m	エージェントのメモリー警告を出力します。
p	エージェントのパフォーマンス統計を出力します。
r	エージェントの実行レポートを出力します。
s	Agent Managerのスケジュールに関する情報を出力します。
v	［より詳細］モードを表します。詳細モードでは、エージェントのロード、スケジュール、およびキューに関する追加のメッセージが出力されます。
*	上記の情報をすべて出力します（すべてのフラグを設定するのと同じことです）。

「Debug_Amgr=*」に設定すると最大限の情報が得られますが、必要以上の出力が生成される可能性があります。また、すべてのデバッグ・フラグを有効にすると、通常、ユーザーに対する平均応答時間について5%のパフォーマンス低下を生じる点に注意してください。

出力は、コンソール・ログおよびNotes Logに表示されます。この変数は、サーバー・コンソールから対話形式で設定することもできます（コンソール・コマンドについては後で説明します）。Notes.iniファイルを変更したら、Agent Manager（またはサーバー）を再起動する必要があります。コンソール・コマンドを使用して変数を設定した場合は、再起動の必要はありません。

また、Notes.iniファイルに次の行を追加することによって、エージェント実行のロギングを有効にすることもできます（これは、Domino Directoryのサーバー設定文書で行うことも可能です）。

Log_AgentManager = 値

値には、次のいずれかを指定できます。

値	説明
0	ロギングを表示しません
1	部分的な成功および完全な成功を表示します。
2	完全な成功を表示します。

Log_AgentManager設定は、Debug_AMgrが生成するデバッグ情報の一部を提供します。この場合、出力される内容は少なくなりますが、パフォーマンスに対する影響も少なくなります。問題のあるエージェントが存在する場合には、追加の情報をログに記録するために常にLog_AgentManagerを有効にします。Log_AgentManagerとDebug_AMgrの両方を指定した場合は、Debug_AMgr設定が優先されます。

バックグラウンド・エージェント（その名が示すとおりのものです）は、ユーザー・インターフェース（UI）に対して出力を生成することはできません。バックグラウンド・エージェント（印刷ステートメントなど）によって生成される出力はすべて、サーバー・コンソールとNotes Logの［Miscellaneous Events］ビューに表示されます。また、エージェントの代わりに生成されるエラー・メッセージと警告メッセージについても同様です。そのため、サーバー・コンソールまたはNotes Logでこの情報を確認することが重要です。

また、サーバーのNotes.iniファイルにDebug_Outfile設定を追加することによって、サーバー・コンソール・メッセージをテキスト・ファイルに記録することもできます。たとえば、「Debug_Outfile="C:\mydebug.txt"」は、「mydebug.txt」というファイルにコンソール・メッセージを出力するようサーバーに指示します。場合によっては、Notes Logやサーバー・コンソールでエントリーを調べるよりも、このファイルを検索する方が簡単かもしれません。ただし、I/Oが増えるとパフォーマンスに悪影響が生じる可能性があることを念頭に置いてください。

定期ローカル・エージェントを実行している場合、デバッグ情報はサーバー・コンソールに表示されません。なぜなら、Agent Managerコードはサーバー上ではなく、クライアント上でローカルに実行されるからです。この場合、クライアントのNotes.iniファイルにDebug_Outfile設定を追加すれば、テキスト・ファイルに情報を出力できます。このテキスト・ファイルは、ワークステーション上でローカルに作成されます。

エージェントに影響するNotes.ini変数の詳細については、LDD TodayのDecember issue（英語）のAsk Professor INIコラム『Agent variables』（英語）をご覧ください。さらに、記事『Minimizing delays in the Agent Manager』（英語）もご覧ください。

上に戻る

ルーターおよびWebエージェントによって生成されるエラー・メッセージ

はじめに述べたように、エージェントを実行できるプロセスはAgent Managerだけではありません。このセクションでは、ルーターおよびWebエージェントで診断情報を表示する方法について取り上げます。

ルーターは配信前エージェントを実行するため、Agent Managerのロギングとデバッグに関するNotes.ini設定の影響を受けません。その代わりに、サーバー設定文書の［ルーター/SMTP］-［詳細］-［制御］タブの［ログ詳細度］フィールドを使用して、サーバー・コンソールに出力される配信前エージェントのエラー・レベルを制御します。［詳細度］フィールドは、［最小］、［普通］（デフォルト）、［詳細］、または［より詳細］に設定できます。

ログ・レベルの設定

［より詳細］を選択した場合、エージェントのエラーはコンソールにロギングされます。ただし、すべてのルーターの動作に関する非常に冗長な出力も生成されます。この別個の設定を使用して配信前エージェントの出力を制御することによって、ルーターのパフォーマンスをチューニングできると同時に、他の操作に関する必要な程度の出力を他のエージェントに生成させることができます。配信前エージェントからサーバー・コンソールへの出力は、以下の例に示すように「Addin:」が接頭部として付きます。

Addin: Agent message box: Message generated by mail pre-delivery agent.

このようになるのは、メッセージがRouterタスク（API呼び出しによってエージェント・ルーチンを実行する）によって生成され、Routerタスクがサーバー・アドインであるためです。エージェントによってブラウザーに戻されるエラーのデフォルト設定では、Notes/Dominoエラーは表示されず、一般的なエラー・メッセージ（「HTTP 500 ‐ 内部サーバーエラー」）が表示されます。Web開発者は、Microsoft Internet Explorerを開き、［ツール］-［インターネットオプション］-［詳細設定］を選択し、［HTTP エラーメッセージを簡易表示する］チェックボックスを選択解除することによって、より意味のあるエラー・メッセージが表示されるようにすることができます。そうすると、Dominoによって生成される実際のエラー・メッセージが表示されるようになります。

上に戻る

NotesLogクラスによるデバッグ

NotesLogクラスを使用すると、情報をエージェント・ログに出力できます。これは、LotusScript/Javaエージェントのデバッグの際に役立ちます。エージェント・ログは、エラー処理や変数値の検査はもちろん、エージェントのロジックの確認にも有用なツールです。たとえば、目的の文書がエージェントの検索ビルダーによって選択されているかどうかを確認できます。

次のコードは、すべての未処理文書を処理し、各文書のタイトルをエージェント・ログに記録するLotusScriptエージェントの例です。ボールド体で示されている4行が、エージェント・ログを生成するコードです。

Dim agentLog As New NotesLog("Agent log")
Call agentLog.OpenAgentLog
Set s = New NotesSession
Set db = s.CurrentDatabase
Set collection = db.UnprocessedDocuments
Set note = collection.GetFirstDocument
count = collection.Count
Do While (count > 0)
Subject = note.Subject
Call agentLog.LogAction( "Processing: "+Subject(0))
Set note = collection.GetNextDocument (note)
count = count - 1
Loop
Call agentLog.Close

生成されたログを確認するには、エージェントを選択し、［エージェント］-［ログ］を選択します（あるいはエージェントを右クリックし、［ログ］を選択します）。次の図は、サンプル・エージェントによって生成されたエージェント・ログを示しています。

エージェント・ログにエラーを記録するのとは別の方法として、テキスト・ファイルにエラーを書き込むこともできます。次のコードは、ファイルにエラーを書き込むエラー・ハンドラーの例です。

On Error DivisionByZero Goto LogError
Dim errorLog As New NotesLog( "Errors" )
Dim x As Integer, y As Integer, z As Integer
Call errorLog.OpenFileLog( "c:\errlog.txt" )
y = 13
z = 0
rem The following line will generate an error for this example
x = y / z
Call errorLog.Close
Exit Sub
LogError:
Call errorLog.LogError( ErrDivisionByZero, Error$( ErrDivisionByZero ) )
Resume Next

上に戻る

サーバー・コンソールでのデバッグ

次のサーバー・コマンドは、Domino 5またはDomino 6でエージェントの問題をトラブルシューティングする際に役立ちます。

Tell amgr schedule
Tell amgr status
Tell amgr debug

Domino 6には、さらに次のコマンドがエージェントの問題のトラブルシューティング用として用意されています。

Tell amgr run
Tell amgr cancel
Tell amgr show agents
Load amgr -?

Tell amgr schedule
Tell amgr scheduleコマンドは、現在のスケジュール期間に実行が予定されているすべてのエージェントのAgent Managerスケジュールを表示します。現在のスケジュール期間の開始は、サーバー・レコードに「キャッシュ更新時刻」として定義されます。現在のスケジュール期間は一定ではなく（つまり、1日の任意の時点から24時間前を指すのではなく）、24時間から開始してゼロまでカウントダウンし、ゼロになった時点で次の24時間のスケジュールが作成されます。現在のスケジュール期間に新しくスケジュールされたエージェントはスケジュールに追加されますが、Agent Managerは現在のスケジュール期間に実行が予定されていないエージェントは追跡しません。この方法によって、Agent Managerは最も効率的に実行予定キューを処理できるようになっています。

Tell amgr scheduleコマンドは、エージェント・トリガーの種類、エージェントの実行予定時刻、エージェント名、およびエージェントが実行されるデータベース名を表示します。Agent Managerのスケジュールを調べれば、エージェントがAgent Managerの3つのキューのいずれかで待ち状態になっているかどうかを確認できるため、デバッグに役立ちます。

キュー	名前	説明
E	実行可能	実行可能なエージェントが置かれるキュー
S	実行予定	実行予定のエージェントが置かれるキュー
V	イベント	イベントの発生を待っているイベント駆動型のエージェントが置かれるキュー

定期エージェントは、S（実行予定）キューに置かれ、実行予定の時刻になると、E（実行可能）キューに置かれます。イベント駆動型エージェント（新規メールおよび文書の作成／編集エージェント）は、トリガーとなるイベントが発生するまでV（イベント）キューに置かれ、イベントが発生するとまずSキューに移動し、最終的にEキューに移動します。
また、トリガーには次の3種類があります。

トリガー	説明
S	指定時刻にエージェントを実行
M	新規メールの受信時にエージェントを実行
U	文書の新規作成／更新時にエージェントを実行

以下は、Tell amgr scheduleコマンドの出力例です。

E	S	04:03 PM Today	agent1	SALES.NSF
S	S	05:04 PM Today	agent2	SALES.NSF
V	U		agent3	SALES.NSF

出力の最初の列は、Agent Managerキューの種類です。2列目は、エージェント・トリガーの種類です。残りの列には、エージェントの実行予定時刻、エージェント名、およびデータベース名が表示されます。

この出力例では、agent1はEキューに移動された定期エージェントであり、Agent Managerが処理可能な状態になると直ちに実行されます。agent2は、Sキューで指定時刻になるのを待っている定期エージェントです。agent3は、Vキューで文書の作成または編集を待っているイベント駆動型エージェントです。

通常、キューへのエージェントの表示、およびあるキューから別のキューへのエージェントの移動には、1分程度かかります。スケジュールを制御するさまざまな要因の詳細については、LDD Todayの記事『Minimizing delays in the Agent Manager』（英語）をご覧ください。

Tell amgr status
Tell amgr statusコマンドは、Agent Managerの状況のスナップショットを表示します。Agent Managerのキューや制御パラメーターの状況を調べることができます。このコマンドを使うと、現在どのパラメーターが有効なのかを確認できます。以下に、出力例を示します。

12/26/02 10:30:15 AM AMgr: Status report at '12/26/02 10:30:15 AM'
12/26/02 10:30:15 AM Agent Manager has been running since '12/22/02 02:18:25 PM'
12/26/02 10:30:15 AM There are currently '1' Agent Executives running
12/26/02 10:30:15 AM There are currently '4' agents in the Scheduled Task Queue
12/26/02 10:30:15 AM There are currently '0' agents in the Eligible Queue
12/26/02 10:30:15 AM There are currently '0' databases containing agents triggered by new mail
12/26/02 10:30:15 AM There are currently '0' agents in the New Mail Event Queue
12/26/02 10:30:15 AM There are currently '3' databases containing agents triggered by document updates
12/26/02 10:30:15 AM There are currently '3' agents in the Document Update Event Queue
12/26/02 10:30:15 AM AMgr: Current control parameters in effect:
12/26/02 10:30:15 AM AMgr: Daily agent cache refresh is performed at '12:00:00 AM'
12/26/02 10:30:15 AM AMgr: Currently in Daytime period
12/26/02 10:30:15 AM AMgr: The maximum number of concurrently executing agents is '1'
12/26/02 10:30:15 AM AMgr: The maximum number of minutes a LotusScript/Java agent is allowed to run is '10'
12/26/02 10:30:15 AM AMgr: The maximum percentage of time agents are allowed to execute is '90'
12/26/02 10:30:15 AM AMgr: Executive '1', total agent runs: 414
12/26/02 10:30:15 AM AMgr: Executive '1', total elapsed run time: 273

Tell amgr debug
Tell amgr debugコマンドを使うと、Agent Managerの現在のデバッグ設定を表示したり、新しい値を設定したりすることができます。このコマンドでデバッグ値を設定する場合、先に説明したNotes.ini設定のDebug_AMgrと同じフラグを使用できます。これらの設定は、Agent Managerやサーバーを再起動しなくても直ちに適用されます。
デバッグ設定を設定する場合は、次のように入力します。

>tell amgr debug *
02/12/98 02:03:14 PM AMgr: Current debug control setting is 'mecvrspl'

現在のデバッグ設定を確認する場合は、引数を付けずにコマンドを入力します。

>tell amgr debug
02/12/98 02:03:15 PM AMgr: Current debug control setting is 'mecvrspl'

デバッグ・モードを無効にするためのコマンドはありませんが、次のいずれかの方法で同様の結果を得ることができます。

デバッグ・モードを［より詳細］以外にリセットする（この例では、エージェントの制御パラメーターを出力する「c」を選びました）

>tell amgr debug c
10/21/02 21:00:01 PM Amgr: Current debug control setting is ‘c’
Agent Managerを終了し、再ロードする

Tell amgr run
"データベース名" 'エージェント名'（Notes/Domino 6のみ）
このコマンドは、エージェントを別のスレッドで実行します。コンピューターの能力上の制限がない限り、同時に実行できるエージェント数に制限はありません。エージェントは、あたかもスケジュールどおりに呼び出されたかのように、サーバー・ベースのエージェントのすべてのルールに従って実行されます。つまり、（優先される）［代理で実行］フィールドに値が入力されていない限り、署名者の権限で実行されます。このコマンドは、システム管理タスクやサーバー・ベースのエージェントのテストを実行する方法として便利です（エージェント名は単一引用符で囲まなければならない点に注意してください）。

Tell amgr cancel
"データベース名" 'エージェント名'（Notes/Domino 6のみ）
このコマンドは、Agent Managerによって現在実行中の定期エージェントを中止します。HTTPやルーターなど、他のプロセスによって実行されるエージェントはキャンセルされません。ただし、リモート・デバッグを使用する場合は、すべてのプロセスによって実行されるエージェントをキャンセルできます。また、サード・パーティー・アプリケーションがハングし、制御がNotesに戻らない場合には、エージェントをキャンセルすることはできません。

Tell amgr show agents "データベース名" [-v]（Notes/Domino 6のみ）
このコマンドの簡略形式（「v」を付けない形）では、個人エージェント、共有エージェント別のデータベース内のエージェント名と総数が表示されます。詳細形式（「v」を付けた形）では、すべてのエージェントとスクリプト・ライブラリーがそれぞれの追加情報と共に表示されます。追加情報として、エージェントの記述言語、署名者、有効なユーザーが表示されます。この情報は、セキュリティーの問題をデバッグする際に役立ちます。

Load amgr -?'（Notes/Domino 6のみ）
このコマンドは、Agent Managerのヘルプ索引を返します。

上に戻る

一般的なエージェントの問題

次に、エージェントの開発時に遭遇する一般的な問題と考えられる解決策について考えてみることにしましょう。

エージェントが、UIからは実行できるが、定期エージェントとしては実行されない。
これは通常、（1）セキュリティーの問題、または（2）エージェントのUIクラスが原因です。エージェント・セキュリティーの詳細については、サイドバー「Notes/Domino 6 agent security at a glance」（英語）および「Notes/Domino 5 agent security at a glance」（英語）をご覧ください。

バックエンド・クラスはNotesデータベースに対する操作を実行し、フロントエンド・クラスはUI（NotesUIWorkspace、NotesUIDatabase、NotesUIView、NotesUIDocument）を処理します。バックエンド・クラスは、場所に関係なく（バックグラウンドとフォアグラウンドのどちらでも、またサーバーとワークステーションのどちらでも）実行できます。フロントエンド・クラスは、ワークステーション上でフォアグラウンドでのみ実行できます。

Notes/Domino 6より前は、バックグラウンド・エージェントでUIクラスを使用すると（たとえNotesUIWorkspaceのDimステートメントのみの場合も）、エージェントはバックグラウンドで実行されませんでした。いずれかのフロントエンド・クラスへの参照を含むエージェントをバックグランドで実行した場合、UIクラスが見つからないため、エージェントは実行されませんでした。これが、エージェントがロード時に失敗する原因となっていました。ロード・エラーは、プログラム内で見つけることができないため、デバッグが困難です。サーバー・コンソールやサーバー・ログにエラーは表示されますが（不明なLotusScriptエラーまたは「USEまたはUSELSXモジュールのロード・エラーです」）、ユーザーによってはサーバー・ログにアクセスする権限がなかったり、ログを調べるという考えに至らなかったりします。

Notes/Domino 6は、デバッグしやすい方法でバックグラウンド・エージェントのUIクラスを処理します。Notes/Domino 6では、エージェントのロード中ではなく、UIオブジェクトが作成された時点でエラーが生成されるようになりました。これは、UIクラスを参照するDimステートメントを含めることが許されることを意味します。UIオブジェクトの作成中に、ランタイム・エラー（エラー217：ErrAdtCreateError）が生成されますが、これはランタイム・エラーであるため、簡単なエラー処理ルーチンによってこの状態を見つけることができます。つまり、このエラーを処理しさえすれば、クライアントでもサーバーでも実行するエージェントを作成できるということです。
以下は、そのようなエラー・ハンドラーの例です。

Function MayIUseFEClass() As Boolean
' error defined in lserr.lss
' Public Const ErrAdtCreateError = 217
On Error 217 Goto NoYouMayNot
Dim uiws As NotesUIWorkspace ' declare front-end class

Set uiws = New notesuiworkspace

MayIUseFEClass = True
Exit Function
NOYOUMAYNOT:
MayIUSEFEClass = False
Exit Function
End Function

制限なしエージェントが動作しない（Notes/Domino 6のみ）
制限なし署名者によって署名され、R5で正常に動作するエージェントをDomino Designer 6で編集すると、動作しなくなります。この場合、［エージェント］プロパティー・ボックスの［セキュリティー］タブで、実行時セキュリティレベルの設定を確認してください。

エージェント・プロパティーのセキュリティー・タブ

Domino Designer 6で編集されていないエージェントは、Domino 6サーバー上では、R5の場合と同様に署名者の権限で実行されます。したがって、制限なし署名者の場合、エージェントは制限なしの権限で実行されます。しかし、エージェントをDomino Designer 6で編集した場合、デフォルト設定は［制限された操作を許可しない］（より安全な設定）となります。Domino Designer 6でエージェントを編集した後にそのエージェントで制限なしの操作を実行したい場合は、このセキュリティー設定を明示的に設定する必要があります。

定期エージェントがクライアントのレプリカ上で動作しない
定期ローカル・エージェントは、デフォルトでは無効です。クライアント上で定期エージェントを有効にするには、［ファイル］-［プリファレンス］-［ユーザー］を選択し、［定期ローカル・エージェントの有効化］をチェックします。

メール・エージェントが動作しない
「新規メールが届いたとき」エージェントは、エージェント所有者（署名者）のホーム・メール・サーバー上で実行するように設計されています。エージェントをホーム・メール・サーバーから他のシステムに複製した場合や、他の誰かによって作成されたエージェントを実行しようとしている場合、ホーム・メール・サーバーとメール・エージェントを実行しようとしているサーバーが一致しないため、エージェントは動作しません。次の設定をサーバーのNotes.iniファイルに追加することによって、ホーム・メール・サーバーのチェックが行われないようにすることができます（R4.5以降でサポートされています）。

AMgr_DisableMailLookup =value

値は、0（ホーム・メール・サーバーをチェックする）または1（ホーム・メール・サーバーをチェックしない）です。デフォルトは「0」です。
エージェントがホーム・サーバー上でのみ実行されるようにするチェックが行われないようにすることによって、複数のサーバー上でエージェントを実行させることができます。エージェントのロジックにもよりますが、エージェントを複数のサーバー上で実行できるようにした場合、複製競合が発生したり、同じロジックが何度も処理されたりする可能性があります。

ルーターによって実行される「新規メールの受信前」エージェントは、メールの配信先サーバー上で実行されます。このトリガーの場合、ホーム・メール・サーバーの概念は適用されません。
AMgr_DisableMailLookupは、配信前エージェントには影響しません。

配信前エージェントと配信後エージェントは共に、実行先のサーバーを決定するためにエージェント内に保存されているサーバー名を使用しません。そのため、［エージェント］プロパティー・ボックスのサーバー名を設定するオプションは利用できません。

「バックグラウンド・エージェントまたは組み込みエージェントでサポートされないトリガーおよび検索」とはどのような意味か
このエラーは、エージェント・ビルダーのトリガー／検索対象設定としてUI要素を参照するサーバー・ベースのエージェント（Webエージェントまたはサーバー上で呼び出されるその他のエージェント）または組み込みエージェント（他のエージェントによって呼び出されるエージェント）で生成されます。たとえば、［アクションメニューから手動で］をトリガーとし、［すべての選択文書］を検索対象とするエージェントを作成するとします。このエージェントをブラウザーで呼び出すと、「…サポートされないトリガー」エラーが表示されます。「すべての選択文書」という概念は、Webエージェントでは理解されず、この設定はNotesクライアントでのみ意味を持ちます。この問題を修正するには、対象の設定を［すべての文書］や［なし］に変更します。この状況では、次の4つのオプションはサポートされません。

ビューのすべての未読文書
ビューのすべての文書
すべての選択文書
貼り付けられた文書の場合

MAIL.BOXで定期エージェントが動作しない
MAIL.BOXデータベースに作成した定期エージェントまたはイベント駆動型エージェントは、決して自動的に実行がスケジュールされることはありません。これは、MAIL.BOXが内部データベースであるため、通常のデータベースとして扱われず、スケジュールされたタスクがAgent Managerによってスキャンされないことによります。MAIL.BOXデータベースの文書は、本質的に一時的なものであり、ごく短い期間だけデータベース内に置かれます。Agent Managerがキューを確認する頻度は1分間隔以上であるため、MAIL.BOXの一部の文書はまず間違いなく、「.BOX」データベースに対して実行が許可されている定期エージェントに認識されないことになります。

実行権限が与えられているユーザーが実行を拒否される
ご存じのとおり、ユーザーへの実行権限の付与は、サーバー文書の［セキュリティー］セクションの［プログラムの制限］フィールドで行います。これらのフィールドには、最大256文字という制限があります。256文字を超える名前はサーバーによって認識されず、それらのユーザーは適切な実行権限を持たないものとして拒否されます。フィールドの編集中にこの制限を超えると、警告が表示されます。この警告はまた、Agent Managerの実行中に定期的に表示されます。サーバー・コンソールでは、次の警告が表示されます。

12/12/02 14:05:45 AMgr: Agent execution ACL is longer than 256 characters. Use groups.

この問題を解決するには、［エージェントの制限］フィールドでグループ名を使用します。

何かがエージェントを無効にしてしまう
Design Updateタスクは、データベース・テンプレートからデータベース設計を更新するシステム・プロセスです。このタスクの目的は、データベースとテンプレートの同期を維持することです。データベースとテンプレートのいずれかが変更され、ユーザーが特定の設計要素に対して［更新しない］設計プロパティーを選択していない場合、Design Updateタスクはテンプレートと一致するようにデータベースを更新します。これは、一般に「夜中に何かが有効なエージェントを無効にしてしまう」と言われるエージェントの問題の原因となる場合があります。

これは、ユーザーがデータベース内のエージェントに大幅な変更を加えていることが原因で発生します。「大幅な変更」とは、エージェントの有効／無効状態やエージェントの実行がスケジュールされているサーバー名以外の変更を指します。この問題の原因として最も一般的なのはエージェントのスケジュールの変更ですが、エージェントのコードやエージェントの設計の他の部分の変更も原因となる可能性があります。

Notes/Domino 6より前は、Design Updateタスクはテンプレートだけでなくデータベースの変更も認識するようになっていましたが、Notes/Domino 6ではテンプレートの変更のみを追跡するようになりました。これによって、テンプレート自体に何らかの大幅な変更を加えない限り、データベースに変更を加えて保持できるようになりました。ただし、テンプレートに加えた変更が優先されます（テンプレートの変更は通常、バグ・フィックスやその他の管理上の変更を意味するためです）。テンプレートを使用してデータベースを更新すると、エージェントはテンプレート内のバージョンに戻され、通常は無効化されます。

［エージェント］プロパティー・ボックスの［更新時に再設計／設計の置換を許可しない］オプションを選択することによって、エージェントの設計の更新が行われないようにすることができます。

テンプレートからエージェントを更新すると、テンプレートのエージェント（テンプレート内の署名を含めて）がユーザー・データベースのエージェントに置き換わるため、エージェントの無効化が必要になります。エージェントが無効化されるのは、ユーザーに署名を強制し、それによって適切なセキュリティー権限でエージェントが実行されるようにするためです（そうしないと、たとえばLotus Notesテンプレート開発者からメールが来るといった好ましくない事態が発生することになります）。サーバー上にユーザーIDファイルは存在しないため、自動的にユーザーIDでエージェントを再署名することはできません。サーバー上にあるのはサーバーIDだけですが、サーバーIDの下でエージェントを実行することも好ましくありません。

サーバー・ベースのエージェントを直ちに実行したい
AgentクラスのRunOnServerメソッドを使用すれば、サーバー・ベースのエージェントを呼び出すフォアグラウンド・エージェントを作成し、そのフォアグラウンド・エージェントをクライアント・インターフェースを介して実行することで、サーバー・ベースのエージェントをサーバー上で実行させることができます。それには、次のコードを使用します。

agent.RunOnServer(),

agentは、サーバー上で実行したいエージェントです。呼び出しは同期して行われるため、エージェントが完了してからワークステーションに制御が返されます。このエージェントは、それが置かれているデータベースと同じサーバー上で実行されます。この方法の利点の1つは、データベース操作を実行するエージェントの場合でも、データベース・ソフトウェアのコピーをクライアント上に置く必要がないことです。
このタイプのエージェントのワークステーション・コンポーネントは、サーバー・コンポーネントとはセキュリティーの点で異なります。各コンポーネントは、次のルールのいずれかに従います。

ワークステーション上で動作する呼び出し側エージェントの場合、ACL権限は起動者の権限によって決定され、エージェントの制限は使用されない。
サーバー上で実行される呼び出し先エージェントの場合、ACL権限は署名者（Notes/Domino 6では［代理で実行］に指定されたユーザー）に基づき、エージェントの制限はそのエージェントの署名者に基づいて決定される。

エージェント・セキュリティーの詳細およびエージェント実行時に影響を与える方法については、サイドバー「Notes/Domino 5 agent security at a glance」（英語）および「Notes/Domino 6 agent security at a glance」（英語）をご覧ください。

Notes/Domino 6のもう1つの新しいオプションとして、エージェントを実行するサーバー・コンソール・コマンドを発行することができます。このコマンドは、サーバー・コンソールから、またはプログラムで発行できます。

Tell amgr run "データベース名" 'エージェント名'

エージェントが生成するメールの見かけ上の送信者を変更するにはどうすればよいか
場合によっては、自分のIDとは別のIDでメールを生成する必要があります。たとえば、ユーザー「Domino Administrator」でメールを生成したい場合、次の3つの方法があります。

ユーザー「Domino Administrator」に対して特殊IDを作成し、そのIDでエージェントに署名する
エージェント・コードの［Principal］フィールドを使用して［From］フィールドを指定変更する
［代理で実行］フィールドを使用する（Notes/Domino 6の新機能）

最初の方法は、コーディングが不要なため最も簡単ですが、ただし、IDの付与と保守が必要です。2番目の方法はより柔軟ですが、多少のコーディングが必要です。特殊な権限は必要ありませんが、監査のために元の送信者に関する情報は保持されます。メール・テンプレートのデフォルトでは、［From］フィールド以下の［送信者］フィールドに元の送信者名が表示されます。［Principal］フィールドの指定方法は、次の3通りです。
doc.Principal="Joe User/Org@NotesDomain"
Joe User/Orgが、［InternetAddress］フィールドに目的のアドレスが指定されたユーザー文書を持っている場合（ストリング「@NotesDomain」が必要）
doc.Principal="CN=Joe User/O=Org"
Joe User/Orgが、［InternetAddress］フィールドに目的のアドレスが指定されたユーザー文書を持っている場合
doc.Principal=User@acme.org@NotesDomain
<mailto:User@acem.org@NotesDomain>（ストリング「@NotesDomain」が必要）

ReplyToアドレスのみに関心がある場合、FromとReplyToの両方を変更する［Principal］フィールドではなく、［ReplyTo］フィールドを使用できます。

Sub Initialize
Dim session As New NotesSession
Dim db As NotesDatabase
Dim view As NotesView
Dim doc As NotesDocument
Dim item As NotesItem
Dim ToWho(40) As String
Dim FirstName(40) As String
Dim Msg As String
Set db = session.CurrentDatabase
Set doc = New notesdocument(db)
**********************************************************

Count = 30
ToWho(0)="joe@yahoo.com"
FirstName(0)="Joe"

ToWho(1) = "teresa@yahoo.com"
FirstName(1)="Teresa"

<more initialization code removed>

doc.Principal = "julie@yahoo.com@NotesDomain"
doc.Form = "Memo"

doc.Subject=" Happy Holidays!"
For i=0 To count
Greet = "Hi " +FirstName(i) +", Happy Holidays!"
Msg1 ="additional text"
doc.Body=Greet + Msg1
Print toWho(i)
Call doc.Send(True,toWho(i))
Next

前のコードで示したように、@NotesDomainは構文に必要なストリングです。これを省略すると、多くの場合、［Principal］フィールドがうまく機能しないという問題が発生します。

3番目の方法（［代理で実行］）は、Notes/Domino 6の新機能です。［エージェント］プロパティー・ボックスのこのフィールドを使用すれば、あたかも他のユーザーによって呼び出されたかのようにエージェントを実行できます。他のユーザーの代理でエージェントを実行するには、特殊な権限が必要です。これらの権限は、サーバー文書の［セキュリティー］タブの［代理で実行する署名エージェント］フィールドで制御されます。ユーザーがこの許可を持っている場合、メールは［代理で実行］フィールドに指定された名前から来たように見えます。これは、非常に高いレベルの権限であり、データベースにアクセスする際のACL権限を含めて、他のユーザーの代理のエージェントの実行をユーザーに許可することになるため、慎重に使用する必要があります。

エージェントの実行場所であるデータベース以外のサーバー上のデータベースにアクセスするにはどうすればよいか
Notes/Domino 6より前は、エージェントを介したリモート・サーバーへのアクセスは、クライアント・エージェントおよび定期ローカル・エージェントで、またCORBAリモート呼び出しJavaバックエンド・クラスおよびDIIOPを介してサポートされていました。しかし、Dominoには、サーバー上でユーザーの権限で実行されるエージェントをリモート・サーバーとの間で適切に認証するためのセキュリティー・プロトコルがありませんでした。したがって、APIルーチンでリモート・サーバーにアクセスするコードを記述することは可能とはいえ、セキュアに実行できなかったため、エージェントでそうした操作を行うことはできませんでした。

Notes/Domino 6には、これを可能にする新しいセキュリティー・プロトコルが追加されています。エージェントがアクセスしたいデータを含むサーバーは、エージェントが実行されているサーバーに対してこの許可を与える必要があります。このレベルの信頼は、Domino Directoryの新しい［Trusted servers］フィールドで設定します。

「新規メールが届いたとき」と「文書が作成または更新されたとき」の違いは何か
違いは、メール・ベースのトリガーがメールの構成要素を理解しており、ドラフトや送信メールなどのアイテムを選択しないことにあります。これらのトリガーは、新規に更新された受信メールを選択しますが、これは状況によって必要になるためです（たとえば、メールがルーター経由で受信されるのではなく、メール・データベースに複製される場合など）。これが目的の動作ではない場合、最初に処理する際に文書にフラグを付け、次回以降は無視するエージェントを作成できます（これが必要になるのは、新規受信メールの更新が見込まれる場合だけです）。
「配信前エージェント」は、ルーター経由で配信されるメールのみに対して動作する点に注意してください。

［新規メールが届いたとき］エージェントと［文書が作成または更新されたとき］エージェントが、予想以上の数の文書を処理するのはなぜか
このタイプのエージェントは、次の場合に文書を再処理します。

エージェント自体が変更され、再保存された場合（エージェントのロジックが完全に変更されている可能性があるため）
エージェントが処理中の文書が変更された場合

エージェントが原因で複製競合が発生する
エージェントによって発生する複製競合は、他の原因で発生する複製競合と何ら違いはありません。原因は、複数のエンティティー（ユーザー、プロセス、またはエージェント）が同じ文書を同時に更新したことです。以下に、一般的なチェックすべき点をいくつか示します。

エージェントの実行場所であるサーバーとして、ワイルド・カード「すべてのサーバー」が指定されていないか
Notes.iniファイルに変数「AMgr_DisableMailLookup」を含み、ホーム・メール・サーバーのチェックが行われないようになっている（したがって、複数のサーバーでエージェントを実行することが可能になっている）サーバー上で、［新規メールが届いたとき］エージェントを実行していないか
サーバー・ベースのエージェントと同じ文書を更新するエージェントがローカル・レプリカに対して設定されていないか
複数のイベント駆動型エージェントが同じ文書を更新していないか（たとえば、QueryOpenとQuerySave）

エージェント・キューが停滞している（Notes/Domino 6のみ）
Webエージェントの実行に通常よりも時間がかかるように感じられたり、エージェント・キューが停滞しているような場合、リモート・デバッグが有効になっているかどうかを確認してください。リモート・デバッグを有効にすると、各エージェントは実行開始前に一時停止します。（この一時停止は、デフォルトでは1分間であり、増減が可能です）。リモート・デバッグを有効にしたことを忘れている場合、エージェントがなぜか遅く感じられるかもしれません。現在のところ、リモート・デバッグが実行前に一時停止している時間はサーバー・ログに記録されません。このメッセージは、次のメンテナンス・リリースで追加される予定です。

上に戻る

複数のサーバーへの展開

複数のシステムへの展開を目的とするエージェントを作成する場合、次のような問題が発生することがあります。

展開する必要のあるサーバー名が開発サーバーの名前とは異なる。また、それらのサーバー名が事前にわからない場合がある。
エージェント開発者の署名がエンド・ユーザーの署名と異なる。
開発サーバーに運用サーバーと共通の証明書がない。

以下、最初の2つの問題を解決する、つまり証明書の問題を無関係にするためのいくつかの方法を考察します。

サーバー名の変更
エージェントを作成する際、エージェントの実行が想定されるサーバー名は、エージェント内に保存します。デフォルトでは、サーバー名はエージェントの開発を行うサーバーです。別のサーバーでエージェントを実行する場合、サーバー名を変更する必要があります。これには3通りの方法があります。まず1つめの方法は、エージェントを「無効」として展開することです。それには、［エージェント］プロパティーボックスの［スケジュール］ボタンをクリックし、［エージェントが有効になったときにサーバーを指定］を選択します。ユーザーが初めてエージェントを有効にしたときに、エージェントを実行するサーバー名を選択するためのプロンプトが表示されます。

2つめの方法は、エージェントがすべてのサーバー上で実行できるように指定することです。それには、［エージェント］プロパティーボックスの［スケジュール］ボタンをクリックし、［実行場所］フィールドで［すべてのサーバー］を選択します。ただし、サーバー間に複製が設定されている場合、エージェントがそれらのサーバー上の同じ文書を更新すると、複製競合が発生する可能性があります。次の画面に、これら2つのオプションを示します。

エージェント実行スケジュール設定ダイアログ・ボックス

3つめの方法は、他のエージェントのサーバー名をプログラムで設定するエージェントを作成することです。これには、次のコードを使用します。

agent.ServerName="ServerName"
Call agent.save()

ServerNameは、新規サーバー名です。これは、データベースから読み込むか、あるいはエンド・ユーザーに入力させることができます。サーバー名を更新するには、エージェントを保存する必要があります。 Notes/Domino 6より前は、サーバー上で実行されているエージェントを他のエージェントが操作したり保存したりすることはできず、他のエージェントを保存するエージェントの実行はクライアント上でのみ可能でした。サーバー上で実行されているエージェントが他のエージェントを更新して保存しようとすると、次のエラー・メッセージが出されるようになっていました。

11/04/02 05:14:35 PM AMgr: Agent ('DoEnable' in 'test1.nsf') error message: Restricted operation on a server

これは、変更されるエージェントに関連付けられたユーザーIDをサーバー上に保存する手段が用意されていなかった（エージェントを再署名するためのユーザーIDがサーバー上に存在しなかった）ことによります。Notes/Domino 6では、適切な権限があればこの操作を行えるようになりました。双方のエージェントに同じ有効なユーザー（エージェントを実行できるユーザー）が設定されている場合、あるいはエージェントの署名者がその権限を持ち、［代理で実行する署名エージェント］フィールド（サーバー文書の［セキュリティ］タブの［プログラムの制限］セクションに追加された新しいフィールド）に指定されている場合、エージェントは他のエージェントを変更し、保存することができます。言い換えると、ユーザーは各自のエージェントの変更は特殊な権限がなくてもできますが、他のユーザーが作成したエージェントを操作するには特殊な権限が必要であるということです。

エージェントの署名
エージェントを開発する際、作成者の署名をエージェントに保存します。エージェントをユーザーの権限をバックグラウンドで実行できるようにするには、作成者の署名をユーザーの署名に置き換える必要があります。これには2通りの方法があります。どちらの方法も、エージェントを有効にすると、その操作を行ったユーザーの署名でエージェントが再署名されるということに基づいています。また、いずれの方法の場合も、エージェントを「無効」として展開する必要があります。1つめの方法は、エンド・ユーザーが［有効］チェックボックスをチェックすることによって、エージェントを手動で有効にすることに頼るというものです。

2つめの方法は、プログラムによるエージェントの有効化です。多数のエージェントを展開する必要がある場合は、この方法の方が適切と言えます。その場合、他のエージェントを有効にするエージェントを作成するのがよいでしょう。エンド・ユーザーがこのエージェントを実行すると、他のすべてのエージェントが有効になります。以下は、他のエージェントをプログラムによって有効化するためにエージェントに含める必要があるコードです。

agent.IsEnabled = True
Call agent.save()

IsEnabledプロパティーを更新するには、エージェントを保存する必要があります。前述のとおり、Notes/Domino 6より前は、サーバー上で実行されているエージェントを他のエージェントが操作したり保存したりすることはできず、他のエージェントを保存するエージェントの実行はクライアント上でのみ可能でした。Notes/Domino 6では、ユーザーに適切な権限がある限り、この制約はなくなりました。

上に戻る

まとめ

元の記事が公開されてから丸4年が経ちますが、エージェントのトラブルシューティングが多くのNotes/Domino開発者、管理者、およびユーザーにとって重要な関心事であることは今も変わりありません。この記事で説明したように、R4.6で利用できたヒントやテクニックの多くは現在も有用です。また、Notes/Domino 5および6では、考慮すべき新たな問題が増えていますが、その一方でエージェントが意図したようには動作しない原因の究明に利用できるツールも増えています。元の記事と同様に、この記事がエージェントの問題を分析する際にあらゆる点でお役に立てば幸いです。また、読者の皆さんが分析を行わなければならないような状況にはめったにならないことを願っております。

筆者について
ジュリー・カダシェヴィッチは、FTP SoftwareでJavaおよびC++モバイル・エージェント・テクノロジーに従事した後、1997年3月にIrisに入社しました。以前は、応用人工知能分野の研究に取り組み、その分野で5件の特許を取得しました。彼女は、ボストン大学で情報工学の学士号および修士号を取得しています。エージェント・マネージャーを別とすれば、主な関心事は写真撮影とキルティングです。

上に戻る

関連リンク


		Notes/Domino 6 agent security at a glance sidebar

		Notes/Domino 5 agent security at a glance sidebar

		Decoding the new Notes/Domino 6 agent features

		Minimizing delays in the Agent Manager

		Agent variables

		Controlling the agents in your system

		Troubleshooting agents (R4.6)

		Julie Kadashevich: Managing the Agent Manager