メッセージ・ファイルを使用する操作

メッセージ・ファイルは、幾つかのタイプの操作で使用されるメッセージのテキストを格納しています。表 9 に、メッセージ・ファイルを使用する操作のタイプと、これらの操作を実行する BaseDLM クラスのメソッドを示します。

表 145. メッセージを生成する操作
操作 関数ブロック メソッド
例外の生成 General/APIs/Maps/Exception/
Raise Map Exception
raiseException()

ロギング General/Logging and Tracing/Log
Information ID
General/Logging and Tracing/Log
error ID
General/Logging and Tracing/Log
warning ID
logInfo()


logError()

logWarning()

トレース General/Logging and Tracing/Trace/Trace on Level trace()

このセクションでは、メッセージを生成する操作のうち、マップの実行に影響を与えるものについて説明します。

例外の生成

raiseException() メソッドには幾つかの形式があります。以下は、一般的に使用される構文の例です。

raiseException(String exceptionType, 
    int messageNum, String param[,...])
 

この構文では、1 つから 3 つの param String パラメーターを指定できます。したがって、1 つの raiseException() 呼び出しに、最大で 5 つまでのコンマで区切ったパラメーターを指定できます。

この例では、メッセージ番号 23 を使用して新しい例外を発生させ、顧客 ID およびストリングが 2 つのパラメーターとしてメッセージに渡されます。

raiseException(AttributeException, 23,
    fromCustomer.getString("CustomerID"), 
    "greater than maximum length");
 

図 136 に、メッセージ 23 のテキストを、メッセージ・ファイルに格納されている形で示してあります。

ロギング・メッセージ

マップは、管理者に関係があると考えられる事態が発生するたびにメッセージを記録できます。マップは、メッセージを記録する場合、BaseDLM クラスの logInfo()logWarning()、および logError() の各メソッドを使用します。 各メソッドには、さまざまなメッセージの重大度レベルが関連付けられています。

重大度レベル

メッセージを記録するためには、そのメッセージの重大度に対応するメソッドを呼び出す必要があります。表 146 に、重大度レベルとそれぞれのレベルに対応するメソッドを示します。

表 146. メッセージ・レベル
重大度レベル メソッド 説明
情報 logInfo() 情報のみ。ユーザーは何もする必要はありません。
警告 logWarning() 問題に関する情報を示します。このレベルは、ユーザーが解決する必要がある問題には使用しないでください。
エラー logError() ユーザーが調べる必要がある重要な問題を示します。

メッセージ・ファイルの使用

すべてのマップには、1 つ以上のメッセージ・ファイルが関連付けられている必要があります。マップでカスタム・メッセージが使用されない場合、そのメッセージはシステム・マップ・メッセージ・ファイル CWMapMessages.txt にあるメッセージです。マップでカスタマイズしたメッセージが使用される場合、そのマップはマップ固有のメッセージ・ファイル (Map Designer Express の「メッセージ」タブで入力されたメッセージから生成される) を持っています。詳細については、"メッセージの位置"を参照してください。

マップがエラーを記録する場合、エラー・メッセージのテキストにはマップのメッセージ・ファイルが使用されます。

例: 次の例では、マップのメッセージ・ファイルにテキストが格納されるエラー・メッセージを記録します。エラー・メッセージ 10 のテキストは、以下のようにメッセージ・ファイルに表示されます。

10 
 Credit report error for {1}, {2}. 
 

メッセージを記録するコードは、以下のようになります。

