MQGET命令 − メッセージの取り出し
機能
MQGET命令で,ローカルキューからメッセージを取り出せます。ローカルキューは,MQOPEN命令でオープンしておく必要があります。
形式
C言語の場合
MQGET(MQHCONN Hconn, MQHOBJ Hobj, PMQVOID MsgDesc, PMQVOID GetMsgOpts, MQLONG BufferLength, PMQVOID Buffer, PMQLONG DataLength, PMQLONG CompCode, PMQLONG Reason)
COBOL言語の場合
CALL 'MQGET' USING HCONN, HOBJ, MSGDESC, GETMSGOPTS, BUFFERLENGTH, BUFFER, DATALENGTH, COMPCODE, REASON.
引数
● Hconn(MQHCONN型) −input
コネクションハンドルです。
キューマネジャへの接続を示すハンドルです。MQCONN命令の戻り値を指定してください。
● Hobj(MQHOBJ型) −input
オブジェクトハンドルです。
メッセージを取り出すキューのハンドルです。MQOPEN命令の戻り値を指定してください。そのキューは,次に示すオプションを一つ以上使用してオープンしておく必要があります。詳細については,この章の「MQOPEN命令 − オブジェクトのオープン」を参照してください。
MQOO_INPUT_SHARED
MQOO_INPUT_EXCLUSIVE
MQOO_INPUT_AS_Q_DEF
MQOO_BROWSE
● MsgDesc(MQMD構造体) −input/output
メッセージ記述子です。
この構造体で,取り出したいメッセージの属性を記述します。また,取り出したメッセージの属性が返されます。詳細については,「1. データタイプ」の「MQMD構造体 − メッセージ記述子」を参照してください。
BufferLength引数の値がメッセージ長より短い場合でも,キューマネジャによってMsgDesc引数に値が設定されます。これは,GetMsgOpts引数でMQGMO_ACCEPT_TRUNCATED_MSGを指定しても指定しなくても同様です。詳細については,「1. データタイプ」の「MQGMO構造体 − メッセージ取り出しオプション」でOptionsフィールドの説明を参照してください。
アプリケーションがバージョン1のMQMD構造体を指定すると,返却されるメッセージには,アプリケーションメッセージデータの前にMQMDE構造体が付加されます。これは,MQMDE構造体の一つ以上のフィールドが初期値以外の場合だけです。MQMDE構造体のFormatフィールドにあるMQFMT_MD_EXTENSIONのフォーマット名は,MQMDE構造体が存在することを示します。
● GetMsgOpts(MQGMO構造体) −input/output
メッセージ取り出しオプションです。
詳細については,「1. データタイプ」の「MQGMO構造体 − メッセージ取り出しオプション」を参照してください。
● BufferLength(MQLONG型) −input
メッセージデータを格納するバッファのバイト長です。
0も指定できます。0を指定した場合は,データのないメッセージを取り出すものとみなされるか,メッセージがキューから削除されて,破棄されなければなりません。メッセージを削除する場合は,MQGMO_ACCEPT_TRUNCATED_MSGの指定が必要です。
- 注意事項
-
キューから取り出せるメッセージの最大長は,ローカルキューのMaxMsgLength属性に定義されています。
● Buffer(MQBYTE型×BufferLength) −output
メッセージデータを格納するバッファです。
バッファには,メッセージ中のデータに適したバウンダリ調整が必要です。多くのメッセージ(MQヘッダ構造体のあるメッセージを含む)には4バイト単位の調整が適していますが,より厳しい調整が必要なメッセージもあります。例えば,64ビット2進整数を含めるメッセージには8バイト単位のバウンダリ調整が必要です。
BufferLength引数の値がメッセージ長より短い場合,Bufferの領域に格納できるだけのメッセージが返されます。これは,GetMsgOpts引数にMQGMO_ACCEPT_TRUNCATED_MSGを指定しても指定しなくても同様です。詳細については,「1. データタイプ」の「MQGMO構造体 − メッセージ取り出しオプション」でOptionsフィールドの説明を参照してください。
Bufferの領域の文字セットとマシンコード形式は,MsgDesc引数のCodedCharSetIdフィールドとEncodingフィールドに返されます。要求される値と異なる場合,アプリケーションメッセージデータを,その文字セットとマシンコード形式に変換してください。アプリケーションメッセージデータを変換するため,
MQGMO_CONVERTオプションを使用できます。詳細については,「1. データタイプ」の「MQGMO構造体 − メッセージ取り出しオプション」でOptionsフィールドの説明を参照してください。
- 注意事項
-
MQGET命令のほかの引数には,ローカルキューマネジャの文字セットとマシンコード形式,つまり,キューマネジャのCodedCharSetId属性とMQENC_NATIVEを使用します。
命令が失敗した場合でも,Bufferの領域の内容が変わることがあります。
C言語では,void型のポインタとしてこの引数を宣言します。したがって,どんなデータタイプのアドレスでも引数として指定できます。
BufferLength引数に0を指定した場合,Buffer引数は参照されません。したがって,C言語のプログラムでは,この引数のアドレスとしてヌルを指定できます。
● DataLength(MQLONG型) −output
メッセージ長です。
メッセージのアプリケーションデータのバイト長です。データ長がBufferLength引数の値より大きい場合,BufferLengthのバイト数だけがBuffer引数に返されます。この場合,領域を超えたメッセージの部分は切り捨てられます。この値が0の場合,メッセージにアプリケーションデータがなかったことを意味します。
BufferLength属性の値がメッセージ長より短い場合でも,キューマネジャによってDataLength引数に実際のメッセージの長さが設定されます。これは,GetMsgOpts引数にMQGMO_ACCEPT_TRUNCATED_MSGオプションを指定しても指定しなくても同様です。詳細については,「1. データタイプ」の「MQGMO構造体 − メッセージ取り出しオプション」でOptionsフィールドの説明を参照してください。これによってアプリケーションは,メッセージ全体を格納できるバッファを確保して,再び命令を呼び出せます。
ただし,MQGMO_CONVERTオプションが指定され,変換されたメッセージデータが大き過ぎてBuffer引数に設定できない場合,DataLength引数には,キューマネジャ定義のフォーマットに対応する未変換データの長さが設定されます。
データの性質上,変換中のデータが拡大することがあるため,アプリケーションは,キューマネジャがDataLength引数に設定した値より大きいバッファを割り当ててください。
● CompCode(MQLONG型) −output
完了コードです。
次のどれかが返されます。
-
MQCC_OK:成功
-
MQCC_WARNING:警告(一部成功)
-
MQCC_FAILED:失敗
● Reason(MQLONG型) −output
理由コードです。
CompCode引数がMQCC_OKの場合
理由コード |
数値 |
意味 |
---|---|---|
MQRC_NONE |
0 |
理由コードはありません。 |
CompCode引数がMQCC_WARNINGの場合
理由コード |
数値 |
意味 |
---|---|---|
MQRC_CONVERTED_MSG_TOO_BIG |
2120 |
変換したメッセージがアプリケーションバッファに対して大き過ぎます。 |
MQRC_FORMAT_ERROR |
2110 |
メッセージのフォーマットが不正です。 |
MQRC_INCONSISTENT_CCSIDS |
2243 |
メッセージセグメントが異なるCCSIDを持っています。 |
MQRC_INCONSISTENT_ENCODINGS |
2244 |
メッセージセグメントが異なるマシンコード形式を持っています。 |
MQRC_INCONSISTENT_UOW |
2245 |
コミット単位の指定が矛盾しています。 |
MQRC_NO_MSG_LOCKED |
2209 |
排他状態のメッセージはありません。 |
MQRC_NOT_CONVERTED |
2119 |
メッセージデータは変換されません。 |
MQRC_SOURCE_CCSID_ERROR |
2111 |
生成元コード化文字セット識別子が無効です。 |
MQRC_TARGET_CCSID_ERROR |
2115 |
受信側コード化文字セット識別子が無効です。 |
MQRC_TRUNCATED_MSG_ACCEPTED |
2079 |
バッファ不足のため,メッセージの後部を切り捨てました(処理は完了しました)。 |
MQRC_TRUNCATED_MSG_FAILED |
2080 |
バッファ不足のため,メッセージの後部を切り捨てました(処理は完了していません)。 |
CompCode引数がMQCC_FAILEDの場合
理由コード |
数値 |
意味 |
---|---|---|
MQRC_BUFFER_ERROR |
2004 |
バッファの引数が不正です。 |
MQRC_BUFFER_LENGTH_ERROR |
2005 |
バッファ長の引数が不正です。 |
MQRC_DATA_LENGTH_ERROR |
2010 |
データ長の引数が不正です。 |
MQRC_GET_INHIBITED |
2016 |
指定されたキューからの取り出しが禁止されています。 |
MQRC_GMO_ERROR |
2186 |
メッセージ取り出しオプションの構造体が不正です。 |
MQRC_HCONN_ERROR |
2018 |
コネクションハンドルが不正です。 |
MQRC_HOBJ_ERROR |
2019 |
オブジェクトハンドルが不正です。 |
MQRC_INCONSISTENT_BROWSE |
2259 |
ブラウズ指定が矛盾しています。 |
MQRC_INCONSISTENT_UOW |
2245 |
コミット単位の指定が矛盾しています。 |
MQRC_INVALID_MSG_UNDER_CURSOR |
2246 |
メッセージ下のカーソルは取り出せません。 |
MQRC_MATCH_OPTIONS_ERROR |
2247 |
一致オプションが不正です。 |
MQRC_MD_ERROR |
2026 |
メッセージ記述子が不正です。 |
MQRC_MSG_SEQ_NUMBER_ERROR |
2250 |
メッセージシーケンス番号が無効です。 |
MQRC_NO_MSG_AVAILABLE |
2033 |
該当するメッセージがありません。 |
MQRC_NO_MSG_UNDER_CURSOR |
2034 |
検索カーソルの位置にメッセージがありません。 |
MQRC_NOT_OPEN_FOR_BROWSE |
2036 |
キューが検索用にオープンされていません。 |
MQRC_NOT_OPEN_FOR_INPUT |
2037 |
キューが取り出し用にオープンされていません。 |
MQRC_OBJECT_DAMAGED |
2101 |
オブジェクトが破損しています。 |
MQRC_OPTIONS_ERROR |
2046 |
オプションが不正です。または,指定されていません。 |
MQRC_Q_DELETED |
2052 |
キューが削除されています。 |
MQRC_Q_MGR_STOPPING |
2162 |
キューマネジャが終了処理中です。 |
MQRC_RESOURCE_PROBLEM |
2102 |
システム資源が不足しています。 |
MQRC_STORAGE_NOT_AVAILABLE |
2071 |
記憶容量が不足しています。 |
MQRC_SYNCPOINT_NOT_AVAILABLE |
2072 |
同期点処理はできません。 |
MQRC_UNEXPECTED_ERROR |
2195 |
予期しないエラーが発生しました。 |
MQRC_WAIT_INTERVAL_ERROR |
2090 |
MQGMO構造体の待ち合わせ最大時間が不正です。 |
MQRC_WRONG_GMO_VERSION |
2256 |
MQGMO構造体で指定されたバージョンは不正です。 |
MQRC_WRONG_MD_VERSION |
2257 |
MQMD構造体で指定されたバージョンは不正です。 |
詳細は,「付録B.2 理由コード」を参照してください。
注意事項
-
取り出したメッセージは,通常,キューから削除されます。この削除は,MQGET命令の処理の一部,または同期点の処理の一部として起こります。
GetMsgOpts引数に検索オプションが指定されている場合,メッセージは削除されません。検索オプションを次に示します。
-
MQGMO_BROWSE_FIRST
-
MQGMO_BROWSE_NEXT
-
MQGMO_BROWSE_MSG_UNDER_CURSOR
これらのオプションの詳細については,「1. データタイプ」の「MQGMO構造体 − メッセージ取り出しオプション」でOptionsフィールドの説明を参照してください。
-
-
検索オプションと同時にMQGMO_LOCKオプションを指定した場合,検索したメッセージは排他状態になり,このハンドルでだけ利用できるようになります。
MQGMO_UNLOCKオプションを指定した場合,以前に排他状態であったメッセージの排他状態が解除されます。この場合,どんなメッセージも取り出せません。また,MsgDesc引数,BufferLength引数,Buffer引数,およびDataLength引数は,参照・変更されません。
-
アプリケーションがキューにメッセージを登録した順序は,次の条件がすべて満たされる場合だけ保たれます。
-
すべてのメッセージが同じ優先度の場合
-
すべてのMQPUT命令で,同じオブジェクトハンドルHobjを使用した場合
-
どのMQPUT命令も,トランザクション内から呼び出していない場合
-
そのキューが,MQPUT命令を呼び出したキューマネジャのローカルキューである場合(詳細は,後述の「注意b.」を参照してください)
これらの条件を満たす場合,かつ次の方法でメッセージを取り出した場合,メッセージは登録された順序で取り出せます。
-
メッセージを取り出すアプリケーションが,MsgIdを指定するなどして,取り出し順序を変更しなかった場合
-
そのキューからメッセージを取り出すのが,一つのアプリケーションだけの場合
複数のアプリケーションがそのキューからメッセージを取り出す場合,それらのアプリケーションは,メッセージが一連のものであることを識別する取り決めをしておく必要があります。例えば,登録元のアプリケーションは,メッセージのCorrelIdフィールドに独自の値を設定できます。
注意
- a.
-
ほかのアプリケーションから,またはアプリケーション内の異なるトランザクションからのメッセージは,一つのトランザクションの観点からは登録した順序である場合も,間隔をおいてキュー内に格納されることがあります。
- b.
-
リモートキューでは,送信側のキューマネジャから受信側のキューマネジャまでに一つの回線しかない構成のときに,メッセージの順序が保たれます。メッセージの幾つかが異なる回線で送信されると,メッセージの到着順序は保証されません。例えば,再構成,トラフィック調整,メッセージ長による回線選択などでは,到着順序は保証されません。また,あて先キューが満杯であるなどの理由で,メッセージの幾つかがデッドレターキューに転送された場合にも,順序が乱れることになります。
登録した順序を保証する条件を満たせない場合も,アプリケーションは,登録した順序を次の方法で保証できます。
-
順序を示す独自の情報をアプリケーションメッセージデータ内に組み込みます。
-
次のメッセージを登録する前に,相手が一つ前のメッセージを受け取ったことを確認します。
-
-
単一のトランザクション内で特定のキューに連続するメッセージをアプリケーションが登録し,トランザクションのコミットに成功する場合,メッセージは次に示す要領で取り出し可能になります。
-
キューが非共用キュー(つまりローカルキュー)である場合,トランザクション内のメッセージはすべて同時に利用できるようになります。
-
-
アプリケーションがメッセージグループを使用しないで,連続するメッセージを同じキューに登録する場合,特定の条件が満たされれば,メッセージの順序が保持されます。詳細については,この章の「MQPUT命令 − メッセージの登録」の「注意事項」を参照してください。条件が満たされると,受信側アプリケーションは送信された順序でメッセージを受信できます。ただし,次に示す制約があります。
-
キューからメッセージを取り出す受信側は一つだけであること
キューからメッセージを取り出すアプリケーションが二つ以上ある場合は,各メッセージを識別するためのメカニズムについて,送信側と申し合わせる必要があります。例えば,送信側アプリケーションで,連続するメッセージのすべてのCorrelIdフィールドに順序に応じたユニークな値を設定できます。
-
特定のMsgIdやCorrelIdを指定することなどによって,受信側は取り出しの順序を故意に変更しないこと
送信側のアプリケーションがメッセージグループとしてメッセージを登録する場合,受信側のアプリケーションがMQGET命令にMQGMO_LOGICAL_ORDERオプションを指定するとき,メッセージは受信側のアプリケーションによって正しい順序で受信されます。メッセージグループの詳細については,次に示す項目を参照してください。
-
MQMD構造体のMsgFlagsフィールド
-
MQPMO構造体のMQPMO_LOGICAL_ORDERオプション
-
MQGMO構造体のMQGMO_LOGICAL_ORDERオプション
-
-
アプリケーションは,MsgDesc引数のFeedbackフィールドがMQFB_QUITかどうかを調べる必要があります。この値の場合は,アプリケーションを終了してください。詳細については,「1. データタイプ」の「MQMD構造体 − メッセージ記述子」でFeedbackフィールドの説明を参照してください。
-
Hobjに該当するキューをMQOO_SAVE_ALL_CONTEXTオプションでオープンしている場合で,MQGET命令の完了コードがMQCC_OKまたはMQCC_WARNINGのとき,キューハンドルHobjに関連するコンテキストは,取り出したメッセージのコンテキストで置き換えられます。ただし,MQGMO_BROWSE_FIRST,MQGMO_BROWSE_NEXT,またはMQGMO_BROWSE_MSG_UNDER_CURSORオプションを指定した場合を除きます。この場合,この注意は該当しません。
保存されたコンテキストはMQPMO_PASS_IDENTITY_CONTEXTまたはMQPMO_PASS_ALL_CONTEXTオプションを指定することによって,以降のMQPUTまたはMQPUT1命令で使用できます。これによって,受信されたメッセージのコンテキストが,その全体または一部を(メッセージが異なるキューに転送されるときなどに)異なるメッセージに伝達することが可能になります。メッセージコンテキストの詳細については,マニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。
-
GetMsgOpts引数にMQGMO_CONVERTオプションが指定されている場合,アプリケーションメッセージデータは,Buffer引数に設定される前に,受信側アプリケーションが要求する表現に変換されます。
-
メッセージの制御情報の中のFormatフィールドがアプリケーションデータの構造を識別し,CodedCharSetIdフィールドとEncodingフィールドがデータの文字セット識別子とマシンコード形式を指定しています。
-
MQGET命令を呼び出すアプリケーションでは,MsgDesc引数のCodedCharSetIdフィールドとEncodingフィールドに,アプリケーションデータ中の変換させる文字セット識別子とマシンコード形式を指定します。
メッセージデータは,変換が必要なとき,メッセージの制御情報のFormatフィールドの値に依存し,キューマネジャ自身によって変換されます。
-
次に示すフォーマット名称に対しては,キューマネジャが変換します。このフォーマット名称は,組み込みフォーマットと呼ばれます。
MQFMT_ADMIN
MQFMT_COMMAND1
MQFMT_COMMAND2
MQFMT_DEAD_LETTER_HEADER
MQFMT_EVENTバージョン 1
MQFMT_MD_EXTENSION
MQFMT_PCF
MQFMT_REF_MSG_HEADER
MQFMT_STRING
MQFMT_TRIGGER
MQFMT_XMIT_Q_HEADER
-
フォーマット名称MQFMT_NONEは,メッセージデータの性質が未定義の特別な値です。したがって,メッセージがキューから取り出されたときも,キューマネジャによってその値が変換されることはありません。
- 注意事項
-
フォーマット名称MQFMT_NONEのメッセージにMQGET命令でMQGMO_CONVERTが指定されたとき,文字セットまたはマシンコード形式がMsgDesc引数に指定されたものと異なる場合,かつほかのエラーがない場合は,メッセージはBuffer引数に返されます。ただし,命令は完了コードMQCC_WARNINGおよび理由コードMRC_FORMAT_ERRORで完了します。
-
MQGET命令から返された値で,次に示す理由コードはメッセージの変換が成功したことを示します。
MQRC_NONE
-
次に示す理由コードはメッセージの変換が成功した可能性があることを示します。成功したかどうかを調べるには,アプリケーションはMsgDesc引数のCodedCharSetIdフィールドとEncodingフィールドをチェックしなければなりません。
MQRC_TRUNCATED_MSG_ACCEPTED
そのほかのすべての理由コードは,メッセージが変換されなかったことを示します。
-
-
メッセージの順序性については,マニュアル「TP1/Message Queue プログラム作成の手引」の「12.3 注意事項」を参照してください。