MatchOptions (MQLONG)
MsgDesc パラメーター内のどのフィールドを使用するかをアプリケーションで決めることができます。 アプリケーションは、このフィールドに必要なオプションを設定してから、MsgDescパラメーター内の対応するフィールドを、それらのフィールドに必要な値に設定します。 MQMD にこれらの値が入っているメッセージのみが、MQGET 呼び出しでMsgDescパラメーターを使用した場合の検索の候補になります。 戻すメッセージの選択時には、対応した一致オプションが指定されていない フィールドは無視されます。 MQGET 呼び出しで選択基準を指定しない (つまり、どの メッセージも受け入れ可能にする) 場合は、MatchOptions を MQMO_NONE に設定します。- z/OS®では、使用できる選択基準は、キューに使用される索引のタイプによって制限される場合があります。 詳細は、
IndexTypeキュー属性を参照してください。
- 現行のグループまたは論理メッセージがない場合は、
MsgSeqNumberが1に等しく、Offsetが0に等しいメッセージのみが戻されます。 この場合には、以下の一致オプションを 1 つ以上使用することにより、戻されるメッセージのうちのどれが戻されるかを選定できます。- 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 は無視されます。
メッセージ・プロパティーに基づくメッセージの取得は、マッチング・オプションを使用して行われません。詳しくは、 SelectionString (MQCHARV)を参照してください。
- MQMO_MATCH_MSG_ID
- 検索するメッセージのメッセージ ID は、MQGET 呼び出しの
MsgDescパラメーターのMsgIdフィールドの値と一致している必要があります。 これは、適用される他の一致 (例えば、相関 ID) に加えて一致している必要があります。このオプションを省略すると、
MsgDescパラメーター内のMsgIdフィールドは無視され、すべてのメッセージ ID が一致することになります。注: メッセージ ID MQMI_NONE は、メッセージの MQMD 内の すべての メッセージ ID と一致する特殊値です。 したがって、MQMO_MATCH_MSG_ID を MQMI_NONE と組み合わせて指定しても、MQMO_MATCH_MSG_ID を指定しなくても 同じことです。 - MQMO_MATCH_CORREL_ID
- 検索するメッセージの相関 ID は、MQGET 呼び出しの
MsgDescパラメーターのCorrelIdフィールドの値と一致している必要があります。 これは、適用される他の一致 (例えば、メッセージ ID) に加えて一致している必要があります。このオプションを省略すると、
MsgDescパラメーターのCorrelIdフィールドは無視され、すべての相関 ID が一致します。注: 相関 ID MQCI_NONE は、メッセージの MQMD 内の すべての 相関 ID と一致する特殊値です。 したがって、MQMO_MATCH_CORREL_ID を MQCI_NONE と組み合わせて指定しても、MQMO_MATCH_CORREL_ID を指定しなくても 同じことです。 - MQMO_MATCH_GROUP_ID
- 検索するメッセージのグループ ID は、MQGET 呼び出しの
MsgDescパラメーターのGroupIdフィールドの値と一致している必要があります。 これは、適用される他の一致 (例えば、相関 ID) に加えて一致している必要があります。このオプションを省略すると、
MsgDescパラメーターのGroupIdフィールドは無視され、すべてのグループ ID が一致します。注: グループ ID MQGI_NONE は、メッセージの MQMD 内の 任意の グループ ID と一致する特殊値です。 したがって、MQMO_MATCH_GROUP_ID を MQGI_NONE と組み合わせて指定しても、MQMO_MATCH_GROUP_ID を指定しなくても 同じことです。 - MQMO_MATCH_MSG_SEQ_NUMBER
- 取り出されるメッセージのメッセージ順序番号は MQGET 呼び出しの
MsgDescパラメーター内のMsgSeqNumberフィールドの値と一致する必要があります。 これは、適用される他の一致 (例えば、グループ ID) に加えて一致している必要があります。このオプションを省略すると、
MsgDescパラメーターのMsgSeqNumberフィールドは無視され、すべてのメッセージ・シーケンス番号が一致します。 - MQMO_MATCH_OFFSET
- 検索するメッセージのオフセットは、MQGET 呼び出しの
MsgDescパラメーターのOffsetフィールドの値と一致している必要があります。 これは、適用される他の一致 (例えば、メッセージ・シーケンス番号) に加えて一致している必要があります。このオプションの指定を省略すると、MsgDescパラメーター内のOffsetフィールドは無視され、すべてのオフセットが一致することになります。- このオプションは、z/OS ではサポートされていません。
- MQMO_MATCH_MSG_TOKEN
- 検索するメッセージのメッセージ・トークンは、MQGET 呼び出しで指定される MQGMO 構造の
MsgTokenフィールドの値と一致している必要があります。このオプションはすべてのローカル・キューで指定できます。
IndexTypeが MQIT_MSG_TOKEN のキュー (WLM 管理キュー) にこれを指定する場合、MQMO_MATCH_MSG_TOKEN と共に他の一致オプションを指定することができません。MQMO_MATCH_MSG_TOKEN は、MQGMO_WAIT や MQGMO_SET_SIGNAL と共に指定することはできません。 MQIT_MSG_TOKEN の
IndexTypeがあるキューにメッセージが到着するまでアプリケーションを待機させる場合は、MQMO_NONE を指定します。このオプションを省略すると、MQGMO の
MsgTokenフィールドは無視され、すべてのメッセージ・トークンが一致します。
- MQMO_NONE
- 戻されるメッセージを選択するときに一致条件を使用しません。
キューに入っているメッセージがすべて取り出せるようになります (ただし、MQGMO_ALL_MSGS_AVAILABLE、MQGMO_ALL_SEGMENTS_AVAILABLE、および MQGMO_COMPLETE_MSG オプションで制御できます)。
MQMO_NONE は、プログラム・ドキュメンテーションの援助機能です。 このオプションを他の MQMO_* オプションと一緒に使用することは意図されていませんが、値がゼロであるため、そのように使用しても、それを検出することはできません。
これは入力フィールドです。 このフィールドの初期値は、MQMO_MATCH_MSG_ID と MQMO_MATCH_CORREL_ID を組み合わせたものです。 Versionが MQGMO_VERSION_2 より小さい場合、このフィールドは無視されます。
MatchOptions フィールドの初期値は、以前の MQSeries® キュー・マネージャーとの互換性のために定義されています。 ただし、選択基準を使用せずにキューから一連のメッセージを読み取る場合、この初期値を使用するには、各 MQGET 呼び出しの前に、アプリケーションが MsgId および CorrelId フィールドを MQMI_NONE および MQCI_NONE にリセットする必要があります。 Version に MQGMO_VERSION_2 を、さらに MatchOptions に MQMO_NONE を設定しておけば、MsgId および CorrelId を各呼び出しごとに再設定しなくてもすみます。