MQOPEN命令　−　オブジェクトのオープン

C言語の場合

MQOPEN(MQHCONN Hconn, PMQVOID ObjDesc, MQLONG Options,
       PMQHOBJ Hobj, PMQLONG CompCode, PMQLONG Reason)

COBOL言語の場合

CALL 'MQOPEN' USING HCONN, OBJDESC, OPTIONS, HOBJ,
                COMPCODE, REASON.

●　Hconn（MQHCONN型）　−input

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

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

ただし，MQOPEN命令では，Hconn引数の値としてMQCONN命令の戻り値以外を指定してもエラーにはなりません。それでも，MQCONN命令は必ず発行しなければならないため，MQCONN命令の戻り値を必ず指定してください。また，MQOPEN命令以降に発行する命令でも，同様にMQCONN命令の戻り値を指定してください。

●　ObjDesc（MQOD構造体）　−input/output

オブジェクト記述子です。

オープンするオブジェクトを識別する構造体です。詳細は，「1.　データタイプ」の「MQOD構造体　−　オブジェクト記述子」を参照してください。

ObjDesc引数のObjectNameフィールドがモデルキューの名称の場合，モデルキューの属性で動的キューが生成されます。これは，Options引数でどのオープンオプションを指定しても同様です。このMQOPEN命令で返されたHobjを使用すると，モデルキューではなく，生成された動的キューを利用することになります。これは，MQINQ命令とMQSET命令のときも同様です。ObjDesc引数のモデルキューの名称は，生成された動的キューの名称に置き換えられます。動的キューのタイプは，モデルキューのDefinitionType属性で決まります。動的キューに対するクローズオプションについては，この章の「MQCLOSE命令　−　オブジェクトのクローズ」を参照してください。

●　Options（MQLONG型）　−input

MQOPEN命令の動作を制御するオープンオプションです。

少なくとも，次の一つのオプションを指定してください。

• MQOO_BROWSE

• MQOO_INPUT_*（これらのオプションのうち一つだけ）

• MQOO_INQUIRE

• MQOO_OUTPUT

• MQOO_SET

これらのオプションの意味を次に示します。また，ほかのオプションも指定できます。複数のオプションを指定する場合は，次のどちらかに従ってください。

• それぞれを加算します。ただし，同じ値は2回以上加算しないでください。

• プログラミング言語がビット演算をサポートしている場合に，それぞれのビット論理和を取ります。

同時に指定できない組み合わせは，そのつど示します。それ以外の組み合わせは自由です。ObjDescのオブジェクトに合ったオプションを指定してください。オプションおよびその指定方法の一覧については，「付録A　命令および引数の一覧」を参照してください。

アクセスオプション：

次に示すオプションはオブジェクトに実行される操作の種類を制御します。

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命令で使用するために，キューをオープンします。そのキューがほかのアプリケーションによってすでに取り出し用にオープンされていると，理由コードMQRC_OBJECT_IN_USEで命令は失敗します。

このオプションは，ローカルキュー，別名キュー，およびモデルキューのときだけ有効です。リモートキュー，配布リスト，キューではないオブジェクトについては不正となります。

これらのオプションに対しては，次の注意があります。

• これらのオプションのうち，一つだけ指定できます。

• キューのInhibitGet属性がMQQA_GET_INHIBITEDの場合でも，MQOPEN命令はこれらのオプションで成功します。ただし，この属性値が設定されている間は，MQGET命令は失敗します。

• キューが共用アクセス用に定義されていない場合，つまり，ローカルキューのShareability属性がMQQA_NOT_SHAREABLEの場合，それに対して共用アクセス用にオープンしようとすると，排他アクセス用にオープンするときと同様に扱われます。

• 別名キューをこれらのオプションでオープンすると，排他アクセスできるかどうか，つまり，ほかのアプリケーションが排他アクセスで使用していないかどうかの確認は，別名キューのベースキューに対してされます。

