MQGMO構造体　−　メッセージ取り出しオプション

目的

MQGMO構造体を使用すれば，キューからのメッセージの取り出し方法を制御するオプションをアプリケーションで指定できます。この構造体は，MQGET命令の入出力用の引数です。

バージョン

MQGMO構造体のバージョンには1および2があります。しかし，すべての環境でMQGMO_VERSION_2がサポートされているわけではありません。複数の環境にアプリケーションを移植する場合は，使用するバージョンのMQGMO構造体が，すべての環境でサポートされている必要があります。MQGMO_VERSION_2以降の構造体にだけ存在するフィールドについては，そのことをフィールドの説明に記載しています。

サポートするプログラミング言語のCOPYファイルとINCLUDEファイルでは，最新バージョンのMQGMO構造体が提供されます。しかし，Versionフィールドの初期値はMQGMO_VERSION_1です。バージョン1の構造体にないフィールドを使用する場合は，アプリケーションで使用したいバージョンの番号をVersionフィールドに設定してください。

文字セットおよびマシンコード

MQGMO構造体のデータは，ローカルキューマネジャの文字セットおよびマシンコードに従います。それぞれ，キューマネジャのCodedCharSetId属性およびMQENC_NATIVEで指定します。TP1/Message Queue Accessのクライアントアプリケーションの場合，MQGMO構造体はクライアントの文字セットとマシンコードに従います。

●　GroupStatus（MQCHAR型）　メッセージグループフラグ

取り出されたメッセージがグループに属するかどうかを示すフラグです。

次の値を取ります。

MQGS_NOT_IN_GROUP

メッセージはグループに属しません。

MQGS_MSG_IN_GROUP

メッセージはグループに属しますが，グループの最終メッセージではありません。

MQGS_LAST_MSG_IN_GROUP

メッセージはグループの最終メッセージです。

これは，グループがただ一つのメッセージで構成されている場合にも返される値です。

これは出力用のフィールドです。

このフィールドの初期値はMQGS_NOT_IN_GROUPです。

このフィールドは，Versionフィールドの値がMQGMO_VERSION_2以降の場合だけ有効です。

●　MatchOptions（MQLONG型）　一致オプション

アプリケーションがMQGET命令で返されるメッセージを選択するのに使用するMsgDesc引数のどのフィールドを選ぶかを指定できます。アプリケーションはこのフィールドに必要なオプションを設定し，MsgDesc引数の対応するフィールドに要求する値を設定します。MQMD構造体の値を持つメッセージだけ，MQGET命令でMsgDesc引数を使用して取り出される可能性があります。対応する一致オプションが指定されないフィールドは，返すメッセージを選ぶときに無視されます。MQGET命令でメッセージを選択しないで，どんなメッセージも受け入れられる場合，MatchOptionsフィールドにはMQMO_NONEが設定されなければなりません。

MQGMO_LOGICAL_ORDERが指定された場合，特定のメッセージだけが次のMQGET命令で返す対象となります。

• 現在のグループまたは現在の論理メッセージがない場合，MsgSeqNumberフィールドが1で，かつOffsetフィールドが0のメッセージだけが返す対象となります。この場合，実際に返されるメッセージを選択するには，次に示す一致オプションのうち，一つ以上のオプションを使用できます。

  • MQMO_MATCH_MSG_ID

  • MQMO_MATCH_CORREL_ID

  • MQMO_MATCH_GROUP_ID

• 現在のグループまたは現在の論理メッセージがある場合，そのグループの次のメッセージ，またはその論理メッセージの次のセグメントだけが返されます。これは，MQMO_*オプションを指定しても変更できません。

上記の条件が両方とも該当する場合も，ほかの一致オプションを指定できます。ただし，MsgDesc引数の対応するフィールドの値は，返す必要があるメッセージのフィールドの値と一致しなければなりません。この条件が満たされない場合は，MQRC_MATCH_OPTIONS_ERRORとなり失敗します。

MQGMO_MSG_UNDER_CURSOR，またはMQGMO_BROWSE_MSG_UNDER_CURSORが指定された場合，MatchOptionsフィールドは無視されます。

次に示す一致オプションを，一つ以上指定できます。

MQMO_MATCH_MSG_ID

指定されたメッセージ識別子のメッセージを取り出します。

取り出されるメッセージは，MQGET命令のMsgDesc引数のMsgIdフィールドの値と一致するメッセージ識別子を持つ必要があることを指定します。

このオプションは，適用できるほかの一致オプション（例：相関識別子）と同時に使用できます。

このオプションが指定されない場合，MsgDesc引数のMsgIdフィールドは無視され，どんなメッセージ識別子とも一致します。

注意事項

メッセージ識別子MQMI_NONEは，MQMD構造体のどんなメッセージ識別子とも一致する特別な値です。そのため，MQMI_NONEと一緒にMQMO_MATCH_MSG_IDを指定しても意味がありません。

MQMO_MATCH_CORREL_ID

指定された相関識別子のメッセージを取り出します。

取り出されるメッセージは，MQGET命令のMsgDesc引数のCorrelIdフィールドの値と一致する相関識別子を持つ必要があることを指定します。このオプションは，適用できるほかの一致オプション（例：メッセージ識別子）と同時に使用できます。

このオプションが指定されない場合は，MsgDesc引数のCorrelIdフィールドは無視され，どんな相関識別子とも一致します。

注意事項

相関識別子MQCI_NONEは，MQMD構造体のどんな相関識別子とも一致する特別な値です。そのため，MQCI_NONEと一緒にMQMO_MATCH_CORREL_IDを指定しても意味がありません。

MQMO_MATCH_GROUP_ID

指定されたグループ識別子のメッセージを取り出します。

取り出されるメッセージは，MQGET命令のMsgDesc引数のGroupIdフィールドの値と一致するグループ識別子を持つ必要があることを指定します。このオプションは，適用できるほかの一致オプション（例：相関識別子）と同時に使用できます。

このオプションが指定されない場合，MsgDesc引数のGroupIdフィールドは無視され，どんなグループ識別子とも一致します。

注意事項

グループ識別子MQGI_NONEは，MQMD構造体のどんなグループ識別子とも一致する特別な値です。そのため，MQGI_NONEと一緒にMQMO_MATCH_GROUP_IDを指定しても意味がありません。

MQMO_MATCH_MSG_SEQ_NUMBER

指定されたメッセージシーケンス番号のメッセージを取り出します。

取り出されるメッセージが，MQGET命令のMsgDesc引数のMsgSeqNumberフィールドの値と一致するメッセージシーケンス番号を持つ必要があることを指定します。このオプションは，適用できるほかの一致オプション（例：グループ識別子）と同時に指定できます。

このオプションが指定されない場合，MsgDesc引数のMsgSeqNumberフィールドは無視され，どんなメッセージシーケンス番号とも一致します。

MQMO_MATCH_OFFSET

指定されたオフセットのメッセージを取り出します。

取り出されるメッセージは，MQGET命令のMsgDesc引数のOffsetフィールドの値と一致するオフセットを持つ必要があることを指定します。このオプションは，適用できるほかの一致オプション（例：メッセージシーケンス番号）と同時に使用できます。

このオプションが指定されない場合，MsgDesc引数のMsgSeqNumberフィールドは無視され，どんなオフセットとも一致します。

上記のオプションがどれも指定されなかった場合，次のオプションが指定できます。

MQMO_NONE

一致指定なし。

返されるメッセージを選択するときに，一致指定を使用しないことを指定します。したがって，キューに存在するすべてのメッセージが，取り出し対象となります。ただし，MQGMO_ALL_MSGS_AVAILABLEオプション，MQGMO_ALL_SEGMENTS_AVAILABLEオプション，およびMQGMO_COMPLETE_MSGオプションによって制御できます。MQMO_NONEはプログラムの文書化のために定義されています。ほかのMQMO_*オプションと組み合わせて使用するオプションではありません。値は0なので，これ以外の用途では使用できません。

これは入力用のフィールドです。

このフィールドの初期値はMQMO_MATCH_CORREL_IDとMQMO_MATCH_MSG_IDです。

このフィールドは，Versionフィールドの値がMQGMO_VERSION_2以降の場合だけ有効です。

注意事項

MatchOptionsフィールドの初期値は，以前のキューマネジャと互換性を保つために定義されています。ただし，選択基準なしでキューから一連のメッセージを取り出すときは，アプリケーションは，MQGET命令が実行される前にMsgIdフィールドとCorrelIdフィールドを，MQMI_NONEとMQCI_NONEにリセットする必要があります。ただし，VersionフィールドにMQGMO_VERSION_2を，MatchOptionsフィールドにMQMO_NONEを設定すれば，MsgIdフィールドとCorrelIdフィールドをリセットする必要はありません。

●　Options（MQLONG型）　取り出しオプション

MQGET命令の動作を制御します。

