MQCTL - コールバック制御
MQCTL 呼び出しは、接続に対してオープンされたコールバックおよびオブジェクト処理に対する制御アクションを実行します。
構文
MQCTL(Hconn、Operation、ControlOpts、CompCode、Reason)
パラメーター
- Hconn
- タイプ: MQHCONN - 入力
このハンドルは、キュー・マネージャーに対する接続を表します。
Hconnの値は、先行の MQCONN または MQCONNX 呼び出しによって戻されたものです。z/OS® for CICS® アプリケーションでは、MQCONN 呼び出しを省略することができ、Hconnに以下の特殊値を指定できます。- MQHC_DEF_HCONN
- デフォルトの接続ハンドル。
- Operation
- タイプ: MQLONG - 入力指定されたオブジェクト・ハンドルに定義されたコールバックで処理されている操作。 以下のオプションのうち、いずれか 1 つだけを指定する必要があります。
- MQOP_START
指定された接続ハンドルについて定義されているすべてのメッセージ・コンシューマー関数のためのメッセージのコンシュームを開始します。
コールバックは、システムによって開始されるスレッド上で実行されます。 それはアプリケーション・スレッドのいずれとも異なります。
この操作は、提供された接続ハンドルの制御をシステムに渡します。 コンシューマー・スレッド以外のスレッドから発行できる MQI 呼び出しは、以下のものだけです。- Operation が MQOP_STOP の MQCTL
- Operation が MQOP_SUSPEND の MQCTL
- MQDISC - HConn の切断前に Operation が MQOP_STOP の MQCTL を実行します。
MQRC_HCONN_ASYNC_ACTIVE は、接続ハンドルの開始中に IBM® MQ API 呼び出しが発行され、呼び出しがメッセージ・コンシューマー機能から発信されない場合に戻されます。
MQCBCT_START_CALL 中にメッセージ・コンシューマーが接続を停止すると、MQCTL 呼び出しは失敗理由コード MQRC_CONNECTION_STOPPED で戻ります。
この呼び出しは、コンシューマー関数で発行できます。 コールバック・ルーチンと同じ接続の場合、以前に発行された MQOP_STOP 操作の取り消しのみが目的です。
このオプションは、 CICS on z/OS 環境ではサポートされません。また、アプリケーションがスレッド化されていない IBM MQ ライブラリーにバインドされている場合もサポートされません。
- MQOP_START_WAIT
- 指定された接続ハンドルについて定義されているすべてのメッセージ・コンシューマー関数のためのメッセージのコンシュームを開始します。メッセージ・コンシューマーは同じスレッド上で実行されます。 以下のことが発生する時点まで、制御は MQCTL の呼び出し側に戻されません。
- MQCTL MQOP_STOP または MQOP_SUSPEND 操作を使用して解放された時点、または
- すべてのコンシューマー・ルーチンが登録解除されたか中断された時点。
現行接続ハンドルまたはその他の接続ハンドルのいずれかについて、コールバック・ルーチン内からこのオプションを使用することはできません。 呼び出しが試行されると、MQRC_ENVIRONMENT_ERROR で戻ります。
MQOP_START_WAIT 操作中のいずれかの時点で、登録も中断もしていないコンシューマーがある場合は、呼び出しは理由コード MQRC_NO_CALLBACKS_ACTIVE で失敗します。
MQOP_START_WAIT 操作中に接続が中断されると、MQCTL 呼び出しは警告の理由コード MQRC_CONNECTION_SUSPENDED を返します。 この時点で接続は「開始済み」のままです。
アプリケーションは MQOP_STOP または MQOP_RESUME の発行を選択できます。 この場合、MQOP_RESUME 操作はブロックします。
このオプションは、単一スレッド・クライアントではサポートされていません。
- MQOP_STOP
- メッセージのコンシュームを停止し、すべてのコンシューマーがそれぞれの操作を完了するのを待機します。
その後、このオプションが完了します。 この操作は、接続ハンドルを解放します。
コールバック・ルーチン内から発行した場合、そのルーチンが終了する時点までこのオプションは有効になりません。 既に読んだメッセージのコンシューマー・ルーチンが完了し、コールバック・ルーチンの停止呼び出しが要求されて実行された後は、それ以上メッセージ・コンシューマー・ルーチンは呼び出されません。
コールバック・ルーチン外から発行された場合、既に読んだメッセージのコンシューマー・ルーチンが完了し、コールバックの停止呼び出しが要求されて実行された後、制御は呼び出し元に戻されません。 しかし、コールバック自体は登録済みのままです。
この関数は、先読みメッセージに対しては何の効果もありません。 コンシューマーがコールバック関数内から MQCLOSE(MQCO_QUIESCE) を実行して、配布可能なメッセージがさらにあるかどうかを判別することを確認しなければなりません。
- MQOP_SUSPEND
- メッセージのコンシュームを休止します。 この操作は、接続ハンドルを解放します。
この機能は、アプリケーションに関するメッセージの先読みに対しては影響しません。 長期間メッセージのコンシュームを停止する場合は、キューをクローズし、コンシュームを続行する時に再オープンすることを検討してください。
コールバック・ルーチン内から発行した場合、そのルーチンが終了する時点までは有効になりません。 現在のルーチンが終了すると、その後、メッセージ・コンシューマー・ルーチンは呼び出されなくなります。
コールバック外から発行された場合、現在のコンシューマー・ルーチンが完了して、それ以降にルーチンが呼び出されなくなるまで、制御は呼び出し元に戻されません。
- MQOP_RESUME
- メッセージのコンシュームを再開します。
通常このオプションはメイン・アプリケーション・スレッドから発行されますが、コールバック・ルーチン内から、同じルーチン内でそれより前に発行された中断要求を取り消す目的で使用することも可能です。
MQOP_RESUME を使用して MQOP_START_WAIT を再開すると、操作はブロックします。
- ControlOpts
- タイプ: MQCTLO - 入力
MQCTL のアクションを制御するオプション
この構造体の詳細については、 MQCTLO を参照してください。
- CompCode
- タイプ: MQLONG - 出力完了コード。以下のいずれかです。
- MQCC_OK
- 正常終了。
- MQCC_WARNING
- 警告 (部分完了)。
- MQCC_FAILED
- 呼び出し失敗。
- 理由
- タイプ: MQLONG - 出力
CompCodeが MQCC_OK の場合:- MQRC_NONE
- (0, X'000') レポートする理由コードはありません。
CompCodeが MQCC_FAILED の場合:- MQRC_ADAPTER_CONV_LOAD_ERROR
- (2133, X'855') データ変換サービス・モジュールをロードできない。
- MQRC_ADAPTER_NOT_AVAILABLE
- (2204, X'89C') アダプターが利用できません。
- MQRC_ADAPTER_SERV_LOAD_ERROR
- (2130, X'852') アダプター・サービス・モジュールをロードできません。
- MQRC_API_EXIT_ERROR
- (2374, X'946') API 出口で障害が発生しました。
- MQRC_API_EXIT_LOAD_ERROR
- (2183, X'887') API 出口をロードできません。
- MQRC_ASID_MISMATCH
- (2157, X'86D') 1 次 ASID とホーム ASID が異なっています。
- MQRC_BUFFER_LENGTH_ERROR
- (2005, X'7D5') バッファー長パラメーターは無効です。
- MQRC_CALLBACK_LINK_ERROR
- (2487, X'9B7') コールバック・ルーチンを呼び出せない
- MQRC_CALLBACK_NOT_ REGISTERED
- (2448, X'990') コールバックが登録されていないので、登録解除、中断、または再開できない
- MQRC_CALLBACK_ROUTINE_ERROR
- (2486, X'9B6') MQOP_REGISTER 呼び出し上で CallbackFunction と CallbackName の両方が指定されている。
- MQRC_CALLBACK_TYPE_ERROR
- (2483, X'9B3') CallBackType フィールドが正しくない。
- MQRC_CALL_IN_PROGRESS
- (2219, X'8AB') 前の呼び出しが完了する前に MQI 呼び出しが入力されました。
- MQRC_CBD_ERROR
- (2444, X'98C') オプション・ブロックが正しくない。
- MQRC_CBD_OPTIONS_ERROR
- (2484, X'9B4') MQCBD オプション・フィールドが正しくない。
- MQRC_CICS_WAIT_FAILED
- (2140, X'85C') 待機要求が CICS によって拒否されました。
- MQRC_CONNECTION_BROKEN
- (2009, X'7D9') キュー・マネージャーとの接続が失われました。
- MQRC_CONNECTION_NOT_AUTHORIZED
- (2217, X'8A9') 接続が許可されていません。
- MQRC_CONNECTION_QUIESCING
- (2202, X'89A') 接続が静止しています。
- MQRC_CONNECTION_STOPPING
- (2203, X'89B') 接続がシャットダウン中です。
- MQRC_CORREL_ID_ERROR
- (2207, X'89F') 相関 ID のエラー。
- MQRC_ENVIRONMENT_ERROR
- (2012, X'7DC') この環境では呼び出しが無効です。
- MQRC_FUNCTION_NOT_SUPPORTED
- (2298, X'8FA') 要求された関数は、現在の環境では使用できない。
- MQRC_GET_INHIBITED
- (2016, X'7E0') キューからの読み取りが禁止されている。
- MQRC_GLOBAL_UOW_CONFLICT
- (2351, X'92F') グローバル作業単位に矛盾がある。
- MQRC_GMO_ERROR
- (2186, X'88A') 読み取りメッセージ・オプションの構造体が無効である。
- MQRC_HANDLE_IN_USE_FOR_UOW
- (2353, X'931') グローバル作業単位のためのハンドルが使用中。
- MQRC_HCONN_ERROR
- (2018, X'7E2') 接続ハンドルが無効です。
- MQRC_HOBJ_ERROR
- (2019, X'7E3') オブジェクト・ハンドルが無効です。
- MQRC_INCONSISTENT_BROWSE
- (2259, X'8D3') ブラウズの指定が不整合である。
- MQRC_INCONSISTENT_UOW
- (2245, X'8C5') 作業単位の指定が不整合である。
- MQRC_INVALID_MSG_UNDER_CURSOR
- (2246, X'8C6') カーソル下のメッセージが取り出し対象として無効である。
- MQRC_LOCAL_UOW_CONFLICT
- (2352, X'930') グローバル作業単位とローカル作業単位に矛盾がある。
- MQRC_MATCH_OPTIONS_ERROR
- (2247, X'8C7') 突き合わせオプションが無効である。
- MQRC_MAX_MSG_LENGTH_ERROR
- (2485, X'9B5') MaxMsgLength フィールドが正しくない
- MQRC_MD_ERROR
- (2026, X'7EA') メッセージ記述子が無効である。
- MQRC_MODULE_ENTRY_NOT_FOUND
- (2497, X'9C1') 指定された機能入り口点がモジュール中になかった。
- MQRC_MODULE_INVALID
- (2496, X'9C0') モジュールが見つかったが、タイプが間違っている (32 ビット/64 ビット) か、有効な DLL ではない。
- MQRC_MODULE_NOT_FOUND
- (2495, X'9BF') モジュールが検索パス中にないか、またはロードが許可されていない。
- MQRC_MSG_ID_ERROR
- (2206, X'89E') メッセージ ID のエラー。
- MQRC_MSG_SEQ_NUMBER_ERROR
- (2250, X'8CA') メッセージ順序番号が無効である。
- MQRC_MSG_TOKEN_ERROR
- (2331, X'91B') メッセージ・トークンについて無効な使い方をしている。
- MQRC_NOT_OPEN_FOR_BROWSE
- (2036, X'7F4') ブラウズのためにキューがオープンされていない。
- MQRC_NOT_OPEN_FOR_INPUT
- (2037, X'7F5') 入力のためにキューがオープンされていない。
- MQRC_OBJECT_CHANGED
- (2041, X'7F9') オープンされた後でオブジェクト定義が変更された。
- MQRC_OBJECT_DAMAGED
- (2101, X'835') オブジェクトが損傷しました。
- MQRC_OPERATION_ERROR
- (2488, X'9B8') API 呼び出し上の命令コードが正しくない。
- MQRC_OPTIONS_ERROR
- (2046, X'7FE') オプションが無効であるか、矛盾しています。
- MQRC_PAGESET_ERROR
- (2193, X'891') ページ・セット・データ・セットへのアクセス中にエラーが発生しました。
- MQRC_Q_DELETED
- (2052, X'804') キューが削除されました。
- MQRC_Q_INDEX_TYPE_ERROR
- (2394, X'95A') キューの索引タイプが間違っている。
- MQRC_Q_MGR_NAME_ERROR
- (2058, X'80A') キュー・マネージャー名が無効であるか、認識されていません。
- MQRC_Q_MGR_NOT_AVAILABLE
- (2059, X'80B') キュー・マネージャーを接続に使用できません。
- MQRC_Q_MGR_QUIESCING
- (2161, X'871') キュー・マネージャーが静止しています。
- MQRC_Q_MGR_STOPPING
- (2162, X'872') キュー・マネージャーのシャットダウン中です。
- MQRC_RESOURCE_PROBLEM
- (2102, X'836') 使用できるシステム・リソースが不足しています。
- MQRC_SIGNAL_OUTSTANDING
- (2069, X'815') このハンドルに未解決のシグナルがある。
- MQRC_STORAGE_NOT_AVAILABLE
- (2071, X'817') ストレージが不足しています。
- MQRC_SUPPRESSED_BY_EXIT
- (2109, X'83D') 出口プログラムにより呼び出しが抑止されました。
- MQRC_SYNCPOINT_NOT_AVAILABLE
- (2072, X'818') 同期点サポートが利用できない。
- MQRC_UNEXPECTED_ERROR
- (2195, X'893') 予期しないエラーが発生しました。
- MQRC_UOW_ENLISTMENT_ERROR
- (2354, X'932') グローバル作業単位の参加に失敗した。
- MQRC_UOW_MIX_NOT_SUPPORTED
- (2355, X'933') 作業単位呼び出しの混合はサポートされていない。
- MQRC_UOW_NOT_AVAILABLE
- (2255, X'8CF') 作業単位がキュー・マネージャーから使用不可。
- MQRC_WAIT_INTERVAL_ERROR
- (2090, X'82A') MQGMO での待機間隔が無効である。
- MQRC_WRONG_GMO_VERSION
- (2256, X'8D0') 提供された MQGMO のバージョンが違っている。
- MQRC_WRONG_MD_VERSION
- (2257, X'8D1') 提供された MQMD のバージョンが違っている。
これらのコードについて詳しくは、 メッセージおよび理由コードを参照してください。
使用上の注意
- コールバック・ルーチンは、呼び出すすべてのサービスからの応答を検査しなければなりません。また解決できない条件をルーチンが検出した場合は、MQCB MQOP_DEREGISTER コマンドを発行してコールバック・ルーチンに対する呼び出しが繰り返されないようにしなければなりません。
- XA トランザクション・マネージャーがグローバル・トランザクション ( IBM MQへの更新を含む) を管理しているアプリケーションで非同期コンシュームを使用する場合は、以下の追加ポイントを考慮する必要があります。
- xa_openの呼び出し後に、作成後に HConnに対して MQCTL (MQOP_START) を呼び出すことは無効です。
理由は、HConn は XA コンテキストにアタッチされた状態になっているため、非同期コンシューム・メカニズムによって使用されている別個のスレッドではアクセスできないからです。
- そのシナリオで MQCTL(MQOP_START) を呼び出すと、呼び出しは理由コード MQRC_ASYNC_XA_CONFLICT (2350) で失敗します。
- HConn の MQCTL(MQOP_START_WAIT) の呼び出しは、 HConn が作成され、xa_open を呼び出した後で有効です。
理由は、非同期コンシューム・メカニズムを開始するこの方式では、HConn のその後のコールバックはすべて、MQCTL 呼び出しが行われたスレッドで実行されるようになるからです。 したがって、HConn とスレッドの間のリンクは失われません。
- xa_openの呼び出し後に、作成後に HConnに対して MQCTL (MQOP_START) を呼び出すことは無効です。
![[z/OS]](ngzos.gif)
オン z/OS、操作が MQOP_START の場合:- 非同期コールバック・ルーチンを使用するプログラムは、 z/OS UNIX System Services (z/OS UNIX) の使用を許可されている必要があります。
- 非同期コールバック・ルーチンを使用する Language Environment (LE) プログラムは、LE 実行時オプション POSIX(ON) を使用しなければなりません。
- 非同期コールバック・ルーチンを使用する非 LE プログラムは、 z/OS UNIX pthread_create インターフェース (呼び出し可能サービス BPX1PTC) を使用してはなりません。
- MQCTL は、 IMS アダプター内ではサポートされません。
C 言語での呼び出し
MQCTL (Hconn, Operation, &ControlOpts, &CompCode, &Reason)
MQHCONN Hconn; /* Connection handle */
MQLONG Operation; /* Operation being processed */
MQCTLO ControlOpts /* Options that control the action of MQCTL */
MQLONG CompCode; /* Completion code */
MQLONG Reason; /* Reason code qualifying CompCode */
COBOL での呼び出し
CALL 'MQCTL' USING HCONN, OPERATION, CTLOPTS, COMPCODE, REASON.
** Connection handle
01 HCONN PIC S9(9) BINARY.
** Operation
01 OPERATION PIC S9(9) BINARY.
** Control Options
01 CTLOPTS.
COPY CMQCTLOV.
** Completion code
01 COMPCODE PIC S9(9) BINARY.
** Reason code qualifying COMPCODE
01 REASON PIC S9(9) BINARY.
PL/I での呼び出し
call MQCTL(Hconn, Operation, CtlOpts, CompCode, Reason)
dcl Hconn fixed bin(31); /* Connection handle */
dcl Operation fixed bin(31); /* Operation */
dcl CtlOpts like MQCTLO; /* Options that control the action of MQCTL */
dcl CompCode fixed bin(31); /* Completion code */
dcl Reason fixed bin(31); /* Reason code qualifying CompCode */