出口関数

このセクションでは、機能の呼び出しを使用するときに役立つ一般情報、および個別の出口関数を呼び出す方法について説明します。

この情報は、API 出口ルーチンに関する一般規則を理解し、出口の実行環境をセットアップおよびクリーンアップするために使用します。

以下の一般規則が API 出口ルーチンを起動する際に適用されます。
  • いずれの場合も、API 出口関数は、API 呼び出しパラメーターの妥当性検査の前、およびすべてのセキュリティー検査の前 (MQCONN、MQCONNX、または MQOPEN の場合) に実行されます。
  • フィールドに入力される値と、出口ルーチンから出力される値は、次のとおりです。
    • 前 IBM® MQ API 出口機能への入力では、アプリケーション・プログラムまたは前の出口機能呼び出しによって、フィールドの値を設定することができます。
    • 前 IBM MQ API 出口機能からの出力では、フィールドの値を未変更のままにすることも、出口機能によって他の値に設定することもできます。
    • 後 IBM MQ API 出口機能への入力では、フィールドの値は、 IBM MQ API 呼び出しの処理後にキュー・マネージャーによって設定された値にすることも、出口機能のチェーン内で前の出口機能呼び出しによって設定された値にすることもできます。
    • 後 IBM MQ API 呼び出し出口機能からの出力では、フィールドの値は未変更のままにすることも、出口機能によって他の値に設定することもできます。
  • 出口関数は ExitResponse および ExitResponse2 フィールドを使用してキュー・マネージャーと通信する必要があります。
  • CompCode および Reason コード・フィールドは、アプリケーションに返されます。 キュー・マネージャーおよび出口関数は、CompCode および Reason コード・フィールドを設定できます。
  • MQXEP 呼び出しは、MQXEP を呼び出す出口関数に新しい理由コードを戻します。 ただし、出口関数は、これらの新しい理由コードを、既存のアプリケーションおよび新規アプリケーションが理解できる既存の理由コードに変換することができます。
  • 各出口関数プロトタイプには、追加のレベルの間接参照を備えた、API 機能に対する同様のパラメーター (CompCode と Reason を除く) があります。
  • API 出口は MQI 呼び出し (MQDISC は除く) を発行できますが、これらの MQI 呼び出しは、 それ自体では API 出口を呼び出しません。

アプリケーションがサーバー上またはクライアント上のいずれにあるかに関係なく、API 出口呼び出しの順序を予測することはできないことに注意してください。 API 出口 BEFORE 呼び出しを AFTER 呼び出しの直前に置くことはできません。

BEFORE 呼び出しを別の BEFORE 呼び出しの前に置くことはできます。 以下に例を示します。
  • BEFORE MQCTL
  • BEFORE Callback
  • BEFORE MQPUT
  • AFTER MQPUT
  • AFTER Callback
  • AFTER MQCTL
または
  • BEFORE XAOPEN
  • BEFORE MQCONNX
  • AFTER MQCONNX
  • AFTER XAOPEN

クライアントでは、PreConnect 出口という、MQCONN 呼び出しまたは MQCONNX 呼び出しの動作を変更できる出口があります。 PreConnect 出口は、MQCONN 呼び出しまたは MQCONNX 呼び出しのすべてのパラメーター (キュー・マネージャー名を含む) を変更できます。 クライアントはこの出口を最初に呼び出し、続けて MQCONN 呼び出しまたは MQCONNX 呼び出しを起動します。 最初の MQCONN 呼び出しまたは MQCONNX 呼び出しのみが API 出口を呼び出すことに注意してください。それ以降の再接続呼び出しはいずれも効果がありません。

実行環境

一般に、出口関数からのすべてのエラーは、MQAXP 内の ExitResponse および ExitResponse2 フィールドを使用して出口ハンドラーに返信されます。

その後、これらのエラーは MQCC_* および MQRC_* 値に変換されて、CompCode フィールドと Reason フィールドに示される形でアプリケーションに返信されます。 ただし、出口ハンドラー・ロジック内で検出されたすべてのエラーは、CompCode フィールドと Reason フィールドに MQCC_* 値および MQRC_* 値として示されてアプリケーションに返信されます。

MQ_TERM_EXIT 機能がエラーを戻す場合は、次のようになります。
  • MQDISC 呼び出しは既に実行されています
  • 後 の MQ_TERM_EXIT 出口関数を実行する (それにより出口実行環境のクリーンアップを実行する) 機会は、この他にありません。
  • 出口実行環境のクリーンアップは行われていません。
出口は、まだ使用中である可能性があるため、アンロードできません。 また、前 出口が正常に実行された出口チェーンをさかのぼって、他の登録済み出口を逆の順序で実行できます。

出口実行環境のセットアップ

明示的な MQCONN または MQCONNX 呼び出しを処理するとき、出口ハンドリング論理は出口初期化機能 (MQ_INIT_EXIT) を起動する前に出口実行環境をセットアップします。 出口実行環境のセットアップには、出口のロード、ストレージの取得、および出口パラメーター構造体の初期化が含まれます。 出口構成ハンドルも割り振られます。

この段階でエラーが生じる場合、MQCONN または MQCONNX 呼び出しは CompCode MQCC_FAILED および以下の理由コードの 1 つを戻して失敗します。
MQRC_API_EXIT_LOAD_ERROR
API 出口モジュールをロードしようとして失敗しました。
MQRC_API_EXIT_NOT_FOUND
API 出口関数が API 出口モジュール内で見つかりませんでした。
MQRC_STORAGE_NOT_AVAILABLE
API 出口関数の実行環境を初期化しようとして、使用可能なストレージが不足しているために失敗しました。
MQRC_API_EXIT_INIT_ERROR
API 出口関数の実行環境を初期化する際にエラーが検出されました。

出口実行環境のクリーンアップ

明示的な MQDISC 呼び出しか、アプリケーション終了の結果としての暗黙の切断要求を処理している間に、出口ハンドリング論理は、出口終了機能 (MQ_TERM_EXIT) が登録されていればそれを起動した後で、出口実行環境をクリーンアップしなければならない場合があります。

出口実行環境のクリーンアップには、それまでにメモリーにロードされているモジュールを削除するなどして、出口パラメーター構造体のストレージを解放することが含まれます。

この段階でエラーが発生する場合、明示的な MQDISC 呼び出しは CompCode MQCC_FAILED および以下の理由コードの 1 つを戻して失敗します (暗黙の切断要求ではエラーは指摘されません)。
MQRC_API_EXIT_TERM_ERROR
API 出口関数の実行環境をクローズする際にエラーが検出されました。 出口は、MQ_TERM* API 出口関数呼び出しの前後に、MQDISC から失敗を戻さないようにします。