Compute ノード

このトピックには、以下のセクションが含まれています。

目的

新規メッセージを作成して、それに新規情報や入力メッセージからの変更された情報、またはデータベースから取得した情報を取り込んで、1 つ以上の新規出力メッセージを構成するには、Compute ノードを使用します。 入力メッセージのエレメント (ヘッダー、ヘッダー・フィールド、および本体データ)、関連する環境、および例外リストを変更して、新しい出力メッセージを作成できます。

メッセージ・フロー ESQL リソース・ファイル内に ESQL をコーディングすることにより、新規メッセージの作成方法を指定します。ユーザーは、ESQL 式を使用してメッセージのコンポーネントを作成および変更し、入力メッセージと外部データベースのデータの両方のエレメントを参照できます。 式では、算術演算子、テキスト演算子 (連結など)、論理演算子、およびその他の組み込み関数を使うことができます。

以下の目的で、Compute ノードを使用します。

  • 割り当てステートメントのセットを使用して、新しいメッセージを構築する
  • パーサー間でメッセージをコピーする
  • メッセージをあるコード・セットから別のコード・セットに変換する
  • メッセージをある形式から別の形式に変換する

このノードに関連付けられるモジュール内の ESQL ステートメントは、このメッセージ・フローに関連付けられる ESQL (.esql) ファイル内に定義します。 メッセージ・フローの定義を完了するには、このファイルを作成する必要があります。

ワークベンチでは、Compute ノードは次のアイコンで表されます。

Compute ノード・アイコン

メッセージ・フロー内でのこのノードの使用

このノードが使用される方法に関しては、次のサンプルを参照してください。

監査目的のため、受け取るオーダーのそれぞれに固有な ID を付けたいメッセージ・フローを考えてください。Compute ノードは入力メッセージを変更しないで、変更された新しいメッセージのコピーを出力メッセージとして作成します。 Compute ノードを使ってオーダーに対する固有の ID を出力メッセージに挿入し、メッセージ・フロー内の後続ノードがそのメッセージを使用することができます。

Compute ノードの構成

Compute ノードのインスタンスをメッセージ・フローに入れると、Compute ノードを構成することができます。 エディター・ビューでノードを右マウス・ボタンでクリックし、「プロパティー (Properties)」をクリックします。 ノードの基本プロパティーが表示されます。

値を入力する必要のある (デフォルト値が定義されていない) すべての必須プロパティーには、プロパティー・ダイアログにアスタリスクが表示されます。

以下のように、Compute ノードを構成します。

  1. データベース対話の定義
  2. ESQL の指定
  3. モードの設定
  4. メッセージの妥当性検査

構成が完了したら、「適用 (Apply)」をクリックします。 これにより、プロパティー・ダイアログを閉じずに Compute ノードが変更されます。 「OK」をクリックすると、変更を適用してプロパティー・ダイアログを閉じます。 「キャンセル (Cancel)」をクリックすると、ダイアログを閉じてプロパティーの変更をすべて破棄します。

データベース対話の定義

