第 6 章 管理實體目標

本章說明如何使用 imqcmd 公用程式，管理實體目標。Message Queue^TM 訊息可以經由代理程式上的實體目標，路由至其使用者用戶端。代理程式會管理實體目標的相關記憶體和永久性存放區，並且設定其運作方式。

在代理程式叢集中，您只要在一個代理程式上建立實體目標，叢集會將此實體目標傳播至所有代理程式。應用程式用戶端可以訂閱或使用叢集中任何代理程式上的主題或佇列，因為代理程式會合作跨叢集路由訊息。但是唯有產生訊息的原始代理程式，可以管理訊息的永久性和確認。

本章涵蓋下列主題：

• 使用指令公用程式

• 建立實體目標

• 列出實體目標

• 顯示實體目標資訊

• 更新實體目標特性

• 暫停和重新繼續實體目標

• 清除實體目標

• 銷毀實體目標

• 壓縮實體目標

• 使用停用的訊息佇列

表 13–5 提供有關使用 imqcmd 子指令來管理實體目標並且完成這些工作的完整參考資訊。

如需實體目標的簡介，請參閱「Message Queue 技術摘要」。

用戶端應用程式與實體目標互動時，會使用 Destination 物件。為了提供者獨立性和可移植性，用戶端通常使用管理員建立的目標物件，即目標管理物件。您可以配置供用戶端應用程式使用的受管理物件，如第 8 章, 管理受管理物件所述。

使用指令公用程式

使用 Message Queue 指令公用程式 (imqcmd) 管理實體目標。imqcmd 指令的語法，與您將其用於管理其他代理程式服務時相同。

如需有關 imqcmd、其子指令和選項的參考資訊，請參閱第 13 章, 指令行參照。

子指令

表 6–1 列出本章描述的 imqcmd 子指令用法。如需有關這些子指令的參考資訊，請參閱實體目標管理。

建立實體目標

若要建立實體目標，請使用 imqcmd create 子指令。create 子指令的語法如下：

create dst -t destType -n 
destName [-o property=value
] [-o property=value1]
…

例如，若要建立佇列目標，請輸入以下指令：

imqcmd create dst -n myQueue -t q -o “maxNumActiveConsumers=5”

若要建立主題目標，請輸入以下指令：

imqcmd create dst -n myTopic -t t -o “maxBytesPerMsg=5000”

建立實體目標時，您必須指定以下項目：

• 實體目標類型 t (topic) 或 q (queue)。

• 實體目標名稱。命名規則如下：

  • 名稱只能使用字母數字字元。不能包含空格。

  • 名稱可以用英文字母字元、底線字元 (_) 或錢幣符號 ($) 開頭。不能以 mq 字元字串開頭。

  實體目標特性的非預設值。

更新實體目標時，您也可以設定特性。

很多實體目標特性都會影響代理程式記憶體資源和訊息流量。例如，您可以指定能夠傳給實體目標的產生器數目、產生器可以傳送的訊息數量和容量，以及到達實體目標限制時代理程式的回應方式。這些限制類似於代理程式配置特性所控制的一切代理程式限制。

下列特性可用於佇列目標和主題目標：

• maxNumMsgs：指定實體目標中允許未使用訊息的最大數目。

• maxTotalMsgBytes：指定實體目標中允許給未使用訊息的最大總記憶體容量 (以位元組為單位)。

• limitBehavior：指定達到記憶體限制執行緒時，代理程式回應的方式。

• maxBytesPerMsg：指定實體目標中允許的單一訊息最大容量 (以位元組為單位)。

• maxNumProducers：指定實體目標中產生器的最大數目。

• consumerFlowLimit：指定單一批次中，傳送給用戶的最大訊息數目。

• isLocalOnly：僅適用於代理程式叢集。指定在其他代理程式上不複製實體目標，且限制實體目標僅傳送訊息給本機用戶 (即連線到已建立實體目標之代理程式的用戶)。

• useDMQ：指定捨棄實體目標之停用的訊息或放到停用的訊息佇列中。

下列特性僅用於佇列目標：

• maxNumActiveConsumers：指定從佇列目標之負載平衡傳送中可成為使用中用戶的最大數目。

• maxNumBackupConsumers：指定最大備份用戶數目，如果無法從佇列目標進行負載平衡傳送，則這些用戶可以取代使用中用戶。