指定できるオプションを説明します。なお，指定しなくてもかまいません。二つ以上を指定する場合は，次のどちらかに従ってください。

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

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

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

待ち合わせオプション：

メッセージがキューに到着するまでの待ち合わせに関連するオプションを次に示します。

MQGMO_WAIT

該当するメッセージの到着を待ちます。

アプリケーションは，該当するメッセージが到着するまで待ちます。アプリケーションの待ち合わせ最大時間は，WaitIntervalフィールドに指定します。

取り出しが禁止されている場合，または待ち合わせの間に禁止された場合は，メッセージの待ち合わせは取り消されます。このとき，完了コードMQCC_FAILED，理由コードMQRC_GET_INHIBITEDで命令は終了します。該当するメッセージがキューにあるかどうかは，関係ありません。

このオプションは，MQGMO_BROWSE_FIRSTオプションまたはMQGMO_BROWSE_NEXTオプションと同時に使用できます。

複数のアプリケーションが同じキューで待ち合わせをしている場合，該当するメッセージが到着したときの動作は，次のようになります。なお，ここでは，検索オプションを指定してMQGMO_LOCKオプションを指定しないものを，検索MQGET命令と呼びます。MQGMO_LOCKを指定したものは，非検索MQGET命令として扱われます。

• 一つ以上の非検索MQGET命令が待ち合わせをしているが，検索MQGET命令は待ち合わせをしていない場合，一つの命令がメッセージを取り出せます。

• 一つ以上の検索MQGET命令が待ち合わせをしているが，非検索MQGET命令は待ち合わせをしていない場合，すべての命令がメッセージを検索できます。

• 一つ以上の非検索MQGET命令と一つ以上の検索MQGET命令が待ち合わせをしている場合，一つの非検索MQGET命令だけがメッセージを取り出せます。同時に，幾つか（すべての場合もあるし，まったくない場合もある）の検索MQGET命令がメッセージを検索できます。なお，検索MQGET命令が実行できる数は，オペレーティングシステムのスケジュール管理やほかの要素に左右されます。

一つ以上の非検索MQGET命令が同じキューについて待ち合わせをしている場合，一つの命令だけがメッセージを取り出せます。このときキューマネジャは，次のように優先順位を付けます。

1. 指定付きメッセージの待ち合わせ

   この場合は，指定に該当するメッセージだけが対象になります（例：指定したMsgIdまたはCorrelIdのどちらかの場合，またはその両方を満たすメッセージの場合）。

2. 一般のメッセージの待ち合わせ

   この場合は，すべてのメッセージが対象になります。

また，次のことに注意してください。

• 1の指定付きメッセージの待ち合わせでは，それよりほかの優先度を付け加えることはできません。

• 1，2の各優先順位内では，どのアプリケーションが選択されるか確定していません。特に，最も長く待ち合わせをしているアプリケーションが選択されるとは限りません。

• パスの長さ，およびオペレーティングシステムのスケジュール管理が影響するため，オペレーティングシステムのプロセス実行優先度の低いアプリケーションが，先にメッセージを取り出せることがあります。

• 上記の理由のため，待ち合わせをしていないアプリケーションがメッセージを取り出せることがあります。

MQGMO_WAITオプションと次に示すオプションを同時に指定した場合，MQGMO_WAITは無視されますが，エラーにはなりません。

• MQGMO_BROWSE_MSG_UNDER_CURSOR

• MQGMO_MSG_UNDER_CURSOR

MQGMO_NO_WAIT

該当するメッセージがない場合，即時に制御を返します。

該当するメッセージがない場合，アプリケーションは待ち合わせをしません。これはMQGMO_WAITオプションの反対で，プログラムのコーディングをわかりやすくするために定義されています。どちらも指定しなかった場合，この値が仮定されます。

MQGMO_NO_WAITオプションとMQGMO_WAITオプションを同時に指定した場合，MQGMO_NO_WAITは無視されますが，エラーにはなりません。

MQGMO_FAIL_IF_QUIESCING

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

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

同期点オプション：

MQGET命令のトランザクションへの参加に関連するオプションを次に示します。

MQGMO_SYNCPOINT

同期点でメッセージを取り出します。

通常のトランザクションの範囲内で取り出します。取り出したメッセージは，ほかのアプリケーションから使用できなくなります。ただし，キューから削除されるのは，トランザクションがコミットしたときだけです。トランザクションがロールバックすると，ほかのアプリケーションから使用できるようになります。

このオプションは，ローカルキューマネジャが同期点処理をサポートしている場合だけ指定できます。同期点処理をサポートしていないキューマネジャでMQGMO_SYNCPOINTを指定した場合，完了コードMQCC_FAILED，理由コードMQRC_SYNCPOINT_NOT_AVAILABLEで命令は終了します。同期点の取得とトランザクションについては，マニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。

このオプションとMQGMO_NO_SYNCPOINTオプションのどちらも指定しなかった場合，取り出し命令がトランザクション内に含められるかどうかは，環境に依存します。TP1/Message Queueでは，この命令をトランザクション内から呼び出したかどうかで，省略時にトランザクション内に含められるかどうかが決まります。省略時の動作が環境によって異なるため，移植を考慮するアプリケーションでは，オプションを省略しないでください。つまり，MQGMO_SYNCPOINTオプションかMQGMO_NO_SYNCPOINTオプションのどちらかを，明確に指定してください。

次に示すオプションは，MQGMO_SYNCPOINTオプションと同時に指定できません。

• MQGMO_BROWSE_FIRST

• MQGMO_BROWSE_MSG_UNDER_CURSOR

• MQGMO_BROWSE_NEXT

• MQGMO_LOCK

• MQGMO_NO_SYNCPOINT

• MQGMO_SYNCPOINT_IF_PERSISTENT

• MQGMO_UNLOCK

MQGMO_NO_SYNCPOINT

同期点の処理なしでメッセージを取り出します。

通常のトランザクションの範囲外で取り出します。検索要求の場合を除いて，メッセージは取り出し直後にキューから削除されます。トランザクションがロールバックしても，メッセージは再び有効になりません。

このオプションは，MQGMO_BROWSE_FIRST，またはMQGMO_BROWSE_NEXTオプションを指定した場合を想定しています。

このオプションとMQGMO_SYNCPOINTオプションのどちらも指定しなかった場合，取り出し命令がトランザクション内に含められるかどうかは，環境に依存します。TP1/Message Queueでは，この命令をトランザクション内から呼び出したかどうかで，省略時にトランザクション内に含められるかどうかが決まります。省略時の動作が環境によって異なるため，移植を考慮するアプリケーションでは，オプションを省略しないでください。つまり，MQGMO_SYNCPOINTオプションかMQGMO_NO_SYNCPOINTオプションのどちらかを，明確に指定してください。

次に示すオプションは，MQGMO_NO_SYNCPOINTオプションと同時に指定できません。

• MQGMO_SYNCPOINT

• MQGMO_SYNCPOINT_IF_PERSISTENT

同期点のオプションとキューマネジャのSyncPoint属性の関係を，次の表に示します。

キューマネジャの SyncPoint属性	MQGET命令の 呼び出し位置	MQGET命令の同期点のオプション
		MQGMO_ SYNCPOINT	MQGMO_NO_ SYNCPOINT	省略
MQSP_AVAILABLE	トランザクション内	1	2	1
	トランザクション外	×	2	2
MQSP_NOT_AVAILABLE	トランザクション内	×	2	×
	トランザクション外	×	2	2

（凡例）

1：命令はトランザクション内に含まれます。

2：命令はトランザクション内に含まれません。

×：命令は理由コードMQRC_SYNCPOINT_NOT_AVAILABLEで失敗します。

MQGMO_SYNCPOINT_IF_PERSISTENT

取り出すメッセージが永続メッセージの場合，キューマネジャはアプリケーションでMQGMO_SYNCPOINTが指定されている場合と同じように取り出し処理を実行します。

取り出すメッセージが非永続メッセージの場合，キューマネジャはアプリケーションでMQGMO_NO_SYNCPOINTが指定されている場合と同じように取り出し処理を実行します。

次に示すオプションは，MQGMO_SYNCPOINT_IF_PERSISTENTオプションと同時に指定できません。

• MQGMO_BROWSE_FIRST

• MQGMO_BROWSE_MSG_UNDER_CURSOR

• MQGMO_BROWSE_NEXT

• MQGMO_COMPLETE_MSG

• MQGMO_NO_SYNCPOINT

• MQGMO_SYNCPOINT

• MQGMO_UNLOCK

• MQGMO_LOCK

検索オプション：

キューからのメッセージ検索に関連するオプションを次に示します。

MQGMO_BROWSE_FIRST

キューの先頭から検索します。