このノードでデータベースからのデータを使用したい場合 (関連付けられている ESQL モジュール内でデータベース・テーブルを参照することにより)、以下のようにします。

  • 「データ・ソース (Data Source)」に、メッセージ・フローが実行されるシステム上で該当するデータベースが認識される名前を指定します。 ブローカーは、mqsicreatebrokermqsichangebroker、または mqsisetdbparms コマンドを使用してセットアップしたユーザー ID およびパスワード情報を使用して、このデータベースに接続します。

    z/OS システムの場合、ブローカーは、ブローカーが開始したタスクの ID を使用します。

  • ドロップダウン・メニューから「トランザクション (Transaction)」を選択します。 値は以下のとおりです。
    • 「自動 (Automatic)」 (デフォルト)。 Compute ノードが属するメッセージ・フローが正常に行われると、そのメッセージ・フローがコミットされます。 つまり、ESQL モジュールで定義したアクションがメッセージ上で実行され、それはメッセージ・フローを通して継続します。 メッセージ・フローは、失敗するとロールバックされます。 「自動 (Automatic)」を選択した場合、データベース上で Compute ノードのアクションをコミットするかロールバックするかは、メッセージ・フロー全体の成功または失敗に依存します。
    • 「コミット (Commit)」。 メッセージ・フロー全体の成功または失敗に関係なく、データベース上で Compute ノードのアクションをコミットしたい場合は、「コミット (Commit)」を選択します。 メッセージ・フローが失敗しても、データベースへの更新はコミットされます。

    ここで選択した値が、ユーザーが追加した 1 つ以上のデータベース・テーブルにインプリメントされます。表毎に違う値を選択することはできません。

  • プロパティー・ダイアログ・ナビゲーターで「基本 (Basic)」を選択し、次の 2 つのチェック・ボックスを選択するかまたはチェックを外します。
    • データベース警告メッセージをエラーとして扱い、ノードから出力メッセージを failure ターミナルに伝搬したい場合は、「警告をエラーとして扱う (Treat warnings as errors)」チェック・ボックスを選択します。 最初、このチェック・ボックスはチェックされていません。

      このボックスを選択した場合、ノードはデータベースからのすべての正の戻りコードをエラーとして扱い、負の戻りコードについてと同じ方法で例外を生成するか、問題がより重大である場合はエラーを生成します。

      このボックスを選択しなかった場合、ノードは警告を通常の戻りコードとして扱い、例外を生成しません。 生成される最も重大な警告は「見つかりません (not found)」であり、これはほとんどの状況で正常な戻りコードとして安全に扱うことができます。

    • データベース・エラーが検出されたときにブローカーが例外を生成するようにしたい場合は、「データベース・エラーで例外を発生させる (Throw exception on database error)」チェック・ボックスを選択します。 最初、このチェック・ボックスは選択されています。

      このチェック・ボックスのチェックを外す場合、データベース呼び出しを行うたびに返される可能性のあるデータベース・エラーを調べるために ESQL を含める必要があります。(これには SQLCODE および SQLSTATE を使うことができます。) エラーが発生した場合、メッセージ・フロー内のエラーを処理してブローカーとデータベースの整合性を確認する必要があります。 ブローカーによるデフォルト・エラー処理を呼び出さないように選択してあるため、自分でエラーを処理しない限り、エラーは無視されます。 たとえば、このノードで例外を発生させるために ESQL THROW ステートメントを含めることができます。 あるいは、メッセージ・フローの中で Throw ノードを使用して後で独自の例外を生成することができます。

ESQL の指定

Compute ノードの動作をカスタマイズするには、ESQL ステートメントをコーディングします。 たとえば、入力メッセージ、データベースの内容 (変更なし、または変更あり)、または新しいデータを使って 1 つ以上の新規出力メッセージを作成するようにこのノードの動作をカスタマイズできます。 データベースからの値を追加することにより入力メッセージ内の値を変更し、その結果を出力メッセージ内のフィールドに保管することもできます。

必要な ESQL ステートメントは、この Compute ノードのインスタンスが含まれるメッセージ・フローに関連付けられた ESQL ファイル内にコーディングします。デフォルトで <message_flow_name>.esql という名前を持つこの ESQL ファイルには、ESQL を必要とするメッセージ・フロー内のすべてのノード用の ESQL が含まれています。 特定のノードに関連したコードの部分はモジュールと呼ばれます。

このメッセージ・フロー用の ESQL ファイルが存在していない場合、Compute ノードを右クリックして、「ESQL のオープン (Open ESQL)」をクリックします。これにより、ESQL エディター・ビューに新しい ESQL ファイルが作成されてオープンされます。

ファイルが既に存在する場合は、「ESQL モジュール (ESQL Module)」プロパティーの横にある「ブラウズ (Browse)」ボタンをクリックします。 「モジュール選択 (Module Selection)」ダイアログが表示され、このメッセージ・フローで使用可能な ESQL ファイルで定義されている Compute ノード・モジュールがリストされます (ESQL ファイルは従属する他のプロジェクトで定義することができます)。 適切なモジュールを選択して、「OK」をクリックします。使用できる適切なモジュールがない場合は、リストは空になります。

指定されたモジュールが存在しない場合、それが作成され、エディターはファイルを表示するために位置付けします。 ファイルとモジュールが既に存在する場合、エディターはファイルを位置付けし、正しいモジュールを強調表示します。

「リソース・ナビゲーター (Resource Navigator)」で適切な ESQL ファイルをオープンし、「アウトライン (Outline)」ビューでこのノードを選択することもできます。