• ObjectQMgrNameフィールドがキューマネジャの別名の場合，これらのオプションは指定できません。また，キューマネジャの別名として使用されるリモートキューのローカル定義のRemoteQMgrName属性がローカルキューマネジャ名の場合も同様です。名称解決については，マニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。

MQOO_BROWSE

検索用にオープンします。

次のどれかのオプションでMQGET命令を使用するために，キューをオープンします。

　MQGMO_BROWSE_FIRST

　MQGMO_BROWSE_NEXT

　MQGMO_BROWSE_MSG_UNDER_CURSOR

これは，すでにMQOO_INPUT_EXCLUSIVEオプションでオープンされているキューに対しても，指定できます。MQOO_BROWSEオプションでMQOPEN命令を呼び出すと，検索カーソルが生成されます。検索カーソルの論理的な位置は，キューにある最初のメッセージの前になります。詳細については，「1.　データタイプ」の「MQGMO構造体　−　メッセージ取り出しオプション」でOptionsフィールドの説明を参照してください。

このオプションは，ローカルキュー，別名キュー，およびモデルキューのときだけ有効です。リモートキュー，配布リスト，キューではないオブジェクトについては不正となります。ObjectQMgrNameフィールドがキューマネジャの別名の場合，このオプションは指定できません。また，キューマネジャの別名として使用されるリモートキューのローカル定義のRemoteQMgrName属性がローカルキューマネジャ名の場合も同様です。名称解決については，マニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。

MQOO_OUTPUT

登録用にオープンします。

以降のMQPUT命令で使用するために，キューをオープンします。

キューのInhibitPut属性がMQQA_PUT_INHIBITEDの場合でも，MQOPEN命令はこのオプションで成功します。ただし，この属性値が設定されている間は，MQPUT命令は失敗します。

このオプションは，配布リストを含むすべてのキューに有効です。

MQOO_INQUIRE

属性の照会用にオープンします。

以降のMQINQ命令で使用するために，キュー，プロセス定義，またはキューマネジャをオープンします。

このオプションは，配布リストを除くすべてのオブジェクトタイプに有効です。ObjectQMgrNameフィールドがキューマネジャの別名の場合は，このオプションは指定できません。これは，キューマネジャの別名として使用されるリモートキューのローカル定義のRemoteQMgrName属性がローカルキューマネジャ名の場合も同様です。名称解決については，マニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。

MQOO_SET

属性の設定用にオープンします。

以降のMQSET命令で使用するために，キューをオープンします。

このオプションは，配布リストを除くすべてのキューに有効です。ObjectQMgrNameフィールドがキューマネジャの別名の場合，このオプションは指定できません。また，キューマネジャの別名として使用されるリモートキューのローカル定義のRemoteQMgrName属性がローカルキューマネジャ名の場合も同様です。名称解決については，マニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。

バインディングオプション：

次に示すオプションは，オープンされたオブジェクトがクラスタキューである場合に適用されます。これらのオプションは，キューハンドルのバインディングを，クラスタキューの特定のインスタンスへと制御します。

MQOO_BIND_ON_OPEN

キューがオープンされたときにハンドルをあて先にバインドします。

このオプションを指定すると，キューがオープンされたとき，ローカルキューマネジャはキューハンドルを特定のあて先キューに固定します。その結果，このハンドルを使用して登録されるすべてのメッセージは，あて先キューの同じインスタンスへ同じルートで送信されます。

このオプションはキューにだけ使用でき，クラスタキューにだけ意味があります。

クラスタキューではないキューに指定された場合，このオプションは無視されます。

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_INQUIREがMQOO_BIND_NOT_FIXEDとともに指定された場合，このハンドルを使用した後続のMQINQでは，クラスタキューの異なるインスタンスを照会することがあります。通常はすべてのインスタンスは同じ属性値を持ちます。

MQOO_BIND_NOT_FIXEDはキューに対してだけ使用でき，クラスタキューに対して意味があります。クラスタキューではないキューに指定された場合，オプションは無視されます。

