Ensemble のプログラミング

概要

ビジネス・ホスト・クラスまたはアダプタ・クラスを作成する場合は、コールバック・メソッドを実装して、必要に応じて追加のメソッドを定義し、設定を追加または削除します。

ビジネス・ホストまたはアダプタ内では、メソッドが以下のタスクの一部または全部を実行します。

• ビジネス・ホストまたはアダプタのプロパティ値の取得または設定。

• コールバック・メソッドの定義。コールバック・メソッドは、デフォルトでは何もしない継承メソッドです。このメソッドを上書きして実装する必要があります。

• ビジネス・ホストまたはアダプタの継承ヘルパー・メソッドの実行。ヘルパー・メソッドは、他のメソッドによって使用されるメソッドの俗称です。

  ビジネス・オペレーションとビジネス・プロセス内のメソッドの多くが、プロダクション内の他のビジネス・ホストにメッセージを送信する継承メソッドを呼び出します。

• 発生したさまざまな状態に応じたログ、アラート、またはトレース通知の生成。以下の用語が使用されます。

  • ログ・エントリは、外部の物理的な問題 (ネットワーク接続の不具合など) のような項目を記録するためのものです。

    これらは自動的にイベント・ログに書き込まれます。

  • アラートは、定義してプロダクションに追加されたアラート・プロセッサ経由でユーザに警告するためのものです。

    これらも自動的にイベント・ログに書き込まれます。

  • トレース項目は、デバッグや診断の目的に使用するためのものです。これらは、プロダクションを展開する前にプログラム・エラーを特定するためなどに使用できます。イベント・ログとターミナルのどちらかまたは両方に書き込まれます。

  すべてのタイプのエラーやアクティビティによってこれらの通知が生成されるわけではありません。どの事象をどのように記録するかは、開発者が決めることです。プログラム・エラーはイベント・ログに登録するべきではないことに注意してください。これらはプロダクションをリリースする前に解決すべき問題です。

基本原理

Ensemble プロダクションに最適なプログラミング方法を理解しておくことが重要です。Ensemble ビジネス・ホストは別々のプロセス内で動作するため、次の点を確認しておく必要があります。

• ビジネス・ホストがシステム・リソースを割り当てる (ロックの取得やデバイスのオープンなど) 場合は、同じビジネス・ホストがそれらのリソースを解放する必要があります。

• ビジネス・ホストがトランザクションを開始する場合は、同じビジネス・ホストがトランザクションを完了するか、ロールバックする必要があります。

• ビジネス・ホスト間で共有される情報はすべて、(パブリック変数を介してではなく) ビジネス・ホスト間で送信されるメッセージ内に含める必要があります。

ビジネス・ルールとデータ変換についても、同様の考え方が適用されます。

また、Ensemble メソッドから受け取ったエラー・コードを頻繁に処理する必要があります。Ensemble 開発フレームワークは、エラー・コードに関してカスタム・コードを極力単純で直線的にできるように設計されています。以下に例を示します。

• ビジネス・サービスの OnProcessInput() メソッドと、ビジネス・オペレーションの OnMessage() メソッドとその他のユーザ作成 MessageMap メソッドが Ensemble フレームワークでラップされるため、コードに新たなエラー・トラッピングを追加する必要がありません。

• カスタムのビジネス・オペレーション・コードで使用できるアダプタ・メソッドでは、SendAlert() や SendRequestSync() などのカスタム・コードに使用できるフレームワーク・メソッドのように、絶対にトラップ・アウトしないように作成されています。また、アダプタ・メソッドは、エラー状態が発生したときに [再試行] と [一時停止] の適切な値を自動的に設定します。

Ensemble フレームワークにはこれらの予防措置が組み込まれているので、一般的な環境では、カスタム・コードは単に各呼び出しのエラー・コードをチェックするだけにとどめ、それがエラー値であったらその値で終了するようにすることをお勧めします。次に、このコーディング・スタイルの例を示します。トラップや Do {} While 0 ブロックがないことに注目してください。

