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

機能

MQCLOSE命令で,オブジェクトの利用を終了します。MQOPEN命令の反対の命令です。

形式

C言語の場合

MQCLOSE(MQHCONN Hconn, PMQHOBJ Hobj, MQLONG Options,
       PMQLONG CompCode, PMQLONG Reason)

COBOL言語の場合

CALL 'MQCLOSE' USING HCONN, HOBJ, OPTIONS, COMPCODE, REASON.

引数

● Hconn(MQHCONN型) -input

コネクションハンドルです。

キューマネジャへの接続を示すハンドルです。MQCONN命令の戻り値を指定してください。

● Hobj(MQHOBJ型) -input/output

オブジェクトハンドルです。

クローズするオブジェクトを示すハンドルです。どんなオブジェクトタイプでもかまいません。MQOPEN命令の戻り値を指定してください。

命令が成功すると,この引数には次の値が返されます。

MQHO_UNUSABLE_HOBJ
使用できないオブジェクトハンドル

● Options(MQLONG型) -input

MQCLOSE命令の動作を制御するクローズオプションです。

オブジェクトのクローズの方法を示します。永続的動的キューの場合だけ,キューを残す方法または削除する方法のどちらかでクローズできます。なお,永続的動的キューは,DefinitionType属性がMQQDT_PERMANENT_DYNAMICのキューです。クローズオプションについては,表2-1に示します。

次のどれかの値を取れます。

MQCO_NONE
特別なクローズオプションを要求しません。
次の場合に指定します。
  • キュー以外のオブジェクト
  • 定義済みキュー
  • 一時的動的キュー(ただし,Hobjのハンドルが,そのキューを生成したMQOPEN関数で返されたハンドルと異なる場合だけ指定できます)
  • 配布リスト
上記の場合,オブジェクトは削除されないで残されます。
このオプションを一時的動的キューに指定した場合で,Hobjのハンドルがそのキューを生成したMQOPEN命令で返されたハンドルのとき,キューは削除されます。そのほかのハンドルのときは,キューは残ります。
このオプションを永続的動的キューに指定した場合,キューは削除されないで残ります。
MQCO_DELETE
キューを削除します。
次のどちらかの場合,キューは削除されます。
  • 永続的動的キューで,メッセージを格納しないで,かつコミットしていないトランザクションからの登録・取り出しがない場合
    ほかのアプリケーションによる登録・取り出しがない場合も含みます。
  • 一時的動的キューで,Hobjのハンドルがそのキューを生成したMQOPEN命令で返されたハンドルの場合
上記以外の場合,理由コードMQRC_OPTION_NOT_VALID_FOR_TYPEで命令は失敗します。このとき,キューは削除されません。
MQCO_DELETE_PURGE
キューを強制的に削除します。
次のどちらかの場合,キューは削除されます。
  • 永続的動的キューで,コミットしていないトランザクションからの登録・取り出しがない場合
    ほかのアプリケーションによる登録・取り出しがない場合も含みます。
  • 一時的動的キューで,Hobjのハンドルがそのキューを生成したMQOPEN命令で返されたハンドルの場合
上記以外の場合,理由コードMQRC_OPTION_NOT_VALID_FOR_TYPEで命令は失敗します。この場合,キューは削除されません。

クローズオプションとオブジェクトの関係を次の表に示します。

表2-1 クローズオプションとオブジェクトの関係

オブジェクトクローズオプション
MQCO_NONEMQCO_DELETEMQCO_DELETE_PURGE
キュー以外122
定義済みキュー122
永続的動的キュー134
一時的動的キュー
(作成者)
555
一時的動的キュー
(作成者以外)
122
配布リスト122
(凡例)
1:オブジェクトは削除されません。
2:不正な組み合わせです。
3:キューが空であり,かつ未決着の登録・取り出しがないときだけ削除されます。
4:未決着の登録・取り出しがないときだけ削除されます。
5:オブジェクトは削除されます。

● CompCode(MQLONG型) -output

完了コードです。

次のどれかが返されます。

● Reason(MQLONG型) -output

理由コードです。

CompCode引数がMQCC_OKの場合

理由コード数値意味
MQRC_NONE0理由コードはありません。

CompCode引数がMQCC_WARNINGの場合

理由コード数値意味
MQRC_INCOMPLETE_GROUP2241メッセージグループが完全ではありません。
MQRC_INCOMPLETE_MSG2242論理メッセージが完全ではありません。

CompCode引数がMQCC_FAILEDの場合