MQOO_BROWSEオプションでキューをオープンした場合，検索カーソルが生成されます。検索カーソルは，キューの最初のメッセージを論理的に指します。以降のMQGET命令では，MQGMO_BROWSE_FIRST，MQGMO_BROWSE_NEXT，またはMQGMO_BROWSE_MSG_UNDER_CURSORオプションを指定することで，メッセージを削除しないで検索できます。検索カーソルは，キュー内のメッセージの位置を指します。このため，MQGMO_BROWSE_NEXTを指定した次のMQGET命令で，適切なメッセージを検索できます。

MQGET命令でMQGMO_BROWSE_FIRSTを指定すると，それまでの検索カーソルの位置は無視されます。そして，メッセージ記述子の指定に該当する最初のメッセージが検索されます。検索されたメッセージはキューに残ります。また，検索カーソルはこのメッセージを指したままです。

この命令が終了すると，検索カーソルは返されたメッセージを指します。MQGMO_BROWSE_NEXTを指定した次のMQGET命令を実行するまでにそのメッセージが削除された場合，その位置にメッセージがなくても，検索カーソルはその位置を指したままです。

検索したメッセージをキューから削除するために，このあとの非検索MQGET命令で，MQGMO_MSG_UNDER_CURSORオプションを指定できます。

同じHobjハンドルを使用して非検索MQGET命令を実行しても，検索カーソルは移動しないことに注意してください。また，完了コードMQCC_FAILED，または理由コードMQRC_TRUNCATED_MSG_FAILEDで終了した検索MQGET命令でも，検索カーソルは移動しません。

検索したメッセージを排他状態にするために，このオプションと同時にMQGMO_LOCKオプションを指定できます。

MQGMO_BROWSE_FIRSTは，グループ内のメッセージおよび論理メッセージのセグメントの処理を制御するMQGMO構造体，およびMQMO構造体のオプションの正しい組み合わせと一緒に指定できます。

MQGMO_LOGICAL_ORDERが指定された場合，メッセージは論理的な順序で検索されます。省略された場合，メッセージは物理的な順序で検索されます。MQGMO_BROWSE_FIRSTが指定されると，論理順序と物理順序をスイッチできますが，MQGMO_BROWSE_NEXTを使用したMQGET命令は，キューハンドルに対してMQGMO_BROWSE_FIRSTを最後に指定した命令と同じ順序でキューを検索しなければなりません。

キューにあるメッセージを検索するMQGET命令で，キューマネジャに保持されるグループおよびセグメントの情報は，キューからメッセージを取り出すMQGET命令でキューマネジャに保持されるグループおよびセグメントの情報とは分離されています。MQGMO_BROWSE_FIRSTが指定されると，キューマネジャは，グループおよびセグメントの情報を無視し，現在のグループおよび論理メッセージがないかのようにキューを探します。MQGET命令が，完了コードMQCC_OKまたはMQCC_WARNINGで成功すると，検索のためのグループおよびセグメントの情報は，返却されたメッセージの値に設定されます。命令が失敗すると，グループおよびセグメントの情報は命令前と同じになります。

次に示すオプションは，MQGMO_BROWSE_FIRSTオプションと同時に指定できません。

• MQGMO_BROWSE_NEXT

• MQGMO_BROWSE_MSG_UNDER_CURSOR

• MQGMO_MSG_UNDER_CURSOR

• MQGMO_SYNCPOINT

• MQGMO_SYNCPOINT_IF_PERSISTENT

• MQGMO_UNLOCK

また，キューを検索用にオープンしていない場合もエラーになります。

MQGMO_BROWSE_NEXT

キューの現在位置から検索します。

検索カーソルは，メッセージ記述子の指定に該当する次のメッセージに移ります。そして，そのメッセージがアプリケーションに返されます。検索されたメッセージは，キューに残ります。

メッセージが検索される順序は，キューにメッセージが格納されているとおりです。メッセージが検索される順序の種類を次に示します。

• 優先度内でのFIFO順序（MQMDS_PRIORITY）

• 優先度に関係ないFIFO順序（MQMDS_FIFO）

詳細は，「3.　オブジェクトの属性」の「キューの属性」でMsgDeliverySequence属性の説明を参照してください。

キューを検索用にオープンしたあと，そのハンドルを使用した最初の検索MQGET命令は，MQGMO_BROWSE_FIRSTを指定した場合もMQGMO_BROWSE_NEXTを指定した場合も同じになります。

MQGMO_BROWSE_NEXTを指定した次のMQGET命令を実行するまでにそのメッセージが削除された場合，その位置にメッセージがなくても，検索カーソルはその位置を指したままです。

注意事項

メッセージをキューに登録するとき，そのキューでのメッセージの位置が決定される時点と，メッセージの位置が有効になってほかのアプリケーションが参照できるようになる時点とは異なります。そのため，複数のアプリケーションまたはチャネルが同一のキューにメッセージを登録する場合には注意が必要です。つまり，メッセージを参照するアプリケーションが検索MQGET命令を実行して，位置が有効になる前のメッセージより後ろに検索カーソルを進めた場合，以降のMQGMO_BROWSE_NEXTを使用した検索ではそのメッセージは見つかりません。この場合は，MQGMO_BROWSE_FIRSTを使用して，キューの先頭から検索する必要があります。

キューのMsgDeliverySequence属性がMQMDS_PRIORITYの場合で，現在の検索カーソルが指すメッセージよりも優先度の高いメッセージが到着したとき，そのメッセージはMQGMO_BROWSE_NEXTを使用した検索では見つかりません。MQGMO_BROWSE_FIRSTオプションで検索カーソルをリセットするか，再びキューをオープンしないと，そのメッセージは検索できません。

検索したメッセージをキューから削除するには，このあとの非検索MQGET命令で，MQGMO_MSG_UNDER_CURSORオプションを指定します。同じHobjハンドルを使用して非検索MQGET命令を実行しても，検索カーソルは移動しないことに注意してください。

検索したメッセージを排他状態にするには，このオプションと同時にMQGMO_LOCKオプションを指定します。

なお，MQGMO_BROWSE_NEXTは，グループ内のメッセージおよび論理メッセージのセグメントの処理を制御するMQGMO構造体，およびMQMO構造体のオプションの正しい組み合わせと一緒に指定できます。

MQGMO_LOGICAL_ORDERが指定された場合，メッセージは論理的な順序で検索されます。省略された場合，メッセージは物理的な順序で検索されます。MQGMO_BROWSE_FIRSTが指定されると，論理順序と物理順序でスイッチできますが，MQGMO_BROWSE_NEXTを使用したMQGET命令はキューハンドルに対してMQGMO_BROWSE_FIRSTを指定した最後の命令と同じ順序でキューを検索しなければなりません。この条件が満たされない場合，MQRC_INCONSISTENT_BROWSEで失敗となります。

注意事項

MQGMO_LOGICAL_ORDERを指定しないで，MQGET命令でメッセージグループ，またはグループに属さない論理メッセージの終わりを超えて検索した場合は，特に注意が必要です。例えば，グループの最終メッセージが，偶然そのグループの最初のメッセージよりも先にキューにある場合に，グループの終わりを超えて検索するとします。この場合，次のグループにある最初のメッセージを見つけるために，MQGMO_BROWSE_NEXTでMQMO_MATCH_MSG_SEQ_NUMBERのMsgSeqNumberを1に設定すると，すでに検索したグループの最初のメッセージが再度返却されます。また，間にグループがある場合に，複数のMQGET命令のあとにも，すでに検索したグループの最初のメッセージが再度返却されることがあります。

このような不確定のループは，検索用にキューを二度オープンすることで避けられます。また，次のことに留意すると，不確定のループを避けられます。

• 最初のハンドルは各グループの最初のメッセージだけを検索するのに使用します。

• 2番目のハンドルは指定したグループ内のメッセージだけを検索するのに使用します。

• 2番目の検索カーソルを最初の検索カーソルの位置に移動するときは，MQMO構造体のオプションをグループのメッセージ検索の前に使用します。

• グループを超えて検索する場合，MQGMO_BROWSE_NEXTは使用しないようにします。

キューにあるメッセージを検索するMQGET命令でキューマネジャに保持されるグループおよびセグメントの情報は，キューからメッセージを取り出すMQGET命令によってキューマネジャに保持されるグループおよびセグメントの情報とは分離されています。

次に示すオプションは，MQGMO_BROWSE_NEXTオプションと同時に指定できません。

• MQGMO_BROWSE_FIRST

• MQGMO_BROWSE_MSG_UNDER_CURSOR

• MQGMO_MSG_UNDER_CURSOR

• MQGMO_SYNCPOINT

• MQGMO_SYNCPOINT_IF_PERSISTENT

• MQGMO_UNLOCK

また，キューを検索用にオープンしていない場合もエラーになります。

MQGMO_BROWSE_MSG_UNDER_CURSOR

検索カーソルの位置を検索します。