Class Test.FTP.FileSaveOperation Extends Ens.BusinessOperation
{
 Parameter ADAPTER = "EnsLib.File.OutboundAdapter";

 Method OnMessage(pRequest As Test.FTP.TransferRequest,
                  Output pResponse As Ens.Response) As %Status
 {
 Set pResponse=$$$NULLOREF
 Set tFilename=..Adapter.CreateTimestamp(pRequest.Filename,"%f_%Q")
 ; file with timestamp should not already exist
 $$$ASSERT('..Adapter.Exists(tFilename))
 Set tSC=..Adapter.PutStream(tFilename,pRequest.StreamIn) Quit:$$$ISERR(tSC) tSC
 Quit $$$OK
 }
}  

SQL アダプタを使用してビジネス・オペレーションで多数の SQL 文を実行した後、そのいずれかが失敗したときに戻る前にロールバックを呼び出す場合など、複雑なシナリオの方が有用なこともあります。しかし、単純な環境では、前の例のコーディング・スタイルが最適な慣行といえます。

後半の章では、特定の種類のビジネス・ホストに関するその他の原理について説明します。

参照によるまたは出力としての値の引き渡し

参照または出力による値の引き渡しに慣れていない場合は、この節を参考にしてください。

多くの Ensemble メソッドが 2 つ以上の値を返します。ステータス (%StatusOpens in a new tab のインスタンス) と応答メッセージまたはその他の戻り値です。通常、応答メッセージは、参照によってまたは出力として返されます。値が参照によってまたは出力として返される場合は、次のような意味があります。

• メソッドを定義するときに、メソッドで対応する変数を設定する必要があります。

• メソッドを呼び出すときに、対応する引数の前に期間を含める必要があります。

下の例は、これらのポイントを示しています。

標準的なコールバック・メソッド

標準的なコールバック・メソッドのシグニチャを以下に示します。

method OnRequest(request As %Library.Persistent, Output response As %Library.Persistent) as %Status

キーワードの Output は、2 つ目の引数を出力として返す必要があることを意味します。このメソッドの実装では、以下のタスクを実行してメソッド・シグニチャを満たす必要があります。

1. response という名前の変数を適切な値に設定します。この変数には、メソッドが実行を完了したときに値を代入する必要があります。

2. %StatusOpens in a new tab のインスタンスを参照している変数の名前が後に続く、終了コマンドで終了します。

以下に例を示します。

Method OnRequest(request As %Library.Persistent, Output response As %Library.Persistent) as %Status
{
   //other stuff
   set response=myObject
   set pSC=..MyMethod() ; returns a status code
   quit pSC
}

この例は、値が出力として返される場合を示していますが、詳細は値が参照によって渡される場合と同じです。

標準的なハイパー・メソッド

標準的な継承ヘルパー・メソッドのシグニチャを以下に示します。

method SendRequestSync(pTargetDispatchName As %String, 
                       pRequest As %Library.Persistent, 
                       ByRef pResponse As %Library.Persistent, 
                       pTimeout As %Numeric = -1, 
                       pDescription As %String = "") as %Status

キーワードの ByRef は、3 つ目の引数を参照によって返す必要があることを意味します。このメソッドを呼び出すには、以下を使用します。

 set sc=##class(pkg.class).SendRequestSync(target,request,.response,timeout,description).

3 つ目の引数の手前の期間に注目してください。

この例は、値が参照によって渡される場合を示していますが、詳細は値が出力として返される場合と同じです。

設定の追加と削除

プロダクション、ビジネス・ホスト、またはアダプタの新しい設定を入力するには、そのクラス定義を次のように修正します。

1. 定義する構成設定ごとにプロパティを追加します。

2. SETTINGS というクラス・パラメータをクラスに追加します。

3. SETTINGS の値として、定義したプロパティの名前のカンマ区切りリストを設定します。以下に例を示します。

   Property foo As %String;
   
   Property bar As %String;
   
   Parameter SETTINGS = "foo,bar";
   

   

   SETTINGS の詳細は、次の節を参照してください。

これで、該当クラスの項目が構成対象として選択されるたびに、Ensemble, プロダクション構成 ページの構成画面に foo および bar の設定が自動的に表示されるようになります。

継承された構成設定を削除するには、ハイフン (-) を先頭に付加したプロパティを SETTINGS クラス・パラメータで指定します。以下に例を示します。

Parameter SETTINGS = "-foo";

設定に関するカテゴリと制御の指定

プロダクションを構成する場合は、デフォルトで、設定が [詳細] タブの [追加設定] カテゴリに表示されます。デフォルトでは、設定は、その基準となるプロパティに応じて、次のいずれかの入力メカニズムを提供します。

• 通常、設定は平文入力フィールドを伴って表示されます。

• プロパティが VALUELIST パラメータを指定している場合、設定はドロップダウン・リストを伴って表示されます。

• プロパティのタイプが %BooleanOpens in a new tab である場合、設定はチェックボックスとして表示されます。

いずれの場合も、プロパティの InitialExpression (指定されている場合) によって入力フィールドの初期状態が制御されます。

場所と制御タイプの両方をオーバーライドできます。デフォルト設定をオーバーライドするには、次の手順で SETTINGS に設定名を含めます。

Parameter SETTINGS = "somesetting:category:control";

または、次の手順を行います。

Parameter SETTINGS = "somesetting:category";

Parameter SETTINGS = "somesetting::control";

ここでは、category と control は、それぞれ使用する カテゴリ および コントロール を示します。次の項では、詳細を説明します。

次の手順により、複数の設定を含めることができます。

Parameter SETTINGS = "setting1:category:control1,setting2:control2:editor,setting3:category:control3";

次に、例を示します (許可されない改行が含まれています)。

Parameter SETTINGS = "HTTPServer:Basic,HTTPPort:Basic,SSLConfig:Connection:sslConfigSelector,
ProxyServer:Connection,ProxyPort:Connection,ProxyHTTPS:Connection,
URL:Basic,Credentials:Basic:credentialsSelector,UseCookies,ResponseTimeout:Connection" 

設定のコントロール

control は、Ensemble, プロダクション構成 ページでの設定の表示時および変更時に使用する特定の Zen コントロールの名前を指定します。このコントロールには任意の有効な Zen コンポーネントが使用できるため、専用のコンポーネントが作成可能です。Ensemble には、共通して必要なデータを処理するコントロールが用意されています。“設定コントロールの例” を参照してください。

適切なオプションのセットを表示するためにコンポーネントに追加の値を指定するには、次のように、一連の名前-値のペアを追加します。

myControl?Prop1=Value1&Prop2=Value2&Prop3=Value3

説明 ：

• Prop1、Prop2、Prop3 などはコントロールのプロパティ名です。例：multiSelect

• Value1、Value2、Value3 などは対応する値です。

  Javascript zenPage オブジェクトのプロパティを参照するには、構文 @propertyname を使用します。サポートされる変数は、次のとおりです。

  • currHostId は、現在の Ens.Config.ItemOpens in a new tab の ID を示します。

  • productionId は、使用中の Ens.Config.ProductionOpens in a new tab の ID を示します。

  文字 @ をそのまま示すには、\@ を使用します。

  コントロールの context プロパティに値を渡すには、値を中括弧で囲みます。次の項を参照してください。

コントロールの context プロパティへの値の受け渡し

Ensemble 内の汎用セレクタ・コンポーネントを使用することもできます。そのためには、control を selector として指定してから、プロパティ/値のペアを追加します。

selector コンポーネントはほぼすべてのデータまたはオプションのリストをユーザに表示可能にするため、ユーザは必要に応じてデータを入力できます。このようにコンポーネントを構成するには、以下の構文を使用してコントロールの context プロパティを設定します。

context={ContextClass/ContextMethod?Arg1=Value1&Arg2=Value2&Arg3=Value3}

説明 ：

• ContextClass はコンテキスト・クラスの名前です。これは、%ZEN.Portal.ContextSearchOpens in a new tab または Ens.ContextSearchOpens in a new tab のサブクラスとして指定する必要があります。“設定コントロールの例” を参照してください。

• ContextMethod はこのクラスのメソッドです。このメソッドによって提供されるデータから、値を選択します。

• Arg1、Arg2、Arg3 などは、このメソッドの多次元引数です。

• Value1、Value2、Value3 などはこれらの引数の値です。値のルールは、前述のルールと同じです (例えば、@propertyname が使用できます)。

セレクタ・コンポーネントには、multiSelect というプロパティも設定されています。デフォルトでは、1 つのアイテムのみが選択可能です。複数のアイテムを使用可能にするには、プロパティ/値のペアを multiSelect=1 のように含めます。

設定コントロールの例

次のリストに control の例を示します。このリストは、ユーザが選択可能なデータの種類別に編成されています。

これらの例では、Ensemble クラスが使用されています。これらの例の多くは Ens.ContextSearchOpens in a new tab クラスを使用していますが、これは有用なメソッドを多数提供します。このリストに必要なシナリオが含まれていない場合は、Ens.ContextSearchOpens in a new tab のクラス・ドキュメントを参照して、既存のメソッドによって必要なデータが提供されるかどうかを判別してください。必要なシナリオがそのクラスで対応していない場合は、専用の Ens.ContextSearchOpens in a new tab のサブクラスを作成できます。

同じプロダクションのビジネス・ホスト

selector?multiSelect=1&context={Ens.ContextSearch/ProductionItems?targets=1&productionName=@productionId}

または、ユーザがビジネス・ホストを 1 つだけ選択しなければならない場合：

selector?context={Ens.ContextSearch/ProductionItems?targets=1&productionName=@productionId}

ビジネス・パートナー

partnerSelector

ビジネス・ルール

ruleSelector

文字セット

selector?context={Ens.ContextSearch/CharacterSets}

資格情報セット

credentialsSelector

構成

selector?context={Ens.ContextSearch/getDisplayList?host=@currHostId&prop=Framing}

ローカル・インタフェース

selector?context={Ens.ContextSearch/TCPLocalInterfaces}

特定のビジネス・ホストに適切なスキーマ・カテゴリ

selector?context={Ens.ContextSearch/SchemaCategories?host=classname}

ここで、classname はビジネス・ホストのクラス名です。以下に例を示します。

selector?context={Ens.ContextSearch/SearchTableClasses?host=EnsLib.MsgRouter.RoutingEngineST}

特定のビジネス・ホストに適切なテーブル・クラス検索

selector?context={Ens.ContextSearch/SearchTableClasses?host=classname}

ここで、classname はビジネス・ホストのクラス名です。以下に例を示します。

selector?context={Ens.ContextSearch/SearchTableClasses?host=EnsLib.EDI.ASTM.Service.Standard}

SSL 構成

sslConfigSelector

設定に関するデフォルト値の指定

ビジネス・ホスト・クラス (およびアダプタ・クラス) を定義するときに、これらの項目の設定に関するデフォルト値の制御方法を検討する必要があります。Ensemble は、次の 3 つのソースのいずれかから設定のデフォルト値を取得できます。

• プロダクション定義。

• 現在の Ensemble インスタンス用に定義されているが、プロダクションの外部に格納されている値。詳細は、"Ensemble プロダクションの構成" の “プロダクション・デフォルトの定義” を参照してください。

• ホスト・クラス内で定義されたプロパティのデフォルト値。この場合は、デフォルト値が InitialExpression プロパティ・キーワードによって決定されます。

設定の中には、TCP/IP アドレスやファイル・パスなどの環境に依存しているものがあります。これらの設定は、プロダクションの外部にソースを持つように構成することが普通です。一方、これ以外の ReplyCodeActions などの設定は設計段階で決定しておくものなので、多くの場合はプロダクション定義からその設定値を取得するようにアプリケーションを開発します。

さまざまなソースにある構成設定を使用するプロダクションを開発できます。その主な目的は、複数の Ensemble インスタンス間でプロダクションを容易に移動できるようにすることです。例えば、テスト環境からライブ環境への移動が考えられます。

プロダクションを定義したら、管理ポータルの [プロダクション構成] ページでプロダクション設定とビジネス・ホスト設定の両方のソースを変更できます。詳細は、"Ensemble プロダクションの構成" を参照してください。

デフォルト設定を使用すると、プロダクション定義の外部でプロダクション設定およびビジネス・ホスト設定を定義でき、プロダクションを更新するときにはその場所に両方の設定を保持しておくことができます。プロダクションのアップグレードやシステム間でのプロダクションの移動を円滑に進めるために、設定処理を省略し、システムにインストールした構造から設定値を取得できます。プロダクション定義に設定が見つからない場合、プロダクション定義の外部にデフォルト設定があれば、そこから値を取得します。

プログラミングの詳細は、"クラス参照" の Ens.DirectorOpens in a new tab のクラス・エントリにある以下のメソッドの説明を参照してください。

• GetProductionSettingValue()

• GetProductionSettings()

ビジネス・ホストからのプロパティとメソッドへのアクセス

ビジネス・ホスト・クラス内でメソッドを定義する場合は、そのクラスまたは関連アダプタのプロパティまたはメソッドにアクセスする必要があります。この節では、その手順について簡単に説明します。

ビジネス・ホストのインスタンス・メソッド内では、以下の構文を使用できます。

• ..bushostproperty

  ビジネス・ホストの設定またはその他のプロパティにアクセスします (すべての設定がそれぞれのクラスのプロパティであることを思い出してください)。

• ..bushostmethod()

  ビジネス・ホストのインスタンス・メソッドにアクセスします。

• ..Adapter.adapterproperty

  アダプタの設定またはその他のプロパティにアクセスします (すべてのビジネス・ホストにプロパティの Adapter があることに注意してください。このプロパティを使用してアダプタにアクセスしてから、ドット構文を使用してアダプタのプロパティにアクセスします)。

• ..Adapter.adaptermethod()

  アダプタのインスタンス・メソッドにアクセスします。

プロダクション設定へのアクセス

プロダクションの設定にアクセスしなければならない場合があります。そのためには、マクロの $$$ConfigProdSetting を使用します。例えば、$$$ConfigProdSetting("mySetting") は、mySetting という名前のプロダクション設定の値を取得します。安全のため、このマクロは $GET 呼び出しにラップすることをお勧めします。以下に例を示します。

 set myvalue=$GET($$$ConfigProdSetting("mySetting"))

$GET の詳細は、Caché ObjectScript リファレンス を参照してください。

“その他のトピック” の章の “Ens.Director の使用による設定へのアクセス” も参照してください。

メッセージの送信方法の選択

ビジネス・オペレーションとビジネス・プロセス内のメソッドの多くが、プロダクション内の他のビジネス・ホストにメッセージを送信する継承メソッドを呼び出します。ここでは、そのオプションについて説明します。

遅延送信

同期 (待つ) と非同期 (待たない) という単純な選択肢のほかに、遅延応答と呼ばれているメカニズムを使用して Ensemble の外部にメッセージを送信できます。

例えば、あるビジネス・プロセスで、Ensemble の外部でアクションを起動する必要があるとします。このビジネス・プロセスはビジネス・オペレーションに要求を送信し、そのビジネス・オペレーションは呼び出しを実行して、受け取った応答をビジネス・プロセスに返します。このビジネス・プロセスはすべての応答が目的とする受信者です。ビジネス・オペレーションは、要求を送り出し、応答を受け取るための手段にすぎません。ビジネス・プロセスが同期的に要求を発行している場合でも、また非同期応答を要求して非同期的に要求を発行している場合でも、このビジネス・オペレーションにより応答が中継されて戻されます。下の図は、このメカニズムをまとめたものです。

あるビジネス・プロセスから要求を受信するビジネス・オペレーションが、延期された応答機能を使用するように作成されているとします。元の送信者は、ビジネス・オペレーションによって応答が延期することを知りません。応答の延期は、ビジネス・オペレーションの開発者の判断で設計に取り入れます。実際に、ビジネス・オペレーションが応答を延期した場合、元の送信者は、延期期間の最後に応答を受信しても、応答が延期されていたことには気付きません。

ビジネス・オペレーションで応答を延期するには、このオペレーションの DeferResponse() メソッドを呼び出し、元の送信者と元の要求を表すトークンを生成します。ビジネス・オペレーションは、このトークンが Ensemble への延期された応答に含まれるように、このトークンを外部エンティティに伝達する方法も見つける必要があります。例えば、外部の宛先が電子メールである場合は、ビジネス・オペレーションから送信する電子メールの件名にこのトークン文字列を記述します。この電子メールを受信した外部エンティティは、要求の件名からこのトークンを抽出し、応答の件名に使用します。次のダイアグラムでは、項目 “t” がこのトークンを表しています。

ビジネス・オペレーションが要求を延期した時点から、その応答を最終的に元の送信者が受信する時点まで、その要求メッセージは延期ステータスになっています。対応する応答を元の送信者が受信すると、要求メッセージのステータスは遅延から完了に変わります。

プロダクション内のどのビジネス・ホストでも、要求に対する応答の受信イベントを判別して、元の送信者に送り返すことができます。Ensemble のどこにイベントが到着するかは、プロダクションの設計によって異なります。通常、Ensemble 外部からの受信イベントを受け取るのはビジネス・サービスです。受信イベントを受け取るビジネス・ホストは、このイベントと共に、延期された応答のトークンを受信する必要があります。その後、このビジネス・ホストは SendDeferredResponse() メソッドを呼び出して、受信イベント・データから適切な応答メッセージを作成し、元の送信者に返します。元の送信者はこの応答を受信しますが、これがどのように返されたかについてはまったくわかりません。下の図は、要求とその遅延応答を示しています。

イベント・ログ・エントリの生成

イベント・ログは、特定のネームスペース内で実行中のプロダクションで発生したイベントが記録されたテーブルです。管理ポータルには、このログを表示するページがあります。このページは、主にシステム管理者向けですが、開発でも役に立ちます (このページの詳細は、"Ensemble プロダクションの監視" を参照してください)。

イベント・ログの主な目的は、プロダクションの実行中に問題が発生した場合にシステム管理者に役立つ診断情報を提供することです。

Ensemble ではイベント・ログ・エントリが自動的に生成されますが、独自のエントリを追加することもできます。イベントは、アサート、情報、警告、エラー、およびステータスのいずれかです (イベント・ログには、次の節で説明するアラート・メッセージとトレース項目を含めることもできます)。

イベント・ログ・エントリを生成するには：

1. ログに記録するイベントを特定します。

   すべてのタイプのエラーまたはアクティビティによってイベント・ログ・エントリが生成されるわけではありません。注目すべき事象、使用するタイプ、および記録する情報を選択する必要があります。例えば、イベント・ログ・エントリは、ネットワークの接続不良などの、外部の物理的な問題が発生したときに生成する必要があります。

   イベント・ログには、プログラム・エラーを登録すべきではありません。それらはプロダクションをリリースする前に解決すべき問題です。

2. 以降の項の説明に従って、ObjectScript または Basic でイベント・ログ・エントリを生成するようにプロダクションの該当部分 (通常はビジネス・ホスト・クラス) を修正します。

ObjectScript でのイベント・ログ・エントリの生成

プロダクションによって使用されるビジネス・ホスト・クラスまたはその他のコード内の ObjectScript でイベント・ログ・エントリを生成できます。そのためには、以下のマクロのいずれかを使用します。これらのマクロは、Ensemble システム・クラスに自動的にインクルードされる Ensemble.inc インクルード・ファイル内で定義されています。

マクロ	詳細
$$$LOGINFO(message)	[情報] タイプのエントリを書き込みます。このテーブルで登場するすべての message は、評価結果として文字列が得られる ObjectScript 式または文字列リテラルです。
$$$LOGERROR(message)	[エラー] タイプのエントリを書き込みます。
$$$LOGWARNING(message)	[警告] タイプのエントリを書き込みます。
$$$LOGSTATUS(status_code)	%StatusOpens in a new tab のインスタンスにする必要のある特定の status_code の値に応じて、エラー・タイプまたは情報タイプのエントリを書き込みます。
$$$ASSERT(condition)	引数が偽の場合に、アサート・タイプのエントリを書き込みます。condition は真か偽かを評価する ObjectScript 式です。
$$$LOGASSERT(condition)	引数の値に関係なく、アサート・タイプのエントリを書き込みます。condition は真か偽かを評価する ObjectScript 式です。

以下では、静的テキストをクラス・プロパティの値と組み合わせた式を使用した例を示しています。

 $$$LOGERROR("Awaiting connect on port "_..Port_" with timeout "_..CallInterval)

以下の例では、ObjectScript 関数を使用しています。

 $$$LOGINFO("Got data chunk, size="_$length(data)_"/"_tChunkSize)

Basic でのイベント・ログ・エントリの生成

Caché Basic でイベント・ログ・エントリを生成するには、以下の構文を使用します。

"Ens.Util.Log".LogMethodName(Me.%ClassName(1),CurrentMethod,arg)

ここで、LogMethodName は下の表内のメソッド名の 1 つ、arg はそのメソッドの引数、CurrentMethod は現在のメソッドの名前です。

メソッド	詳細
LogInfo	[情報] タイプのエントリを書き込みます。引数は、文字列リテラル、または、文字列に対して評価する ObjectScript 式です。
LogError	[エラー] タイプのエントリを書き込みます。 引数は、文字列リテラル、または、文字列に対して評価する ObjectScript 式です。
LogWarning	[警告] タイプのエントリを書き込みます。引数は、文字列リテラル、または、文字列に対して評価する ObjectScript 式です。
LogStatus	引数の値に応じて、エラー・タイプまたは情報タイプのエントリを書き込みます。
LogAssert	引数が偽の場合に、アサート・タイプのエントリを書き込みます。引数は真か偽かを評価する ObjectScript 式です。

以下に例を示します。

"Ens.Util.Log".LogInfo(Me.%ClassName(1),MyMethod,"log this")

アラートの生成

アラートは、Ensemble プロダクションの実行中にアラート・イベントが発生した場合に該当するユーザに通知を送信します。その目的は、システム管理者またはサービス技術者に問題の存在を警告することです。アラートは電子メール、携帯電話、またはその他のメカニズムにより送信されます。すべてのアラートが、アラート・タイプの Ensemble イベント・ログにもメッセージを書き込みます。

Ensemble のアラート・メカニズムは、次のように動作します。

• プロダクション用のビジネス・ホスト・クラスを作成するときに、次のようなコードを追加します。

  1. ユーザが解決しなければならない望ましくない状態やその他の環境を検出する。

  2. このような状況に対してアラートを生成する。

• ビジネス・ホストである Ens.Alert という名前のアラート・プロセッサを定義して構成します。このアラート・プロセッサは、イベントを解決するプロセスを追跡するアラートを必要に応じて管理できます。アラート・プロセッサの定義方法の詳細は、"アラート・プロセッサの定義" を参照してください。どのプロダクションにも、1 つのアラート・プロセッサしか組み込むことはできません。

ビジネス・ホスト・クラス (BPL プロセス・クラス以外) で、以下を実行してアラートを生成します。

1. Ens.AlertRequestOpens in a new tab のインスタンスを作成します。

2. このインスタンスの AlertText プロパティを設定します。このプロパティの値には、技術者が問題に適切に対処できるための十分な情報を提供する文字列を指定してください。

3. ビジネス・ホスト・クラスの SendAlert() メソッドを呼び出します。このメソッドは非同期的に実行されるため、ビジネス・ホストの通常の処理を遅延させません。

例えば、ObjectScript では以下のようになります。

 set alert=##class(Ens.AlertRequest).%New()
 set msg="Suspended HL7 Message "_pRequest.%Id()
   _" because ACK.MSA.Acknowledgment Code = '"_tAcknowledgmentCode_"'"
 set alert.AlertText=msg
 do ..SendAlert(alert)

トレース要素の追加

トレースは、主に開発時に使用するツールです。トレース要素を追加することで、デバッグや診断のために、プロダクション内のさまざまな要素の動作を確認できるようになります。プロダクションにトレース要素を追加するには、実行時情報を表示するコード内の領域 (通常はビジネス・ホスト・クラス) を特定します。これらの領域で、トレース・メッセージを (状況に応じて) 書き込むコード行を追加します。トレース・メッセージは、大まかな意味でのメッセージにすぎません。すなわち、トレース・メッセージは単なる文字列であり、Ens.Message やそのサブクラスとは無関係です。

ほとんどの場合は、ユーザ要素とシステム要素という 2 種類のトレース要素を定義できます。ほとんどの場合は、ユーザ・トレース要素を定義する方が適切です。

ObjectScript でのトレース・メッセージの書き込み

ObjectScript を使用してトレース・メッセージを書き込むには、以下のコード行を使用します。

• ユーザ・トレース・メッセージを書き込むには、以下のように記述します。

   $$$TRACE(trace_message)

  

  ここで trace_message は、このコード行を追加するコンテキストに関する有用な情報が含まれた文字列です。

• システム・トレース・メッセージを書き込むには (あまり一般的ではありません)、以下のように記述します。

   $$$sysTRACE(trace_message)

  

  Ensemble システム・コードに $$$sysTRACE が含まれていることがありますが、独自のビジネス・ホスト・クラスでは一般的には $$$TRACE を使用するのが適切です。

以下に例を示します。

$$$TRACE("received application for "_request.CustomerName)