MQCLOSE - オブジェクトのクローズ

MQCLOSE 呼び出しは、オブジェクトへのアクセスを解放するもので、MQOPEN および MQSUB 呼び出しの逆です。

構文

MQCLOSE(Hconn、Hobj、Options、CompCode、Reason)

パラメーター

Hconn
タイプ: MQHCONN - 入力

このハンドルは、キュー・マネージャーに対する接続を表します。 Hconn の値は、先行の MQCONN または MQCONNX 呼び出しによって戻されたものです。

z/OS® for CICS® アプリケーションでは、MQCONN 呼び出しを省略し、 Hconn に以下の値を指定することができます。
MQHC_DEF_HCONN
デフォルトの接続ハンドル。
Hobj
タイプ: MQHOBJ - 入出力

このハンドルは、クローズするオブジェクトを表します。 オブジェクトは、どのタイプでも構いません。 Hobj の値は、前の MQOPEN 呼び出しで戻されたものです。

呼び出しが正常に完了すると、キュー・マネージャーは、環境に対して有効なハンドルでない値にこのパラメーターを設定します。 値は、以下のとおりです。
MQHO_UNUSABLE_HOBJ
使用できないオブジェクト・ハンドル。

z/OSでは、 Hobj は未定義の値に設定されます。

オプション
タイプ: MQLONG - 入力

このパラメーターは、オブジェクトをクローズする方法を制御します。

複数の方法でクローズできるのは、永続的に動的なキューとサブスクリプションのみです。これらは、保持または削除する必要があるためです。これらは、値が MQQDT_PERMANENT ent_dynamic の DefinitionType 属性を持つキューです ( キューの属性 で説明されている DefinitionType 属性を参照してください)。 クローズ・オプションについては、このトピックで要約されています。

永続サブスクリプションについては、保持される場合と除去される場合があります。永続サブスクリプションは MQSO_DURABLE オプションを指定して MQSUB 呼び出しを使用することによって作成されます。

管理対象宛先に対するハンドル (MQSO_MANAGED オプションを使用した MQSUB 呼び出しで戻された Hobj パラメーター) をクローズする場合は、キュー・マネージャーが、関連サブスクリプションが除去されたときに取り出されなかったパブリケーションをすべてクリーンアップします。 サブスクリプションは、MQSUB 呼び出しで戻される Hsub パラメーターに対して MQCO_REMOVE_SUB オプションを使用して除去されます。 MQCO_REMOVE_SUB は、非永続サブスクリプションに対する MQCLOSE のデフォルトの動作であることに注意してください。

非管理対象の宛先へのハンドルを閉じる場合、パブリケーションが送信されるキューのクリーンアップはユーザーの責任で行います。 まず MQCO_REMOVE_SUB を使ってサブスクリプションをクローズし、その後、キューにメッセージが何も残らなくなるまで処理してください。

以下からオプションを 1 つだけ指定する必要があります。

動的キュー・オプション: このオプションは、永続動的キューをクローズする方法を制御します。
MQCO_DELETE
以下の条件のいずれかが真の場合、キューは削除されます。
  • 前の MQOPEN 呼び出しによって作成された永続動的キューであり、メッセージ、およびキューに対して未解決になっているコミットされていない読み取り要求また書き込み要求がない (現行タスクまたは任意のタスクのための)。
  • Hobj を戻す MQOPEN 呼び出しにより作成された一時動的キューである。 この場合、キューに入っているすべてのメッセージは消去されます。
その他の場合 (MQSUB 呼び出しで Hobj が戻された場合を含む) はすべて、呼び出しは失敗し、理由コード MQRC_OPTION_NOT_VALID_FOR_TYPE が戻ります。オブジェクトは削除されません。

z/OS では、キューが論理的に削除された動的キューであって、このハンドルがその動的キューの最後のハンドルである場合、キューは物理的に削除されます。 詳しくは、 使用上の注意 を参照してください。