• localDeliveryPreferred：僅適用於代理程式叢集中的負載平衡佇列傳送。如果本機代理程式沒有用戶，則指定訊息僅傳送給遠端用戶。

如需有關實體目標特性的完整參考資訊，請參閱第 15 章, 實體目標特性參照。

針對自動建立的目標，請在代理程式實例配置檔案中設定預設特性值。表 14–3 中有自動建立特性的參考資訊。

列出實體目標

您可以取得關於實體目標目前特性值的相關資訊、關於與實體目標相關之產生器或用戶的數目以及關於訊息傳送度量的資訊，例如實體目標中訊息的數目和容量。

若要尋找實體目標以便取得其相關資訊，請使用 list dst 子指令，列出代理程式上的所有實體目標。list dst 子指令的語法如下：

list dst [-t destType] [-tmp]

該指令可以列出所指定類型的實體目標。目標類型值 (-t) 的選項可為 q (佇列) 或 t (主題)。

如果省略目標類型，則會列出所有類型的實體目標。

list dst 子指令可選擇性指定要列出的目標類型，或包括暫時目標 (使用 -tmp 選項)。用戶端建立的暫時目標，通常用來接收傳送到其他用戶端的訊息回應。

例如，若要取得連接埠 4545 上 myHost 執行的代理程式的所有實體目標，請輸入以下指令：

imqcmd list dst -b myHost:4545

除非您指定目標類型 t 只包含主題，否則除了其他實體目標，也一定會顯示停用的訊息佇列 mq.sys.dmq 之資訊。

顯示實體目標資訊

若要取得實體目標的目前特性，請使用 query dst 子指令。query dst 子指令的語法如下：

query dst -t destType -n 
destName

該指令列出指定類型和名稱之目標的相關資訊。例如，下列指令會顯示佇列目標 XQueue 的相關資訊：

imqcmd query dst -t q -n XQueue -u admin

此指令的輸出如下：

------------------------------------
Destination Name    Destination Type
------------------------------------
XQueue              Queue

On the broker specified by:

-------------------------
Host         Primary Port
-------------------------
localhost    7676

Destination Name                      XQueue
Destination Type                      Queue
Destination State                     RUNNING
Created Administratively              true

Current Number of Messages            0
Current Total Message Bytes           0
Current Number of Producers           0
Current Number of Active Consumers    0
Current Number of Backup Consumers    0

Max Number of Messages                unlimited (-1)
Max Total Message Bytes               unlimited (-1)
Max Bytes per Message                 unlimited (-1)
Max Number of Producers               100
Max Number of Active Consumers        1
Max Number of Backup Consumers        0

Limit Behavior                        REJECT_NEWEST
Consumer Flow Limit                   1000
Is Local Destination                  false
Local Delivery is Preferred           false
Use Dead Message Queue                true

輸出也會顯示與目標相關之產生器與用戶的數目。佇列目標的這個數目包含使用中用戶和備份用戶。

您可以使用 update dst 子指令來變更一個或多個特性值 (請參閱更新實體目標特性)。

更新實體目標特性

透過使用 update dst 子指令和 -o 選項指定要更新的特性，您可以變更實體目標的特性。update bkr 子指令的語法如下：

update dst -t destType -n 
destName -o property=value [[-o 
property=value1]…]

該指令會更新指定目標上的指定特性的值。 特性名稱可以是表 15–1 中所列出的任何特性。

您可以多次使用 -o 選項，更新多個特性。例如，以下指令將 maxBytesPerMsg 特性變更為 1000，並將 MaxNumMsgs 特性變更為 2000：

imqcmd update dst -t q -n myQueue -o “maxBytesPerMsg=1000”
              -o “maxNumMsgs=2000” -u admin

請參閱第 15 章, 實體目標特性參照，以獲得可以更新的特性清單。

您無法使用 update dst 子指令更新實體目標的類型，或更新 isLocalOnly 特性。

停用的訊息佇列是特殊的實體目標，其特性與其他目標的特性不同。如需更多資訊，請參閱使用停用的訊息佇列。

暫停和重新繼續實體目標

您可以暫停實體目標，以便控制從產生器傳送訊息到目標，或從目標傳送訊息到用戶，或同時控制上述兩個動作。要特別注意的是，您可以暫停進入目標的訊息流量，以避免目標在訊息產生速度高於使用速度時收到過多訊息。壓縮實體目標之前，必須先暫停該目標。

