● 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 | ○ | ○ | ○ | ○ | ○ |
- (凡例)
- ○:有効
- ×:無効
- △:リモートキューのローカル定義にだけ有効
- 注※1
- 別名キューに対するオプションの有効性は,別名が解決されるキューでのオプションの有効性に依存します。
- 注※2
- このオプションは任意のキュータイプに指定できますが,キューがクラスタキューではない場合は無視されます。
● 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 理由コード」を参照してください。