MQCO_DELETE_PURGE
以下の条件のいずれかが真の場合、キューは削除され、キュー内のメッセージはパージされます。
  • 前の MQOPEN 呼び出しで作成された永続動的キューであり、キューに対して未解決になっているコミットされていない読み取り要求または書き込み要求がない (現行タスクまたはそれ以外の任意のタスクのための)。
  • Hobj を戻す MQOPEN 呼び出しにより作成された一時動的キューである。
その他の場合 (MQSUB 呼び出しで Hobj が戻された場合を含む) はすべて、呼び出しは失敗し、理由コード MQRC_OPTION_NOT_VALID_FOR_TYPE が戻ります。オブジェクトは削除されません。
表 1. さまざまなオブジェクト・タイプのクローズ・オプション
オブジェクトまたはキューのタイプ MQCO_NONE MQCO_DELETE MQCO_DELETE_PURGE
キュー以外のオブジェクト 保存 無効 無効
事前定義されたキュー 保存 無効 無効
永続動的キュー 保存 空で、保留中の更新がない場合は削除 メッセージを削除。保留中の更新がないキューを削除
一時動的キュー (キューの作成者から発行された呼び出し) 削除 削除 削除
一時動的キュー (キューの作成者から発行されていない呼び出し) 保存 無効 無効
配布リスト 保存 無効 無効
管理対象サブスクリプション宛先 保存 無効 無効
配布リスト (サブスクリプションは除去済み) メッセージを削除。キューを削除。 無効 無効
サブスクリプション閉止オプション: このオプションは、ハンドルをクローズしたときに永続サブスクリプションを除去するかどうか、アプリケーションによる読み取りを待機しているパブリケーションをクリーンアップするかどうかを制御します。 これらのオプションは、MQSUB 呼び出しの Hsub パラメーターで返されるオブジェクト・ハンドルで使用する場合にのみ有効です。
MQCO_KEEP_SUB
サブスクリプションに対するハンドルはクローズされますが、作成されたサブスクリプションは保持されます。 パブリケーションは引き続き、サブスクリプションで指定された宛先に送られます。 このオプションは、オプション MQSO_DURABLE を指定してサブスクリプションが作成された場合のみ有効です。
サブスクリプションが永続サブスクリプションの場合、MQCO_KEEP_SUB はデフォルトです。
MQCO_REMOVE_SUB
サブスクリプションは除去され、サブスクリプションに対するハンドルはクローズされます。
MQSUB 呼び出しの Hobj パラメーターは Hsub パラメーターの閉止によって無効にされず、残りのパブリケーションを受け取るために引き続き MQGET または MQCB で使用することができます。 MQSUB 呼び出しの Hobj パラメーターもクローズされると、それが管理対象宛先だった場合、取得されていないパブリケーションはすべて除去されます。
サブスクリプションが非永続サブスクリプションの場合、MQCO_REMOVE_SUB はデフォルトです。
MQCO_REMOVE_SUB の正常終了は、アクションが完了したことを意味しません。 この呼び出しが完了したことを確認するには、 分散ネットワークの非同期コマンドが終了したことの確認の DELETE SUB ステップを参照してください。

このサブスクリプション閉止オプションについては次の表で要約されています。

