MQGMO 的選項 (MQLONG)

如果禁止 MQGET 要求，或在等待時禁止 MQGET 要求，則會取消等待。 不論佇列上是否有適當的訊息，呼叫都會完成，並傳回 MQCC_FAILED 及原因碼 MQRC_GET_INHIBITED。

您可以將 MQGMO_WAIT 與 MQGMO_BROWSE_FIRST 或 MQGMO_BROWSE_NEXT 選項搭配使用。

如果數個應用程式在相同的共用佇列上等待，則下列規則會選取當適當的訊息到達時要啟動的應用程式:

1. 只有特定訊息 (例如，具有特定 MsgId 或 CorrelId (或兩者) 的訊息) 才能滿足的特定取得等待要求。
2. 可由任何訊息滿足的一般 get-wait 要求。

在 z/OS®上，適用下列要點:

• 如果您想要應用程式在等待訊息送達時繼續進行其他工作，請考慮改用信號選項 (MQGMO_SET_SIGNAL)。 不過，信號選項是環境特有的; 您在不同環境之間連接的應用程式不得使用它。
• 如果有多個 MQGET 呼叫正在等待相同訊息，並混合等待及信號選項，則會平均考慮每一個等待中的呼叫。 將 MQGMO_SET_SIGNAL 與 MQGMO_WAIT一起指定是錯誤的。 將此選項與信號未處理的佇列控點一起指定也是錯誤。
• 如果您針對 IndexType 為 MQIT_MSG_TOKEN的佇列指定 MQGMO_WAIT 或 MQGMO_SET_SIGNAL ，則不允許任何選取準則。 這表示：
  • 如果您使用 version-1 MQGMO，請在 MQGET 呼叫 MQMI_NONE 及 MQCI_NONE上指定的 MQMD 中設定 MsgId 及 CorrelId 欄位。
  • 如果您使用 version-2 或更新版本 MQGMO，請將 MatchOptions 欄位設為 MQMO_NONE。
• 對於共用佇列上的 MQGET 呼叫，且該呼叫是瀏覽要求或群組訊息的破壞性取得，且 MsgId 和 CorrelId 都不符合，則會在 200 毫秒之後公佈您的信號 ECB。

  當以 MQEC_WAIT_INTERVAL_EXPIRED 公佈佇列時，即使適當的訊息可能尚未到達佇列，也會發生此情況，直到等待間隔過期為止。 公佈 MQEC_MSG_RESIDE 時，您必須重新發出第二個 MQGET 呼叫來擷取訊息 (如果有的話)。

  此技術是用來確保及時通知您訊息到達，但在與非共用佇列上的類似呼叫序列相比較時，可能會顯示為非預期的處理額外負擔。

如果指定 MQGMO_BROWSE_MSG_UNDER_CURSOR 或 MQGMO_MSG_UNDER_CURSOR ，則會忽略 MQGMO_WAIT ; 不會引發任何錯誤。

如果目前沒有符合訊息描述子中所指定準則的訊息可用，則控制會回到應用程式，而不等待訊息送達。 CompCode 和 Reason 參數設為 MQCC_WARNING 和 MQRC_SIGNAL_REQUEST_ACCEPTED。 未設定訊息描述子中的其他輸出欄位以及 MQGET 呼叫的輸出參數。 當適當的訊息稍後到達時，會透過張貼歐洲央行來傳遞信號。

然後，呼叫者必須重新發出 MQGET 呼叫來擷取訊息。 應用程式可以使用作業系統提供的功能來等待此信號。

如果作業系統提供多重等待機制，您可以使用它來等待訊息到達數個佇列中的任何一個佇列。

如果指定非零 WaitInterval ，則會在等待間隔到期之後遞送信號。 佇列管理程式也可以取消等待，在此情況下會遞送信號。

多個 MQGET 呼叫可以為相同的訊息設定信號。 應用程式的啟動順序與 MQGMO_WAIT的說明相同。

如果多個 MQGET 呼叫正在等待相同的訊息，則會平均考慮每一個等待中的呼叫。 呼叫可以包含等待和信號選項的混合。

在特定條件下， MQGET 呼叫可以擷取訊息，並且可以遞送相同訊息到達所產生的信號。 當信號遞送時，應用程式必須準備好沒有可用的訊息。

佇列控點最多只能有一個信號要求未完成。

對於共用佇列上的 MQGET 呼叫，且該呼叫是瀏覽要求或群組訊息的破壞性取得，且 MsgId 或 CorrelId 都不符合，使用者的信號 ECB 會在 200 毫秒之後 MQEC_MSG_ARRIVED 公佈。

即使適當的訊息可能尚未到達佇列，在等待間隔到期之前，當佇列隨 MQEC_WAIT_INTERVAL_EXPIRED一起公佈時，仍會發生此情況。 當 MQEC_MSG_ARRIVED 公佈時，您必須重新發出第二個 MQGET 呼叫來擷取訊息 (如果有的話)。

