MQOPEN - オブジェクトのオープン

MQOPEN の呼び出しはオブジェクトへのアクセスを確立します。

次のタイプのオブジェクトが有効です。
  • キュー (配布リストを含む)
  • 名前リスト
  • プロセス定義
  • キュー・マネージャー
  • トピック

構文

MQOPEN(Hconn、ObjDesc、Options、Hobj、CompCode、Reason)

パラメーター

Hconn
タイプ: MQHCONN - 入力

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

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

これは、オープンするオブジェクトを識別する構造体です。詳しくは、 MQOD-オブジェクト記述子 を参照してください。

ObjDesc パラメーターの ObjectName フィールドがモデル・キューの名前である場合、モデル・キューの属性を使用して動的ローカル・キューが作成されます。これは、 Options パラメーターで指定したオプションに関係なく発生します。 MQOPEN 呼び出しによって返される Hobj を使用する後続の操作は、モデル・キューではなく新しい動的キューで行われます。 MQINQ 呼び出しおよび MQSET 呼び出しの場合でも同じです。 ObjDesc パラメーターのモデル・キューの名前は、作成された動的キューの名前で置き換えられます。 動的キューのタイプは、モデル・キューの DefinitionType 属性の値によって決まります ( キューの属性 を参照)。 動的キューに適用されるクローズ・オプションの詳細については、MQCLOSE 呼び出しの記述を参照してください。

オプション
タイプ: MQLONG - 入力
以下のオプションのうち少なくとも 1 つを指定する必要があります。
  • MQOO_BROWSE
  • MQOO_INPUT_* (このうちの 1 つだけ)
  • MQOO_INQUIRE
  • MQOO_OUTPUT
  • MQOO_SET
  • MQOO_BIND_* (このうちの 1 つだけ)
これらのオプションの詳細については、以下の表を参照してください。その他のオプションは必要に応じて指定することができます。 複数のオプションを指定するには、値を加算する (同じ定数を複数回加算しない) か、ビット単位 OR 演算を使用して値を結合 (プログラミング言語でビット演算がサポートされる場合) します。 無効な組み合わせには、その旨を示しています。その他の組み合わせはすべて有効です。 ObjDesc によって指定されたオブジェクトのタイプに適用されるオプションだけが許可されます。
表 1. キューおよびトピックに有効な MQOPEN オプション
オプション 別名 1 ローカルおよびモデル リモート 非ローカル・クラスター 配布リスト トピック
MQOO_INPUT_AS_Q_DEF はい はい いいえ いいえ いいえ いいえ
MQOO_INPUT_SHARED はい はい いいえ いいえ いいえ いいえ
MQOO_INPUT_EXCLUSIVE はい はい いいえ いいえ いいえ いいえ
MQOO_OUTPUT はい はい はい はい はい はい
MQOO_BROWSE はい はい いいえ いいえ いいえ いいえ
MQOO_CO_OP はい はい いいえ いいえ いいえ いいえ
MQOO_INQUIRE はい はい 2 はい いいえ いいえ
MQOO_SET はい はい 2 いいえ いいえ いいえ
MQOO_BIND_ON_OPEN 3 はい はい はい はい はい いいえ
MQOO_BIND_NOT_FIXED 3 はい はい はい はい はい いいえ
MQOO_BIND_ON_GROUP 3 はい はい はい はい はい いいえ
MQOO_BIND_AS_Q_DEF 3 はい はい はい はい はい いいえ
MQOO_SAVE_ALL_CONTEXT はい はい いいえ いいえ いいえ いいえ
MQOO_PASS_IDENTITY_CONTEXT はい はい はい はい はい 4
MQOO_PASS_ALL_CONTEXT はい はい はい はい はい はい
MQOO_SET_IDENTITY_CONTEXT はい はい はい はい はい 4
MQOO_SET_ALL_CONTEXT はい はい はい はい はい はい
MQOO_NO_READ_AHEAD はい はい いいえ いいえ いいえ いいえ
MQOO_READ_AHEAD はい はい いいえ いいえ いいえ いいえ
MQOO_READ_AHEAD_AS_Q_DEF はい はい いいえ いいえ いいえ いいえ
MQOO_ALTERNATE_USER_AUTHORITY はい はい はい はい はい はい
MQOO_FAIL_IF_QUIESCING はい はい はい はい はい はい
MQOO_RESOLVE_LOCAL_Q はい はい はい はい いいえ いいえ
MQOO_RESOLVE_LOCAL_TOPIC いいえ いいえ いいえ いいえ いいえ はい
MQOO_NO_MULTICAST いいえ いいえ いいえ いいえ いいえ はい
注:
  1. 別名のオプションの妥当性は、その別名が解決されるキューのオプションの妥当性に応じて決められます。
  2. このオプションは、リモート・キューのローカル定義の場合にのみ有効です。
  3. このオプションは、どのタイプのキューについても指定できますが、そのキューがクラスター・キューでない場合は無視されます。 ただし DefBind キュー属性は、別名キューがクラスター内にない場合でも基本キューをオーバーライドします。
  4. これらの属性はトピックで使用できますが、サブスクライバーに送信されるコンテキスト・フィールドではなく、保持されるメッセージに設定されたコンテキストにのみ影響します。
アクセス・オプション: 以下のオプションは、オブジェクトに対して実行できる操作のタイプを制御します。
MQOO_INPUT_AS_Q_DEF
キュー定義のデフォルトを使用してメッセージを取得するためにキューを開きます。

後続の MQGET 呼び出しで使用するために、キューが開かれます。 アクセスのタイプは、 DefInputOpenOption キュー属性の値に応じて、共用または排他のいずれかになります。詳しくは、 キューの属性 を参照してください。

このオプションは、ローカル・キュー、別名キュー、およびモデル・キューに関してのみ有効です。リモート・キューや配布リスト、さらにキューでないオブジェクトに関しては無効です。

MQOO_INPUT_SHARED
共有アクセスによりメッセージを読み取るためにキューをオープンする。

後続の MQGET 呼び出しで使用するために、キューが開かれます。 このアプリケーションまたは別のアプリケーションによって、キューが MQOO_INPUT_SHARED で現在オープンされている場合は、この呼び出しは正常に行われますが、キューが MQOO_INPUT_EXCLUSIVE でオープンされている場合は失敗し、理由コード MQRC_OBJECT_IN_USE が戻ります。

このオプションは、ローカル・キュー、別名キュー、およびモデル・キューに関してのみ有効です。リモート・キューや配布リスト、さらにキューでないオブジェクトに関しては無効です。

MQOO_INPUT_EXCLUSIVE
メッセージを読み取るためにキューを排他アクセス・モードでオープンする。

後続の MQGET 呼び出しで使用するために、キューが開かれます。 このアプリケーションまたは別のアプリケーションによって、キューがいずれかのタイプ (MQOO_INPUT_SHARED または MQOO_INPUT_EXCLUSIVE) の入力用に現在開かれている場合、この呼び出しは失敗し、理由コード MQRC_OBJECT_IN_USE が戻ります。

