API 出口の構成

API 出口は、ユーザー自身が用意するコード・モジュール (.dll ファイル) で、MQI 呼び出しの直前または直後に実行します。

このタスクについて

IBM® MQ がプログラムからその API エントリー・ポイントへのいずれかに対する呼び出しを受け取ると、IBM MQ はユーザーの API 出口を呼び出します。ユーザーが出口をどのように構成したかに応じて、API 出口は MQI 実行の前か後に実行されます。

呼び出される出口を全く構成しないことも、1 つあるいは多くの出口が呼び出されるように構成することもでき、複数の出口が呼び出される順序を構成することもできます。 WindowsLinux® (x86 および x86-64 プラットフォーム) では、IBM MQ エクスプローラーを使って API 出口を構成することができます。 構成の詳細は .ini ファイルに保管されています。

  1. IBM MQ エクスプローラー で API 出口を構成する。
  2. 共通 API 出口をローカル API 出口でオーバーライドする。
API 出口定義には 3 つのタイプがあります。
共通 (ApiExitCommon)
コンピューターごとに 1 セットの定義です。 キュー・マネージャーが開始するときに、定義されている API 出口があればそれらが読み取られてキュー・マネージャーに適用されます。 共通 API 出口は IBM MQ プロパティー・ダイアログで構成します。 共通出口は、各ローカル・キュー・マネージャーのプロパティー・ダイアログ内の「ローカル API 出口」テーブルに表示されます。
テンプレート (ApiExitTemplate)
コンピューターごとに 1 セットの定義です。 キュー・マネージャーが作成されるときに、ここに定義されている API 出口があれば、それらはローカル出口として、新たに作成されるキュー・マネージャーにコピーされます。 テンプレート API 出口は IBM MQ プロパティー・ダイアログで構成します。
ローカル (ApiExitLocal)
キュー・マネージャーごとに 1 セットの定義です。 キュー・マネージャーが開始するときに、「名前」属性が共通出口と同じで「指定変更」が指定されている API 出口が定義されていれば、それらは共通出口をオーバーライドします。 共通 API 出口がオーバーライドされる場合、たとえオプションの「データ」属性に割り当てられた値があっても、共通定義内のフィールドはどれも保存されません。 ローカル API 出口は、キュー・マネージャーのプロパティー・ダイアログで構成します。
IBM MQ およびキュー・マネージャー・プロパティー・ダイアログで API 出口を構成すると、構成ファイル内または Windows レジストリー内の ApiExitCommonApiExitTemplate、および ApiExitLocal スタンザに属性値が追加されます。
表 1. API 出口属性
属性 意味 スタンザ鍵
名前 MQAXP 構造の ExitInfoName フィールドの API 出口に渡される API 出口の記述名を指定します。 この名前は固有でなければならず、48 文字の長さに制限されています。また IBM MQ オブジェクトの 名前 (キュー名など) に有効な文字だけを使用する必要があります。 名前
タイプ 出口のタイプとして、共通テンプレートローカル、または指定変更を指定します。 (個別のスタンザ鍵以外。)
シーケンス この属性は符号なしの数値で、この API 出口が他の API 出口との比較で呼び出されるシーケンスを定義します。 シーケンス番号の小さい API 出口は、シーケンス番号の大きい他の API 出口よりも先に呼び出されます。 同じシーケンス番号を持つ異なる複数の API 出口が呼び出される順序は定義されていません。 つまり、キュー・マネージャーに定義された API 出口のシーケンス番号において確実にギャップが存在します。 シーケンス
モジュール API 出口のコードを含むモジュールを指定します。 このフィールドにモジュールの絶対パス名が入っている場合、それがそのまま使用されます。 このフィールドにモジュール名のみが入っている場合は、モジュールはチャネル出口と同じ方法を使用して配置されます。つまり、「キュー・マネージャー・プロパティー」ダイアログの「出口」ページの「出口デフォルト・パス」フィールドの値を使用して配置されます。 モジュール
関数 API 出口のコードを含むモジュールへの関数エントリー・ポイントの名前を指定します。 このエントリー・ポイントは MQ_INIT_EXIT 関数です。 このフィールドの長さは MQ_EXIT_NAME_LENGTH に制限されています。 関数
データ この属性が指定されている場合、先行ブランクと末尾ブランクは除去され、 残りのストリングは 32 文字に切り捨てられ、その結果が MQAXP 構造の ExitData フィールドの出口に渡されます。 この属性が指定されていない場合は、デフォルト値の 32 ブランクが MQAXP 構造の ExitData フィールドの出口に渡されます。 データ

手順

  • [オプション 1] IBM MQ エクスプローラー で API 出口を構成する。
    1. 関係するプロパティー・ダイアログを開きます。
    2. 「出口」ページで、「追加...」をクリックします。 「API 出口の追加」ダイアログが開きます。
    3. 「API 出口の追加」ダイアログのフィールドに必要な情報を入力します。
    4. 「OK」をクリックして出口を作成し、「API 出口の追加」ダイアログをクローズします。
    新規 API 出口のプロパティーが、「出口」ページのテーブル内に表示されます。
  • [オプション 2] 共通 API 出口をローカル API 出口でオーバーライドする。

    共通出口と同じ名前のローカル API 出口がキュー・マネージャー上に定義されている場合には、共通出口がオーバーライドされます。 つまり、共通出口は呼び出されず、オーバーライドしたローカル出口が代わりに呼び出されます。 不慮のオーバーライドを避けるために、ユーザー・インターフェースは、オーバーライドを構成する際に慎重なアクションを取るようユーザーに求めます。例えば、既存の出口と同じ名前の新規出口を追加することはできず、出口の名前を既存の出口と同じ名前に変更することもできません。 しかし、ローカル API 出口をキュー・マネージャーに追加して、共通 API 出口ではなく、ローカル API 出口を使用したい場合もあります。 このような場合には、共通 API 出口をローカル API 出口でオーバーライドする必要があります。

    1. キュー・マネージャーのプロパティー・ダイアログの「出口」ページを開きます。
    2. 「ローカル API 出口」テーブルで、オーバーライドする共通出口をクリックします。
    3. 「オーバーライド」をクリックします。
      その共通 API 出口の名前が表示された「API 出口の編集」ダイアログが開きます。
    4. 「API 出口の編集」ダイアログで、ローカル API 出口の詳細を入力し、「OK」をクリックして変更を保存します。
    これで、ローカル出口が同じ名前の共通出口をオーバーライドします。