このオプションは，MQGMO構造体のMatchOptionsフィールドに指定されたMQMO構造体のオプションに関係なく，検索のために検索カーソルがメッセージにポイントされます。

また，このオプションでは，検索カーソルが指すメッセージを削除しないで検索します。MsgDesc引数のMsgIdフィールドおよびCorrelIdフィールドに指定した値は無視されます。

検索カーソルが指すメッセージは，MQGMO_BROWSE_FIRSTまたはMQGMO_BROWSE_NEXTオプションで，一つ前に検索されたものです。オープンしてから一度も検索しなかった場合，または該当するメッセージが削除されていた場合は，命令は失敗します。

このオプションの命令で，検索カーソルの位置が移動することはありません。検索したメッセージをキューから削除するために，このあとの非検索MQGET命令で，MQGMO_MSG_UNDER_CURSORオプションを指定できます。

同じHobjハンドルを使用して非検索MQGET命令を実行しても，検索カーソルは移動しないことに注意してください。また，完了コードMQCC_FAILED，または理由コードMQRC_TRUNCATED_MSG_FAILEDで終了した検索MQGET命令でも，検索カーソルは移動しません。

MQGMO_LOCKオプションと同時にMQGMO_BROWSE_MSG_UNDER_CURSORオプションを指定した場合，次のようになります。

• すでに排他状態のメッセージがある場合，検索カーソルはそのメッセージを指しています。この場合，そのメッセージを排他状態にしたままで検索できます。

• 排他状態のメッセージがない場合，検索カーソルが指すメッセージが排他状態になり，アプリケーションに返されます。検索カーソルが指す位置にメッセージがない場合，命令は失敗します。

MQGMO_LOCKオプションを指定しないでMQGMO_BROWSE_MSG_UNDER_CURSORオプションを指定した場合，次のようになります。

• すでに排他状態のメッセージがある場合，検索カーソルはそのメッセージを指しています。そのメッセージはアプリケーションに返され，排他状態は解除されます。メッセージの排他状態が解除されるため，再び検索したり取り出したりできる保証はありません。したがって，そのメッセージは，ほかのアプリケーションによって削除されることがあります。

• 排他状態のメッセージがない場合，検索カーソルが指すメッセージがアプリケーションに返されます。検索カーソルが指す位置にメッセージがない場合，命令は失敗します。

MQGMO_COMPLETE_MSGがMQGMO_BROWSE_MSG_UNDER_CURSORと一緒に指定される場合，検索カーソルは，MQMD構造体のOffsetフィールドが0であるメッセージを特定しなければなりません。この条件が満たされない場合，理由コードMQRC_INVALID_MSG_UNDER_CURSORで失敗となります。

キューにあるメッセージを検索するMQGET命令でキューマネジャに保持されるグループおよびセグメントの情報は，キューからメッセージを取り出すMQGET命令によってキューマネジャに保持されるグループ，およびセグメントの情報とは分離されています。

次に示すオプションは，MQGMO_BROWSE_MSG_UNDER_CURSORオプションと同時に指定できません。

• MQGMO_BROWSE_FIRST

• MQGMO_BROWSE_NEXT

• MQGMO_MSG_UNDER_CURSOR

• MQGMO_SYNCPOINT

• MQGMO_SYNCPOINT_IF_PERSISTENT

• MQGMO_UNLOCK

また，キューを検索用にオープンしていない場合もエラーになります。

MQGMO_MSG_UNDER_CURSOR

検索カーソルの位置で取り出します。

このオプションを指定すると，MQGMO構造体のMatchOptionsフィールドに指定されたMQMO構造体のオプションには関係なく，検索カーソルが指すメッセージを取り出します。MsgDesc引数のMsgIdフィールドまたはCorrelIdフィールドで指定した値は無視されます。このメッセージは，キューから削除されます。

検索カーソルが指すメッセージは，MQGMO_BROWSE_FIRSTまたはMQGMO_BROWSE_NEXTオプションで，一つ前に検索されたものです。

MQGMO_COMPLETE_MSGがMQGMO_MSG_UNDER_CURSORと一緒に指定された場合，検索カーソルはMQMD構造体のOffsetフィールドが0であるメッセージを特定しなければなりません。この条件が満たされない場合，理由コードMQRC_INVALID_MSG_UNDER_CURSORで，MQGET命令は失敗します。

次に示すオプションは，MQGMO_MSG_UNDER_CURSORオプションと同時に指定できません。

• MQGMO_BROWSE_FIRST

• MQGMO_BROWSE_NEXT

• MQGMO_BROWSE_MSG_UNDER_CURSOR

• MQGMO_UNLOCK

また，キューを検索用と取り出し用の両方でオープンしていない場合もエラーになります。検索カーソルが取り出せるメッセージを指していなかった場合，MQGET命令は失敗します。

ロックオプション：

キュー上のメッセージの排他に関連するオプションを次に示します。

MQGMO_LOCK

メッセージを排他状態にします。

検索したメッセージを排他状態にします。そのキューのほかのオープンハンドルからは，そのメッセージを参照できなくなります。このオプションは，MQGMO_BROWSE_FIRST，MQGMO_BROWSE_NEXT，またはMQGMO_BROWSE_MSG_UNDER_CURSORオプションのどれかと同時に指定してください。

それぞれのハンドルでは，一つのメッセージだけを排他状態にできます。排他状態にできるメッセージは，論理メッセージまたは物理メッセージとなります。

• MQGMO_COMPLETE_MSGが指定されると，論理メッセージを構成するすべてのメッセージセグメントが，キューハンドルにロックされます。ただし，すべてのメッセージがキューに存在し，取り出し可能でなければなりません。

• MQGMO_COMPLETE_MSGが指定されない場合，単一の物理メッセージだけがキューハンドルにロックされます。このメッセージが論理メッセージのセグメントであるとき，ロックされたセグメントはMQGMO_COMPLETE_MSGを使用するほかのアプリケーションが論理メッセージを取り出したり，検索したりするのを防止します。

完了コードMQCC_FAILEDが返された場合，または完了コードMQCC_WARNINGで理由コードMQRC_TRUNCATED_MSG_FAILEDが返された場合，メッセージは排他状態になりません。

あるハンドルで排他状態にしているメッセージがある場合は，そのメッセージは常に検索カーソルで指しているメッセージになります。

排他状態のメッセージは，次のMQGET命令で取り出せます。そのMQGET命令では，同じHobjハンドルを使用して，MQGMO_MSG_UNDER_CURSORオプション，またはそのほかの取り出し用オプションを指定します。

アプリケーションがメッセージを取り出さない場合は，次のようにして排他状態を解除します。

• 該当するハンドルを使用して，MQGMO_BROWSE_FIRSTまたはMQGMO_BROWSE_NEXTオプションで，MQGET命令を実行します。このとき，MQGMO_LOCKオプションは，指定しても指定しなくてもかまいません。完了コードMQCC_OKまたはMQCC_WARNINGで命令が終了した場合，メッセージの排他状態は解除されます。MQCC_FAILEDで完了した場合は，排他状態は解除されません。ただし，次の例外があります。

  −　完了コードMQCC_WARNING，理由コードMQRC_TRUNCATED_MSG_FAILEDで終了した場合，メッセージの排他状態は解除されません。

  −　完了コードMQCC_FAILED，理由コードMQRC_NO_MSG_AVAILABLEで終了した場合，メッセージの排他状態は解除されます。

  同時にMQGMO_LOCKオプションを指定すると，ほかのメッセージが排他状態になります。MQGMO_LOCKオプションを指定しない場合は，命令終了後には，どんなメッセージも排他状態になりません。

  MQGMO_WAITオプションを指定した場合で，該当するメッセージが直後にないときは，待ち合わせが始まる前に，元のメッセージの排他状態が解除されます。このため，エラーは発生しません。

• 該当するハンドルを使用して，MQGMO_BROWSE_MSG_UNDER_CURSORオプションでMQGET命令を実行します。このとき，MQGMO_LOCKは指定しません。完了コードMQCC_OKまたはMQCC_WARNINGで命令が終了した場合，メッセージの排他状態は解除されます。MQCC_FAILEDで完了した場合は，メッセージの排他状態は解除されません。ただし，次の例外があります。

  −　完了コードMQCC_WARNING，理由コードMQRC_TRUNCATED_MSG_FAILEDで終了した場合，メッセージの排他状態は解除されません。

• 該当するハンドルを使用して，MQGMO_UNLOCKオプションでMQGET命令を実行します。

• 該当するハンドルを使用して，MQCLOSE命令を実行します。これは，アプリケーションの終了によってキューがクローズされる場合も含みます。

このオプションを指定するための，特別なオープンオプションは必要ありません。ただし，検索オプションを使用するためには，MQOO_BROWSEオプションが必要です。

次に示すオプションは，MQGMO_LOCKオプションと同時に指定できません。