このオプションは、ローカル・キュー、別名キュー、およびモデル・キューに関してのみ有効です。リモート・キューや配布リスト、さらにキューでないオブジェクトに関しては無効です。

MQOO_OUTPUT

キューを開いてメッセージを書き込んだり、トピックまたはトピック・ストリングを開いてメッセージを公開したりします。

後続の MQPUT 呼び出しで使用するために、キューまたはトピックが開かれます。

このオプションを使用して MQOPEN 呼び出しを行うと、InhibitPut キュー属性が MQQA_PUT_INHIBITED に設定されていても成功します (ただし、属性がこの値に設定されていると、後続の MQPUT 呼び出しは失敗します)。

このオプションは、配布リストをはじめ、すべてのタイプのキューおよびトピックで有効です。

以下の注は、次のオプションに適用されます。
  • これらのオプションは、1 つだけ指定できます。
  • これらのオプションのいずれかを指定した MQOPEN 呼び出しは、 InhibitGet キュー属性が MQQA_GET_INHIBITED に設定されていても成功します (ただし、属性がこの値に設定されていると、後続の MQGET 呼び出しは失敗します)。
  • キューが共有可能でないものとして定義されている場合は (つまり、Shareability キュー属性の値が MQQA_NOT_SHAREABLE)、共有アクセスでそのキューを開こうとしても、排他アクセスによるものとして扱われます。
  • 別名キューがこれらのオプションのいずれかで開かれている場合は、排他的使用をしているかどうか (または別のアプリケーションで排他的使用をしているか) のテストが、別名解決先の基本キューに対して行われます。
  • これらのオプションは、ObjectQMgrName がキュー・マネージャーの別名であるときには無効になります。キュー・マネージャーの別名として使用されるリモート・キューのローカル定義の中の RemoteQMgrName 属性の値が、ローカル・キュー・マネージャーの名前である場合も同様です。
「MQOO_BROWSE」
メッセージをブラウズするためにキューを開きます。
以下のいずれかのオプションを使用する後続の MQGET 呼び出しで使用するために、キューが開かれます。
  • MQGMO_BROWSE_FIRST
  • MQGMO_BROWSE_NEXT
  • MQGMO_BROWSE_MSG_UNDER_CURSOR
これは、キューが現在 MQOO_INPUT_EXCLUSIVE で開かれている場合でも使用できます。 MQOO_BROWSE オプションを指定した MQOPEN 呼び出しは、ブラウズ・カーソルを論理的にキューの最初のメッセージの前に設定します。詳細については、 MQGMO-Options フィールド を参照してください。

このオプションは、ローカル・キュー、別名キュー、およびモデル・キューに関してのみ有効です。リモート・キューや配布リスト、さらにキューでないオブジェクトに関しては無効です。 ObjectQMgrName がキュー・マネージャーの別名であるときにもこれは無効になります。キュー・マネージャーの別名として使用されるリモート・キューのローカル定義の中の RemoteQMgrName 属性の値が、ローカル・キュー・マネージャーの名前である場合も同様です。

MQOO_CO_OP
連携するハンドル・セットのメンバーとして開きます。

このオプションは、MQOO_BROWSE オプションの場合にのみ有効です。 MQOO_BROWSE を使用せずに指定した場合、MQOPEN の実行結果として MQRC_OPTIONS_ERROR が返されます。

返されるハンドルは、後続の MQGET 呼び出しにおける連携するハンドル・セットのメンバーであると見なされ、以下のいずれかのオプションがあります。
  • MQGMO_MARK_BROWSE_CO_OP
  • MQGMO_UNMARKED_BROWSE_MSG
  • MQGMO_UNMARK_BROWSE_CO_OP

このオプションは、ローカル・キュー、別名キュー、およびモデル・キューに関してのみ有効です。リモート・キューや配布リスト、さらにキューでないオブジェクトに関しては無効です。

MQOO_INQUIRE
属性を照会するためにオブジェクトを開きます。

後続の MQINQ 呼び出しで使用するために、キュー、名前リスト、プロセス定義、またはキュー・マネージャーが開かれます。

このオプションは、配布リスト以外のすべてのタイプのオブジェクトで有効です。 ObjectQMgrName がキュー・マネージャーの別名であるときにはこれは無効になります。キュー・マネージャーの別名として使用されるリモート・キューのローカル定義の中の RemoteQMgrName 属性の値が、ローカル・キュー・マネージャーの名前である場合も同様です。

MQOO_SET
属性を設定するためにキューを開きます。

後続の MQSET 呼び出しで使用するために、キューが開かれます。

このオプションは、配布リスト以外のすべてのタイプのキューで有効です。 ObjectQMgrName がリモート・キューのローカル定義名であるときにはこれは無効になります。キュー・マネージャーの別名として使用されるリモート・キューのローカル定義の中の RemoteQMgrName 属性の値が、ローカル・キュー・マネージャーの名前である場合も同様です。

バインディング・オプション: 以下のオプションは、開かれるオブジェクトがクラスター・キューである場合に適用されます。これらのオプションは、クラスター・キューのインスタンスへのキュー・ハンドルのバインディングを制御します。
MQOO_BIND_ON_OPEN
キューが開いたときに、ローカル・キュー・マネージャーが、キュー・ハンドルを宛先キューのインスタンスにバインドします。 その結果、このハンドルを使って書き込まれるすべてのメッセージが、宛先キューの同じインスタンスに、同じ経路で送信されます。

このオプションは、キューの場合にのみ有効であり、クラスター・キューにのみ影響します。 クラスター・キューではないキューに対して指定された場合、このオプションは無視されます。

MQOO_BIND_NOT_FIXED (MQOO_BIND_NOT_FIXED)
このオプションを指定すると、ローカル・キュー・マネージャーは、宛先キューのインスタンスへのキュー・ハンドルのバインドを停止します。 その結果、このハンドルを使用するその後の MQPUT 呼び出しでは、メッセージは、その宛先キューのさまざまなインスタンスに送信されたり、同じインスタンスに送信されてもさまざまな経路を経由したりします。 また、このオプションを使用すると、選択されたインスタンスを、ネットワーク条件に従って、ローカル・キュー・マネージャー、リモート・キュー・マネージャー、またはメッセージ・チャネル・エージェント (MCA) で後で変更することもできます。
注: トランザクションを完了するために一連のメッセージを交換する必要があるクライアント・アプリケーションおよびサーバー・アプリケーションは、MQOO_BIND_NOT_FIXED (または DefBind の値が MQBND_BIND_NOT_FIXED である場合は MQOO_BIND_AS_Q_DEF) を使用してはなりません。これは、一連のメッセージがサーバー・アプリケーションの異なるインスタンスに送信される可能性があるためです。

クラスター・キューに MQOO_BROWSE オプションまたはいずれかの MQOO_INPUT_* オプションを指定すると、キュー・マネージャーでは必ずそのクラスター・キューのローカル・インスタンスが選択されます。 その結果、MQOO_BIND_NOT_FIXED が指定されている場合でも、キュー・ハンドルのバインディングは固定されます。

