上一章 目錄 索引 下一章 |
Sun Java System Message Queue 3.5 SP1 管理指南

> ## 第 6 章
> 代理程式和應用程式管理

> 本章介紹如何執行與管理代理程式及其提供的服務相關的工作。其中的某些工作獨立於任何特定的用戶端應用程式。這些工作包括：

> - 控制代理程式的狀態：您可以暫停、繼續、關閉以及重新啟動代理程式。
> - 查詢與更新代理程式特性
> - 管理連接服務

> 其他代理程式工作作為特定應用程式執行；這些工作包括管理實體目標、長期訂閱以及異動：

> - Message Queue 訊息經由代理程式目標路由至它們的接收者或用戶。您負責在代理程式上建立這些目標。
> - Message Queue 為長期用戶配置並維護資源，即使擁有長期訂閱的用戶端成為非作用中的用戶端。使用 Message Queue 指令工具可取得長期訂閱的相關資訊，並可銷毀長期訂閱或清除它們的訊息以便儲存 Message Queue 資源。
> - Message Queue 異動與分散式異動由代理程式追蹤。如果發生故障，您可能需要手動確定或回轉異動。

> 本章介紹如何使用指令公用程式 (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 中列出的子指令：本章的相關工作各節內容會更加詳細說明子指令。

> 表 6-1 imqcmd 子指令

> 子指令與引數 | 說明
> --- | ---
> commit txn | 確定異動。
> compact dst | 壓縮用於一個或多個目標的內建且基於檔案的資料倉庫。
> create dst | 建立目標。
> destroy dst | 銷毀目標。
> destroy dur | 銷毀長期訂閱。
> list cxn | 列出代理程式的連接。
> list dst | 列出代理程式上的目標。
> list dur | 列出主題的長期訂閱。
> list svc | 列出代理程式上的服務。
> list txn | 列出代理程式上的異動。
> metrics bkr | 顯示代理程式度量。
> metrics dst | 顯示目標度量。
> metrics svc | 顯示服務度量。
> pause bkr | 暫停代理程式上的所有服務。
> pause dst | 暫停代理程式上的一個或多個目標。
> pause svc | 暫停代理程式上的單一服務。
> purge dst | 清除目標上的所有訊息而不銷毀目標。
> purge dur | 清除長期訂閱上的所有訊息而不銷毀長期訂閱。
> query bkr | 查詢並顯示代理程式的相關資訊。
> query cxn | 查詢並顯示連接的相關資訊。
> query dst | 查詢並顯示目標的相關資訊。
> query svc | 查詢並顯示服務的相關資訊。
> query txn | 查詢並顯示異動的相關資訊。
> reload cls | 重新載入代理程式叢集配置。
> restart bkr | 重新啟動目前執行的代理程式實例。不能用於啟動新的代理程式實例。
> resume bkr | 繼續代理程式上的所有服務。
> resume dst | 繼續代理程式上一個或多個暫停的目標。
> resume svc | 繼續服務。
> rollback txn | 回轉異動。
> shutdown bkr | 關閉代理程式實例。接著可以使用 imqbrokerd 指令啟動，而不是使用 imqcmd 的 restart bk r 子指令。
> update bkr | 更新代理程式的屬性。
> update dst | 更新目標的屬性。
> update svc | 更新服務的屬性。

> ### 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 指令以管理代理程式，您必須執行以下作業：

> - 使用 imqbrokerd 指令啟動代理程式。

> 請參閱「啟動代理程式」。您僅可以使用指令公用程式管理執行中的代理程式；您不能使用它啟動代理程式。

> - 使用 -b 選項指定目標代理程式，除非代理程式正在使用連接埠 7676 的本地主機上執行。
> - 指定適當的管理員使用者名稱和密碼。如果您未指定，系統將提示您提供名稱和密碼。而且，請注意您使用 imqcmd 執行的每項作業都將由使用者儲存庫認證。如需更多資訊，請參閱「認證使用者」。

> 當您安裝 Message Queue 時，同時也安裝了預設文字檔案使用者儲存庫。此儲存庫出廠時隨附兩個項目：一個用於擁有管理員權限的使用者，一個用於客人使用者。這些項目可讓您連接至代理程式實例而不執行任何其他工作。例如，如果您僅要測試 Message Queue，則可以使用預設的使用者名稱和密碼 (admin/admin) 來執行 imqcmd 公用程式。

> 如果您要配置生產系統，則將需要執行一些其他工作以認證和授權使用者 (請參閱第 8 章「管理安全性」)。要特別注意的是，您必須在 Message Queue 使用者儲存庫中建立項目 (請參閱「使用文字檔案使用者儲存庫」)。您還可以選擇使用您的使用者儲存庫的現有 LDAP 目錄伺服器 (請參閱「將 LDAP 伺服器用於使用者儲存庫」)。

> ### 範例 imqcmd 的用法

> 以下範例說明 imqcmd 指令的使用：

> - 若要列出在連接埠 7676 的 localhost 執行之代理程式的特性：

> imqcmd query bkr -u admin -p admin

> - 若要列出在連接埠 1564 的 myserver 執行之代理程式的特性，則使用者名稱為 alladin，使用者密碼為 abracadabra。

> imqcmd query bkr -b myserver:1564 -u alladin -p abracadabra

> 假設使用者名稱 alladin 已指定給 admin 群組，您將作為管理用戶端連接至指定的代理程式。

> - 若要列出在連接埠 7676 的 localhost 執行之代理程式的特性，則該指令的初始逾時配置為 20 秒，且重試 (逾時後) 次數配置為 7。

> imqcmd query bkr -u admin -p admin -rtm 20 -rtr 7

> ##

> 管理代理程式

> 指令公用程式包括您可用來執行以下代理程式管理工作的子指令：

> - 顯示代理程式資訊
> - 更新代理程式特性
> - 顯示代理程式度量
> - 控制代理程式的狀態

> 若要管理代理程式的連接服務，請參閱「管理連接服務」。若要管理代理程式目標，請參閱「管理目標」。

> 表 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

> 此指令的輸出如下：

> Version 3.5 SP1
> Instance Name imqbroker
> Primary Port 7676
> Current Number of Messages in System 0
> Current Total Message Bytes in System 0
> Max Number of Messages in System unlimited (-1)
> Max Total Message Bytes in System unlimited (-1)
> Max Message Size 70m
> Auto Create Queues true
> Auto Create Topics true
> Auto Created Queue Max Number of Active Consumers 1
> Auto Created Queue Max Number of Backup Consumers 0
> Cluster Broker List (active)
> Cluster Broker List (configured)
> Cluster Master Broker
> Cluster URL
> Log Level INFO
> Log Rollover Interval (seconds) 604800
> Log Rollover Size (bytes) unlimited (-1)

> ### 更新代理程式特性

> 您可以使用 update bkr 子指令更新表 6-4 中列出的任何代理程式特性。請注意，對代理程式的更新會自動寫入代理程式的實例配置檔案。

> 表 6-4 imqcmd 更新的代理程式特性

> 特性 | 參考
> --- | ---
> imq.autocreate.queue | 表 2-10
> imq.autocreate.topic | 表 2-10
> imq.autocreate.queue.maxNumActiveConsumers | 表 2-10
> imq.autocreate.queue.maxNumBackupConsumers | 表 2-10
> imq.cluster.url | 表 5-3.
> imq.log.level | 表 2-9
> imq.log.file.rolloversecs | 表 2-9
> imq.log.file.rolloverbytes | 表 2-9
> imq.system.max_count | 表 2-4
> imq.system.max_size | 表 2-4
> imq.message.max_size | 表 2-4
> imq.portmapper.port | 表 2-3

> 例如，以下指令會關閉佇列目標的自動建立功能：

> imqcmd update bkr -o "imq.autocreate.queue=false"
> -u admin -p admin

> ### 控制代理程式的狀態

> 啟動代理程式之後，您可以使用以下 imqcmd 子指令控制代理程式的狀態。

> #### 暫停與繼續代理程式

> - 暫停代理程式。暫停代理程式會暫停代理程式的連接服務執行緒，這將導致代理程式停止偵聽連接連接埠。因此，代理程式將無法繼續接受新的連接、接收訊息和派送訊息。

> 但是，暫停代理程式不會暫停管理連接服務。此服務可讓您執行所需的管理工作，以管理代理程式的訊息流量。例如，如果某特定目標受到訊息的攻擊，則您可以暫停代理程式，並執行以下可能幫助您解決問題的任何動作：追蹤訊息來源、限制目標大小或銷毀目標。

> 暫停代理程式也不會暫停叢集連接服務。但是，叢集中的訊息發送會根據叢集中不同代理程式執行的發送功能而有差異。

> 以下指令暫停在使用連接埠 1588 的 myhost 上執行的代理程式。

> imqcmd pause bkr -b myhost:1588 -u admin -p admin

> (您也可以暫停個別連接服務 (請參閱「暫停與繼續連接服務」) 和個別目標 (請參閱「暫停和繼續目標」)

> - 繼續代理程式。繼續代理程式會重新啟動代理程式的服務執行緒，並且此代理程式會繼續偵聽連接埠。以下指令繼續在使用連接埠 7676 的 localhost 上執行的代理程式。

> imqcmd resume bkr -u admin -p admin

> #### 關閉和重新啟動代理程式

> - 關閉代理程式。關閉代理程式會終止代理程式程序。這是適當的終止：代理程式停止接受新的連接和訊息，它將完成現有訊息的發送並終止代理程式程序。以下指令關閉在使用連接埠 1572 的 ctrlsrv 上執行的代理程式

> imqcmd shutdown bkr -b ctrlsrv:1572 -u admin -p admin

> - 重新啟動代理程式。關閉並重新啟動代理程式。以下指令重新啟動在使用連接埠 7676 的 localhost 上執行的代理程式：

> imqcmd restart bkr -u admin -p admin

> ### 顯示代理程式度量

> 若要顯示有關代理程式的度量資訊，請使用 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

> 暫停服務會造成以下影響：

> - 代理程式會停止接受暫停服務上的新用戶端連接。如果 Message Queue 用戶端嘗試開啟新的連接，將會發生異常。
> - 暫停服務上的所有現有連接會維持持續狀態，但在繼續服務前，代理程式會暫停此類連接上的所有訊息處理。(例如，如果用戶端嘗試傳送訊息，在繼續服務前，send() 方法會封鎖此訊息。)
> - 將會維護任何已被代理程式接收之訊息的訊息發送狀態。(例如，繼續服務時，不會中斷異動且將繼續訊息發送。)

> 若要繼續服務，請使用以下指令：

> 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 中所述的任何屬性。

> ### 建立目標

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

> - 目標類型：主題或佇列
> - 目標名稱：必須僅包含字母數字字元 (無空格)，並且以字母字元或字元「_」和「$」開頭。名稱不可以以「mq」字元字串開頭。
> - 任何用於目標屬性的非預設值

> 很多目標屬性是用來管理代理程式記憶體資源和訊息流量。例如，您可以指定允許用於目標的產生者最大數目，或目標中允許的最大訊息數目 (或大小)。這些限制與使用代理程式配置特性，在代理程式範圍基礎上進行配置相似 (請參閱「管理記憶體資源和訊息流量」)。您也可以指定達到這些限制時，代理程式確認的方式。

> 還有僅適用於佇列目標的目標屬性。這些屬性可用來指定使用中或備份使用者的數目，這些使用者在至多個使用者的訊息負載平衡發送時使用 (請參閱 「佇列目標」)。

> 表 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. 在叢集環境中，此特性適用於叢集中的每個目標實例，但整體上，不適用於叢集中的所有實例。

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

> imqcmd create dst -n myQueue -t q -o "maxNumActiveConsumers=5"

> 請注意：目標名稱必須僅包含字母數字字元 (無空格)，且以字母字元或字元「_」和「$」開頭。它不可以以「mq」(保留供度量主題目標使用) 字元字串開頭 (請參閱表 2-8)。

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

> imqcmd create dst -n myTopic -t t -o "maxBytesPerMsg=5000"

> ### 列出目標

> 您可以取得目標目前屬性值的相關資訊，這些屬性值是關於與目標相關之產生者或使用者的數目，以及訊息傳送度量，例如目標中訊息的數目和大小。

> 若要尋找您要取得相關資訊的目標，您可以先使用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)。

> ##### 若要回收未使用的目標磁碟空間

> 1. 暫停目標。

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

> 2. 壓縮磁碟。

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

> 3. 繼續目標。

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

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

> ##

> 管理長期訂閱

> 您可能需要使用 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 特性，以獲得更多資訊。

> 上一章 目錄 索引 下一章

> Copyright 2004 Sun Microsystems, Inc. All rights reserved.