• MQGMO_SYNCPOINT

• MQGMO_SYNCPOINT_IF_PERSISTENT

• MQGMO_UNLOCK

MQGMO_UNLOCK

メッセージの排他状態を解除します。

MQGMO_LOCKオプションを指定した以前のMQGET命令で排他状態にしたメッセージがある場合だけ，このオプションを指定できます。このハンドルで排他状態にしたメッセージがない場合，完了コードMQCC_WARNING，理由コードMQRC_NO_MSG_LOCKEDで命令は終了します。

MQGMO_UNLOCKオプションを指定した場合，MsgDesc引数，BufferLength引数，Buffer引数，およびDataLength引数は参照・変更されません。また，Buffer引数にメッセージは返されません。

オプションを省略して仮定された場合も含めて，MQGMO_UNLOCKオプションと同時に指定できるのは，MQGMO_NO_WAITオプションとMQGMO_NO_SYNCPOINTオプションだけです。そのほかのオプションと同時に指定すると不正になります。

このオプションを指定するための，特別なオープンオプションは必要ありません。ただし，メッセージを排他状態にする時点では，MQOO_BROWSEオプションが必要です。

メッセージデータオプション：

メッセージがキューから取り出されるときの処理に関連するオプションを次に示します。

MQGMO_ACCEPT_TRUNCATED_MSG

後部が切り捨てられたメッセージでも，取り出しを許容します。

メッセージを格納する十分なバッファ領域がなかった場合にこのオプションを指定していると，バッファ領域に格納できる部分のメッセージだけでも取り出しを許容します。このときMQGET命令は警告の完了コードを返して，次のように処理を完了します。

• メッセージの検索の場合は，検索カーソルは返されたメッセージの位置に進みます。

• メッセージの取り出しの場合は，返されたメッセージはキューから削除されます。

• そのほかにエラーが発生しなかった場合，理由コードMQRC_TRUNCATED_MSG_ACCEPTEDが返されます。

このオプションを指定しなかった場合も，バッファ領域分のメッセージが返されて警告の完了コードが返されますが，処理は完了しません。この場合は，次のように処理されます。

• メッセージの検索の場合は，検索カーソルは進みません。

• メッセージの取り出しの場合は，メッセージはキューから削除されません。

• そのほかにエラーが発生しなかった場合，理由コードMQRC_TRUNCATED_MSG_FAILEDが返されます。

MQGMO_CONVERT

メッセージデータを変換します。

このオプションは，メッセージ内のアプリケーションデータが，Buffer引数にコピーされる前に，MQGET命令のMsgDesc引数で指定されるCodedCharSetIdフィールドおよびEncodingフィールドの値に従って変換されることを要求します。

メッセージが登録されるときに指定されるFormatフィールドは，変換プロセスによってメッセージ内のデータ構造を記述しているとみなされます。メッセージデータは，組み込みフォーマットに関しては，キューマネジャで変換されます。

変換が成功した場合，MsgDesc引数に指定されたCodedCharSetIdフィールドおよびEncodingフィールドは変更されません。すべての関連するデータタイプに関して変換できない場合は，MQGET命令は失敗しないで完了しますが，メッセージデータのフィールドは変換されません。この場合は，MsgDesc引数に指定されたCodedCharSetIdフィールドおよびEncodingフィールドには，未変換のメッセージの値が設定されます。

したがって，どちらの場合でも，これらのフィールドはBuffer引数に設定されたメッセージデータの文字セット識別子およびマシンコード形式を表しています。

キューマネジャが変換するフォーマット名のリストの詳細は，この章の「MQMD構造体　−　メッセージ記述子」でFormatフィールドの説明を参照してください。

コード変換対象となっている文字セット識別子については，「付録G　コード変換対象の文字セット識別子一覧」を参照してください。

グループとセグメントに関するオプション：

グループ内のメッセージおよび論理メッセージのセグメントの処理に関連するオプションを次に示します。オプションを理解するために，次の用語について説明します。

物理メッセージ

キューに登録したり取り出したりすることのできる最も小さい情報単位です。通常，単一のMQPUT命令，MQPUT1命令，またはMQGET命令で指定したり取り出したりする情報に該当します。

それぞれの物理メッセージは，メッセージ記述子（MQMD構造体）を持っています。

キューマネジャによって定義されているわけではありませんが，一般的に，物理メッセージはメッセージ記述子（MQMD構造体のMsgIdフィールド）の値で区別されます。

論理メッセージ

アプリケーション情報の一単位です。システムの強制がない場合，論理メッセージは物理メッセージと同じである場合があります。ただし，論理メッセージが極端に大きい場合，論理メッセージを二つまたはそれ以上のセグメントと呼ばれる物理メッセージに分割することをお勧めします。また，分割が必要となる場合もあります。

セグメント分割された論理メッセージは，同一のヌルではないグループ記述子（MQMD構造体のGroupIdフィールド）と同一のメッセージシーケンス番号（MQMD構造体のMsgSeqNumberフィールド）を持つ二つ以上の物理メッセージによって構成されます。セグメントはセグメントオフセット（MQMD構造体のOffsetフィールド）の値で区別されます。セグメントオフセットは，論理メッセージのデータ先頭からの，物理メッセージのデータの位置を表します。それぞれのセグメントは物理メッセージであるため，論理メッセージのセグメントは，通常，異なるメッセージ記述子を持ちます。

セグメント分割はされていないメッセージのうち，送信アプリケーションによってセグメント分割が許可されている論理メッセージも，ヌルではないグループ記述子を持ちます。この場合，論理メッセージがメッセージグループに属していないときは，そのグループ記述子を持つ物理メッセージはただ一つしか存在しないことになります。送信アプリケーションによってセグメント分割が禁止されている論理メッセージがメッセージグループに属していない場合は，ヌルのグループ記述子（MQGI_NONE）を持っています。

メッセージグループ

ヌルではない同一のグループ記述子を持つ一つ以上の物理メッセージの集まりです。

グループ内の論理メッセージは，メッセージシーケンス番号の値で区別されます。メッセージシーケンス番号は，1からNの整数範囲となります。なお，Nはグループ内の論理メッセージの数を表します。一つ以上の論理メッセージがセグメント分割されている場合，グループ内にはN個以上の物理メッセージが存在します。

次に，メッセージが，MQGET命令で返却される方法を制御する個々のオプションについて説明します。

MQGMO_LOGICAL_ORDER

グループ内のメッセージや論理メッセージのセグメントを論理的な順序で返します。

キューハンドルに対し，成功したMQGET命令によって返されるメッセージの順序を制御します。このオプションは，おのおのの命令に指定した場合に有効となります。

キューハンドルに対するMQGET命令が成功した場合，MQGMO_LOGICAL_ORDERが指定されていると，グループ内のメッセージはメッセージシーケンス番号の順序で返されます。また，論理メッセージのセグメントは，セグメントオフセットの順序で返されます。この順序は，メッセージとセグメントのキュー内での位置には関係ありません。

キューマネジャは要求された順序でメッセージを返すために，成功したMQGET命令間でのグループとセグメントの情報を保持しています。この情報で，キューハンドルに対する現在のメッセージグループと現在の論理メッセージとその位置，およびメッセージが同期点で取り出されているかどうかを識別します。キューマネジャがこの情報を保持しているため，アプリケーションはそれぞれのMQGET命令に先立って，グループとセグメントの情報を指定する必要はありません。つまり，アプリケーションはMQMD構造体のGroupIdフィールドやMsgSeqNumberフィールド，およびOffsetフィールドを指定する必要はありません。ただし，アプリケーションはそれぞれの命令でMQGMO_SYNCPOINTまたはMQGMO_NO_SYNCPOINTオプションを正しく指定しなければなりません。

キューのオープン時，現在のメッセージグループおよび現在の論理メッセージは存在しません。

MQMF_MSG_IN_GROUPフラグが設定されたメッセージがMQGET命令で返された場合は，そのメッセージグループが現在のメッセージグループとなります。成功したMQGET命令で指定されたMQGMO_LOGICAL_ORDERによって次に示すどちらかのメッセージが返されるまで，そのグループが現在のグループとなります。

• MQMF_SEGMENTなしのMQMF_LAST_MSG_IN_GROUP

  （グループ内のセグメント分割されていない最終論理メッセージ）

• MQMF_LAST_SEGMENTありのMQMF_LAST_MSG_IN_GROUP

  （グループ内の最終論理メッセージの最終セグメント）

上記のメッセージが返されると，メッセージグループは終了し，MQGET命令の成功で現在のグループは存在しなくなります。同様に，論理メッセージは，MQGET命令でMQMF_SEGMENTフラグが設定されたメッセージが返されたときに現在の論理メッセージとなります。MQMF_LAST_SEGMENTフラグを持つメッセージが返されると，現在の論理メッセージは終了します。