通常は、すべてのインスタンスが同じ属性値を持っていますが、MQOO_BIND_NOT_FIXED と MQOO_INQUIRE を組み合わせて指定した場合、そのハンドルを使用するその後の MQINQ 呼び出しでは、クラスター・キューのさまざまなインスタンスが照会される可能性があります。

MQOO_BIND_NOT_FIXED はキューの場合にのみ有効であり、クラスター・キューにのみ影響します。 クラスター・キューではないキューに対して指定された場合、このオプションは無視されます。

MQOO_BIND_ON_GROUP
グループ内のメッセージすべてを同じ宛先のインスタンスに割り振る要求をアプリケーションが行えるようになります。

このオプションは、キューの場合にのみ有効であり、クラスター・キューにのみ影響します。 クラスター・キューではないキューに対して指定された場合、このオプションは無視されます。

MQOO_BIND_AS_Q_DEF
ローカル・キュー・マネージャーは、DefBind キュー属性で定義された方法でキュー・ハンドルをバインドします。 この属性の値は、MQBND_BIND_ON_OPEN、MQBND_BIND_NOT_FIXED、または MQBND_BIND_ON_GROUP のいずれかです。

MQOO_BIND_ON_OPEN、MQOO_BIND_NOT_FIXED、MQOO_BIND_ON_GROUP のいずれも指定されていない場合は、MQOO_BIND_AS_Q_DEF がデフォルトです。

MQOO_BIND_AS_Q_DEF は、プログラムの文書化を助けます。 このオプションは、他の 2 つのバインド・オプションのいずれかと組み合わせて使用することを意図して用意されたオプションではありません。しかしその値はゼロであるため、そのように組み合わせて使用しても検出できません。

コンテキスト・オプション: 以下のオプションは、メッセージ・コンテキストの処理を制御します。
MQOO_SAVE_ALL_CONTEXT
コンテキスト情報がこのキュー・ハンドルに関連付けられます。 この情報は、このハンドルを使用して取り出されたメッセージのコンテキストから設定されます。 メッセージ・コンテキストについて詳しくは、 メッセージ・コンテキスト および コンテキスト情報の制御を参照してください。

このコンテキスト情報は、メッセージに渡してから、MQPUT 呼び出しまたは MQPUT1 呼び出しを使用してキューに書き込むことができます。 MQPMO-メッセージ書き込みオプションで説明されている MQPMO_PASS_IDENTITY_CONTEXT および MQPMO_PASS_ALL_CONTEXT オプションを参照してください。

メッセージが正常に取り出されるまでは、キューに書き込まれるメッセージにコンテキストを渡すことはできません。

MQGMO_BROWSE_* ブラウズ・オプションのいずれかを使用して取り出されるメッセージには、そのコンテキスト情報が保存されません (ただし、MsgDesc パラメーターのコンテキスト・フィールドは、ブラウズの後で設定されます)。

このオプションは、ローカル・キュー、別名キュー、およびモデル・キューに関してのみ有効です。リモート・キューや配布リスト、さらにキューでないオブジェクトに関しては無効です。 MQOO_INPUT_* オプションのいずれかを指定する必要があります。

MQOO_PASS_IDENTITY_CONTEXT
これを使用すると、メッセージがキューに書き込まれるときに、PutMsgOpts パラメーターで MQPMO_PASS_IDENTITY_CONTEXT オプションを指定できます。この結果、MQOO_SAVE_ALL_CONTEXT オプションを指定して開かれた入力キューからの識別コンテキスト情報がメッセージに渡されます。 メッセージ・コンテキストについて詳しくは、 メッセージ・コンテキスト および コンテキスト情報の制御を参照してください。

指定する必要があるオプションは MQOO_OUTPUT です。

このオプションは、配布リストをはじめ、すべてのタイプのキューで有効です。

MQOO_PASS_ALL_CONTEXT
これを使用すると、メッセージがキューに書き込まれるときに、PutMsgOpts パラメーターで MQPMO_PASS_ALL_CONTEXT オプションを指定できます。この結果、MQOO_SAVE_ALL_CONTEXT オプションを指定して開かれた入力キューからの識別コンテキスト情報と発信元コンテキスト情報がメッセージに渡されます。 メッセージ・コンテキストについて詳しくは、 メッセージ・コンテキスト および コンテキスト情報の制御を参照してください。

このオプションでは、MQOO_PASS_IDENTITY_CONTEXT が暗黙指定されるため、これをあらためて指定する必要はありません。 指定する必要があるオプションは MQOO_OUTPUT です。

このオプションは、配布リストをはじめ、すべてのタイプのキューで有効です。

MQOO_SET_IDENTITY_CONTEXT
これを使用すると、メッセージがキューに書き込まれるときに、PutMsgOpts パラメーターで MQPMO_SET_IDENTITY_CONTEXT オプションを指定できます。この結果、MQPUT 呼び出しまたは MQPUT1 呼び出しで指定された MsgDesc パラメーターに格納されている識別コンテキスト情報がメッセージに渡されます。 メッセージ・コンテキストについて詳しくは、 メッセージ・コンテキスト および コンテキスト情報の制御を参照してください。

このオプションでは、MQOO_PASS_IDENTITY_CONTEXT が暗黙指定されるため、これをあらためて指定する必要はありません。 指定する必要があるオプションは MQOO_OUTPUT です。

このオプションは、配布リストをはじめ、すべてのタイプのキューで有効です。

MQOO_SET_ALL_CONTEXT
これを使用すると、メッセージがキューに書き込まれるときに、PutMsgOpts パラメーターで MQPMO_SET_ALL_CONTEXT オプションを指定できます。この結果、MQPUT 呼び出しまたは MQPUT1 呼び出しで指定された MsgDesc パラメーターに格納されている識別およびコンテキスト情報がメッセージに渡されます。 メッセージ・コンテキストについて詳しくは、 メッセージ・コンテキスト および コンテキスト情報の制御を参照してください。
このオプションでは、以下のオプションが暗黙指定されるため、これらをあらためて指定する必要はありません。
  • MQOO_PASS_IDENTITY_CONTEXT
  • MQOO_PASS_ALL_CONTEXT
  • MQOO_SET_IDENTITY_CONTEXT
指定する必要があるオプションは MQOO_OUTPUT です。

このオプションは、配布リストをはじめ、すべてのタイプのキューで有効です。

先読みオプション:

MQOO_READ_AHEAD を使用して MQOPEN を呼び出すときに、特定の条件が満たされている場合にのみ、 IBM® MQ クライアントは先読みを使用可能にします。 それらの条件には、以下のものが含まれます。
  • クライアントとリモート・キュー・マネージャーの両方が IBM WebSphere® MQ 7.0 以降でなければなりません。
  • クライアント・アプリケーションは、スレッド化された IBM MQ MQI クライアント・ライブラリーに対してコンパイルおよびリンクする必要があります。
  • クライアント・チャネルが TCP/IP プロトコルを使用している必要があります。
  • チャネルでは、クライアントとサーバー両方のチャネル定義で、SharingConversations (SHARECNV) がゼロ以外に設定されていなければなりません。