logError(10, customer.get("LName"), customer.get("FName");
 

logError() メソッドが実行されると、メッセージ 10 のテキストがログ・ファイルに書き込まれます。この場合、パラメーター 1 および 2 は顧客のラストネームおよびファーストネームに置換されます。

例: 顧客名が John Davidson である場合、記録されるメッセージは、以下のようになります。

Credit report error for Davidson, John.
 

理想的なメッセージ・ロギングの原則

メッセージを作成する場合、管理者がロギング機能を使用する方法は大変重要です。

重大度レベルの割り当て

メッセージに対するエラー・レベルの割り当ては、厳密に行う必要があります。 IBM システムの E メール通知機能では、エラー・メッセージや致命エラー・メッセージの生成が検出されたとき、指定された人 (通常は管理者) にメッセージを送信します。管理者は、この IBM システム E メール通知機能を使用しますが、さらに、エラーの発生時にページを送信する E メール・ページャーにリンクすることもできます。エラー・レベルをメッセージに正確に割り当てることにより、重大メッセージの数を減らすことができます。

メッセージの変更

例えば、テキストをわかりやすくしたり、拡張するために、メッセージのテキストをいつでも変更できます。ただし、ある一定のタイプのエラーにメッセージ番号を割り当てた後は、その番号の変更をしないということが重要です。多くの管理者はスクリプトを使用してログ・メッセージをフィルターに掛けています。ただし、これらのスクリプトはメッセージ番号に依存しています。このため、メッセージ・ファイルの番号の意味を変更しないことが重要です。番号が変更されると、ユーザーがメッセージを喪失したり、間違ったメッセージを受信することがあります。

情報メッセージを使用するタイミング

logInfo() メソッドを使用して、ユーザー独自のデバッグ用一時メッセージを作成できます。

ただし、開発が完了したら、これらのデバッグ・メソッド呼び出しは除去するようにしてください。

コラボレーションの通常操作を文書化する場合は、logInfo() メソッドを使用しないようにしてください。このメソッドを使用すると、管理者のログ・ファイルが関係のないメッセージでいっぱいになってしまいます。代わりに、trace() メソッドを使用して、管理者用のデバッグの詳細情報を記録してください。

トレース・メッセージの追加

トレース・メッセージをマップに追加することにより、マップ・インスタンスの実行時にそのアクションの詳細な説明が生成されるようにすることができます。トレース・メッセージは、ユーザー独自のデバッグや、管理者によるオンサイトのトラブルシューティングに役立ちます。

トレース・メッセージは、そのトレース・メッセージに含まれるログ・メッセージとは異なり、デフォルトでは削除可能となっています。ただし、そのログ・メッセージを削除することはできません。通常、トレース・メッセージの方がより詳細で、一定の状況下でのみ表示されるようになっています。例えば、あるユーザーがマップのトレース・レベルを意図的にゼロより大きい番号に構成した場合などがあります。トレース・メッセージとログ・メッセージは別のファイルに送信できます。

トレース・メッセージをマップに追加して、そのマップに固有の操作を報告できます。マップがトレース・ファイルに書き込むことが可能な情報のタイプを以下に示します。

トレース・レベルの割り当て

各トレース・メッセージには、1 から 5 までのトレース・レベルを関連付ける必要があります。トレース・レベルは通常、詳細の度合いと相互に関係があります。一般にレベル 1 のメッセージより、レベル 2 のメッセージの方がより詳細で、レベル 3 のメッセージの方がレベル 2 より詳細となっています。このため、レベル 1 のトレースをオンにした場合、レベル 5 のメッセージより詳細ではないメッセージが表示されます。ただし、レベルは必要なレベルに設定できます。

推奨: レベルの割り当てに関する提案事項を以下に示します。

特定のレベルでのトレースをオンにすると、特定のレベルに関するメッセージと、これ以下のレベルに関するメッセージが表示されます。例えば、レベル 2 のトレースの場合は、レベル 2 とレベル 1 に関するメッセージが表示されます。

ヒント:
トレース・レベルは、文書に記録して、ユーザーがトレースを行うときに使用すべきレベルがわかるようにしてください。

トレース・メッセージの生成

例: 以下は、メッセージと、メッセージを生成するメソッドの呼び出しの例です。メッセージは、以下のようにメッセージ・ファイルに表示されます。

20
 Begin transformation on {1} attribute: value = {2}
 

このメソッドの呼び出しは、属性 LName の値を取得し、この値を使用してメッセージのパラメーターを置換します。コードは、以下のようにマップに表示され、このメッセージは、ユーザーがトレースをレベル 3 に設定したときに表示されます。

trace(3, 20, "LName", customer.get("LName"));
 

トレース・レベルの設定

図 137 に、Map Designer Express の「マップ・プロパティー」ダイアログの「一般」タブを示します。 (「マップ・プロパティー」ダイアログの表示方法については、"マップ・プロパティー情報の指定"を参照してください。) このダイアログで、トレース・メッセージのトレース・レベルを設定することができます。



図 137. マップのトレース・レベル

マップの開発者が、"トレース・レベルの割り当て"の説明に従って、マップ生成のトレース機能を要求できるレベルを作成します。

注:
アクティブなマップのトレース・レベルを変更する場合は、マップを停止してから再始動した後、新しいトレース・レベルを有効にする必要があります。 System Manager の「コンポーネント」メニューを使用して、マップを停止して始動します。

Map Designer Express の「マップ・プロパティー」ダイアログでトレース・レベルを設定すると、このマップのマップ定義に従って、マップのすべての インスタンスを対象に、トレース・レベルを設定することになります。マップのすべてのインスタンスにトレース・レベルを設定する場合、System Manager の「マップ・プロパティー」ウィンドウから行うこともできます。

Copyright IBM Corp. 2004