新規または既存の ESQL ファイル内でこのノード用にモジュール・スケルトンが作成された場合、以下の ESQL が含まれます。この例では、デフォルトのモジュール名が表示されています。


CREATE COMPUTE MODULE <flow_name>_Compute
              CREATE FUNCTION Main() RETURNS BOOLEAN
         BEGIN
                            -- CALL CopyMessageHeaders();
                            -- CALL CopyEntireMessage();
                             RETURN TRUE; 
       END;

       CREATE PROCEDURE CopyMessageHeaders() BEGIN
              DECLARE I INTEGER 1;
              DECLARE J INTEGER CARDINALITY(InputRoot.*[]);
              WHILE I < J DO
                     SET OutputRoot.*[I] = InputRoot.*[I];
                     SET I = I + 1;
              END WHILE;
       END;

              CREATE PROCEDURE CopyEntireMessage() BEGIN
              SET OutputRoot = InputRoot;
       END;
END MODULE;

注: 変更の始まりこの Compute ノードを含むメッセージ・フローを、バージョン 5.0 より前のバージョンのブローカーにデプロイしたい場合には、上に示されているモジュール・スケルトンの ESQL に以下の変更を加える必要があります。
  • DECLARE I INTEGER 1;
    DECLARE I INTEGER; SET I=1;
    に置換する
  • DECLARE J INTEGER CARDINALITY(InputRoot.*[]);
    DECLARE J INTEGER; SET J=CARDINALITY(InputRoot.*[]);
    に置換する
変更の終わり

自分で ESQL モジュールを作成する場合、このスケルトンをそのまま正確に作成する必要があります。 ただし、プロシージャー呼び出しと定義は別です (後述)。 デフォルトの名前を更新することができますが、指定する名前は、対応するノード・プロパティー「ESQL モジュール (ESQL Module)」と一致することを確認してください。 モジュール名に 1 つ以上のスペースを含めるには、「ESQL モジュール (ESQL Module)」プロパティーで、名前を二重引用符で囲まなければなりません。

このノードをカスタマイズするための ESQL を、BEGIN ステートメントと CREATE FUNCTION から RETURN TRUE の間に追加します。 スケルトンに組み込まれている、プロシージャー CopyEntireMessage と CopyMessageHeaders への 2 つの呼び出しを使用することができます。

これらのプロシージャーは、関数 Main の次に定義されており、メッセージを操作するときに必要となるかもしれない一般的な機能を備えています。 スケルトンの中で、呼び出しはコメント化されています。 プロシージャーを使用するには、コメント・マーカーを除去します。 プロシージャーを使用しない場合は、呼び出しとプロシージャー定義を両方ともモジュールから除去します。

前のリリースでは、これらのプロシージャーによって実行される機能は、これに相当するプロパティー・ダイアログ上の 2 つの Compute ノードのラジオ・ボタンによって提供されていました。

「ファイル (File)」 > 「新規 (New)」 > 「メッセージ・フロー ESQL ファイル (Message Flow ESQL File)」 により ESQL ファイルを作成することもできます。

モードの設定

「計算モード (Compute mode)」を選択する場合、出力メッセージの MessageLocalEnvironment (以前は DestinationList と呼ばれていました)、および Exception コンポーネントのどの組み合わせを生成および変更するかを指定します。 選択しなかったコンポーネントは、未変更で渡されます。これらのコンポーネントを変更しても、このプロパティーに対して適切なモードを選択しなかった場合、更新はこのノードに対してローカルになります。

(メッセージ・ツリーの「環境」コンポーネントは、モード設定に影響されません。 これに内容がある場合、その内容は出力メッセージの中のこのノードから受け渡されます。)

このプロパティーは、必要な出力メッセージ形式を正しく反映するように設定する必要があります。メッセージの特定の内容を含んでいないオプションを選択した (またはデフォルト値を受け入れた) 場合、メッセージのその部分は、構成される出力メッセージに組み込まれません。

これらのオプションについては、以下の表で説明します。