以下のオプションは、アプリケーションが非持続メッセージを要求する前にそれらをクライアントに送信するかどうかを制御します。 以下の注意事項は、先読みオプションに適用されます。
  • これらのオプションは、1 つだけ指定できます。
  • これらのオプションは、ローカル・キュー、別名キュー、およびモデル・キューでのみ有効です。 これらは、リモート・キュー、配布リスト、トピックおよびキュー・マネージャーでは無効です。
  • これらのオプションは、MQOO_BROWSE、MQOO_INPUT_SHARED、MQOO_INPUT_EXCLUSIVE のいずれかと一緒に指定されている場合にのみ適用されます。ただし、これらのオプションを MQOO_INQUIRE または MQOO_SET と一緒に指定してもエラーにはなりません。
  • アプリケーションが IBM MQ クライアントとして実行されていない場合、これらのオプションは無視されます。
MQOO_NO_READ_AHEAD
非持続メッセージは、それをアプリケーションが要求する前にクライアントに送信されることはありません。
MQOO_READ_AHEAD
非持続メッセージは、アプリケーションからの要求がある前に、クライアントに送信されます。
MQOO_READ_AHEAD_AS_Q_DEF
先読みするときの振る舞いは、開いているキューのデフォルトの先読み属性によって決まります。 これがデフォルト値です。
その他のオプション: 以下のオプションは、許可検査を制御するほか、キュー・マネージャーが静止しているときに発生するイベント、ローカル・キュー名を解決するかどうか、およびマルチキャストを制御します。
MQOO_ALTERNATE_USER_AUTHORITY
ObjDesc パラメーターの AlternateUserId フィールドには、この MQOPEN 呼び出しの妥当性検査に使用するユーザー ID が含まれています。 この呼び出しが成功するのは、指定されたアクセス・オプションでオブジェクトを開く許可を、この AlternateUserId が持っている場合だけです。 アプリケーションの実行に使用されているユーザー ID が、そのような許可を持っているかどうかは関係ありません。 ただし、これは、指定されたコンテキスト・オプションには適用されません。コンテキスト・オプションの場合は常に、そのアプリケーションの実行に使用されているユーザー ID に対して検査されます。

このオプションは、すべてのタイプのオブジェクトで有効です。

MQOO_FAIL_IF_QUIESCING
MQOPEN 呼び出しは、キュー・マネージャーが静止状態になっている場合は失敗します。

[z/OS] z/OSでは、 CICS または IMS アプリケーションの場合、接続が静止状態であれば、このオプションによって MQOPEN 呼び出しも強制的に失敗します。

このオプションは、すべてのタイプのオブジェクトで有効です。

クライアント・チャネルについては、 IBM MQ MQI clients の概要を参照してください。

MQOO_RESOLVE_LOCAL_Q
MQOD 構造の ResolvedQName に、開かれたローカル・キューの名前が入ります。 同様に、ResolvedQMgrName には、ローカル・キューをホストするローカル・キュー・マネージャーの名前が入ります。 MQOD 構造がバージョン 3 より小さい場合、MQOO_RESOLVE_LOCAL_Q は無視され、エラーも返されません。

ローカル・キュー、別名キュー、またはモデル・キューのいずれかが開かれている場合、ローカル・キューは常に返されますが、例えば、リモート・キューまたは非ローカル・クラスター・キューが MQOO_RESOLVE_LOCAL_Q オプションを指定せずに開かれている場合には返されません。ResolvedQName および ResolvedQMgrName には、リモート・キュー定義にある RemoteQName および RemoteQMgrName が入ります。あるいは選択されたリモート・クラスター・キューから同様に入ります。

リモート・キューなどを開くときに MQOO_RESOLVE_LOCAL_Q を指定した場合、ResolvedQName はメッセージの書き込み先の伝送キューになります。 ResolvedQMgrName には、伝送キューをホストするローカル・キュー・マネージャーの名前が入ります。

キューでの参照、入力、または出力を許可されている場合、このフラグを MQOPEN 呼び出しで指定するために必要な権限があるといえます。 特殊権限は必要ありません。

このオプションはキューおよびキュー・マネージャーにのみ有効です。

MQOO_RESOLVE_LOCAL_TOPIC
MQOD 構造の ResolvedQName に、開かれた管理トピックの名前が入れられます。
MQOO_NO_MULTICAST
パブリケーション・メッセージの送信に、マルチキャストは使用されません。

このオプションは、MQOO_OUTPUT オプションと併用する場合にのみ有効です。 MQOO_OUTPUT を使用せずに指定した場合、MQOPEN の実行結果として MQRC_OPTIONS_ERROR が返されます。

このオプションはトピックでのみ有効です。

Hobj
タイプ: MQHOBJ - 出力

このハンドルは、オブジェクトに対し設定されているアクセスを表します。 これは、オブジェクトを操作する後続の IBM MQ 呼び出しで指定する必要があります。 MQCLOSE 呼び出しが発行されたとき、またはハンドルの有効範囲を定義する処理の単位が終了したときに、有効でなくなります。

返されるオブジェクト・ハンドルの有効範囲は、呼び出しで指定される接続ハンドルの有効範囲と同じです。 ハンドルの有効範囲については、 MQCONN-Hconn パラメーター を参照してください。

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

CompCodeを限定する理由コード。