何も選択されない場合，成功したMQGET命令は，キューの最初にあるメッセージグループのメッセージ，2番目にあるメッセージグループのメッセージの順に，有効なメッセージがなくなるまで正しい順序で返します。このとき，MatchOptionsフィールドに，次に示すオプションを一つ以上指定することで，特定のメッセージグループを選択できます。

• MQMO_MATCH_MSG_ID

• MQMO_MATCH_CORREL_ID

• MQMO_MATCH_GROUP_ID

ただし，これらのオプションは，現在のメッセージグループまたは現在の論理メッセージが存在しないときだけ有効となります。詳細については，「MatchOptionsフィールド」を参照してください。

MQGET命令が返すメッセージの検索時に，キューマネジャが参照するMsgIdフィールド，CorrelIdフィールド，GroupIdフィールド，MsgSeqNumberフィールド，およびOffsetフィールドの値を次の表に示します。この値は，キューからメッセージを取り出すときと，キューのメッセージを参照するときの両方に適用されます。

指定した オプション	命令に先行するグループ と論理メッセージの状態		キューマネジャが検索する値
MQGMO_ LOGICAL_ ORDER	命令に先行する現在のメッセージグループ がある	命令に先行する現在の論理メッセージがある	Msg Idフィールド	Correl Idフィールド	Group Idフィールド	MsgSeq Numberフィールド	Offsetフィールド
○	×	×	Match Optionsで制御される	Match Optionsで制御される	Match Optionsで制御される	1	0
○	×	○	メッセージ識別子	相関識別子	グループ識別子※	1	先行するオフセット値とセグメント長の和
○	○	×	メッセージ識別子	相関識別子	グループ識別子※	シーケンス番号＋1※	0
○	○	○	メッセージ識別子	相関識別子	グループ識別子※	シーケンス番号※	先行するオフセット値とセグメント長の和
×	−	−	Match Optionsで制御される	Match Optionsで制御される	Match Optionsで制御される	Match Optionsで制御される	Match Optionsで制御される

（凡例）

○：該当します。

×：該当しません。

−：有無に関係ありません。

注※

キューハンドルに対する前の命令で返された値です。

複数のメッセージグループがキューに存在する場合，各グループの最初の論理メッセージの先頭セグメントがキュー内のどこに位置するかによって，メッセージの返される順序が決まります。つまり，メッセージシーケンス番号が1でオフセットが0である物理メッセージによって，メッセージが返されるときの順序が決まります。

MQGMO_LOGICAL_ORDERオプションは次に示すように，同期点に影響を及ぼします。

• グループの最初の論理メッセージまたはセグメントがトランザクション内で取り出された場合で，同じキューハンドルを使うときは，そのグループにあるほかのすべての論理メッセージとセグメントが，トランザクション内で取り出されなければなりません。しかし，それらのメッセージが同じトランザクション内で取り出される必要はありません。これによって，多くの物理メッセージで構成されるメッセージグループは，そのキューハンドルで二つ以上の連続したトランザクションに分割できます。

• グループの最初の論理メッセージまたはセグメントがトランザクション内で取り出されなかった場合で，同じキューハンドルを使うときは，そのグループのほかの論理メッセージとセグメントは，トランザクション内で取り出せません。

これらの条件が満たされなかった場合，MQGET命令は理由コードMQRC_INCONSISTENT_UOWで失敗となります。MQGMO_LOGICAL_ORDERが指定されたとき，MQGET命令で指定されたMQGMO構造体は，MQGMO_VERSION_2より前のバージョンではいけません。また，MQMD構造体はMQMD_VERSION_2より前のバージョンではいけません。この条件が満たされない場合，理由コードMQRC_WRONG_GMO_VERSIONまたはMQRC_WRONG_MD_VERSIONで失敗となります。

キューハンドルでMQGET命令にMQGMO_LOGICAL_ORDERが指定されない場合，メッセージはメッセージグループまたは論理メッセージのセグメントに属しているかどうかに関係なく返されます。これは，特定のグループまたは論理メッセージから，メッセージまたはセグメントが順序に従わないで返されることを示します。または，メッセージやセグメントが，ほかのグループや論理メッセージからのメッセージ，セグメント，およびグループに属していないセグメントのメッセージと混在していることを示しています。この場合，MQGET命令で返される特定のメッセージは，それぞれの命令で指定されるMQMO_*オプションで制御されます。詳細については，「MatchOptionsフィールド」を参照してください。

システムに障害が起きた場合は，次に示す方法でメッセージグループや論理メッセージを途中から再開できます。システム再開時，アプリケーションはGroupIdフィールド，MsgSeqNumberフィールド，Offsetフィールド，およびMatchOptionsフィールドに適当な値を設定します。その後，MQGMO_SYNCPOINTまたはMQGMO_NO_SYNCPOINTに適当な値を設定します。これによって，MQGMO_LOGICAL_ORDERを指定しないでMQGET命令を発行できるようになります。このMQGET命令が成功したとき，キューマネジャはグループとセグメントの情報を保持できます。したがって，そのキューハンドルを使用した次のMQGET命令では，通常のMQGMO_LOGICAL_ORDERを指定できます。

キューマネジャがMQGET命令用に保持しているグループとセグメントの情報は，MQPUT命令用に保持しているグループとセグメントの情報とは別です。さらに，キューマネジャは，次に示す命令について別の情報を保持しています。

• キューからメッセージを取り出すMQGET命令

• キューのメッセージを参照するMQGET命令

どのキューハンドルについても，アプリケーションはMQGMO_LOGICAL_ORDERを指定したMQGET命令と，指定しないMQGET命令を混在させてもかまいません。ただし，次の点に注意してください。

• MQGMO_LOGICAL_ORDERを指定していない場合，MQGET命令が成功するたびに，キューマネジャは返されたメッセージに対応する値を，保持しているグループおよびセグメント情報に設定します。その情報で，キューハンドルに対してキューマネジャが保持していたグループとセグメントの情報を置き換えます。そのとき，参照または取り出し命令の動作に必要な情報だけが変更されます。

• MQGMO_LOGICAL_ORDERが指定されない場合，現在のメッセージグループまたは論理メッセージが存在するとき，その命令は失敗しません。命令は完了コードMQCC_WARNINGで成功します。

  グループおよびセグメントの情報と一致しないMQGET命令およびMQCLOSE命令の結果を次の表に示します。

  実行時の命令	直前の命令がMQGMO_LOGICAL_ORDER指定ありのMQGET命令	直前の命令がMQGMO_LOGICAL_ORDER指定なしのMQGET命令
  MQGMO_LOGICAL_ORDER指定ありのMQGET命令	MQCC_FAILED	MQCC_FAILED
  MQGMO_LOGICAL_ORDER指定なしのMQGET命令	MQCC_WARNING	MQCC_OK
  非永続グループ，または論理メッセージのあるMQCLOSE命令	MQCC_WARNING	MQCC_OK

  上記の表の場合で，完了コードがMQCC_OK以外のとき，理由コードは次のどれかになります。

  MQRC_INCOMPLETE_GROUP

  MQRC_INCOMPLETE_MSG

  MQRC_INCONSISTENT_UOW

  注意事項

  キューマネジャは，参照するためにオープンされていますが，入力用にオープンされていないキューを参照したり，クローズしたりした場合には，グループとセグメントの情報をチェックしません。この場合，完了コードは常にMQCC_OK（ほかのエラーがない場合）となります。

論理的な順序でメッセージとセグメントを取り出したいアプリケーションでは，MQGMO_LOGICAL_ORDERを指定することをお勧めします。このオプションを指定すると，キューマネジャがグループとセグメントの情報を管理するため，アプリケーションではキューマネジャとセグメントの情報を管理する必要がありません。しかし，アプリケーションによっては，MQGMO_LOGICAL_ORDERオプションが提供する機能より高い制御機能を必要とする場合があります。その場合，MQGMO_LOGICAL_ORDERオプションを指定しないでください。MQGMO_LOGICAL_ORDERを指定しなかったとき，アプリケーションは，MQGET命令に先立って，MQMD構造体のMsgIdフィールド，CorrelIdフィールド，GroupIdフィールド，MsgSeqNumberフィールド，Offsetフィールド，およびMQGMO構造体のMatchOptionsフィールドのMQMO_*オプションを正しく指定しなければなりません。

例えば，受信した物理メッセージがグループまたは論理メッセージのセグメントに属する場合でも，転送するアプリケーションにMQGMO_LOGICAL_ORDERを指定しないでください。送信側と受信側のキューマネジャ間に複数の通信路がある複雑なネットワークの場合，MQGMO_LOGICAL_ORDERを指定すると，物理メッセージが順序どおりに到着しません。