モード 説明
メッセージ (Message)(デフォルト) メッセージが Compute ノードにより生成されるか、または Compute ノード内で変更されて渡されます。
LocalEnvironment LocalEnvironment ツリー構造が Compute ノードにより生成されるか、または Compute ノード内で変更されて渡されます。
LocalEnvironment とメッセージ (Message) LocalEnvironment ツリー構造とメッセージが Compute ノードにより生成されるか、または Compute ノード内で変更されて渡されます。
例外 (Exception) 例外リストが Compute ノードにより生成されるか、または Compute ノード内で変更されて渡されます。
例外 (Exception) とメッセージ (Message) 例外リストとメッセージが Compute ノードにより生成されるか、または Compute ノード内で変更されて渡されます。
例外 (Exception) と LocalEnvironment 例外リストと LocalEnvironment ツリー構造が Compute ノードにより生成されるか、または Compute ノード内で変更されて渡されます。
すべて (All) メッセージ、例外リスト、および LocalEnvironment が Compute ノードにより生成されるか、または Compute ノード内で変更されて渡されます。

Compute ノードは入力メッセージと出力メッセージの両方を持つため、ESQL を使って両方のフィールドを参照することができます。また、入力および出力メッセージの本体だけでなく、InputLocalEnvironment、OutputLocalEnvironment、InputExceptionList および OutputExceptionList で作業することもできます。

メッセージの妥当性検査

MRM パーサーの場合、メッセージ・セットから生成されたディクショナリーに対してメッセージ本文の妥当性検査を行いたいのであれば、プロパティー・ダイアログ・ナビゲーターの「妥当性検査 (Validation)」を選択します。 Compute ノードに設定した妥当性検査オプションは、作成される出力メッセージのみに適用されます。 妥当性検査はノード内では実施されず、メッセージがその後ビット・ストリームに変換される時だけ検査が行われます。

  • 「妥当性検査 (Validate)」プロパティーは、最初は「なし (None)」に設定されています。 内容妥当性検査 (タイプ内容検査およびタイプ構成検査) と値妥当性検査 (値データ・タイプ検査、ヌル許可検査、長さ検査、範囲検査、列挙型検査など) の両方を要求するには、この設定を「内容および値 (Content and Value)」に変更します。Compute ノードは、出力メッセージ・ツリーに指定されたオプションを、そのツリーが後で妥当性検査される時に追加します。
  • 妥当性検査障害が発生した場合の処理を指定するには、「障害アクション (Failure Action)」プロパティーのオプションのいずれかを選択します。
    • 「ユーザー・トレース (User Trace)」: すべての妥当性検査障害をユーザー・トレースに書き込み、処理を継続します。
    • 「ローカル・エラー・ログ (Local Error Log)」: すべての妥当性検査障害をイベント・ログに書き込み、処理を継続します。
    • 「例外 (Exception)」: 最初の妥当性検査障害で例外をスローします。 これがデフォルトの動作です。

    妥当性検査を最初に起動する場合には、最初の 2 つのオプションが特に有用です。 最初に発生した妥当性検査障害だけでなく、すべての障害を確認できるからです。 障害を既に分析した場合には、一般にその後の使用に関しては「例外 (Exception)」を選択できます。

    障害宛先は、トレース・ノード出力の障害宛先のように動作します。 したがって、たとえば「ユーザー・トレース (User Trace)」を選択した場合には、メッセージ・フローのユーザー・トレース・フラグの設定にかかわりなく、トレース・エントリーが書き込まれます。

  • 「値制約すべてを組み込む (Include All Value Constraints)」は、デフォルトで選択状態であり、変更できません。 この設定の場合、全データ・タイプ検査および値検査が行われます (制約の詳細については、単純タイプの論理値制約を参照してください)。
  • 「修正 (Fix)」は、デフォルト設定の「なし (None)」から変更することはできません。 「障害アクション (Failure Action)」「例外 (Exception)」に設定されていない場合、妥当性検査障害が発生すると、限定的な修復アクションが行われます。 「障害アクション (Failure Action)」「例外 (Exception)」に設定されている場合、修復アクションは行われず、妥当性検査で最初に発生した障害で例外がスローされます。

ターミナルおよびプロパティー

Compute ノード・ターミナルについては、次の表に説明されています。

ターミナル 説明
In ノードが処理するメッセージを受け入れる入力ターミナル。
Failure 計算時に障害が検出された場合、入力メッセージがルーティングされる出力ターミナル。 (「妥当性検査 (Validate)」プロパティーが設定されていても、ノードの failure ターミナルへ伝搬されたメッセージは検査されません。)
Out 変換されたメッセージがルーティングされる出力ターミナル。