CompCodeが MQCC_OK の場合:
MQRC_NONE
(0, X'000') レポートする理由コードはありません。
CompCodeが MQCC_WARNING の場合:
MQRC_MULTIPLE_REASONS
(2136, X'858') 複数の理由コードが返されました。
CompCodeが MQCC_FAILED の場合:
MQRC_ADAPTER_NOT_AVAILABLE
(2204, X'89C') アダプターが利用できません。
MQRC_ADAPTER_SERV_LOAD_ERROR
(2130, X'852') アダプター・サービス・モジュールをロードできません。
MQRC_ALIAS_BASE_Q_TYPE_ERROR
(2001, X'7D1') 別名基本キューのタイプは無効です。
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_AUTH_FAILED
(2348, X'92C') カップリング・ファシリティー構造の許可検査に失敗しました。
MQRC_CF_STRUC_ERROR
(2349, X'92D') カップリング・ファシリティー構造が無効です。
MQRC_CF_STRUC_FAILED
(2373, X'945') カップリング・ファシリティー構造体で障害が発生しました。
MQRC_CF_STRUC_IN_USE
(2346, X'92A') カップリング・ファシリティー構造体が使用中です。
MQRC_CF_STRUC_LIST_HDR_IN_USE
(2347, X'92B') カップリング・ファシリティー構造体のリスト・ヘッダーが使用中です。
MQRC_CICS_WAIT_FAILED
(2140, X'85C') 待機要求が CICS によって拒否されました。
MQRC_CLUSTER_EXIT_ERROR
(2266, X'8DA') クラスター・ワークロード出口で障害が発生しました。
MQRC_CLUSTER_PUT_INHIBITED
(2268, X'8DC') クラスター内のすべてのキューで書き込み呼び出しは使用禁止になっています。
MQRC_CLUSTER_RESOLUTION_ERROR
(2189, X'88D') クラスター名の解決に失敗しました。
MQRC_CLUSTER_RESOURCE_ERROR
(2269, X'8DD') クラスター・リソース・エラー。
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_DB2_NOT_AVAILABLE
(2342, X' 926 ') Db2® サブシステムが使用できません。
MQRC_DEF_XMIT_Q_TYPE_ERROR
(2198, X'896') デフォルト伝送キューはローカルではありません。
MQRC_DEF_XMIT_Q_USAGE_ERROR
(2199, X'897') デフォルト伝送キューの使用法エラー。
MQRC_DYNAMIC_Q_NAME_ERROR
(2011, X'7DB') 動的キューの名前が無効です。
MQRC_HANDLE_NOT_AVAILABLE
(2017, X'7E1') 使用可能なハンドルがなくなりました。
MQRC_HCONN_ERROR
(2018, X'7E2') 接続ハンドルが無効です。
MQRC_HOBJ_ERROR
(2019, X'7E3') オブジェクト・ハンドルが無効です。
MQRC_MULTIPLE_REASONS
(2136, X'858') 複数の理由コードが返されました。
MQRC_NAME_IN_USE
(2201, X'899') 名前が使用中です。
MQRC_NAME_NOT_VALID_FOR_TYPE
(2194, X'892') オブジェクト名がオブジェクト・タイプとして無効です。
MQRC_NOT_AUTHORIZED
(2035, X'7F3') アクセスは許可されません。
MQRC_OBJECT_ALREADY_EXISTS
(2100, X'834') オブジェクトが存在しています。
MQRC_OBJECT_DAMAGED
(2101, X'835') オブジェクトが損傷しました。
MQRC_OBJECT_IN_USE
(2042, X'7FA') オプションが矛盾するオブジェクトが既に開いています。
MQRC_OBJECT_LEVEL_INCOMPATIBLE
(2360, X'938') オブジェクト・レベルに互換性がありません。
MQRC_OBJECT_NAME_ERROR
(2152, X'868') オブジェクト名が無効です。
MQRC_OBJECT_NOT_UNIQUE
(2343, X'927') オブジェクトが固有ではありません。
MQRC_OBJECT_Q_MGR_NAME_ERROR
(2153, X'869') オブジェクト・キュー・マネージャー名が無効です。
MQRC_OBJECT_RECORDS_ERROR
(2155, X'86B') オブジェクト・レコードが無効です。
MQRC_OBJECT_STRING_ERROR
(2441, X'0989') Objectstring フィールドが無効です。
MQRC_OBJECT_TYPE_ERROR
(2043, X'7FB') オブジェクト・タイプが無効です。
MQRC_OD_ERROR
(2044, X'7FC') オブジェクト記述子の構造が無効です。
MQRC_OPTION_NOT_VALID_FOR_TYPE
(2045, X'7FD') オプションが、オブジェクト・タイプとして無効です。
MQRC_OPTIONS_ERROR
(2046, X'7FE') オプションが無効であるか、矛盾しています。
MQRC_PAGESET_ERROR
(2193, X'891') ページ・セット・データ・セットへのアクセス中にエラーが発生しました。
MQRC_PAGESET_FULL
(2192, X'890') 外部ストレージ・メディアが満杯です。
MQRC_Q_DELETED
(2052, X'804') キューが削除されました。
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_Q_TYPE_ERROR
(2057, X'809') キュー・タイプが無効です。
MQRC_RECS_PRESENT_ERROR
(2154, X'86A') 存在するレコード数が無効です。
MQRC_REMOTE_Q_NAME_ERROR
(2184, X'888') リモート・キュー名が無効です。
MQRC_RESOURCE_PROBLEM
(2102, X'836') 使用できるシステム・リソースが不足しています。
MQRC_RESPONSE_RECORDS_ERROR
(2156, X'86C') 応答レコードが無効です。
MQRC_SECURITY_ERROR
(2063, X'80F') セキュリティー・エラーが発生しました。
MQRC_SELECTOR_SYNTAX_ERROR
2459 (X'099B') MQOPEN、MQPUT1、または MQSUB の呼び出しが発行されましたが、構文エラーが含まれる選択ストリングが指定されました。
MQRC_STOPPED_BY_CLUSTER_EXIT
(2188, X'88C') クラスター・ワークロード出口によって呼び出しが拒否されました。
MQRC_STORAGE_MEDIUM_FULL
(2192, X'890') 外部ストレージ・メディアが満杯です。
MQRC_STORAGE_NOT_AVAILABLE
(2071, X'817') ストレージが不足しています。
MQRC_SUPPRESSED_BY_EXIT
(2109, X'83D') 出口プログラムにより呼び出しが抑止されました。
MQRC_UNEXPECTED_ERROR
(2195, X'893') 予期しないエラーが発生しました。
MQRC_UNKNOWN_ALIAS_BASE_Q
(2082, X'822') 別名の基本キューが不明です。
MQRC_UNKNOWN_DEF_XMIT_Q
(2197, X'895') デフォルト伝送キューが不明です。
MQRC_UNKNOWN_OBJECT_NAME
(2085, X'825') オブジェクト名が不明です。
MQRC_UNKNOWN_OBJECT_Q_MGR
(2086, X'826') オブジェクトのキュー・マネージャーが不明です。
MQRC_UNKNOWN_REMOTE_Q_MGR
(2087, X'827') リモート・キュー・マネージャーが不明です。
MQRC_UNKNOWN_XMIT_Q
(2196, X'894') 伝送キューが不明です。
MQRC_WRONG_CF_LEVEL
(2366, X'93E') カップリング・ファシリティー構造のレベルが正しくありません。
MQRC_XMIT_Q_TYPE_ERROR
(2091, X'82B') 伝送キューはローカルではありません。
MQRC_XMIT_Q_USAGE_ERROR
(2092, X'82C') 伝送キューの使用方法が正しくありません。

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