此技術是用來確保及時通知您訊息到達，但在與非共用佇列上的類似呼叫序列相比較時，可能會顯示為非預期的處理額外負擔。

當不常新增訊息時，這不是有效的訊息擷取方法。 為了避免瀏覽案例的額外負擔，請在 MQGET 呼叫上指定符合的 MsgId (如果未檢索或依 MsgId檢索) 或 CorrelId (如果依 CorrelId檢索)。

僅在 z/OS 上支援此選項。

在 z/OS上，如果連線 (適用於 CICS® 或 IMS 應用程式) 處於靜止狀態，則此選項也會強制 MQGET 呼叫失敗。

由於這些差異，您想要埠的應用程式不得容許此選項預設; 請明確指定 MQGMO_SYNCPOINT 或 MQGMO_NO_SYNCPOINT 。

• 如果訊息持續存在，佇列管理程式會如同應用程式已指定 MQGMO_SYNCPOINT一樣處理呼叫。
• 如果訊息不是持續的，佇列管理程式會如同應用程式已指定 MQGMO_NO_SYNCPOINT一樣處理呼叫。

如果您指定 MQGMO_BROWSE_FIRST 或 MQGMO_BROWSE_NEXT，則會假設此選項。

由於這些差異，您要連接的應用程式不得容許此選項預設; 請明確指定 MQGMO_SYNCPOINT 或 MQGMO_NO_SYNCPOINT 。

具有 MQGMO_BROWSE_FIRST 的 MQGET 呼叫會忽略瀏覽游標的前一個位置。 會擷取佇列上滿足訊息描述子中所指定條件的第一個訊息。 訊息會保留在佇列上，而瀏覽游標會定位在此訊息上。

在此呼叫之後，瀏覽游標會定位在已傳回的訊息上。 在發出具有 MQGMO_BROWSE_NEXT 的下一個 MQGET 呼叫之前，可能會從佇列中移除該訊息。 在此情況下，瀏覽游標會保留在佇列中訊息所佔用的位置，即使該位置現在是空的。

搭配使用 MQGMO_MSG_UNDER_CURSOR 選項與非瀏覽 MQGET 呼叫，以從佇列中移除訊息。

即使使用相同的 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 呼叫保留兩組群組及區段資訊。 瀏覽呼叫的群組和區段資訊與從佇列中移除訊息之呼叫的資訊分開保留。 如果您指定 MQGMO_BROWSE_FIRST，佇列管理程式會忽略用於瀏覽的群組和區段資訊。 它會掃描佇列，就像沒有現行群組和現行邏輯訊息一樣。 如果 MQGET 呼叫成功，完成碼 MQCC_OK 或 MQCC_WARNING，則用於瀏覽的群組和區段資訊會設為所傳回訊息的群組和區段資訊。 如果呼叫失敗，則群組及區段資訊會保持與呼叫之前的相同。

瀏覽游標所指向的訊息是前次使用 MQGMO_BROWSE_FIRST 或 MQGMO_BROWSE_NEXT 選項擷取的訊息。

如果使用 MQGMO_MSG_UNDER_CURSOR指定 MQGMO_COMPLETE_MSG ，則瀏覽游標必須識別其 MQMD 中的 Offset 欄位為零的訊息。 如果未滿足此條件，則呼叫會失敗，原因碼為 MQRC_INVALID_MSG_UNDER_CURSOR。

訊息未從佇列中移除。

合作層次標記是除了任何可能已設定的控點層次標記之外的其他標記。

訊息未從佇列中移除。

如果已標示訊息，且未指定 MQGMO_UNMARKED_BROWSE_MSG 選項，則呼叫會失敗，並傳回 MQCC_FAILED 及原因碼 MQRC_MSG_MARKED_BROWSE_CO_OP。

使用 MQGMO_UNMARK_BROWSE_CO_OP 只有在使用選項 MQOO_CO_OP成功呼叫 MQOPEN 所傳回的控點時才有效。 即使未將訊息視為由一組協同作業的控點所標示， MQGET 仍會成功。

即使未標示此控點的訊息，呼叫仍會成功。

• MQGMO_BROWSE_FIRST
• MQGMO_BROWSE_NEXT
• MQGMO_BROWSE_MSG_UNDER_CURSOR

鎖定訊息一律是瀏覽游標下的訊息。 稍後指定 MQGMO_MSG_UNDER_CURSOR 選項的 MQGET 呼叫可以從佇列中移除訊息。 其他使用佇列控點的 MQGET 呼叫也可以移除訊息 (例如，指定已鎖定訊息之訊息 ID 的呼叫)。

如果呼叫傳回完成碼 MQCC_FAILED或 MQCC_WARNING ，原因碼為 MQRC_TRUNCATED_MSG_FAILED，則不會鎖定任何訊息。