以下の表でノードのプロパティーを説明します。M の見出しの列は、プロパティーが必須 かどうかを示します (デフォルトが定義されていない場合に値を入力することが必要なら、プロパティー・ダイアログにアスタリスクのマークが付きます)。 C の見出しの列は、プロパティーが構成可能 かどうかを示します (メッセージ・フローを bar ファイルに追加してデプロイするとき、値を変更できます)。

Compute ノードの「基本 (Basic)」プロパティーについては、次の表に説明されています。

プロパティー M C デフォルト 説明
データ・ソース (Data Source) いいえ はい   このメッセージ・フローに関連付けられた ESQL ファイル (「ESQL モジュール (ESQL Module)」プロパティーにより識別される) で参照するテーブルが存在するデータベースの ODBC データ・ソース名。 ノードに対して指定できるデータ・ソースは 1 つだけです。
トランザクション (Transaction) はい いいえ 自動 (Automatic) ノードのトランザクション・モードです。 「自動 (Automatic)」または「コミット (Commit)」を選択できます。 これは、データベース・テーブルを入力として指定した場合にのみ有効です。
ESQL モジュール (ESQL Module) はい いいえ Compute データベースおよび入力・出力メッセージに対して実行されるステートメントを含む、ESQL リソース (ファイル) 内のモジュールの名前。
Compute モード (Compute Mode) はい いいえ メッセージ (Message) 以下から選択できます。
  • メッセージ (Message)
  • LocalEnvironment
  • LocalEnvironment とメッセージ (Message)
  • 例外 (Exception)
  • 例外 (Exception) とメッセージ (Message)
  • 例外 (Exception) と LocalEnvironment
  • すべて (All)
これについては、モードの設定で説明しています。
警告をエラーとして扱う (Treat warnings as errors) はい いいえ 選択されていない データベース SQL 警告をエラーとして扱います。 チェック・ボックスを選択すると、このアクションが実行されます。
データベース・エラーで例外を発生させる (Throw exception on database error) はい いいえ 選択されている データベース・エラーによりブローカーが例外を発生させます。 チェック・ボックスを選択すると、このアクションが実行されます。

Compute ノードの「妥当性検査 (Validation)」プロパティーについては、次の表に説明されています。

プロパティー M C デフォルト 説明
妥当性検査 (Validate) はい いいえ 「なし (None)」 妥当性検査が行われるかどうか。 有効な値は、「なし (None)」および「内容および値 (Content and Value)」です。
障害アクション (Failure Action) はい いいえ 例外 (Exception) 妥当性検査障害が発生した場合の処理。 「妥当性検査 (Validate)」「内容および値 (Content and Value)」に設定されている場合にのみ、このプロパティーを設定できます。 有効な値は、「ユーザー・トレース (User Trace)」「ローカル・エラー・ログ (Local Error Log)」および「例外 (Exception)」です。
値制約すべてを組み込む (Include All Value Constraints) はい いいえ 選択されている このプロパティーは編集できません。 チェック・ボックスが選択されていることにより示されるデフォルトのアクションは、すべての値制約が妥当性検査に含まれるということです。
修正 (Fix) はい いいえ 「なし (None)」 このプロパティーは編集できません。 最小限の修正が行われます。

Compute ノードの「説明 (Description)」プロパティーについては、次の表に説明されています。

プロパティー M C デフォルト 説明
簡略説明 (Short Description) いいえ いいえ   ノードの簡単な説明
詳細説明 (Long Description) いいえ いいえ   メッセージ・フロー内のノードの目的を説明するテキスト

関連概念
メッセージ・フロー
メッセージ・フロー、マッピング、および ESQL
相関名

関連タスク
DB2 のセットアップ
使用するノードの決定
メッセージの妥当性検査
宛先リストの作成
メッセージ・フローのエラー処理
整合されたメッセージ・フローの構成
ノードに対する ESQL の作成
ノードでの ESQL の構成
構成可能プロパティーの編集

関連資料
ESQL
単純タイプの論理値制約
mqsichangebroker コマンド
mqsicreatebroker コマンド
mqsisetdbparms コマンド