一般的な使用上の注意

  1. 開かれるオブジェクトは、以下のいずれかです。
    • 以下の目的をもつキュー。
      • メッセージを取得またはブラウズする (MQGET 呼び出しを使用)。
      • メッセージを書き込む (MQPUT 呼び出しを使用)。
      • キューの属性について照会する (MQINQ 呼び出しを使用)。
      • キューの属性を設定する (MQSET 呼び出しを使用)。

      指定されたキューがモデル・キューである場合は、動的ローカル・キューが作成されます。 MQOPEN-オブジェクトのオープンで説明されている ObjDesc パラメーターを参照してください。

      配布リストは、キューのリストを格納する特殊なタイプのキュー・オブジェクトです。 これを開いてメッセージを書き込むことはできますが、メッセージの取得やブラウズ、あるいは属性の照会や設定を行うことはできません。 詳しくは、使用上の注意 8 を参照してください。

      QSGDISP(GROUP) があるキューは特別なタイプのキュー定義であり、MQOPEN または MQPUT1 呼び出しでは使用できません。

    • リスト内のキューの名前について照会する名前リスト (MQINQ 呼び出しを使用)。
    • プロセス属性について照会するプロセス定義 (MQINQ 呼び出しを使用)。
    • ローカル・キュー・マネージャーの属性について照会するキュー・マネージャー (MQINQ 呼び出しを使用)。
    • メッセージをパブリッシュするトピック (MQPUT 呼び出しを使用)。
  2. 1 つのアプリケーションで同じオブジェクトを複数回オープンすることができます。 オープンするたびに異なるオブジェクト・ハンドルが返されます。 返されるそれぞれのハンドルは、対応するオープンの実行対象となる関数において使用できます。
  3. 開かれるオブジェクトが、クラスター・キュー以外のキューである場合、ローカル・キュー・マネージャー内の名前解決はすべて、 MQOPEN 呼び出しの時点で行われます。 これには、次のことが含まれます。
    • リモート・キューのローカル定義の名前を、リモート・キュー・マネージャーの名前と、そのキューがリモート・キュー・マネージャーで認識されている名前に解決する。
    • リモート・キュー・マネージャーの名前をローカル伝送キューの名前に解決する。
    • [z/OS] z/OS の場合のみ、リモート・キュー・マネージャー名を、IGQ エージェントが使用する共有伝送キューの名前に解決する (ローカル・キュー・マネージャーとリモート・キュー・マネージャーが同じキュー共有グループに属している場合にのみ適用される)。
    • 別名を基本キューまたはトピック・オブジェクトの名前に解決する。

    ただし、そのハンドルに対する後続の MQINQ 呼び出しまたは MQSET 呼び出しは、オープンされている名前にのみ関連するものであり、ネーム・レゾリューションが行われた後の結果のオブジェクトとは関連がない点に注意してください。 例えば、オープンされたオブジェクトが別名である場合、MQINQ 呼び出しで返される属性は別名の属性であり、別名の解決先の基本キューまたはトピック・オブジェクトの属性ではありません。

    オープンするオブジェクトがクラスター・キューの場合、ネーム・レゾリューションは MQOPEN 呼び出しの時点で行うことも、据え置くこともできます。 ネーム・レゾリューションをいつ行うかは、MQOPEN 呼び出しで指定された MQOO_BIND_* オプションで制御されます。
    • MQOO_BIND_ON_OPEN
    • MQOO_BIND_NOT_FIXED
    • MQOO_BIND_AS_Q_DEF
    • MQOO_BIND_ON_GROUP

    クラスター・キューのネーム・レゾリューションについて詳しくは、 ネーム・レゾリューション を参照してください。

  4. MQOO_BROWSE オプションを使用して MQOPEN 呼び出しを行うと、オブジェクト・ハンドルといずれか 1 つのブラウズ・オプションを指定する MQGET 呼び出しで使用されるブラウズ・カーソルが設定されます。 これにより、内容を変更せずにキューをスキャンすることができます。 ブラウズによって見つかったメッセージは、MQGMO_MSG_UNDER_CURSOR オプションを使用してキューから除去することができます。

    同一のキューに対していくつかの MQOPEN 要求を出すと、1 つのアプリケーションに対して複数のブラウズ・カーソルをアクティブにすることができます。

  5. トリガー・モニターにより開始されるアプリケーションには、そのアプリケーションに関連付けられているキューの名前が、開始時に渡されます。 このキュー名を ObjDesc パラメーターに指定してキューを開くことができます。 詳しくは、 MQTMC2 -トリガー・メッセージ 2 (文字形式) を参照してください。

先読みオプション

MQOO_READ_AHEAD を使用して MQOPEN を呼び出すときに、特定の条件が満たされている場合にのみ、 IBM MQ クライアントは先読みを使用可能にします。 それらの条件には、以下のものが含まれます。
  • クライアントとリモート・キュー・マネージャーの両方が IBM WebSphere MQ 7.0 以降でなければなりません。
  • クライアント・アプリケーションは、スレッド化された IBM MQ MQI クライアント・ライブラリーに対してコンパイルおよびリンクする必要があります。
  • クライアント・チャネルが TCP/IP プロトコルを使用している必要があります。
  • チャネルでは、クライアントとサーバー両方のチャネル定義で、SharingConversations (SHARECNV) がゼロ以外に設定されていなければなりません。

先読みオプションを使用する際には、以下の注記の内容が適用されます。

  1. 先読みオプションが適用されるのは、MQOO_BROWSE、MQOO_INPUT_SHARED、または MQOO_INPUT_EXCLUSIVE いずれかのオプションが 1 つだけ一緒に指定されている場合のみです。 先読みオプションが MQOO_ INQUIRE オプションまたは MQOO_SET オプションと一緒に指定されている場合、エラーはスローされません。
  2. 最初の MQGET 呼び出しで使用されるオプションが先読みでの使用に対応していない場合、先読みを要求しても使用可能になりません。 さらに、クライアントが先読みをサポートしないキュー・マネージャーに接続する場合も、先読みは使用不可になります。
  3. アプリケーションが IBM MQ クライアントとして実行されていない場合、先読みオプションは無視されます。

クラスター・キュー

以下の注意事項は、クラスター・キューの使用に適用されます。

  1. 初めてクラスター・キューが開かれたとき、ローカル・キュー・マネージャーがフル・リポジトリー・キュー・マネージャーでなければ、ローカル・キュー・マネージャーは、フル・リポジトリー・キュー・マネージャーからそのクラスター・キューに関する情報を取得します。 ネットワークが使用中である場合は、ローカル・キュー・マネージャーがリポジトリー・キュー・マネージャーから必要な情報を受信するまでに何秒か要する場合があります。 その結果、MQOPEN 呼び出しを発行したアプリケーションは最大 10 秒間待機しなければならない場合があり、その後、 MQOPEN 呼び出しから制御が戻ります。 この時間内にローカル・キュー・マネージャーがクラスター・キューに関する必要情報を受信しなかった場合、呼び出しは失敗し、理由コード MQRC_CLUSTER_RESOLUTION_ERROR が返されます。
  2. あるクラスター・キューが開いており、クラスター内にそのキューのインスタンスが複数存在する場合、どのインスタンスが開かれるかは、MQOPEN 呼び出しで指定されたオプションによって決まります。
    • 指定したオプションに、次のいずれかが含まれている場合:
      • MQOO_BROWSE
      • MQOO_INPUT_AS_Q_DEF
      • MQOO_INPUT_EXCLUSIVE
      • MQOO_INPUT_SHARED
      • MQOO_SET
      開かれるクラスター・キューのインスタンスは、ローカル・インスタンスでなければなりません。 そのキューにローカル・インスタンスがない場合は、MQOPEN 呼び出しは失敗します。
    • 指定したオプションに上記のオプションがいずれも含まれておらず、次のうち 1 つまたは両方が含まれている場合:
      • MQOO_INQUIRE
      • MQOO_OUTPUT
      開かれるインスタンスは、ローカル・インスタンスがあればローカル・インスタンスになり、なければリモート・インスタンスになります (CLWLUSEQ のデフォルトを使用する場合)。 ただし、キュー・マネージャーによって選択されたインスタンスを、クラスター・ワークロード出口によって変更することもできます (そのような出口がある場合)。
  3. キューのサブスクリプションが存在するが、フル・リポジトリーで認知されていない場合、オブジェクトはクラスター内に存在せず、呼び出しは失敗して理由コード MQRC_OBJECT_NAME が返されます。