MQOO_BIND_AS_Q_DEF

キューについてのデフォルトバインディングを使用します。

このオプションを指定すると，ローカルキューマネジャは，DefBindキュー属性で定義された方法でキューハンドルをバインドします。この属性の値は，MQBND_BIND_ON_OPENまたはMQBND_BIND_NOT_FIXEDのどちらかです。

MQOO_BIND_ON_OPENおよびMQOO_BIND_NOT_FIXEDのどちらも指定されていない場合，MQOO_BIND_AS_Q_DEFがデフォルト値となります。

MQOO_BIND_AS_Q_DEFは，プログラムの文書化のために定義されています。

このオプションは，ほかに二つあるバインドオプションのどちらかと一緒に指定されることは意図していません。しかし，値が0であるため，そのような指定を検知できません。

コンテキストオプション：

次に示すオプションは，メッセージコンテキストの処理を制御します。

MQOO_SAVE_ALL_CONTEXT

取り出し時にコンテキストを保存します。

コンテキスト情報は，このキューハンドルに関連づけられます。このハンドルを使用して取り出したメッセージのコンテキストから，この情報が取り出されます。メッセージコンテキストについては，マニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。

このコンテキスト情報は，以降のMQPUT命令およびMQPUT1命令で登録するメッセージに引き渡せます。コンテキスト情報の引き渡しについては，「1.　データタイプ」の「MQPMO構造体　−　メッセージ登録オプション」で，OptionsフィールドのMQPMO_PASS_IDENTITY_CONTEXTオプションとMQPMO_PASS_ALL_CONTEXTオプションの説明を参照してください。

一度もメッセージを取り出さないうちは，登録するメッセージにコンテキストを引き渡せません。

MQGMO_*検索オプションを使用した取り出しでは，コンテキスト情報は保存されません。ただし，MsgDesc引数のコンテキストフィールドには返されます。

このオプションは，ローカルキュー，別名キュー，およびモデルキューのときだけ有効です。リモートキュー，配布リスト，キューではないオブジェクトについては不正となります。

MQOO_INPUT_*オプションのどれかと同時に指定してください。

MQOO_PASS_IDENTITY_CONTEXT

識別コンテキストを引き渡せるようにします。

このオプションを指定することで，メッセージ登録時のPutMsgOpts引数にMQPMO_PASS_IDENTITY_CONTEXTオプションを指定できるようになります。具体的には，MQOO_SAVE_ALL_CONTEXTオプションでオープンした入力キューからの識別コンテキストの情報をメッセージに組み込みます。メッセージコンテキストについては，マニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。

MQOO_OUTPUTオプションと同時に指定してください。

このオプションは，配布リストを含むすべてのキューに有効です。

MQOO_PASS_ALL_CONTEXT

全コンテキストを引き渡せるようにします。

このオプションを指定することで，メッセージ登録時のPutMsgOpts引数にMQPMO_PASS_ALL_CONTEXTオプションを指定できるようになります。具体的には，MQOO_SAVE_ALL_CONTEXTオプションでオープンした入力キューからの識別コンテキストと登録元コンテキストの情報をメッセージに組み込みます。メッセージコンテキストについては，マニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。

このオプションは，MQOO_PASS_IDENTITY_CONTEXTオプションの内容を含みます。このため，同時にMQOO_PASS_IDENTITY_CONTEXTオプションを指定する必要はありません。MQOO_OUTPUTオプションと同時に指定してください。

このオプションは，配布リストを含むすべてのキューに有効です。

MQOO_SET_IDENTITY_CONTEXT

識別コンテキストを設定できるようにします。

このオプションを指定することで，メッセージ登録時のPutMsgOpts引数にMQPMO_SET_IDENTITY_CONTEXTオプションを指定できるようになります。具体的には，MQPUT命令またはMQPUT1命令のMsgDesc引数に指定した識別コンテキストの情報をメッセージに組み込みます。メッセージコンテキストについては，マニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。

