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　注意事項」を参照してください。

ページの先頭へ

MQGET命令 − メッセージの取り出し

機能

形式

C言語の場合

COBOL言語の場合

引数

● Hconn（MQHCONN型） −input

● Hobj（MQHOBJ型） −input

● MsgDesc（MQMD構造体） −input/output

● GetMsgOpts（MQGMO構造体） −input/output

● BufferLength（MQLONG型） −input

● Buffer（MQBYTE型×BufferLength） −output

● DataLength（MQLONG型） −output

● CompCode（MQLONG型） −output

● Reason（MQLONG型） −output

注意事項

MQGET命令　−　メッセージの取り出し

●　Hconn（MQHCONN型）　−input

●　Hobj（MQHOBJ型）　−input

●　MsgDesc（MQMD構造体）　−input/output

●　GetMsgOpts（MQGMO構造体）　−input/output

●　BufferLength（MQLONG型）　−input

●　Buffer（MQBYTE型×BufferLength）　−output

●　DataLength（MQLONG型）　−output

●　CompCode（MQLONG型）　−output

●　Reason（MQLONG型）　−output