如果您指定 MQGMO_UNLOCK，則不會檢查或變更 MsgDesc、 BufferLength、 Buffer及 DataLength 參數。 Buffer中未傳回任何訊息。

指定 MQGMO_UNLOCK 不需要特殊開啟選項 (雖然首先需要 MQOO_BROWSE 才能發出鎖定要求)。

• 瀏覽訊息時，瀏覽游標會進階至傳回的訊息。
• 移除訊息時，會從佇列中移除傳回的訊息。
• 如果未發生其他錯誤，則會傳回原因碼 MQRC_TRUNCATED_MSG_ACCEPTED。

• 瀏覽訊息時，瀏覽游標不是進階的。
• 移除訊息時，不會從佇列中移除訊息。
• 如果未發生其他錯誤，則會傳回原因碼 MQRC_TRUNCATED_MSG_FAILED 。

請參閱 MQMD-訊息描述子 中說明的 Format 欄位，以取得佇列管理程式為其執行轉換的格式名稱清單。

已分段的邏輯訊息包含兩個以上具有相同非空值群組 ID ( MQMD中的 GroupId 欄位) 的實體訊息。 它們在 MQMD中具有相同的訊息序號 MsgSeqNumber 欄位。 透過 MQMD中區段偏移 Offset 欄位的不同值來識別區段。 區段偏移是實體訊息中資料從邏輯訊息中資料開始的偏移。 因為每一個區段都是實體訊息，所以邏輯訊息中的區段通常具有不同的訊息 ID。

尚未分段但傳送應用程式已允許分段的邏輯訊息也具有非空值群組 ID。 在此情況下，如果邏輯訊息不屬於訊息群組，則只有一個實體訊息具有該群組 ID。 除非邏輯訊息屬於訊息群組，否則傳送應用程式已禁止分段的邏輯訊息具有空值群組 ID MQGI_NONE。

如果針對相同佇列控點的連續 MQGET 呼叫指定 MQGMO_LOGICAL_ORDER ，則會依訊息序號的順序傳回群組中的訊息。 邏輯訊息的區段會依其區段偏移所給定的順序傳回。 此順序可能與那些訊息及區段在佇列上出現的順序不同。

若要以所需順序傳回訊息，佇列管理程式會在連續 MQGET 呼叫之間保留群組及區段資訊。 群組及區段資訊可識別佇列控點的現行訊息群組及現行邏輯訊息。 它也會識別群組及邏輯訊息中的現行位置，以及是否在工作單元內擷取訊息。 因為佇列管理程式會保留此資訊，所以在每次 MQGET 呼叫之前，應用程式都不需要設定群組和區段資訊。 具體而言，它表示應用程式不需要在 MQMD中設定 GroupId、 MsgSeqNumber及 Offset 欄位。 不過，應用程式必須在每次呼叫時正確設定 MQGMO_SYNCPOINT 或 MQGMO_NO_SYNCPOINT 選項。

如果佇列上存在多個訊息群組，且符合傳回資格，則會以每一個群組中第一個邏輯訊息之第一個區段的佇列位置所決定的順序來傳回群組。 亦即，訊息序號為 1 且偏移為 0 的實體訊息會決定傳回合格群組的順序。

指定 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_* 選項控制 (如需這些選項的詳細資料，請參閱 MQGMO-Get-message 選項 中說明的 MatchOptions 欄位)。

這是在系統失效之後，可用來在中間重新啟動訊息群組或邏輯訊息的技術。 當系統重新啟動時，應用程式可以將 GroupId、 MsgSeqNumber、 Offset及 MatchOptions 欄位設為適當的值，然後發出 MQGET 呼叫並設定 MQGMO_SYNCPOINT 或 MQGMO_NO_SYNCPOINT ，但不指定 MQGMO_LOGICAL_ORDER。 如果此呼叫成功，佇列管理程式會保留群組和區段資訊，後續使用該佇列控點的 MQGET 呼叫可以正常指定 MQGMO_LOGICAL_ORDER 。

建議以邏輯順序擷取訊息及區段的應用程式指定 MQGMO_LOGICAL_ORDER，因為這是最簡單的選項。 此選項可讓應用程式解除管理群組和區段資訊的需求，因為佇列管理程式會管理該資訊。 不過，特殊化應用程式可能需要比 MQGMO_LOGICAL_ORDER 選項所提供的更多控制，不指定該選項即可達成此目的。 然後，應用程式必須確保 MQMD中的 MsgId、 CorrelId、 GroupId、 MsgSeqNumber及 Offset 欄位，以及 MQGMO中的 MatchOptions 中的 MQMO_* 選項，在每一個 MQGET 呼叫之前都正確設定。