表 2. 永続サブスクリプション・ハンドルをクローズしてもサブスクリプションは保持するためのオプション
タスク サブスクリプション閉止オプション
MQOPENed ハンドルのパブリケーションを保持する MQCO_KEEP_SUB
MQOPENed ハンドルのパブリケーションを除去する アクションは許可されていない
MQSO_MANAGED ハンドルのパブリケーションを保持する MQCO_KEEP_SUB
MQSO_MANAGED ハンドルのパブリケーションを除去する アクションは許可されていない
永続サブスクリプション・ハンドルを閉じてアンサブスクライブするか、または非永続サブスクリプション・ハンドルを閉じることによってアンサブスクライブを行うには、以下のサブスクリプションのクローズ・オプションを使用します。
表 3. アンサブスクライブのオプション
タスク サブスクリプション閉止オプション
MQOPENed ハンドルのパブリケーションを保持する MQCO_REMOVE_SUB
MQOPENed ハンドルのパブリケーションを除去する アクションは許可されていない
MQSO_MANAGED ハンドルのパブリケーションを保持する MQCO_REMOVE_SUB
先読みオプション: 次のオプションは、アプリケーションによって要求される前に非永続メッセージがクライアントに送られ、アプリケーションによってコンシュームされなかった場合の非永続メッセージの処理を制御します。 これらのメッセージは、クライアント先読みバッファーに格納されてアプリケーションによる要求を待機し、MQCLOSE が完了する前にキューから廃棄またはコンシュームすることができます。
MQCO_IMMEDIATE
オブジェクトは即時にクローズされ、アプリケーションが要求する前にクライアントに送信されたメッセージはすべて廃棄されます。アプリケーションがこのメッセージをコンシュームすることはできません。 これがデフォルト値です。
MQCO_QUIESCE
オブジェクトのクローズ要求は行われますが、アプリケーションがそれを要求する前にクライアントに送られたメッセージがクライアントの先読みバッファーに存在する場合、MQCLOSE を呼び出す際に MQRC_READ_AHEAD_MSGS という警告が戻され、オブジェクト・ハンドルは有効なままとなります。

アプリケーションは引き続きそのオブジェクト・ハンドルを使用することができ、メッセージがなくなるまで取り出しを続行します。その後、オブジェクトを再びクローズします。 アプリケーションが要求する前にメッセージがクライアントに送られることはなくなり、先読みはオフになります。

アプリケーションでは、クライアントの先読みバッファーにメッセージがなくなる時点まで試すのではなく、MQCO_QUIESCE を使用することをお勧めします。 最後に MQGET を呼び出してから次の MQCLOSE までの間にメッセージが到着する可能性があり、MQCO_IMMEDIATE が使用されている場合にそのメッセージは廃棄されてしまうからです。

MQCO_QUIESCE を指定した MQCLOSE を非同期コールバック関数内から発行すると、先読みメッセージと同じ動作になります。 警告 MQRC_READ_AHEAD_MSGS が戻された場合、少なくとももう一度コールバック関数が呼び出されます。 最後に残っている先読みメッセージがコールバック関数に渡されると、MQCBC ConsumerFlags フィールドが MQCBCF_READA_BUFFER_EMPTY に設定されます。

デフォルト・オプション: 上記で説明されたオプションのいずれも必要としない場合、以下のオプションを使用できます。

MQCO_NONE
オプションのクローズ処理は不要である。
これは、次のものに対して指定しなければなりません。
  • キュー以外のオブジェクト
  • 事前定義キュー
  • 一時動的キュー (ただし、 Hobj が、キューを作成した MQOPEN 呼び出しによって戻されるハンドルではない場合に限ります)。
  • 配布リスト
上記の場合はすべて、オブジェクトは残され、削除されません。
このオプションが一時動的キューに対して指定されていると、次のようになります。
  • キューは、 Hobj を戻した MQOPEN 呼び出しによって作成された場合には削除されます。キュー上にあるメッセージはすべて除去されます。
  • 上記以外の場合、キュー (およびキュー内のすべてのメッセージ) は保存されます。

永続動的キューに対してこのオプションが指定されていると、キューは残され、削除されません。

z/OS では、キューが論理的に削除された動的キューであって、このハンドルがその動的キューの最後のハンドルである場合、キューは物理的に削除されます。 詳しくは、 使用上の注意 を参照してください。

CompCode
タイプ: MQLONG - 出力
完了コード。以下のいずれかです。
MQCC_OK
正常終了。
MQCC_WARNING
警告 (部分完了)。
MQCC_FAILED
呼び出し失敗。