このオプションは，MQOO_PASS_IDENTITY_CONTEXTオプションの内容を含みます。このため，同時にMQOO_PASS_IDENTITY_CONTEXTオプションを指定する必要はありません。MQOO_OUTPUTオプションと同時に指定してください。

このオプションは，配布リストを含むすべてのキューに有効です。

MQOO_SET_ALL_CONTEXT

全コンテキストを設定できるようにします。

このオプションを指定することで，メッセージ登録時のPutMsgOpts引数にMQPMO_SET_ALL_CONTEXTオプションを指定できるようになります。具体的には，MQPUT命令またはMQPUT1命令のMsgDesc引数に指定した識別コンテキストと登録元コンテキストの情報をメッセージに組み込みます。メッセージコンテキストについては，マニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。

このオプションは，次のオプションの内容を含みます。このため，同時にこれらのオプションを指定する必要はありません。

　MQOO_PASS_IDENTITY_CONTEXT

　MQOO_PASS_ALL_CONTEXT

　MQOO_SET_IDENTITY_CONTEXT

MQOO_OUTPUTオプションと同時に指定してください。

このオプションは，配布リストを含むすべてのキューに有効です。

そのほかのオプション：

次に示すオプションは権限チェックおよびキューマネジャ停止時の動作を制御します。

MQOO_ALTERNATE_USER_AUTHORITY

代替ユーザ識別子を使用します。

オブジェクトを利用するユーザの識別子として，アプリケーションを実行しているユーザ識別子ではなく，ObjDesc引数のAlternateUserIdの代替ユーザ識別子が使用されます。

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

MQOO_FAIL_IF_QUIESCING

TP1/Message Queueでは意味がありません。

このオプションを指定しても，TP1/Message Queueの動作には影響しません。これは，アプリケーションの移植性を向上させるために定義されています。

次に，MQOPEN命令のオプションとキュータイプとの関係を示します。

オプション	別名キュー※1	ローカルキューおよびモデルキュー	リモートキュー	非ローカルクラスタキュー	配布リスト
MQOO_INPUT_AS_Q_DEF	○	○	×	×	×
MQOO_INPUT_SHARED	○	○	×	×	×
MQOO_INPUT_EXCLUSIVE	○	○	×	×	×
MQOO_BROWSE	○	○	×	×	×
MQOO_OUTPUT	○	○	○	○	○
MQOO_INQUIRE	○	○	△	○	×
MQOO_SET	○	○	△	×	×
MQOO_BIND_ON_OPEN※2	○	○	○	○	○
MQOO_BIND_NOT_FIXED※2	○	○	○	○	○
MQOO_BIND_AS_Q_DEF※2	○	○	○	○	○
MQOO_SAVE_ALL_CONTEXT	○	○	×	×	×
MQOO_PASS_IDENTITY_CONTEXT	○	○	○	○	○
MQOO_PASS_ALL_CONTEXT	○	○	○	○	○
MQOO_SET_IDENTITY_CONTEXT	○	○	○	○	○
MQOO_SET_ALL_CONTEXT	○	○	○	○	○
MQOO_ALTERNATE_USER_AUTHORITY	○	○	○	○	○
MQOO_FAIL_IF_QUIESCING	○	○	○	○	○

●　Hobj（MQHOBJ型）　−output

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

利用するオブジェクトを示すハンドルです。以降の命令でこのオブジェクトを利用するときに，このハンドルを指定します。MQCLOSE命令を呼び出すと，またはこのハンドルの範囲の処理が終了すると，このハンドルは無効になります。

返されるオブジェクトハンドルの有効範囲は，命令に指定されたコネクションハンドルと同じです。コネクションハンドルの有効範囲については，この章の「MQCONN命令　−　キューマネジャへの接続」でHconn引数を参照してください。

●　CompCode（MQLONG型）　−output

完了コードです。

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

• MQCC_OK：成功