若要暫停傳送到實體目標的訊息或暫停從實體目標傳送的訊息，請使用 pause dst 子指令。pause dst 子指令的語法如下：

pause dst [-t destType -n 
destName] [-pst pauseType]

針對指定類型和名稱的目標，該子指令可以暫停至用戶的訊息傳送 (-pst CONSUMERS)，或暫停來自產生器的訊息傳送 (-pst PRODUCERS)，或者兩者皆暫停 (-pst ALL)。如果沒有指定目標類型與名稱，則會暫停所有實體目標。預設為 ALL。

範例：

imqcmd pause dst -n myQueue -t q -pst PRODUCERS -u admin
imqcmd pause dst -n myTopic -t t -pst CONSUMERS -u admin

若要重新繼續向暫停的目標傳送，請使用 resume dst 子指令。resume dst 子指令的語法如下：

resume dst [-t destType -n 
destName]

該子指令重新繼續向指定類型和名稱之暫停目標傳送訊息。如果沒有指定目標類型與名稱，則會重新繼續所有目標。

範例：

imqcmd resume dst -n myQueue -t q

在代理程式叢集中，實體目標實例會常駐在叢集中的每個代理程式。必須予以個別暫停。

清除實體目標

您可以清除目前在實體目標上形成佇列的所有訊息。清除實體目標即表示會刪除儲存於該目標的所有訊息。

當累積的訊息佔用太多的系統資源時，您可能需要清除訊息。當佇列沒有註冊的用戶用戶端並要接收許多訊息時，可能需要清除訊息。如果非使用中的主題長期訂閱者未成為使用中訂閱者，也可能需要清除訊息。在這兩種情況下，沒有必要保留訊息。

若要清除實體目標上的訊息，請使用 purge dst 子指令。purge dst 子指令的語法如下：

purge dst -t destType -n 
destName

此子指令會清除實體目標上指定類型與名稱的訊息。

範例：

imqcmd purge dst -n myQueue -t q -u admin
imqcmd purge dst -n myTopic -t t -u admin

如果已關閉代理程式，並且不想在其重新啟動時傳送舊的訊息，請使用 -reset messages 選項清除舊的訊息，例如：

imqbrokerd -reset messages -u admin

這可避免重新啟動代理程式後清除目標的麻煩。

在代理程式叢集中，實體目標實例會常駐在叢集中的每個代理程式。您必須個別清除這些目標。

銷毀實體目標

若要銷毀實體目標，請使用 destroy dst 子指令。destroy dst 子指令的語法如下：

destroy dst -t destType -n 
destName

此子指令會銷毀指定類型與名稱的實體目標。

範例：

imqcmd destroy dst -t q -n myQueue -u admin

銷毀實體目標會清除此目標上的所有訊息，並從代理程式中移除此目標；此作業不可復原。

您不能銷毀停用的訊息佇列。

壓縮實體目標

如果您使用檔案式資料存放區作為訊息的永久性存放區，即可監視磁碟使用，並於需要時壓縮磁碟。

檔案式訊息存放區的結構方式，是讓訊息可以儲存在與收納訊息之實體目標相對應的目錄中。在各個實體目標的目錄中，大部分訊息會儲存在一個檔案中，該檔案由大小不定的記錄所組成。(若要減少分段程序，大小超過可配置臨界值的訊息會儲存在其個別的檔案中。)

因為會存留不同大小的訊息，接著從記錄檔移除這些訊息，所以檔案中可能會產生空白片段，且將無法再重新使用這些可用記錄。

若要管理未使用的可用記錄，使用率下降時，指令公用程式包括每個實體目標監視磁碟使用及收回可用磁碟空間的子指令。

監視實體目標的磁碟使用

若要監視實體目標的磁碟使用，請使用下列指令：

imqcmd metrics dst -t q -n myQueue -m dsk -u admin

此指令的輸出如下：

--------------------------------------
Reserved   Used      Utilization Ratio
--------------------------------------
806400     804096    99
1793024    1793024   100
2544640    2518272   98

子指令輸出中的欄有下列涵義：

收回未使用的實體目標磁碟空間

磁碟使用模式依使用特定實體目標之訊息傳送應用程式的特徵而異。根據傳入和傳出實體目標的相關訊息流量和相關的訊息容量，保留的磁碟空間可能會不斷增加。

如果訊息產生速率大於訊息使用速率，那麼通常會重新使用可用記錄，且使用率應較高。但是，如果訊息產生速率與訊息使用速率相似或小於訊息使用速率，那麼使用率會比較低。