例如，想要轉遞所接收實體訊息的應用程式，不論這些訊息是在邏輯訊息的群組或區段中，都不能指定 MQGMO_LOGICAL_ORDER。 在傳送與接收佇列管理程式之間具有多條路徑的複雜網路中，實體訊息可能不正常送達。 透過在 MQPUT 呼叫上既未指定 MQGMO_LOGICAL_ORDER，也未指定對應的 MQPMO_LOGICAL_ORDER ，轉遞應用程式可以在每一個實體訊息到達時立即擷取並轉遞它，而不需要等待邏輯順序中的下一個實體訊息到達。

如果要使用這個選項，應用程式必須提供足夠大的緩衝區來容納完整訊息，或指定 MQGMO_ACCEPT_TRUNCATED_MSG 選項。

如果佇列包含部分區段遺漏的分段訊息 (可能是因為它們在網路中已延遲且尚未到達) ，則指定 MQGMO_COMPLETE_MSG 會阻止擷取屬於不完整邏輯訊息的區段。 不過，這些訊息區段仍會構成 CurrentQDepth 佇列屬性的值; 這表示即使 CurrentQDepth 大於零，也可能沒有可擷取的邏輯訊息。

對於非持續訊息，佇列管理程式不需要工作單元即可執行重新組合。

每一個屬於區段的實體訊息都有自己的訊息描述子。 對於構成單一邏輯訊息的區段，訊息描述子中的大部分欄位對於邏輯訊息中的所有區段都是相同的; 通常只有 MsgId、 Offset和 MsgFlags 欄位在邏輯訊息中的區段之間會有所不同。 不過，如果區段放置在中間佇列管理程式的無法傳送郵件的佇列上，則 DLQ 處理程式會擷取指定 MQGMO_CONVERT 選項的訊息，這可能會導致變更區段的字集或編碼。 如果 DLQ 處理程式順利傳送區段，則區段可能具有字集或編碼，與區段到達目的地佇列管理程式時邏輯訊息中的其他區段不同。

由 CodedCharSetId 和 Encoding 欄位不同的區段所組成的邏輯訊息，無法由佇列管理程式重新組合成單一邏輯訊息。 相反地，佇列管理程式會重新組合並傳回邏輯訊息開頭的前幾個連續區段，這些區段具有相同的字集 ID 及編碼，且 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，將它們擷取為單一訊息。 若要這樣做，必須由支援分段的佇列管理程式或 MCA 產生報告訊息，或原始應用程式必須要求至少 100 個位元組的訊息資料 (亦即，必須指定適當的 MQRO_*_WITH_DATA 或 MQRO_*_WITH_FULL_DATA 選項)。 如果區段存在的應用程式資料量小於完整數量，則會在傳回的報告訊息中以空值取代遺漏的位元組。

如果使用 MQGMO_MSG_UNDER_CURSOR 或 MQGMO_BROWSE_MSG_UNDER_CURSOR指定 MQGMO_COMPLETE_MSG ，則瀏覽游標必須位於其 MQMD 中 Offset 欄位值為 0 的訊息上。 如果未滿足此條件，則呼叫會失敗，原因碼為 MQRC_INVALID_MSG_UNDER_CURSOR。

MQGMO_COMPLETE_MSG 默示 MQGMO_ALL_SEGMENTS_AVAILABLE，因此不需要指定。

順利完成指定 MQGMO_ALL_MSGS_AVAILABLE 的 MQGET 呼叫，表示在發出 MQGET 呼叫時，群組中的所有訊息都在佇列上。 不過，請注意，其他應用程式仍可以從群組中移除訊息 (該群組未鎖定至擷取群組中第一個訊息的應用程式)。

如果省略此選項，則即使群組不完整，也可以擷取屬於群組的訊息。

MQGMO_ALL_MSGS_AVAILABLE 默示 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 會成功。 如果特定邏輯訊息的區段存在混合的報告類型，則必須逐一擷取這些報告訊息。

訊息的內容 (訊息描述子或延伸中的除外) 應該如 PropertyControl 佇列屬性所定義來表示。 如果提供 MsgHandle ，則除非 PropertyControl 佇列屬性的值為 MQPROP_FORCE_MQRFH2，否則會忽略此選項，且訊息的內容可透過 MsgHandle取得。

如果未指定內容選項，這是預設動作。

訊息的內容應該透過 MsgHandle提供。 如果未提供訊息控點，則呼叫會失敗，原因為 MQRC_HMSG_ERROR。

將不會擷取訊息的內容，但訊息描述子 (或延伸) 中包含的內容除外。 如果提供 MsgHandle ，則會忽略它。

訊息的內容 (訊息描述子或延伸中的除外) 應該使用 MQRFH2 標頭來表示。 對於預期擷取內容但無法變更為使用訊息控點的應用程式，這可提供與舊版的相容性。 如果提供 MsgHandle ，則會忽略它。