• MQCC_WARNING：警告（部分的完了）

• MQCC_FAILED：失敗

●　Reason（MQLONG型）　−output

理由コードです。

CompCode引数がMQCC_OKの場合

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

CompCode引数がMQCC_WARNINGの場合

理由コード	数値	意味
MQRC_MULTIPLE_REASONS	2136	複数のリターンコードが返されました。

CompCode引数がMQCC_FAILEDの場合

理由コード	数値	意味
MQRC_CLUSTER_PUT_INHIBITED	2268	クラスタ内のすべてのキューに対して登録が禁止されています。
MQRC_CLUSTER_RESOLUTION_ERROR	2189	クラスタ名称の解決に失敗しました。
MQRC_CLUSTER_RESOURCE_ERROR	2269	クラスタリソースのエラーです。
MQRC_DEF_XMIT_Q_USAGE_ERROR	2199	省略時の転送キューの使用方法に誤りがあります。
MQRC_DYNAMIC_Q_NAME_ERROR	2011	動的キュー名が不正です。
MQRC_HANDLE_NOT_AVAILABLE	2017	現在そのハンドルは有効ではありません。
MQRC_HCONN_ERROR	2018	コネクションハンドルが不正です。
MQRC_HOBJ_ERROR	2019	オブジェクトハンドルが不正です。
MQRC_MULTIPLE_REASONS	2136	複数の理由コードが返されました。
MQRC_NAME_NOT_VALID_FOR_TYPE	2194	オブジェクトタイプに対してオブジェクト名が不正です。
MQRC_OBJECT_ALREADY_EXISTS	2100	オブジェクトがすでにあります。
MQRC_OBJECT_DAMAGED	2101	オブジェクトが破損しています。
MQRC_OBJECT_IN_USE	2042	オブジェクトは衝突するオプションですでにオープンされています。
MQRC_OBJECT_NAME_ERROR	2152	オブジェクト名が不正です。
MQRC_OBJECT_Q_MGR_NAME_ERROR	2153	オブジェクトキューマネジャ名が不正です。
MQRC_OBJECT_RECORDS_ERROR	2155	オブジェクトレコードが不正です。
MQRC_OBJECT_TYPE_ERROR	2043	オブジェクトタイプが不正です。
MQRC_OD_ERROR	2044	オブジェクト記述子の構造体が不正です。
MQRC_OPTION_NOT_VALID_FOR_TYPE	2045	オブジェクトタイプに対してオプションが不正です。
MQRC_OPTIONS_ERROR	2046	オプションが不正です。または，指定されていません。
MQRC_Q_TYPE_ERROR	2057	キュータイプが不正です。
MQRC_RECS_PRESENT_ERROR	2154	存在するレコードの数が不正です。
MQRC_REMOTE_Q_NAME_ERROR	2184	リモートキュー名が不正です。
MQRC_RESOURCE_PROBLEM	2102	システム資源が不足しています。
MQRC_RESPONSE_RECORDS_ERROR	2156	応答レコードが不正です。
MQRC_STORAGE_NOT_AVAILABLE	2071	記憶容量が不足しています。
MQRC_UNEXPECTED_ERROR	2195	予期しないエラーが発生しました。
MQRC_UNKNOWN_ALIAS_BASE_Q	2082	別名キューのベースキューを認識できません。
MQRC_UNKNOWN_DEF_XMIT_Q	2197	省略時の転送キューを認識できません。
MQRC_UNKNOWN_OBJECT_NAME	2085	オブジェクト名を認識できません。
MQRC_UNKNOWN_OBJECT_Q_MGR	2086	オブジェクトのキューマネジャを認識できません。
MQRC_UNKNOWN_REMOTE_Q_MGR	2087	リモートキューマネジャを認識できません。
MQRC_UNKNOWN_XMIT_Q	2196	転送キューを認識できません。
MQRC_XMIT_Q_USAGE_ERROR	2092	転送キューの使用方法に誤りがあります。

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