|
| |
| Sun Java System Message Queue 3.5 SP1 管理指南 | |
第 6 章
代理程式和應用程式管理本章介紹如何執行與管理代理程式及其提供的服務相關的工作。其中的某些工作獨立於任何特定的用戶端應用程式。這些工作包括：
其他代理程式工作作為特定應用程式執行；這些工作包括管理實體目標、長期訂閱以及異動：
本章介紹如何使用指令公用程式 (imqcmd) 以執行所有這些工作。使用管理主控台 (即 Message Queue 訊息伺服器的圖形介面)，您也可以完成這些相同工作中的許多項。如需更多資訊，請參閱第 4 章「管理主控台指導」。
指令公用程式指令公用程式可讓您管理代理程式及其提供的服務。本節描述基本的 imqcmd 指令語法、提供子指令的清單，並總結 imqcmd 選項。後續各節介紹如何使用這些指令完成特定的工作。
imqcmd 指令的語法
imqcmd 指令的一般語法如下：
imqcmd subcommand argument [options]
imqcmd -h|H
imqcmd -v請注意，如果您指定 -v、-h 或 -H 選項，則系統不會執行指令行上指定的子指令。例如，如果您輸入以下指令，則系統會顯示版本資訊但不會執行 restart 子指令。
imqcmd restart bkr -v
imqcmd 子指令
指令公用程式 (imqcmd) 包括表 6-1 中列出的子指令：本章的相關工作各節內容會更加詳細說明子指令。
imqcmd 選項摘要
表 6-2 列出了 imqcmd 指令的選項。如需它們用法的說明，請參閱以下基於工作的各節。
表 6-2 imqcmd 選項
選項
說明
-b hostName:port
指定代理程式主機名稱及其連接埠號。預設值為 localhost:7676。
僅指定連接埠：-b :7878
僅指定名稱： -b somehost-c clientID
將長期用戶的 ID 指定至主題。請參閱「管理長期訂閱」。
-d destinationName
指定主題名稱。與 list dur 和 destroy dur 子指令配合使用。請參閱「管理長期訂閱」。
-f
未經使用者確認即執行動作。
-h
顯示用法說明。不執行指令行上的其他任何指令。
-H
顯示用法說明、屬性清單和範例。不執行指令行上的其他任何指令。
-int interval
指定 metrics bkr、metrics dst 與 metrics svc 子指令顯示度量輸出的時間間隔 (以秒為單位)。
-javahome path
指定要使用的替代 Java 2 相容運行時間 (預設為使用系統上的運行時間，或 Message Queue 隨附的運行時間)。
-m metricType
指定要顯示的度量資訊類型。將此選項與 metrics dst、metrics svc 或 metrics bkr 子指令配合使用。metricType 的值會根據是否產生用於目標、服務或代理程式的度量而變化。
-msp numSamples
指定度量輸出中，顯示作為metrics bkr、metrics dst 與 metrics svc 子指令範例的度量數目。
-n argumentName
指定子指令引數的名稱。此選項可能為服務名稱、實體目標名稱、長期訂閱名稱、連接 ID 或異動 ID，這取決於子指令。
-o attribute=value
指定屬性的值。此選項可以為代理程式 (請參閱「管理代理程式」) 的屬性、服務 (請參閱「管理連接服務」) 的屬性或目標 (請參閱「管理目標」) 的屬性，這取決於子指令引數。
-p password
指定您的 (管理員的) 密碼。如果您遺漏此值，系統將提示您提供此名稱。
-pst pauseType
暫停目標時，指定是否要暫停產生者、使用者或兩者皆暫停。請參閱「管理目標」。
-rtm timeout
指定 imqcmd 子指令的初始 (重試) 逾時期間 (以秒為單位)。送出請求到代理程式後，imqcmd 子指令將等待的逾時時間長度。每個子指令的後續重試會使用一個逾時值，該逾時值為初始逾時期間的倍數。預設值： 10
-rtr numRetries
指定 imqcmd 子指令第一次逾時後，嘗試重試的次數。預設值： 5
-s
無訊息模式。不顯示輸出。
-secure
使用 ssladmin 連接服務指定與代理程式的安全管理連接 (請參閱「步驟 4. 配置並執行基於 SSL 的用戶端」)。
-svn serviceName
指定所列出連接的服務。請參閱「取得連接資訊」。
-t destType
指定目標的類型：t (主題) 或 q (佇列)。請參閱「管理目標」。
-tmp
顯示暫存目標。請參閱表 6-9。
-u userName
指定您的 (管理員的) 名稱。如果您遺漏此值，系統將提示您提供此名稱。
-v
顯示版本資訊。不執行指令行上的其他任何指令。
每次發出 imqcmd 子指令時，您必須為主機名稱和連接埠號 (-b)、使用者名稱 (-u)、密碼 (-p) 和安全連接 (-secure) 指定選項。如果未指定主機名稱和連接埠號，則使用預設值。如果未指定使用者名稱和密碼資訊，則系統將提示您提供名稱和密碼。如果未指定 -secure，則連接可能會不安全。
備註
若想要使用 -secure 選項，您必須先配置並啟用目標代理程式實例中的 ssladmin 服務，如「透過 TCP/IP 設定基於 SSL 的服務」所述。
使用 imqcmd 指令
為了使用 imqcmd 指令以管理代理程式，您必須執行以下作業：
請參閱「啟動代理程式」。您僅可以使用指令公用程式管理執行中的代理程式；您不能使用它啟動代理程式。
- 使用 -b 選項指定目標代理程式，除非代理程式正在使用連接埠 7676 的本地主機上執行。
- 指定適當的管理員使用者名稱和密碼。如果您未指定，系統將提示您提供名稱和密碼。而且，請注意您使用 imqcmd 執行的每項作業都將由使用者儲存庫認證。如需更多資訊，請參閱「認證使用者」。
當您安裝 Message Queue 時，同時也安裝了預設文字檔案使用者儲存庫。此儲存庫出廠時隨附兩個項目：一個用於擁有管理員權限的使用者，一個用於客人使用者。這些項目可讓您連接至代理程式實例而不執行任何其他工作。例如，如果您僅要測試 Message Queue，則可以使用預設的使用者名稱和密碼 (admin/admin) 來執行 imqcmd 公用程式。
如果您要配置生產系統，則將需要執行一些其他工作以認證和授權使用者 (請參閱第 8 章「管理安全性」)。要特別注意的是，您必須在 Message Queue 使用者儲存庫中建立項目 (請參閱「使用文字檔案使用者儲存庫」)。您還可以選擇使用您的使用者儲存庫的現有 LDAP 目錄伺服器 (請參閱「將 LDAP 伺服器用於使用者儲存庫」)。
範例 imqcmd 的用法
以下範例說明 imqcmd 指令的使用：
管理代理程式指令公用程式包括您可用來執行以下代理程式管理工作的子指令：
若要管理代理程式的連接服務，請參閱「管理連接服務」。若要管理代理程式目標，請參閱「管理目標」。
表 6-3 列出用來管理代理程式的 imqcmd 子指令。如果未指定主機名稱或連接埠，則使用預設值 (localhost 和 7676)。
表 6-3 用來管理代理程式的 imqcmd 子指令
子指令語法
說明
metrics bkr [-b hostName:port]
[-m metricType]
[-int interval]
[-msp numSamples]顯示預設代理程式或指定主機和連接埠上的代理程式的代理程式度量。
使用 -m 選項指定要顯示的度量類型：
ttl 顯示代理程式流入和流出訊息和封包的度量。(預設度量類型)
rts 顯示代理程式 (每秒) 流入和流出訊息和封包之流量速率的度量。
cxn 顯示連接、虛擬記憶體堆疊和執行緒。
使用 -int 選項，指定顯示度量的間隔時間 (以秒為單位)。預設為 5 秒鐘。
使用 -msp 選項，指定輸出中顯示的範例數目。預設的數目為沒有限制 (無限)。
pause bkr [-b hostName:port]
暫停預設代理程式或指定主機和連接埠上的代理程式。請參閱「暫停與繼續代理程式」。
query bkr -b hostName:port
列出預設代理程式或指定主機和連接埠上的代理程式特性的目前配置。還顯示連接至指定代理程式的執行中的代理程式 (在多重代理程式叢集中) 之清單。
reload cls
僅適用於代理程式叢集。強制叢集中的所有代理程式重新載入 imq.cluster.brokerlist 特性並更新叢集資訊。請參閱「將代理程式新增至叢集」，以獲得更多資訊。
restart bkr [-b hostName:port]
關閉並重新啟動預設代理程式或指定主機和連接埠上的代理程式。
請注意，此指令使用首次啟動代理程式時指定的選項重新啟動此代理程式。如果您要使用不同的選項，則必須關閉代理程式然後再次啟動它，從而指定您需要的選項。
resume bkr [-b hostName:port]
繼續預設代理程式或指定主機和連接埠上的代理程式。
shutdown bkr [-b hostName:port]
關閉預設代理程式或指定主機和連接埠上的代理程式。
update bkr [-b hostName:port]
-o attribute=value
[-o attribute=value1]...變更預設代理程式或指定主機和連接埠上的代理程式的指定屬性。
請記住，當使用表 6-3 中列出的任何子指令時，您必須指定代理程式主機名稱和連接埠號，除非您的目標為在使用連接埠 7676 的 localhost 上執行的代理程式。
顯示代理程式資訊
若要查詢並顯示單一代理程式的相關資訊，請使用 query bkr 子指令。例如：
imqcmd query bkr -u admin -p admin
此指令的輸出如下：
更新代理程式特性
您可以使用 update bkr 子指令更新表 6-4 中列出的任何代理程式特性。請注意，對代理程式的更新會自動寫入代理程式的實例配置檔案。
表 6-4 imqcmd 更新的代理程式特性
特性
參考
imq.autocreate.queue
imq.autocreate.topic
imq.autocreate.queue.maxNumActiveConsumers
imq.autocreate.queue.maxNumBackupConsumers
imq.cluster.url
imq.log.level
imq.log.file.rolloversecs
imq.log.file.rolloverbytes
imq.system.max_count
imq.system.max_size
imq.message.max_size
imq.portmapper.port
例如，以下指令會關閉佇列目標的自動建立功能：
imqcmd update bkr -o "imq.autocreate.queue=false"
-u admin -p admin控制代理程式的狀態
啟動代理程式之後，您可以使用以下 imqcmd 子指令控制代理程式的狀態。
暫停與繼續代理程式
但是，暫停代理程式不會暫停管理連接服務。此服務可讓您執行所需的管理工作，以管理代理程式的訊息流量。例如，如果某特定目標受到訊息的攻擊，則您可以暫停代理程式，並執行以下可能幫助您解決問題的任何動作：追蹤訊息來源、限制目標大小或銷毀目標。
暫停代理程式也不會暫停叢集連接服務。但是，叢集中的訊息發送會根據叢集中不同代理程式執行的發送功能而有差異。
以下指令暫停在使用連接埠 1588 的 myhost 上執行的代理程式。
(您也可以暫停個別連接服務 (請參閱「暫停與繼續連接服務」) 和個別目標 (請參閱「暫停和繼續目標」)
關閉和重新啟動代理程式
顯示代理程式度量
若要顯示有關代理程式的度量資訊，請使用 metrics bkr 子指令。例如，若要取得每 10 秒時間間隔，代理程式流入與流出的訊息速率，請使用：
imqcmd metrics bkr -m rts -int 10 -u admin -p admin
此指令的輸出如下：
--------------------------------------------------------
Msgs/sec Msg Bytes/sec Pkts/sec Pkt Bytes/sec
In Out In Out In Out In Out
--------------------------------------------------------
0 0 27 56 0 0 38 66
10 0 7365 56 10 10 7457 1132
0 0 27 56 0 0 38 73
0 10 27 7402 10 20 1400 8459
0 0 27 56 0 0 38 73
如需使用 imqcmd 報告代理程式度量的更多詳細說明，請參閱「監視工具」。
管理連接服務指令公用程式包括允許您執行以下連接服務管理工作的子指令：
如需 Message Queue 連接服務的簡介，請參閱「連接服務」。
表 6-5 列出用來管理連接服務的 imqcmd 子指令。如果未指定主機名稱或連接埠，則使用預設值 (localhost 和 7676)。
表 6-5 用於管理連接服務的 imqcmd 子指令
子指令語法
說明
list svc [-b hostName:port]
列出預設代理程式或指定主機和連接埠上的代理程式上的所有連接服務。
metrics svc -n serviceName
[-b hostName:port]
[-m metricType]
[-int interval]
[-msp numSamples]顯示預設代理程式或指定主機和連接埠上的代理程式上的指定服務之標準資訊。
使用 -m 選項指定要顯示的度量類型：
ttl 顯示代理程式經由指定服務，流入和流出訊息和封包的度量。(預設度量類型)
rts 顯示代理程式經由指定服務， (每秒) 流入和流出訊息和封包之流量速率的度量。
cxn 顯示連接、虛擬記憶體堆疊和執行緒。
使用 -int 選項，指定顯示度量的間隔時間 (以秒為單位)。預設為 5 秒鐘。
使用 -msp 選項，指定輸出中顯示的範例數目。預設的數目為沒有限制 (無限)。
pause svc -n serviceName
[-b hostName:port]暫停在預設代理程式或指定主機和連接埠上的代理程式上執行的指定服務。您無法暫停管理服務。
query svc -n serviceName
[-b hostName:port]顯示在預設代理程式或指定主機和連接埠上的代理程式上執行的指定服務的相關資訊。
resume svc -n serviceName
[-b hostName:port]繼續在預設代理程式或指定主機和連接埠上的代理程式上執行的指定服務。
update svc -n serviceName
[-b hostName:port]
-o attribute=value
[-o attribute=value1]...更新在預設代理程式或指定主機和連接埠上的代理程式上執行的指定服務的指定屬性。如需服務屬性的說明，請參閱表 6-7。
代理程式支援來自應用程式用戶端和管理用戶端的連接。目前，Message Queue 代理程式可提供的連接服務如表 6-6 中所示。[服務名稱] 欄中的值是指用於為 -n 選項指定服務名稱的值。如表格中所示，每種服務均由它使用的服務類型和基本傳輸層指定，所使用的服務類型為 NORMAL (應用程式用戶端) 或 ADMIN (管理用戶端)。
表 6-6 代理程式支援的連接服務
服務名稱
服務類型
協定類型
jms
NORMAL
tcp
ssljms (企業版)
NORMAL
tls (基於 SSL 的安全性)
httpjms (企業版)
NORMAL
http
httpsjms (企業版)
NORMAL
https (基於 SSL 的安全性)
admin
ADMIN
tcp
ssladmin (企業版)
ADMIN
tls (基於 SSL 的安全性)
列出連接服務
若要列出代理程式上可用的連接服務，請使用以下指令：
imqcmd list svc [-b hostName:portNumber] -u admin -p admin
例如，以下指令列出在使用連接埠 6565 的主機 myServer 上執行代理程式上的可用服務。
imqcmd list svc -b MyServer:6565 -u admin -p admin
以下指令列出在使用連接埠 7676 的 localhost 上執行的代理程式上的所有服務：
imqcmd list svc -u admin -p admin
此指令將輸出以下資訊：
------------------------------------------------
Service Name Port Number Service State
------------------------------------------------
admin 41844 (dynamic) RUNNING
httpjms - UNKNOWN
httpsjms - UNKNOWN
jms 41843 (dynamic) RUNNING
ssladmin dynamic UNKNOWN
ssljms dynamic UNKNOWN
顯示連接服務資訊
若要查詢並顯示單一服務的相關資訊，請使用查詢子指令。例如，
imqcmd query svc -n jms -u admin -p admin
此指令的輸出如下：
Service Name jms
Service State RUNNING
Port Number 60920 (dynamic)
Current Number of Allocated Threads 0
Current Number of Connections 0
Min Number of Threads 10
Max Number of Threads 1000
更新連接服務特性
您可以使用 update 子指令變更表 6-7 中列出的一個或多個服務特性的值。
表 6-7 imqcmd 更新的連接服務特性
特性
說明
port
指定給要更新的服務之連接埠 (不適用於 httpjms 或 httpsjms)。0 值表示連接埠對映器會動態配置連接埠。
minThreads
指定給服務的執行緒之最小數目。
maxThreads
指定給服務的最大執行緒數目。
以下指令將指定給 jms 服務之執行緒的最小數目變更至 20。
imqcmd update svc -n jms -o "minThreads=20"
顯示連接服務度量
若要顯示有關單一服務的度量資訊，請使用 metrics 子指令。例如，若要取得由 jms 連接服務處理之訊息和封包的累計總數，請使用：
imqcmd metrics svc -n jms -m ttl -u admin -p admin
此指令的輸出如下：
-------------------------------------------------
Msgs Msg Bytes Pkts Pkt Bytes
In Out In Out In Out In Out
-------------------------------------------------
164 100 120704 73600 282 383 135967 102127
657 100 483552 73600 775 876 498815 149948
如需使用 imqcmd 報告連接服務度量的更多詳細說明，請參閱「監視工具」。
暫停與繼續連接服務
若要暫停管理服務 (無法暫停) 之外的任何服務，請使用以下指令：
imqcmd pause svc -n serviceName -u admin -p admin
暫停服務會造成以下影響：
若要繼續服務，請使用以下指令：
imqcmd resume svc -n serviceName -u admin -p admin
取得連接資訊指令公用程式包括允許您列出和取得連接相關資訊的子指令。
表 6-8 列出適用於連接的 imqcmd 子指令。如果未指定主機名稱或連接埠，則假設它們為 localhost 和 7676。
表 6-8 用於管理連接服務的 imqcmd 子指令
子指令語法
說明
list cxn [-svn serviceName]
[-b hostName:port]列出預設代理程式上指定服務名稱的所有連接，或指定主機和連接埠上代理程式上的所有連接。如果未指定服務名稱，則會列出所有服務。
query cxn -n connectionID
[-b hostName:port]顯示在預設代理程式或指定主機和連接埠上的代理程式上，指定服務的相關資訊。
若要查詢並顯示單一服務的相關資訊，請使用查詢子指令。例如，
imqcmd query cxn -n 421085509902214374 -u admin -p admin
此指令的輸出如下：
Connection ID 421085509902214374
User guest
Service jms
Producers 0
Consumers 1
Host 111.22.333.444
Port 60953
Client ID
Client Platform
管理目標所有 Message Queue 訊息均可經由在特定代理程式上建立的佇列和主題目標，路由至它們的使用者用戶端。
指令公用程式包括允許您執行以下目標管理工作的子指令：
如需目標的介紹，請參閱「實體目標」。
表 6-9 提供了 imqcmd 目標子指令的摘要。如果代理程式不是預設代理程式 (localhost:7676)，請記得指定它的主機名稱和連接埠。
表 6-9 用於管理目標的 imqcmd 子指令
子指令語法
說明
compact dst [-t destType
-n destName]壓縮用於指定類型與名稱之目標的內建且基於檔案的資料倉庫。如果沒有指定目標類型與名稱，則會壓縮所有目標。必須在壓縮目標前暫停目標。
create dst -t destType
-n destName
[-o attribute=value]
[-o attribute=value1]...建立指定類型、指定名稱以及指定屬性的目標。目標名稱必須僅包含字母數字字元 (無空格)，並且以字母字元或字元「_」和「$」開頭。它們不可以以「mq」字元字串開頭。
destroy dst -t destType
-n destName銷毀指定類型和名稱的目標。
list dst [-t destType] [-tmp]
列出所有指定類型的目標，以及列出暫存目標的選項 (請參閱「暫存目標」)。
類型引述可以有兩個值：
destType = q (queue)
destType = t (topic)如果未指定類型，則會列出所有類型的所有目標。
metrics dst -t destType
-n destName
[-m metricType]
[-int interval]
[-msp numSamples]顯示有關指定類型和名稱之目標的度量資訊。
使用 -m 選項指定要顯示的度量類型：
ttl 顯示目標流入和流出訊息和封包以及常駐記憶體的度量。(預設度量類型)
rts 顯示目標 (每秒) 流入和流出訊息和封包之流量速率的度量，及其他速率資訊。
con 顯示使用者相關的度量。
dsk 顯示磁碟使用度量。
使用 -int 選項，指定顯示度量的間隔時間 (以秒為單位)。預設為 5 秒鐘。
使用 -msp 選項，指定輸出中顯示的範例數目。預設的數目為沒有限制 (無限)。
pause dst [-t destType
-n destName]
[-pst pauseType]針對指定類型和名稱的目標，暫停至使用者的訊息發送 (-pst CONSUMERS)，或暫停來自產生者的訊息發送 (-pst PRODUCERS)，或者兩者皆暫停 (-pst ALL)。如果沒有指定目標類型與名稱，則會暫停所有目標。預設為 ALL。
purge dst -t destType
-n destName清除在指定類型與名稱的目標的訊息。
query dst -t destType
-n destName列出指定類型和名稱之目標的相關資訊。
resume dst [-t destType
-n destName]繼續用於指定類型和名稱之暫停目標的訊息發送。如果沒有指定目標類型與名稱，則會繼續所有目標。
update dst -t destType
-n destName
-o attribute=value
[-o attribute=value1]…更新指定目標上的指定屬性的值。
屬性名稱可以為表 6-10 中所述的任何屬性。
建立目標
建立目標時，您必須指定以下項目：
很多目標屬性是用來管理代理程式記憶體資源和訊息流量。例如，您可以指定允許用於目標的產生者最大數目，或目標中允許的最大訊息數目 (或大小)。這些限制與使用代理程式配置特性，在代理程式範圍基礎上進行配置相似 (請參閱「管理記憶體資源和訊息流量」)。您也可以指定達到這些限制時，代理程式確認的方式。
還有僅適用於佇列目標的目標屬性。這些屬性可用來指定使用中或備份使用者的數目，這些使用者在至多個使用者的訊息負載平衡發送時使用 (請參閱 「佇列目標」)。
表 6-10 描述適用於每個目標類型的屬性。建立或更新目標時，可以配置屬性值。針對自動建立的目標，請在代理程式實例配置檔案中配置預設特性值。(請參閱「配置檔案」)。
表 6-10 目標屬性
目標類型
屬性
預設值
說明
佇列和主題
maxNumMsgs1
-1
(無限制)指定目標中允許給未使用訊息的最大數目。
佇列和主題
maxTotalMsgBytes1
-1
(無限制)指定目標中允許給未使用訊息的最大總記憶體容量 (以字元組為單位)。
佇列和主題
limitBehavior
REJECT_
NEWEST指定達到記憶體限制執行緒時，代理程式確認的方式。值為：
FLOW_CONTROL - 減緩產生者速度
REMOVE_OLDEST - 拋出最舊的訊息
REMOVE_LOW_PRIORITY - 根據訊息存在時間，拋出具最低優先權的訊息 (生產型用戶端不會收到訊息刪除的通知)
REJECT_NEWEST - 拒絕最新資訊 (拒絕永久性訊息時，生產型用戶端會發生異常，但拒絕非永久性訊息時則不會收到通知)
佇列和主題
maxBytesPerMsg
-1
(無限制)指定允許給目標中任何單一訊息的最大容量 (以字元組為單位)。拒絕永久性訊息時，生產型用戶端會發生異常，但拒絕非永久性訊息時則不會收到通知。
佇列和主題
maxNumProducers1
-1
(無限制)指定允許給目標中產生者的最大數目。達到限制時，將無法建立新的產生者。
僅佇列
maxNumActiveConsumers
1
指定最大使用者數，此數值可作用於來自佇列目標的負載平衡發送。值 -1 表示沒有限制數目。
(平台版本會將此值限制為 2。)僅佇列
maxNumBackupConsumers
0
指定最大備份使用者數，如果無法從佇列目標進行負載平衡發送，那麼這些使用者可以取代作用中的使用者。值 -1 表示沒有限制數目。
佇列和主題
consumerFlowLimit
主題： 1000
佇列： 1000
指定最大訊息數目，這些訊息將會發送給單一批次中的某個使用者。在負載平衡佇列發送中，負載平衡開始前，此數目是路由到作用中使用者的佇列訊息初始數目。 (請參閱「佇列發送至多個使用者」)。目標的使用者在其個別連接上，可指定一個較低的值來置換此限制 (請參閱「Message Queue Java 用戶端開發人員指南」中連線工廠屬性的相關資訊)。值 -1 表示沒有限制數目。
僅佇列
localDeliveryPreferred
false
僅適用於代理程式叢集中的負載平衡佇列發送。如果本地代理程式沒有使用者，則指定訊息僅發送給遠端使用者。要求目標不僅限於本地發送 (isLocalOnly = false)。
佇列和主題
isLocalOnly
false
僅適用於代理程式叢集。指定在其他代理程式上不重複目標，且限制目標僅發送訊息給本地使用者 (連接到目標上所建立之代理程式的使用者)。一旦建立目標，即無法更新屬性。
1. 在叢集環境中，此特性適用於叢集中的每個目標實例，但整體上，不適用於叢集中的所有實例。
請注意：目標名稱必須僅包含字母數字字元 (無空格)，且以字母字元或字元「_」和「$」開頭。它不可以以「mq」(保留供度量主題目標使用) 字元字串開頭 (請參閱表 2-8)。
列出目標
您可以取得目標目前屬性值的相關資訊，這些屬性值是關於與目標相關之產生者或使用者的數目，以及訊息傳送度量，例如目標中訊息的數目和大小。
若要尋找您要取得相關資訊的目標，您可以先使用list dst 子指令列出特定代理程式上的所有目標。例如，若要取得在連接埠 4545 的 myHost 上執行之代理程式的所有目標，請輸入以下指令：
imqcmd list dst -b myHost:4545
list dst 子指令可選擇性指定要列出的目標類型，或選擇性納入暫存目標 (使用 -tmp 選項)。用戶端建立的暫存目標，通常用來接收傳送到其他用戶端的訊息確認
(請參閱「暫存目標」)。顯示目標資訊
若要取得目標目前屬性值的相關資訊，請使用 query dst 子指令，例如下列指令：
imqcmd query dst -t q -n XQueue -u admin -p 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 100
Is Local Destination false
Local Delivery is Preferred false
輸出也會顯示與目標相關之產生者與使用者的數目。對佇列目標而言，此輸出同時包括作用中和備份使用者。
您可以使用 update dst 子指令變更一個或多個屬性的值 (請參閱「更新目標屬性」)。
更新目標屬性
透過使用 update dst 子指令和 -o 選項指定要更新的屬性，您可以變更目標的屬性。如果要更新多個屬性，您可以多次使用 -o 選項。例如，以下指令將 maxBytesPerMsg 屬性變更至 1000，並將 MaxNumMsgs 屬性變更至 2000：
imqcmd update dst -t q -n myQueue -o "maxBytesPerMsg=1000"
-o "maxNumMsgs=2000" -u admin -p admin請參閱表 6-10，以獲得您可以更新的屬性清單。
您無法使用 update dst 子指令更新目標的 類型或更新 isLocalOnly 屬性。
顯示目標度量
若要取得與目標相關的訊息度量資訊，請使用 metrics dst 子指令，例如下列指令：
imqcmd metrics dst -t q -n XQueue -m ttl -u admin -p admin
此指令的輸出如下：
-----------------------------------------------------------------------------
Msgs Msg Bytes Msg Count Total Msg Bytes (k) Largest
In Out In Out Current Peak Avg Current Peak Avg Msg (k)
-----------------------------------------------------------------------------
200 200 147200 147200 0 200 0 0 143 71 0
300 200 220800 147200 100 200 10 71 143 64 0
300 300 220800 220800 0 200 0 0 143 59 0
如需使用 imqcmd 報告目標度量的更多詳細說明，請參閱「監視工具」。
暫停和繼續目標
您可以暫停目標，以便控制從產生者發送訊息到目標，或從目標發送訊息到使用者，或同時控制上述兩個動作。要特別注意的是，您可以暫停到目標的訊息流量，以避免目標在訊息產生速度高於使用速度時收到過多訊息。
若要暫停發送到目標的訊息或暫停從目標發送的訊息，請使用 pause dst 子指令，如以下指令所示：
imqcmd pause dst -n myQueue -t q -pst PRODUCERS -u admin -p admin
imqcmd pause dst -n myTopic -t t -pst CONSUMERS -u admin -p admin
當您暫停目標後想要繼續發送，請輸入以下指令：
imqcmd resume dst -n myQueue -t q
在多重代理程式叢集中，目標實例會常駐在叢集中的每個代理程式。您必須個別暫停這些目標。
清除目標
您可以清除目前在目標上形成佇列的所有訊息。清除目標意味著刪除在實體目標上形成佇列的所有訊息。當目標上累積的訊息佔用太多的系統資源時，您可能需要清除訊息。當佇列沒有任何註冊的使用者用戶端並要接收許多訊息時，可能需要清除訊息。如果非作用中的主題長期用戶未成為作用中的用戶，也可能需要清除訊息。在這兩種情況下，訊息均會被不必要地保留。
若要清除在目標的訊息，請使用 purge dst 子指令，如以下指令所示：
imqcmd purge dst -n myQueue -t q -u admin -p admin
imqcmd purge dst -n myTopic -t t -u admin -p admin
如果您已關閉代理程式，並且不想在重新啟動它時發送舊的訊息，請使用 -reset messges 選項清除舊的訊息，例如：
imqbrokerd -reset messages -u admin -p admin
這可避免重新啟動代理程式後清除目標的麻煩。
在多重代理程式叢集中，目標實例會常駐在叢集中的每個代理程式。您必須個別清除這些目標。
銷毀目標
若要銷毀目標，請使用 destroy dst 子指令，如以下指令所示：
imqcmd destroy dst -t q -n myQueue -u admin -p admin
銷毀目標會清除此目標上的所有資訊，並從代理程式中移除此目標；此作業不可復原。
壓縮目標
如果您使用內建且基於檔案的資料倉庫 (而非外掛式 JDBC 相容的資料倉庫) 作為用於訊息的永久性倉庫，您可以監視磁碟使用和壓縮磁碟 (需要時)。
建立基於檔案的訊息倉庫，以便根據訊息於目標的位置，將訊息儲存在目錄中。在各個目標的目錄中，大部分的訊息會儲存在一個智慧型記錄 (即智慧型記錄檔案) 組成的檔案中。(若要減少分段程序，大小超過可配置執行緒的訊息將會儲存在其個別的檔案中。)因為會存留不同大小的訊息，接著從智慧型記錄檔案移除這些訊息，所以檔案中可能會產生空白片段，且將無法再重新使用這些可用記錄。
若要管理未使用的可用記錄，使用率下降時，指令公用程式包括每個目標監視磁碟使用及回收可用磁碟空間的子指令。
監視目標的磁碟使用
若要監視目標的磁碟使用，請使用以下 imqcmd 子指令：
imqcmd metrics dst -t q -n myQueue -m dsk -u admin -p admin
此指令的輸出如下：
--------------------------------------
Reserved Used Utilization Ratio
--------------------------------------
806400 804096 99
1793024 1793024 100
2544640 2518272 98
子指令輸出中的欄有以下意思：
表 6-11 目標磁碟使用度量
度量
說明
已保留
所有記錄使用的磁碟空間 (以字元組為單位)，包括保留作用中訊息和等待被重新使用之可用記錄的記錄
已使用
保留作用中訊息的記錄所使用的磁碟空間 (以字元組為單位)
使用率
使用的磁碟空間除以保留的磁碟空間所得之商數比率越高表示有越多磁碟空間被用來保留作用中訊息。
回收未使用的目標磁碟空間
磁碟使用模式依使用特定目標之訊息傳送應用程式的特徵而異。根據流入和流出目標的相關訊息流量和相關的訊息大小，保留的磁碟空間可能會不斷增加。
如果訊息產生速率大於訊息使用速率，那麼通常會重新使用可用記錄，且使用率應較高。但是，如果訊息產生速率與訊息使用速率相似或小於訊息使用速率，那麼使用率會比較低。
一般而言，您會穩定保留的磁碟空間並保持高使用率。根據經驗，如果系統到達一個穩定狀態，即保留的磁碟空間非常固定且使用率高 (75% 以上)，那麼就沒有需要回收未使用著磁碟空間。如果系統到達穩定狀態且使用率低 (50% 以下)，您可以壓縮磁碟，回收可用記錄佔用的磁碟空間。
如果保留的磁碟空間不斷增加，您應藉由配置目標記憶體限制特性和限制行為，重新配置目標的記憶體管理 (請參閱表 6-10)。
若要回收未使用的目標磁碟空間
如果未指定目標類型和名稱，則會在所有目標上執行這些作業。
管理長期訂閱您可能需要使用 imqcmd 子指令管理代理程式的長期訂閱。長期訂閱是指由用戶端註冊為長期的主題訂閱；它具有唯一的身份，並要求代理程式保留此訂閱的訊息 (即使它的使用者成為非作用中的使用者)。通常，代理程式僅在為長期用戶保留的訊息過期時，才刪除該訊息。
表 6-12 提供了 imqcmd 長期訂閱子指令的摘要。如果代理程式不是預設 (localhost:7676) 代理程式，請記得指定它的主機名稱和連接埠。
表 6-12 用於管理長期訂閱的 imqcmd 子指令
子指令
說明
list dur -d destName
列出指定目標的所有長期訂閱。
destroy dur -n subscrName
-c client_id使用指定的用戶端識別碼銷毀指定的長期訂閱 (請參閱「用戶端識別碼」)。
purge dur -n subscrName
-c client_id使用指定的用戶端識別碼清除指定之長期訂閱的所有訊息 (請參閱「用戶端識別碼」)。
例如，以下指令列出主題 SPQuotes 的所有長期訂閱
imqcmd list dur -d SPQuotes
對於主題的每個長期訂閱，list dur 子指令會傳回長期訂閱的名稱、使用者的用戶端 ID、在此主題上形成佇列的訊息數目以及長期訂閱的狀態 (作用中/非作用中)。例如：
Name Client ID Number of Durable Sub
Messages State
----------------------------------------------------------------
myDurable myClientID 1 INACTIVE
您可以使用從 list dur 子指令傳回的資訊，識別您可能要銷毀或要為其清除訊息的長期訂閱。使用訂閱名稱和用戶端 ID 識別此訂閱。例如：
imqcmd destroy dur -n myDurable -c myClientID
管理異動由用戶端應用程式啟動的所有異動可由代理程式追蹤。這些異動可以是簡單的 Message Queue 異動或由 XA 資源管理員管理的分散式異動 (請參閱「本地異動」)。每個異動都有 Message Queue 異動 ID，即在代理程式上唯一識別異動的 64 位元的號碼。分散式異動還有由分散式異動管理員指定的分散式異動 ID (XID)，此 ID 長達 128 個位元組。Message Queue 可維護 Message Queue 異動 ID 與 XID 的關聯。
如果發生故障，分散式異動很可能未經確定便處於 PREPARED 狀態。因此，作為管理員，您可能需要監視然後回轉或確定處於準備狀態的異動。
表 6-13 提供了 imqcmd 異動子指令的摘要。如果代理程式不是預設 (localhost:7676) 代理程式，請記得指定它的主機名稱和連接埠。
表 6-13 用於管理異動的 imqcmd 子指令
子指令
說明
list txn
列出要由代理程式追蹤的所有異動。
query txn -n transaction_id
列出指定異動的相關資訊。
commit txn -n transaction_id
確定指定的異動。
rollback txn -n transaction_id
回轉指定的異動。
例如，以下指令列出代理程式中的所有異動。
imqcmd list txn
對於每個異動，list 子指令會傳回異動 ID、狀態、使用者名稱、訊息或確認的數目以及建立時間。例如：
---------------------------------------------------------------
Transaction ID State User name # Msgs/ Creation time
# Acks
---------------------------------------------------------------
64248349708800 PREPARED guest 4/0 1/30/02 10:08:31 AM
64248371287808 PREPARED guest 0/4 1/30/02 10:09:55 AM
此指令顯示代理程式中的所有本機異動和分散式異動。您僅能確定或回轉處於 PREPARED 狀態的異動。如果您知道由於故障使異動處於此狀態，並且此異動未處於由分散式異動管理員確定的過程中，您應確定或回轉此異動。
例如，如果代理程式的自動回轉特性配置為 false (請參閱表 2-4)，那麼您必須在啟動代理程式時手動確定或回轉處於 PREPARED 狀態的異動。
list 子指令還顯示在異動中產生的訊息數目，以及在異動 (#Msgs/#Acks) 中確認的訊息數目。這些訊息不會被發送，並且確認也不會被處理，直至異動被確定。
query 子指令可讓您查閱相同的資訊以及一些其他值：用戶端 ID、連接識別以及分散式異動 ID (XID)。例如，
imqcmd query txn -n 64248349708800
產生的輸出如下：
Client ID
Connection guest@192.18.116.219:62209->jms:62195
Creation time 1/30/02 10:08:31 AM
Number of acknowledgements 0
Number of messages 4
State PREPARED
Transaction ID 64248349708800
User name guest
XID
6469706F6C7369646577696E6465723130313234313431313030373230
commit 和 rollback 子指令可用於確定或回轉分散式異動。如前面所提及，僅可確定或回轉處於 PREPARED 狀態的異動。例如：
imqcmd commit txn -n 64248349708800
還可配置代理程式，以在啟動代理程式時自動回轉處於 PREPARED 狀態的異動。請參閱表 2-4 中的 imq.transaction.autorollback 特性，以獲得更多資訊。