理由
タイプ: MQLONG - 出力

次に示す理由コードは、キュー・マネージャーが Reason パラメーターに対して返すことのある理由コードです。

CompCodeが MQCC_OK の場合:
MQRC_NONE
(0, X'000') レポートする理由コードはありません。
CompCodeが MQCC_WARNING の場合:
MQRC_INCOMPLETE_GROUP
(2241, X'8C1') メッセージ・グループが不完全である。
MQRC_INCOMPLETE_MSG
(2242, X'8C2') 論理メッセージが不完全である。
MQRC_READ_AHEAD_MSGS
(nnnn, X'xxx') クライアントに、まだアプリケーションによってコンシュームされていない先読みメッセージがある。
CompCodeが MQCC_FAILED の場合:
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_CALL_IN_PROGRESS
(2219, X'8AB') 前の呼び出しが完了する前に MQI 呼び出しが入力されました。
MQRC_CF_NOT_AVAILABLE
(2345, X'929') カップリング・ファシリティーが使用できません。
MQRC_CF_STRUC_FAILED
(2373, X'945') カップリング・ファシリティー構造体で障害が発生しました。
MQRC_CF_STRUC_IN_USE
(2346, X'92A') カップリング・ファシリティー構造体が使用中です。
MQRC_CICS_WAIT_FAILED
(2140, X'85C') 待機要求が CICS によって拒否されました。
MQRC_CONNECTION_BROKEN
(2009, X'7D9') キュー・マネージャーとの接続が失われました。
MQRC_CONNECTION_NOT_AUTHORIZED
(2217, X'8A9') 接続が許可されていません。
MQRC_CONNECTION_STOPPING
(2203, X'89B') 接続がシャットダウン中です。
MQRC_DB2_NOT_AVAILABLE
(2342, X' 926 ') Db2® サブシステムが使用できません。
MQRC_HCONN_ERROR
(2018, X'7E2') 接続ハンドルが無効です。
MQRC_HOBJ_ERROR
(2019, X'7E3') オブジェクト・ハンドルが無効です。
MQRC_NOT_AUTHORIZED
(2035, X'7F3') アクセスは許可されません。
MQRC_OBJECT_DAMAGED
(2101, X'835') オブジェクトが損傷しました。
MQRC_OPTION_NOT_VALID_FOR_TYPE
(2045, X'7FD') MQOPEN または MQCLOSE 呼び出しで、オプションが、オブジェクト・タイプとして無効である。
MQRC_OPTIONS_ERROR
(2046, X'7FE') オプションが無効であるか、矛盾しています。
MQRC_PAGESET_ERROR
(2193, X'891') ページ・セット・データ・セットへのアクセス中にエラーが発生しました。
MQRC_Q_MGR_NAME_ERROR
(2058, X'80A') キュー・マネージャー名が無効であるか、認識されていません。
MQRC_Q_MGR_NOT_AVAILABLE
(2059, X'80B') キュー・マネージャーを接続に使用できません。
MQRC_Q_MGR_STOPPING
(2162, X'872') キュー・マネージャーのシャットダウン中です。
MQRC_Q_NOT_EMPTY
(2055, X'807') メッセージ、またはコミットされていない 書き込み要求か取得要求が、1 つ以上キューに入っています。
MQRC_RESOURCE_PROBLEM
(2102, X'836') 使用できるシステム・リソースが不足しています。
MQRC_SECURITY_ERROR
(2063, X'80F') セキュリティー・エラーが発生しました。
MQRC_STORAGE_NOT_AVAILABLE
(2071, X'817') ストレージが不足しています。
MQRC_SUPPRESSED_BY_EXIT
(2109, X'83D') 出口プログラムにより呼び出しが抑止されました。
MQRC_UNEXPECTED_ERROR
(2195, X'893') 予期しないエラーが発生しました。

これらのコードについて詳しくは、 メッセージおよび理由コードを参照してください。