MQGMO_LOGICAL_ORDERおよびMQPUT命令で対応するMQPMO_LOGICAL_ORDERを指定しない場合は，各メッセージが到着すると，転送するアプリケーションは次の論理的な順序のメッセージを待たないで，そのメッセージを取り出したり転送したりできます。

MQGMO_LOGICAL_ORDERは，ほかのMQGMO_*オプションのどれとも同時に指定できます。また，上記に示したような適当な環境では，MQMO_*オプションの組み合わせとともに指定できます。

MQGMO_COMPLETE_MSG

完全な論理メッセージだけ取り出します。

このオプションは，MQGET命令で完全な論理メッセージだけ返すことを指定します。論理メッセージがセグメント分割されている場合，キューマネジャはセグメントを組み立てて，アプリケーションに完全な論理メッセージを返します。なお，論理メッセージがセグメント分割されていても，取り出すアプリケーションからは見えません。

注意事項

このオプションは，キューマネジャにメッセージセグメントを組み立てさせるためだけのオプションです。指定されなかった場合，セグメントがキューに存在していて，MQGET命令で指定されたほかの条件を満たすときには，セグメントごとにアプリケーションに返されます。したがって，個々にセグメントを受信しないアプリケーションでは，常にMQGMO_COMPLETE_MSGを指定してください。

MQGMO_COMPLETE_MSGを使用する場合，アプリケーションは完全なメッセージを格納するのに十分なバッファを用意するか，MQGMO_ACCEPT_TRUNCATED_MSGオプションを指定する必要があります。

ネットワークの遅延などによってキューにセグメントはなく，かつセグメント分割されたメッセージがある場合，MQGMO_COMPLETE_MSGを指定すると，不完全な論理メッセージに属するセグメントは取り出されません。ただし，そのメッセージセグメントは，CurrentQDepthキュー属性の値と関係があります。つまり，CurrentQDepth属性の値が0より大きくても，取り出せる論理メッセージが存在しない場合があります。

キューマネジャはトランザクション内でだけセグメントを組み立てることができます。例えば，MQGET命令がユーザの定義したトランザクション内で発行された場合，そのトランザクションが使用されます。命令が組み立てる途中で部分的に失敗した場合，キューマネジャは組み立て中に取り出されたセグメントをキューに戻します。その失敗によって，トランザクションのコミットの成功が妨げられることはありません。

セグメントであるそれぞれの物理メッセージは，それ自身のメッセージ記述子を持っています。一つの論理メッセージを構成するセグメントについては，メッセージ記述子のほとんどのフィールドが，論理メッセージ内のすべてのセグメントで同じになります。通常，論理メッセージ内のセグメント間で異なるのは，MsgIdフィールド，Offsetフィールド，およびMsgFlagsフィールドだけです。しかし，セグメントがネットワークの異なる通信路を通り，そのうちの幾つかの通信路でMCA送信変換ができる場合，セグメントが最終的にあて先キューに到着したとき，セグメント間でCodedCharSetIdフィールドとEncodingフィールドが異なる場合があります。CodedCharSetIdフィールドまたはEncodingフィールドが異なるセグメントで構成されている論理メッセージは，キューマネジャで一つの論理メッセージとして組み立てることはできません。その代わり，キューマネジャは，論理メッセージの最初から同じ文字セット識別子とマシンコード形式を持つ連続した一部のセグメントを返し，MQGET命令はMQCC_WARNINGの完了コードとMQRC_INCONSISTENT_CCSIDS，またはMQRC_INCONSISTENT_ENCODINGSの理由コードで完了します。これは，MQGMO_CONVERTの指定には関係ありません。残りのセグメントを取り出すために，アプリケーションはMQGMO_COMPLETE_MSGオプションを指定しないでMQGET命令を再発行し，一つ一つセグメントを取り出さなければなりません。このとき，MQGMO_LOGICAL_ORDERは残ったセグメントを順番に取り出すために使用できます。

セグメントを登録するアプリケーションは，メッセージ記述子のほかのフィールドに，セグメント間で異なる値を設定することもできます。しかし，受信するアプリケーションがMQGMO_COMPLETE_MSGを使用して論理メッセージを取り出す場合は意味がありません。キューマネジャが論理メッセージを組み立てるとき，メッセージ記述子の値に最初のセグメントの値を返します。唯一の例外はMsgFlagsフィールドです。キューマネジャは，組み立てられたメッセージがただ一つのセグメントであることを示す値を設定します。

報告メッセージにMQGMO_COMPLETE_MSGが指定されると，キューマネジャは次に示す特別な処理をします。

キューマネジャは，論理メッセージ内の異なるセグメントに関する報告形式の報告メッセージが，キューにすべて存在するかチェックします。存在する場合，MQGMO_COMPLETE_MSGを指定すると，それらは1メッセージとして取り出されます。この処理を可能にするために，報告メッセージはセグメント分割をサポートするキューマネジャまたはMCAによって生成されなければなりません。または，報告を要求したアプリケーションが少なくとも100バイトのメッセージデータを要求しなければなりません。つまり，MQRO_*_WITH_DATAオプションまたはMQRO_*_WITH_FULL_DATAオプションが指定されなければなりません。セグメントのデータがアプリケーションデータのすべてより小さい場合，失われたバイトは報告メッセージでヌルに置き換えられて返されます。

MQGMO_COMPLETE_MSGがMQGMO_MSG_UNDER_CURSORまたはMQGMO_BROWSE_MSG_UNDER_CURSORとともに指定された場合，参照カーソルはMQMD構造体のOffsetフィールドの値が0のメッセージに位置していなければなりません。この条件が満たされない場合，理由コードMQRC_INVALID_MSG_UNDER_CURSORで失敗します。

MQGMO_COMPLETE_MSGはMQGMO_ALL_SEGMENTS_AVAILABLEと同じ機能です。したがって，MQGMO_ALL_SEGMENTS_AVAILABLEを指定する必要はありません。

なお，MQGMO_COMPLETE_MSGは，MQGMO_SYNCPOINT_IF_PERSISTENT以外のMQGMO_*オプションおよびMQMO_MATCH_OFFSET以外のMQMO_*オプションと組み合わせて指定できます。

MQGMO_ALL_MSGS_AVAILABLE

グループのすべてのメッセージが有効である場合に取り出すことを指定します。

グループ内のメッセージは，すべてのメッセージが有効な場合だけ取り出し可能になります。ネットワークの遅延などによってキューに幾つかのメッセージが抜けているグループがある場合，MQGMO_ALL_MSGS_AVAILABLEを指定すると，不完全なグループに属するメッセージを取り出すことを抑止できます。ただし，そのメッセージはCurrentQDepthキュー属性の値と関係があります。つまり，CurrentQDepth属性の値が0より大きくても，取り出せるメッセージグループが存在しない場合があります。取り出せるメッセージがない場合，待ち時間が指定されていると，待ち時間が経過したあとでMQRC_NO_MSG_AVAILABLEの理由コードが返されます。

MQGMO_ALL_MSGS_AVAILABLEが有効となるかどうかは，MQGMO_LOGICAL_ORDERが指定されているかどうかによって，次に示すように決まります。

• MQGMO_ALL_MSGS_AVAILABLEとMQGMO_LOGICAL_ORDERが両方とも指定された場合，MQGMO_ALL_MSGS_AVAILABLEは現在のグループまたは現在の論理メッセージがないときだけ有効となります。現在のグループまたは現在の論理メッセージがある場合，MQGMO_ALL_MSGS_AVAILABLEは無視されます。したがって，MQGMO_ALL_MSGS_AVAILABLEは，論理メッセージのメッセージを処理するときに無効となります。

• MQGMO_LOGICAL_ORDERなしでMQGMO_ALL_MSGS_AVAILABLEが指定された場合，MQGMO_ALL_MSGS_AVAILABLEは常に有効となります。したがって，グループの最初のメッセージがキューから取り出されたあと，そのグループの残りのメッセージを削除するためには，オプションの指定を外さなければなりません。

MQGMO_ALL_MSGS_AVAILABLEを指定するMQGET命令が正常に完了した場合，MQGET命令が発行された時点でグループ内のすべてのメッセージがキュー上にあることになります。しかし，ほかのアプリケーションがグループからメッセージを除去できることに注意してください。グループは，グループ内の最初のメッセージを検索するアプリケーションにロックされていません。

MQGMO_ALL_MSGS_AVAILABLEが指定されない場合，グループに属するメッセージはグループが不完全なときも取り出すことができます。

MQGMO_ALL_MSGS_AVAILABLEはMQGMO_ALL_SEGMENTS_AVAILABLEと同じ機能です。したがって，MQGMO_ALL_SEGMENTS_AVAILABLEを指定する必要はありません。

MQGMO_ALL_MSGS_AVAILABLEはMQGMO構造体のほかのオプション，またはMQMO構造体のオプションのどのオプションとも同時に指定できます。

MQGMO_ALL_SEGMENTS_AVAILABLE