理由コード数値意味
MQRC_HCONN_ERROR2018コネクションハンドルが不正です。
MQRC_HOBJ_ERROR2019オブジェクトハンドルが不正です。
MQRC_OBJECT_DAMAGED2101オブジェクトが破損しています。
MQRC_OPTION_NOT_VALID_FOR_TYPE2045オブジェクトタイプに適合しないオプションが指定されました。
MQRC_OPTIONS_ERROR2046オプションが不正です。または,指定されていません。
MQRC_Q_NOT_EMPTY2055キューに一つ以上のメッセージがあります。または,キューに対する登録・取り出し要求がコミットしていません。
MQRC_RESOURCE_PROBLEM2102システム資源が不足しています。
MQRC_STORAGE_NOT_AVAILABLE2071記憶容量が不足しています。
MQRC_UNEXPECTED_ERROR2195予期しないエラーが発生しました。

詳細は,「付録B.2 理由コード」を参照してください。

注意事項

  1. アプリケーションがMQDISC命令を呼び出したとき,または正常終了・異常終了したときに,オープンしたままのオブジェクトはMQCO_NONEオプションで自動的にクローズされます。
  2. キューをクローズするときは,次の点に注意してください。
    • トランザクション内で処理するときでも,同期点の結果に影響しません。同期点の前でもあとでもキューをクローズできます。
    • MQOO_BROWSEオプションでキューをオープンしていた場合,検索カーソルは消滅します。MQOO_BROWSEオプションで再びオープンしたときは,新しい検索カーソルが生成されます。MQOO_BROWSEオプションについては,この章の「MQOPEN命令 - オブジェクトのオープン」でOptions引数の説明を参照してください。
    • MQCLOSE命令を呼び出した時点で,そのハンドルで排他状態にしたメッセージがある場合,排他状態は解除されます。「1. データタイプ」の「MQGMO構造体 - メッセージ取り出しオプション」でOptionsフィールドのMQGMO_LOCKオプションの説明を参照してください。
  3. クローズされるオブジェクトが動的キュー(永続的動的キューまたは一時的動的キュー)であるとき,次の点に注意してください。
    • 一時的動的キューの場合で,Hobjのハンドルがそのキューを生成したMQOPEN命令で返されたハンドルのとき,キュー内にメッセージが格納されていてもキューは削除されます。このとき,Options引数に指定したオプションは関係ありません。これは,コミットしていないMQGET命令,MQPUT命令またはMQPUT1命令が,このハンドルを使用した場合,使用しなかった場合,およびそのキューに対して未決着のままの場合でも同様です。コミットしていない処理での更新が失われた場合も,トランザクションの失敗にはなりません。
    • 動的キューが削除されるときにキューに対して未解決のMQGMO_WAITオプションを指定するMQGET命令は取り消され,理由コードMQRC_Q_DELETEDが返されます。
      MQGMO_WAITオプションについては,「1. データタイプ」の「MQGMO構造体 - メッセージ取り出しオプション」でOptionsフィールドの説明を参照してください。
      動的キューが削除されたあとで,取得済みのHobjハンドルを使用してMQCLOSE命令以外の命令がキューを参照しようとすると,理由コードMQRC_Q_DELETEDで失敗します。
      削除されたキューにアプリケーションからアクセスできなくても,キューを参照するすべてのハンドルがクローズされ,キューに影響するすべてのトランザクションがコミットされるかロールバックされるまでは,キューはシステムから除去されず,関連リソースも解放されないことに注意してください。
    • 一時的動的キューをクローズするときにMQCLOSE命令に指定したHobjハンドルが,キューを作成したMQOPEN命令が返したハンドルである場合,キューは削除されます。これはMQCLOSE命令のクローズオプションに関係なく発生します。キューにメッセージがある場合は破棄されます。報告メッセージは生成されません。
      キューに影響を与える未コミットのトランザクションがあるときでも,キューとメッセージは削除されます。しかし,これによってトランザクションは失敗しません。ただし,上記のとおり,各トランザクションがコミットされるかロールバックされるまでは,トランザクションに関連するリソースは解放されません。
  4. クローズされるオブジェクトが配布リストの場合,次の点に注意してください。
    • 配布リストに対する適当なオプションはMQCO_NONEだけです。ほかのオプションが指定されると,理由コードMQRC_OPTIONS_ERRORまたはMQRC_OPTION_NOT_VALID_FOR_TYPEで失敗します。
    • 配布リストがクローズされるとき,リスト中のキューについてのおのおのの完了コードと理由コードは,返却されません。CompCode引数とReason引数は結果を確認するためだけに利用できます。
      キューのうち一つのクローズに失敗した場合も,キューマネジャは処理を続行し,配布リストの残りのキューをクローズしようとします。CompCode引数とReason引数は失敗を記述した情報を返します。しかし,ほとんどのキューのクローズに成功しても,完了コードがMQCC_FAILEDになる場合があります。なお,エラーの発生したキューは識別できません。
      一つ以上のキューでクローズに失敗しても,どんな失敗がCompCode引数とReason引数に報告されるかは定義されていません。