クラスター・キューについて詳しくは、 クラスター・キューを参照してください。

配布リスト

次の注意事項は、配布リストの使用に適用されます。

配布リストは、次の環境でサポートされます。
  • [AIX]AIX®
  • [IBM i]IBM i
  • [Linux]Linux®
  • [Windows]Windows
および、これらのシステムに接続された IBM MQ MQI clients の場合。
  1. MQOD 構造内の各フィールドは、配布リストを開くときに、次のように設定しなければなりません。
    • Version は、MQOD_VERSION_2 以上にする必要があります。
    • ObjectType は、MQOT_Q にする必要があります。
    • ObjectName は、ブランクまたはヌル・ストリングにする必要があります。
    • ObjectQMgrName は、ブランクまたはヌル・ストリングにする必要があります。
    • RecsPresent は、ゼロより大きな値にする。
    • ObjectRecOffset と ObjectRecPtr のうちの片方をゼロ、もう片方をゼロ以外にする必要があります。
    • ResponseRecOffset および ResponseRecPtr のうち、ゼロ以外にできるのは片方のみです。
    • ObjectRecOffset または ObjectRecPtr のいずれかにより扱われる RecsPresent オブジェクト・レコードが存在する必要があります。 これらのオブジェクト・レコードには、開かれる宛先キューの名前を設定しなければなりません。
    • ResponseRecOffset および ResponseRecPtr のうちの片方がゼロ以外であるとき、RecsPresent 応答レコードが存在する必要があります。 この応答レコードは、呼び出しが終了して理由コード MQRC_MULTIPLE_REASONS が返された場合に、キュー・マネージャーにより設定されます。

    RecsPresent をゼロにすることにより、バージョン 2 の MQOD を使用して、配布リストに存在しない 1 つのキューを開くこともできます。

  2. Options パラメーターでは、次のオープン・オプションだけが有効です。
    • MQOO_OUTPUT
    • MQOO_PASS_*_CONTEXT
    • MQOO_SET_*_CONTEXT
    • MQOO_ALTERNATE_USER_AUTHORITY
    • MQOO_FAIL_IF_QUIESCING
  3. 配布リスト内の宛先キューとして、ローカル・キュー、別名キュー、またはリモート・キューを指定することは可能ですが、モデル・キューを指定することはできません。 モデル・キューを指定すると、キューのオープンが失敗し、理由コード MQRC_Q_TYPE_ERROR が返されます。 ただし、このようになっても、リスト内の他のキューは正常に開かれます。
  4. 完了コード・パラメーターおよび理由コード・パラメーターは、次のように設定されます。
    • 配布リスト内のキューに対するオープン操作がすべて同じ結果になった (すべて成功または失敗した) 場合、完了コード・パラメーターおよび理由コード・パラメーターは、この共通の結果を示す値に設定されます。 MQRR 応答レコード (アプリケーションにより提供されている場合) は、この場合には設定されません。

      例えば、すべてのオープンが成功すると、完了コードは MQCC_OK に設定され、理由コードは MQRC_NONE に設定されます。 いずれのキューも存在しないためにすべてのオープンが失敗すると、それらのパラメーターは MQCC_FAILED および MQRC_UNKNOWN_OBJECT_NAME に設定されます。

    • 配布リスト内のキューに対するオープン操作が同じ結果にならなかった (すべて成功でもすべて失敗でもない) 場合には、次のようになります。
      • 完了コード・パラメーターは、少なくとも 1 つのオープンが成功した場合には MQCC_WARNING に設定され、すべて失敗した場合には MQCC_FAILED に設定されます。
      • 理由コード・パラメーターは、MQRC_MULTIPLE_REASONS に設定されます。
      • 応答レコード (アプリケーションにより提供されている場合) は、配布リスト内のキューごとに、個別の完了コードおよび理由コードに設定されます。
  5. 配布リストが正常にオープンされた場合、呼び出しにより返された Hobj ハンドルを後続の MQPUT 呼び出しで使用して、配布リスト内のキューにメッセージを書き込むことができます。さらにこのハンドルを MQCLOSE 呼び出しで使用して、配布リストへのアクセスを解放することもできます。 配布リストで有効なクローズ・オプションは、MQCO_NONE のみです。

    配布リストにメッセージを書き込むために、MQPUT1 呼び出しを使用することもできます。このリスト内のキューを定義する MQOD 構造は、その呼び出しのパラメーターとして指定されます。

  6. アプリケーションが最大許容ハンドル数を超えたかどうかを検査するとき、配布リスト内の正常に開かれた宛先ごとに、別のハンドルとしてカウントされます (MaxHandles キュー・マネージャー属性を参照)。 配布リスト内の複数の宛先が同一の物理キューに解決されるときにも同じようにカウントされます。 1 つの配布リストについて発行された MQOPEN または MQPUT1 の呼び出しの結果として、アプリケーションで使用されるハンドルの数が MaxHandles を超える場合、呼び出しは失敗し、理由コード MQRC_HANDLE_NOT_AVAILABLE が返されます。
  7. 宛先が正常に開かれるたびに、OpenOutputCount 属性の値が 1 つずつ加算されます。 配布リスト内の複数の宛先が同一の物理キューに解決される場合、そのキューの OpenOutputCount 属性は、そのキューに解決される配布リスト内の宛先数だけ加算されます。
  8. 各キューを個々にオープンするとハンドルが無効になるようなキュー定義の変更 (例えば、解決パスの変更) があっても、配布リスト・ハンドルは無効にはなりません。 しかし、後続の MQPUT 呼び出しで配布リスト・ハンドルが使用される際、その特定のキューについては失敗します。
  9. 配布リストに含めることができるのは 1 つの宛先のみです。

リモート・キュー

以下の注意事項は、リモート・キューの使用に適用されます。

この呼び出しの ObjDesc パラメーターには、リモート・キューを次の 2 つの方法のいずれかで指定できます。

  • ObjectName として、リモート・キューのローカル定義の名前を指定する。 この場合、ObjectQMgrName は、ローカル・キュー・マネージャーを指しており、ブランクまたは (C プログラミング言語では) ヌル・ストリングとして指定することができます。

    ローカル・キュー・マネージャーで実行されるセキュリティー妥当性検査では、そのユーザーが、リモート・キューのローカル定義をオープンする許可を持っているかどうかが検査されます。

  • ObjectName として、リモート・キュー・マネージャーに認識されているリモート・キューの名前を指定する。 この場合、ObjectQMgrName はリモート・キュー・マネージャーの名前です。

    ローカル・キュー・マネージャーによって実行されるセキュリティー妥当性検査では、ユーザーが、名前解決プロセスからの結果の伝送キューにメッセージを送る許可を持っているかどうかが検査されます。