論理メッセージのすべてのセグメントが有効である場合に取り出すことを指定します。

論理メッセージ内のセグメントは，論理メッセージ内のすべてのセグメントが有効にならなければ取り出せません。ネットワークの遅延などによってキューに幾つかのセグメントが抜けている論理メッセージがある場合，MQGMO_ALL_SEGMENTS_AVAILABLEを指定すると，不完全な論理メッセージに属するセグメントを取り出すことを抑止できます。ただし，そのセグメントはCurrentQDepthキュー属性の値と関係があります。つまり，CurrentQDepth属性の値が0より大きくても，取り出せるメッセージが存在しない場合があります。取り出せるメッセージがない場合，待ち時間が指定されていると，その待ち時間が経過したあとでMQRC_NO_MSG_AVAILABLEの理由コードが返されます。

MQGMO_ALL_SEGMENTS_AVAILABLEが有効であるかどうかは，MQGMO_LOGICAL_ORDERが指定されているかどうかによって次に示すように決まります。

• MQGMO_ALL_SEGMENTS_AVAILABLEとMQGMO_LOGICAL_ORDERが両方とも指定された場合，MQGMO_ALL_SEGMENTS_AVAILABLEは現在の論理メッセージがないときだけ有効となります。現在の論理メッセージがある場合，MQGMO_ALL_SEGMENTS_AVAILABLEは無視されます。したがって，MQGMO_ALL_SEGMENTS_AVAILABLEは，論理メッセージのメッセージを処理するときに無効となります。

• MQGMO_LOGICAL_ORDERなしでMQGMO_ALL_SEGMENTS_AVAILABLEが指定された場合，MQGMO_ALL_SEGMENTS_AVAILABLEは常に有効となります。したがって，論理メッセージの最初のセグメントがキューから取り出されたあと，その論理メッセージの残りのセグメントを削除するためには，オプションの指定を外さなければなりません。

MQGMO_ALL_SEGMENTS_AVAILABLEが指定されない場合，論理メッセージに属するセグメントは，論理メッセージが不完全なときも取り出すことができます。

MQGMO_COMPLETE_MSGとMQGMO_ALL_SEGMENTS_AVAILABLEはすべてのセグメントが有効になるまで，セグメントの取り出しを禁止します。MQGMO_COMPLETE_MSGは完全なメッセージを返します。MQGMO_ALL_SEGMENTS_AVAILABLEは，セグメントを一つ一つ取り出せるようにします。

MQGMO_ALL_SEGMENTS_AVAILABLEが報告メッセージに指定された場合，キューマネジャは次の特別な処理をします。

キューマネジャは，完全な論理メッセージを構成する各セグメントに対して，報告メッセージが少なくとも一つ存在するかどうか，キューをチェックします。報告メッセージが存在する場合は，MQGMO_ALL_SEGMENTS_AVAILABLEの条件が満たされています。

ただし，キューマネジャは報告メッセージの形式まではチェックしないので，論理メッセージのセグメントに関連するさまざまな報告メッセージの形式が混在している可能性があります。つまり，MQGMO_ALL_SEGMENTS_AVAILABLEが成功しても，MQGMO_COMPLETE_MSGが成功するとは限りません。特別な論理メッセージのセグメントに対する報告形式が混在している場合，その報告メッセージは一つ一つ取り出されなければなりません。

MQGMO_ALL_SEGMENTS_AVAILABLEは，ほかのMQGMO_*オプション，またはMQMO_*オプションと同時に指定できます。

デフォルトオプション：

ここまでで説明されたオプションを指定しない場合，次に示すオプションを使用できます。

MQGMO_NONE

オプションを指定しません。

このオプションは，ほかにオプションを指定しない場合に指定します。このほかのオプションには，どれも省略時の仮定値があります。MQGMO_NONEオプションは，プログラムのコーディングをわかりやすくするために定義されています。値としては0が定義されていますが，コーディングをわかりやすくする以外の目的はありません。

このフィールドの初期値はMQGMO_NO_WAITです。

●　Reserved1（MQCHAR型）　予備

これは予備のフィールドです。このフィールドの初期値は空白です。

このフィールドは，Versionフィールドの値がMQGMO_VERSION_2以降の場合だけ有効です。

●　ResolvedQName（MQCHAR48型）　受信キュー名

キューマネジャによって設定される出力用のフィールドです。メッセージを取り出したキューの名称が返されます。返される名称はローカルキューマネジャに定義された名称です。

次に示す場合はオープン時に指定したキューの名称とは異なる名称が返されます。

• 別名キューをオープンした場合は，別名キューのベースキューの名称が返されます。

• モデルキューをオープンした場合は，動的ローカルキューの名称が返されます。

このフィールドの長さは，MQ_Q_NAME_LENGTHに定義されています。

このフィールドの初期値は，C言語ではヌル文字列です。そのほかのプログラミング言語では，48個の空白です。

●　Segmentation（MQCHAR型）　セグメント分割フラグ

取り出されたメッセージがセグメント分割できるかどうかを示すフラグです。

次の値を取ります。

MQSEG_INHIBITED

セグメント分割は許可されていません。

MQSEG_ALLOWED

セグメント分割が許可されています。

これは出力用のフィールドです。

このフィールドの初期値はMQSEG_INHIBITEDです。

このフィールドは，Versionフィールドの値がMQGMO_VERSION_2以降の場合だけ有効です。

●　SegmentStatus（MQCHAR型）　論理メッセージフラグ

取り出されたメッセージが，論理メッセージグループのセグメントかどうかを示すフラグです。

次の値を取ります。

MQSS_NOT_A_SEGMENT

メッセージはセグメントではありません。

MQSS_SEGMENT

メッセージはセグメントですが，論理メッセージの最終セグメントではありません。

MQSS_LAST_SEGMENT

メッセージは論理メッセージの最終セグメントです。

これは，論理メッセージがただ一つのセグメントで構成されている場合にも返される値です。

これは出力用のフィールドです。

このフィールドの初期値はMQSS_NOT_A_SEGMENTです。

このフィールドは，Versionフィールドの値がMQGMO_VERSION_2以降の場合だけ有効です。

●　Signal1（MQLONG型）　シグナル

TP1/Message Queueでは，このフィールドは使用されません。

このフィールドの初期値は0です。

●　Signal2（MQLONG型）　予備

予備のフィールドです。キューマネジャはこの内容を特に使用しません。

このフィールドの初期値は0です。

●　StrucId（MQCHAR4型）　構造体識別子

次の値を取ります。

MQGMO_STRUC_ID

メッセージ取り出しオプションの構造体識別子

C言語では，MQGMO_STRUC_ID_ARRAYも定義されています。これは，MQGMO_STRUC_IDと同じ値です。ただし，文字列ではなく文字の配列として定義されています。

これは入力用のフィールドです。

このフィールドの初期値はMQGMO_STRUC_IDです。

●　Version（MQLONG型）　構造体バージョン番号

次に示す値を取ります。

MQGMO_VERSION_1

バージョン1のメッセージ取り出しオプションの構造体バージョン番号

MQGMO_VERSION_2

バージョン2のメッセージ取り出しオプションの構造体バージョン番号

MQGMO_VERSION_2以降の構造体にだけ存在するフィールドについては，そのことがフィールドの説明に記載されています。次に示す定数は，現在のバージョン番号を指定します。

MQGMO_CURRENT_VERSION

メッセージ取り出しオプションの現在の構造体バージョン番号

これは入力用のフィールドです。

このフィールドの初期値はMQGMO_VERSION_1です。

●　WaitInterval（MQLONG型）　待ち合わせ最大時間

MQGET命令が該当するメッセージの到着を待つ最大時間を，ミリ秒単位で指定します。該当するメッセージとは，MQGET命令のMsgDesc引数に指定した選択規準を満たすものです。詳細は，この章の「MQMD構造体　−　メッセージ記述子」でMsgIdフィールドの説明を参照してください。この時間が経過しても該当するメッセージが到着しなかった場合，完了コードMQCC_FAILED，理由コードMQRC_NO_MSG_AVAILABLEで命令は終了します。

このフィールドは，MQGMO_WAITオプションと組み合わせて使用します。MQGMO_WAITオプションを指定しなかった場合，このフィールドは無視されます。指定した場合は，WaitIntervalフィールドには0以上を指定してください。また，次の定数値も指定できます。

MQWI_UNLIMITED

無制限に待ち合わせをします。無制限に待ち合わせ中に，アプリケーションまたはOpenTP1が終了した場合，MQGET命令はMQRC_Q_MGR_STOPPINGの理由コードで完了します。

このフィールドの初期値は0です。TP1/Message Queueでは待ち合わせ最大時間の精度をMQAサービス定義のmqa_getwait_timeoutオペランドで指定できます。指定を省略した場合，秒単位の精度で待ち合わせます。