一般而言，您會穩定保留的磁碟空間並保持高使用率。通常如果系統到達穩定狀態 (即保留的磁碟空間大致固定)，並且使用率高 (高於 75%)，則不需要收回未使用的磁碟空間。如果系統到達穩定狀態且使用率低 (低於 50%)，您可以壓縮磁碟，收回可用記錄佔用的磁碟空間。

compact dst 子指令可用來壓縮資料存放區。compact dst 子指令的語法如下：

compact dst [-t destType -n 
destName]

此子指令會壓縮指定類型與名稱之實體目標的檔案式資料存放區。如果沒有指定目標類型與名稱，則會壓縮所有目標。必須在壓縮目標前暫停實體目標。

如果保留的磁碟空間不斷增加，請藉由設定目標記憶體限制特性和限制運作方式，重新配置目標的記憶體管理 (請參閱表 15–1)。

收回未使用的實體目標磁碟空間

1. 暫停目標。

   imqcmd pause dst -t q -n myQueue -u admin

2. 壓縮磁碟。

   imqcmd compact dst -t q -n myQueue -u admin

3. 重新繼續實體目標。

   imqcmd resume dst -t q -n myQueue -u admin

   如果未指定目標類型和名稱，則會在所有實體目標上執行這些作業。

使用停用的訊息佇列

停用的訊息佇列 mq.sys.dmq 是系統建立的實體目標，保留代理程式和其他實體目標之停用的訊息。停用的訊息佇列是用來監視、調校系統效率以及疑難排解的工具。如需「停用的訊息」一詞的定義和停用的訊息佇列之詳細資訊，請參閱「 Message Queue 技術摘要」。

代理程式啟動時會自動建立停用的訊息佇列。代理程式將無法處理或到期的訊息放在此佇列中。此外，其他實體目標可以使用停用的訊息佇列來保留已捨棄的訊息。使用停用的訊息佇列提供的資訊，有助於系統的疑難排解。

配置使用停用的訊息佇列

依預設，系統會配置實體目標以使用停用的訊息佇列。您可以設定實體目標特性 useDMQ，讓實體目標使用或不使用停用的訊息佇列。

下列範例建立的佇列 myDist，依預設使用停用的訊息佇列：

imqcmd create dst -n myDist -t q

下列範例讓相同的佇列停用此停用的訊息佇列：

imqcmd update dst -n myDist -t q -o useDMQ=false

設定 imq.autocreate.destination.useDMQ 代理程式特性，可以讓代理程式上所有自動建立的實體目標使用或不使用停用的訊息佇列。

管理停用的訊息佇列

您可使用 Message Queue 指令公用程式 (imqcmd) 管理停用的訊息佇列，方式與管理其他佇列僅有些微差異。例如，因為停用的訊息佇列是系統所建立的，因此您不能建立、暫停或銷毀它。此外，如表 6–3 中所示，停用的訊息佇列之預設值，有時會和正常佇列的預設值不相同。

停用的訊息佇列特性

您可以使用配置其他佇列的方式來配置停用的訊息佇列，但是有些實體目標特性可能不適用或是預設值不同。表 6–3 列出的佇列特性，會由停用的訊息佇列以特殊方式處理。

訊息內容

代理程式可以將整個訊息放入停用的訊息佇列中，或是捨棄訊息內文的內容，只保留標頭和特性資料。依預設，停用的訊息佇列儲存整個訊息。

若想要降低停用的訊息佇列容量，且不打算復原停用的訊息，請考慮將 imq.destination.DMQ.truncateBody 代理程式特性設為 true：

imqcmd update bkr -o imq.destination.DMQ.truncateBody=true

如此將會捨棄訊息本文，而只保留標頭與特性資料。

啟用停用的訊息之記錄功能

依預設，不記錄停用的訊息。啟用停用的訊息之記錄功能，可讓代理程式記錄下列事件：

• 代理程式將訊息移至停用的訊息佇列

• 代理程式捨棄來自停用的訊息佇列之訊息，以及不使用停用的訊息佇列之任何實體目標的訊息

• 實體目標達其上限

下列指令會啟用停用的訊息之記錄功能：

imqcmd update bkr -o imq.destination.logDeadMsgs=true

停用的訊息之記錄功能套用於所有使用停用的訊息佇列的實體目標。您不能啟用或停用個別實體目標的記錄功能。