いずれの場合も、次のようになります。
  • ユーザーがキューにメッセージを書き込む許可を持っているかどうかを検査するために、ローカル・キュー・マネージャーからリモート・キュー・マネージャーへメッセージが送られることはありません。
  • メッセージがリモート・キュー・マネージャーに届くとき、リモート・キュー・マネージャーは、メッセージを発信しているユーザーが許可を持っていないため、それを拒否することがあります。

詳しくは、 MQOD-オブジェクト記述子 で説明されている ObjectName および ObjectQMgrName フィールドを参照してください。

オブジェクト

セキュリティー

以下の注記は、MQOPEN を使用する場合のセキュリティーに関連した内容です。

キュー・マネージャーは、MQOPEN 呼び出しが発行されるときにセキュリティー検査を行い、アプリケーションの実行に使用されるユーザー ID に適切なレベルの権限があることを確認してからアクセスが許可されます。 許可検査は、オープンされるオブジェクトの名前に対して行われ、名前が解決された後の結果の名前 (1 つ以上) に対しては行われません。

開かれるオブジェクトがトピック・オブジェクトを指す別名キューである場合、キュー・マネージャーは、トピック・オブジェクトが直接使用されているかのように、トピックのセキュリティー検査を行う前に、別名キュー名に対してセキュリティー検査を行います。

開かれるオブジェクトがトピック・オブジェクトである場合、ObjectName のみを使用するか、あるいは (ベースになる ObjectName を共に使用してあるいは使用せずに) ObjectString を使用するかにかかわらず、キュー・マネージャーはセキュリティー検査を行います。これは、ObjectName で指定されたトピック・オブジェクト内から取られる結果トピック・ストリングを使用して、必要な場合にはそのストリングを ObjectString で提供されるストリングと連結してから、セキュリティー検査を行う対象となるトピック・ツリーのそのポイントまたはそれより上のポイントにある最も近いトピック・オブジェクトを検出することによって行われます。 これは、ObjectName で指定されたトピック・オブジェクトと同じではない場合があります。

オープンされるオブジェクトがモデル・キューの場合、キュー・マネージャーは、モデル・キューの名前と作成された動的キューの名前の両方に対して、完全セキュリティー検査を行います。 作成される動的キューが後で明示的に開かれると、さらにリソース・セキュリティー検査が動的キューの名前に対して実行されます。

[z/OS] z/OSでは、キュー・マネージャーは、セキュリティーが有効になっている場合にのみセキュリティー検査を実行します。 セキュリティー検査について詳しくは、 z/OS でのセキュリティーのセットアップ を参照してください。

属性

以下の注記は、属性に関連した内容です。

アプリケーションでオブジェクトがオープンされている間に、そのオブジェクトの属性が変わることもあります。 多くの場合、アプリケーションでは属性の変化を通知しませんが、特定の属性についてキュー・マネージャーがハンドルに「無効」としてマーク付けます。 以下の属性が該当します。

  • オブジェクトの名前の解決に影響するすべての属性。 これは使用されるオープン・オプションに関係なく当てはまります。以下のものが含まれます。
    • 開いている別名キューの BaseQName 属性に対する変更。
    • 開いている別名キューの TargetType 属性に対する変更。
    • RemoteQName キュー属性または RemoteQMgrName キュー属性に対する変更では、このキュー、またはキュー・マネージャーの別名としてこの定義を使って解決されるキューの、開いているハンドル。
    • リモート・キュー用に現在開いているハンドルの解決先が別の伝送キューになるような変更、あるいはまったく解決できなくなるような変更。 例えば、次のものが含まれます。
      • リモート・キューのローカル定義の XmitQName 属性に対する変更 (その定義がキュー用に使用されるかキュー・マネージャーの別名用に使用されているかには無関係)。
      • [z/OS] z/OS の場合のみ、 IntraGroupqueuing キュー・マネージャー属性の値に対する変更、または共用伝送キュー (SYSTEM.QSG.TRANSMIT.QUEUE) は、IGQ エージェントによって使用されます。

      この条件には例外が 1 つあります。その例外とは、新規伝送キューの作成です。 ハンドルを開くとき、このキューが存在していればそれが解決先となっていたものの、実際にはそれがなかったためにデフォルトの伝送キューが解決先となった場合、このハンドルは無効にはなりません。

    • DefXmitQName キュー・マネージャーに対する変更。 この場合は、以前に指定されたキューに解決されたすべてのオープン・ハンドル (デフォルトの伝送キューであるというだけの理由でそれに解決されたオープン・ハンドル) に、無効のマークが付けられます。 その他の理由でこのキューに解決されたハンドルは影響を受けません。
  • Shareability キュー属性では、このキュー、またはこのキューに解決されるキューに対して、現在 MQOO_INPUT_SHARED アクセスを提供しているハンドルが 2 つ以上ある場合。 この場合は、オープン・オプションとは関係なく、このキュー、またはこのキューに解決されるキューの、開かれているすべてのハンドルに無効のマークが付けられます。

    [z/OS] z/OSでは、1 つ以上のハンドルが現在キューへの MQOO_INPUT_SHARED アクセスまたは MQOO_INPUT_EXCLUSIVE アクセスを提供している場合、前述のハンドルは無効としてマークされます。

  • オープン・オプションとは関係なく、このキュー、またはこのキューに解決されるキューに対して開かれているすべてのハンドルの Usage キュー属性。
ハンドルに無効のマークが付けられると、このハンドルを使用する後続の呼び出し (MQCLOSE 以外) はすべて失敗し、理由コード MQRC_OBJECT_CHANGED が返されます。 アプリケーションで、MQCLOSE 呼び出し (元のハンドルを使用) を発行してから、キューを再オープンする必要があります。 以前に成功した呼び出しで使用した古いハンドルに対するコミットされていない更新は、この時点でもアプリケーション・ロジックの必要に応じてコミットまたはバックアウトが可能です。

属性を変更した結果このようなことが起こる場合は、特別な強制バージョンの呼び出しを使用します。

C 言語での呼び出し

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

COBOL での呼び出し

CALL 'MQOPEN' USING HCONN, OBJDESC, OPTIONS, HOBJ, COMPCODE, REASON
パラメーターを次のように宣言します。
**   Connection handle
 01  HCONN     PIC S9(9) BINARY.
**   Object descriptor
 01  OBJDESC.
     COPY CMQODV.
**   Options that control the action of MQOPEN
 01  OPTIONS   PIC S9(9) BINARY.
**   Object handle
 01  HOBJ      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 MQOPEN (Hconn, ObjDesc, Options, Hobj, CompCode, Reason);
パラメーターを次のように宣言します。
dcl Hconn     fixed bin(31);  /* Connection handle */
dcl ObjDesc   like MQOD;      /* Object descriptor */
dcl Options   fixed bin(31);  /* Options that control the action of
                                 MQOPEN */
dcl Hobj      fixed bin(31);  /* Object handle */
dcl CompCode  fixed bin(31);  /* Completion code */
dcl Reason    fixed bin(31);  /* Reason code qualifying CompCode */

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

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

Visual Basic での呼び出し

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