使用上の注意

  1. アプリケーションが MQDISC 呼び出しを発行するか、正常終了または異常終了すると、このアプリケーションによってオープンされたままになっているすべてのオブジェクトは、MQCO_NONE オプションで自動的にクローズされます。
  2. クローズされるオブジェクトがキュー であるときに、以下の点が適用されます。
    • キューに対する操作が作業単位の一部として実行された場合は、そのキューは、同期点の前後のいずれでも、同期点の結果に影響を与えることなくクローズすることができます。 キューがトリガーされる場合に、キューをクローズする前にロールバックを実行すると、トリガー・メッセージが発行されます。 トリガー・メッセージについて詳しくは、 トリガー・メッセージのプロパティーを参照してください。
    • キューが MQOO_BROWSE オプションでオープンされた場合、ブラウズ・カーソルは破棄されます。 その後、MQOO_BROWSE オプションを指定してキューを再オープンすると、新しいブラウズ・カーソルが作成されます ( MQOO_BROWSE を参照)。
    • MQCLOSE 呼び出しの時点でこのハンドルに対して現在ロックされているメッセージがある場合、ロックは解除されます ( MQGMO_LOCK を参照)。
    • z/OSでは、クローズされるキュー・ハンドルに対して MQGMO_SET_SIGNAL オプションを指定した MQGET 要求が未解決の場合、その要求は取り消されます ( MQGMO_SET_SIGNAL を参照)。 同じキューのシグナル要求でも、異なるハンドル (Hobj) に対して設定されている要求は、影響を受けません (ただし、動的キューが削除対象でない場合は、このような要求も取り消されます)。
  3. クローズされるオブジェクトが動的キュー (永続または一時) であるとき、以下の点が適用されます。
    • 動的キューの場合、MQCO_DELETE および MQCO_DELETE_PURGE オプションは、対応する MQOPEN 呼び出し上に指定されたオプションに関係なく指定することができます。
    • 動的キューが削除されると、キューに対して未解決になっている、MQGMO_WAIT オプションをもつすべての MQGET 呼び出しは取り消され、理由コード MQRC_Q_DELETED が戻ります。 MQGMO_WAITを参照してください。

      削除されたキューはアプリケーションからアクセスできません。しかし、キューを参照するすべてのハンドルがクローズして、キューに影響を与えるすべての作業単位がコミットされるかまたはバックアウトされるまでは、キューはシステムから除去されず、また関連リソースも解放されません。

      z/OS において、論理的には削除されているがまだシステムから除去されていないキューがあると、削除したキューと同じ名前を指定してキューを新規作成することができません。 このような場合、MQOPEN 呼び出しは失敗し、理由コード MQRC_NAME_IN_USE が戻されます。 また、そのようなキューは MQSC コマンドを使用して表示されたままになる場合があります。ただし、アプリケーションからアクセスすることはできません。

    • 永続動的キューが削除されると、MQCLOSE 呼び出しで指定した Hobj ハンドルが、キューを作成した MQOPEN 呼び出しによって戻されたハンドルではない場合は、MQOPEN 呼び出しを妥当性検査するために使用されたユーザー ID が、キューを削除する許可を持っているかどうかが検査されます。 MQOPEN 呼び出し時に MQOO_ALTERNATE_USER_AUTHORITY オプションが指定された場合、検査されたユーザー ID は AlternateUserId になります。
      この検査は以下のような場合は実行されません。
      • 指定されたハンドルが、キューを作成した MQOPEN 呼び出しによって戻されたハンドルである場合。
      • 削除されるキューが一時動的キューの場合。
    • 一時動的キューがクローズされるときに、MQCLOSE 呼び出しで指定された Hobj ハンドルが、キューを作成した MQOPEN 呼び出しによって戻されたハンドルである場合、そのキューは削除されます。 これは MQCLOSE 呼び出し時にクローズ・オプションが指定されているか否かにかかわりなく起こります。 キューにメッセージがある場合、それらは廃棄されます。その際、レポート・メッセージは生成されません。

      キューに影響を与える、コミットされていない作業単位がある場合でも、キューとそのメッセージは削除されます。しかし、作業単位は失敗しません。 ただし、前述のとおり、各作業単位がコミットされるか、またはバックアウトされるまでは、作業単位に関連するリソースは解放されません。

  4. クローズされるオブジェクトが配布リスト であるとき、以下の点が適用されます。
    • 配布リストに有効なクローズ・オプションは MQCO_NONE だけです。この呼び出しは、他のオプションが指定されている場合には失敗し、理由コード MQRC_OPTIONS_ERROR または MQRC_OPTION_NOT_VALID_FOR_TYPE が戻ります。
    • 配布リストがクローズされると、リスト内のキューについて個々の完了コードおよび理由コードは戻されません。診断目的に利用できるのは、この呼び出しの CompCode および Reason パラメーターだけです。

      いずれかのキューのクローズ時に障害が起こっても、キュー・マネージャーは処理を継続し、配布リスト内の残りのキューをクローズしようとします。 次に、この呼び出しの CompCode および Reason パラメーターが、その障害を記述する情報を戻すよう設定されます。 キューのほとんどが正常にクローズされた場合でも、完了コードが MQCC_FAILED になる場合があります。 クローズ中にエラーが発生したキューは、識別されません。

      複数のキューで障害が発生した場合、 CompCode および Reason パラメーターで報告される障害は定義されません。

C 言語での呼び出し

MQCLOSE (Hconn, &Hobj, Options, &CompCode, &Reason);
パラメーターを次のように宣言します。
MQHCONN  Hconn;     /* Connection handle */
MQHOBJ   Hobj;      /* Object handle */
MQLONG   Options;   /* Options that control the action of MQCLOSE */
MQLONG   CompCode;  /* Completion code */
MQLONG   Reason;    /* Reason code qualifying CompCode */

COBOL での呼び出し

     CALL 'MQCLOSE' USING HCONN, HOBJ, OPTIONS, COMPCODE, REASON.
パラメーターを次のように宣言します。
**   Connection handle
 01  HCONN     PIC S9(9) BINARY.
**   Object handle
 01  HOBJ      PIC S9(9) BINARY.
**   Options that control the action of MQCLOSE
 01  OPTIONS   PIC S9(9) BINARY.
**   Completion code
 01  COMPCODE  PIC S9(9) BINARY.
**   Reason code qualifying COMPCODE
 01  REASON    PIC S9(9) BINARY.

PL/I での呼び出し

call MQCLOSE (Hconn, Hobj, Options, CompCode, Reason);
パラメーターを次のように宣言します。
dcl Hconn     fixed bin(31);  /* Connection handle */
dcl Hobj      fixed bin(31);  /* Object handle */
dcl Options   fixed bin(31);  /* Options that control the action of
                                 MQCLOSE */
dcl CompCode  fixed bin(31);  /* Completion code */
dcl Reason    fixed bin(31);  /* Reason code qualifying CompCode */

高水準アセンブラー呼び出し

CALL MQCLOSE,(HCONN,HOBJ,OPTIONS,COMPCODE,REASON)
パラメーターを次のように宣言します。
HCONN     DS  F  Connection handle
HOBJ      DS  F  Object handle
OPTIONS   DS  F  Options that control the action of MQCLOSE
COMPCODE  DS  F  Completion code
REASON    DS  F  Reason code qualifying COMPCODE

Visual Basic での呼び出し

MQCLOSE Hconn, Hobj, Options, CompCode, Reason
パラメーターを次のように宣言します。
Dim Hconn    As Long 'Connection handle'
Dim Hobj     As Long 'Object handle'
Dim Options  As Long 'Options that control the action of MQCLOSE'
Dim CompCode As Long 'Completion code'
Dim Reason   As Long 'Reason code qualifying CompCode'