modifySIBDestination 指令

請利用 modifySIBDestination 指令來變更服務整合匯流排的匯流排目的地內容。

如果要執行這個指令，請使用 wsadmin Scripting 用戶端的 AdminTask 物件。

[IBM i][IBM i]從 Qshell 執行 wsadmin Scripting 用戶端。

服務整合匯流排指令有指令行說明：
  • 如需 Jython 中可用的服務整合匯流排指令清單，以及每個指令的簡要說明，請在 wsadmin 提示下，輸入下列指令：

    print AdminTask.help('SIBAdminCommands')

  • 如需給定指令的概觀說明，請在 wsadmin 提示下，輸入下列指令：

    print AdminTask.help('command_name')

使用指令之後，請利用下列指令，儲存對主要配置所做的變更：

AdminConfig.save()

用途

modifySIBDestination 會變更服務整合匯流排的匯流排目的地內容。

目標物件

匯流排目的地。

必要參數

-bus
在其中配置匯流排目的地的服務整合匯流排名稱。 您可以使用 listSIBuses 指令列出現有匯流排的名稱。
-name
用來識別這個目的地以進行管理的 ID。

條件式參數

無。

選用參數

-description
指定匯流排目的地的說明，以進行管理。
-reliability
指定在生產者應用程式尚未設定明確可靠性時，要指派給產生至此目的地之訊息的預設可靠性層次。 服務整合支援可靠性層次（也稱為遞送選項或服務品質）：
BEST_EFFORT_NONPERSISTENT
傳訊引擎停止或失效時捨棄的訊息。 訊息也可能因為用來傳送訊息的連線無法使用，或系統資源受到限制，而遭到捨棄。
EXPRESS_NONPERSISTENT
傳訊引擎停止或失效時捨棄的訊息。 如果用來傳送訊息的連線無法使用，也可能捨棄訊息。
RELIABLE_NONPERSISTENT
傳訊引擎停止或失效時捨棄的訊息。
RELIABLE_PERSISTENT
當傳訊引擎失敗時，可能會捨棄訊息。
ASSURED_PERSISTENT
不捨棄訊息。
附註: 可靠性層次越高，對效能的影響越大。

如需服務整合可靠性層次的相關資訊，請參閱 訊息可靠性層次-JMS 遞送模式和服務整合服務品質。

-overrideOfQOSByProducerAllowed TRUE | FALSE
控制生產者和目的地之間訊息流程的服務品質。 選取此選項，用生產者指定的服務品質來取代定義給目的地的品質。
-defaultPriority 數字
當生產者未設定優先順序時，指派給傳送到這個目的地之訊息的預設優先順序。
-maxFailedDeliveries 數字
嘗試處理訊息的失敗次數上限。 一旦超過這個失敗嘗試次數，即會將訊息從預期的目的地轉遞至其異常狀況目的地。 請指定在 0 到 2147483647範圍內的值。 值 0 (零) 表示如果第一次嘗試時無法遞送訊息，則會將訊息轉遞至異常狀況目的地或捨棄 (如 -exceptionDestination 參數所定義)。
-exceptionDestination 值
使用這些內容，可定義任何無法遞送到此目的地的訊息會發生什麼情況。
依預設，所有無法遞送至這個目的地的訊息都會重新遞送至這個目的地所指派之傳訊引擎的系統預設異常狀況目的地 (_SYSTEM.Exception.Destination.messaging_engine_name)。 請利用這個參數來置換預設值。 您可以對這個目的地設定特定的異常狀況目的地，也可以輸入空字串 ("")，指定無法遞送的訊息不要重新遞送到異常狀況目的地，這時失敗的遞送次數上限計數沒有作用。
附註: 無法遞送的訊息可能會阻止處理等待遞送至相同目的地的其他訊息。
您可以使用這個選項，指定無異常狀況目的地，以保留訊息排序。
-sendAllowed TRUE | FALSE
清除這個選項 (將它設為 FALSE) ，讓生產者無法將訊息傳送到這個目的地。
  • 對於非調解目的地的佇列點，或調解目的地的調解點，如果您清除這個選項，則會將新訊息 (從附加的產生者或從另一個目的地轉遞) 重新導向至任何可用的訊息點。 如果沒有可用的訊息點，匯流排會保留已接受到匯流排的訊息，以及來自附加生產者的新訊息，直到訊息點變成可用為止。 唯一的例外是只有一個訊息點的目的地 (佇列點或調解點，視目的地是調解或非調解而定) ，其中生產者連接到相同的傳訊引擎。 在此情況下，每次傳送呼叫都會產生異常狀況訊息。 異常狀況訊息指出已停用唯一的現存本地化傳送。 生產者仍照常開啟，如果重新選取本地化的 容許傳送 內容 (重設為 TRUE) ，則任何其他傳送呼叫都會成功。
  • 對於調解目的地的佇列點，如果您清除這個選項，則調解實例中的訊息會重新導向至任何可用的訊息點。 如果沒有可用的訊息點，匯流排會保留這些訊息，直到訊息點變成可用為止。 對於任何調解實例 (亦即，在具有調解點的任何伺服器上) ，如果相同伺服器管理佇列點，且該佇列點是目的地的唯一佇列點，則調解會變更為 stopped on error 狀態。
-receiveAllowed TRUE | FALSE
清除這個選項（將它設為 false），消費者便無法接收來自這個目的地的訊息。 對於訊息點，如果您清除這個選項，則任何開啟的消費者都會變更狀態，如果消費者要求訊息，則會產生異常狀況。 訊息可以繼續傳送，並累積在訊息點上。
-receiveExclusive TRUE | FALSE
選取這個選項（將它設為 true），便只允許一個消費者連接到目的地。 如果您選取此選項，則一次只能將單一消費者連接至佇列目的地的每一個佇列點。 嘗試連接至已連接消費者的佇列點的後續消費者會被拒絕。
-maintainStrictMessageOrder TRUE | FALSE
選取此選項 (將它設為 TRUE) ，以維護生產者將訊息傳送至目的地的順序。
在執行時期，此內容優先於其他配置內容值。 如需在執行時期置換之配置內容的相關資訊，請參閱 匯流排目的地的嚴格訊息排序。
附註: 如果在現有主題目的地上啟用嚴格訊息排序，則任何現有的可延續訂閱以及相關聯的訊息都會變成無效。 當啟用嚴格訊息排序，且已重新啟動環境時，會刪除及重建現有的可延續訂閱；也會刪除與可延續訂閱相關聯的訊息。
-topicAccessCheckRequired
如果需要授權檢查才能存取主題，請包含此選項。
-replyDestination
送往這個目的地的訊息的任何非空白反向遞送路徑中所要附加的目的地名稱。 這個內容用來和回覆訊息的調解一起使用。 如需使用此內容的相關資訊，請參閱 配置目的地反向遞送路徑。
-replyDestinationBus
回覆目的地配置在其中的匯流排名稱。 這個內容用來和回覆訊息的調解一起使用。 如需使用此內容的相關資訊，請參閱 配置目的地反向遞送路徑。
-delegateAuthorizationCheckToTarget
指示是否在別名或目標目的地上執行授權檢查。 如果您想要在目標目的地上執行授權檢查，請包含此選項。
-auditAllowed TRUE | FALSE
清除這個選項 (將它設為 FALSE) ，當匯流排和應用程式伺服器已啟用審核時，防止匯流排審核主題層次授權檢查。 預設值為 true。 您必須具有「審核管理者」專用權才能使用此參數。 如果在建立其他類型的目的地時使用此參數，則會忽略此參數。
-defaultForwardRoutingPath
如果訊息未包含正向遞送路徑，則為訊息正向遞送路徑所設定的值。 這是識別訊息在送達目標匯流排目的地之前， 必須循序經過的中繼匯流排目的地清單。

欄位的格式是完整匯流排目的地清單。 每一個完整匯流排目的地包含一個 bus_name ，後面接著 destination_name 。

如果指定多個完整匯流排目的地，請以空格區隔每一個完整匯流排目的地。

例如，您指定 (在 Jython 中) 包含來自 BUS1 的 Queue1 及來自 BUS2 的 Queue2 的遞送路徑，如下所示:
-defaultForwardRoutingPath=[[BUS1 Queue1] [BUS2 Queue2]]
-queuePoints
別名目的地的使用者所使用的佇列點清單。 如果未提供特定的佇列點，則可以使用所有佇列點。 目標目的地必須是與別名目的地定義位於相同匯流排中的佇列目的地。 目標目的地也必須是具有多個佇列點的佇列目的地。

以下列格式指定佇列點: destination_name@messaging_engine_name

-useAllQueuePoints TRUE | FALSE
如果您將此選項設為 TRUE ，則會使用所有可用的佇列點，而如果將此選項設為 FALSE，則只會使用 -queuePoints 選項所指定清單中的那些佇列點。
-mediationPoints
別名目的地的使用者所使用的調解點清單。 如果未提供特定的調解點，則可以使用所有調解點。 在與別名目的地定義相同的匯流排中，目標目的地必須是調解的佇列目的地。 目標目的地也必須是具有多個調解點的佇列目的地。

調解點以下列格式指定: destination_name@messaging_engine_name

-useAllMediationPoints TRUE | FALSE
如果您將此選項設為 TRUE ，則會使用所有可用的佇列點，而如果將此選項設為 FALSE，則只會使用 -mediationPoints 選項所指定清單中的那些佇列點。
-persistRedeliveryCount TRUE | FALSE
選取此選項 (將它設為 TRUE) ，以將 JMS 訊息的失敗遞送計數持續保存在訊息儲存庫中。 依預設，選項的值會設為 FALSE 。
重要事項: 雖然選取此內容，但在使用 WebSphere® Application Server 9.0 以及更新版本的 sibDBUpgrade 指令升級資料庫表格之前，此內容將不會生效。

範例

  • 使用 Jython：
    wsadmin>AdminTask.showSIBDestination([-bus, abus, -name, myqueue])
{receiveExclusive=false, defaultForwardRoutingPath=[], defaultPriority=0, 
exceptionDestination=_SYSTEM.Exception.Destination.node01.aserver-abus, 
uuid=97CC75AC71E5932CAB3417AC,  overrideOfQOSByProducerAllowed=true, 
sendAllowed=true, maxFailedDeliveries=5, 
maxReliability=ASSURED_PERSISTENT, reliability=ASSURED_PERSISTENT, 
receiveAllowed=true, identifier=myqueue}

wsadmin>AdminTask.modifySIBDestination([-bus, abus, -name, myqueue,
 -receiveAllowed, FALSE])

wsadmin>AdminTask.showSIBDestination([-bus, abus, -name, myqueue])
{receiveExclusive=false, defaultForwardRoutingPath=[], defaultPriority=0, 
exceptionDestination=_SYSTEM.Exception.Destination.node01.aserver-abus, 
uuid=97CC75AC71E5932CAB3417AC, overrideOfQOSByProducerAllowed=true, 
sendAllowed=true, maxFailedDeliveries=5,  
maxReliability=ASSURED_PERSISTENT, reliability=ASSURED_PERSISTENT, 
receiveAllowed=false, identifier=myqueue}
  • 使用 Jacl：
    wsadmin>$AdminTask showSIBDestination {-bus abus -name myqueue} 
{receiveExclusive=false, defaultForwardRoutingPath=[], defaultPriority=0, 
exceptionDestination=_SYSTEM.Exception.Destination.node01.aserver-abus, 
uuid=97CC75AC71E5932CAB3417AC, overrideOfQOSByProducerAllowed=true, 
sendAllowed=true, maxFailedDeliveries=5, 
maxReliability=ASSURED_PERSISTENT, reliability=ASSURED_PERSISTENT, 
receiveAllowed=true, identifier=myqueue}

wsadmin>$AdminTask modifySIBDestination {-bus abus -name myqueue 
-receiveAllowed FALSE}
(cells/9994GKCCell01/buses/abus|sib-destinations.xml#SIBQueue_1098215169998)

wsadmin>$AdminTask showSIBDestination {-bus abus -name myqueue} 
{receiveExclusive=false, defaultForwardRoutingPath=[], defaultPriority=0, 
exceptionDestination=_SYSTEM.Exception.Destination.node01.aserver-abus, 
uuid=97CC75AC71E5932CAB3417AC, overrideOfQOSByProducerAllowed=true, 
sendAllowed=true, maxFailedDeliveries=5,  
maxReliability=ASSURED_PERSISTENT, reliability=ASSURED_PERSISTENT, 
receiveAllowed=false, identifier=myqueue}

範例: 修改目的地別名 MyAlias2 ，以使用可用佇列點和調解點的子集:

  • 使用 Jython：
    cluster=AdminConfig.list(ServerCluster).splitlines()[0]
Qp1=AdminConfig.list(SIBQueueLocalizationPoint , cluster).splitlines()[0]
Mp1=AdminConfig.list(SIBMediationLocalizationPoint).splitlines()[0]
AdminTask.modifySIBDestination([-bus , bus1 , -name , MyAlias2, 
 -queuePoints, [[Qp1]], -mediationPoints , [[Mp1]]])
  • 使用 Jacl：
    set cluster [ lindex [ $AdminConfig list ServerCluster ] 1 ]
set Qp1 [ lindex [ $AdminConfig list SIBQueueLocalizationPoint $cluster ] 0 ]
set Mp1 [ lindex [ $AdminConfig list SIBMediationLocalizationPoint ] 0 ]
$AdminTask modifySIBDestination {-bus bus1 -name MyAlias2 
 -queuePoints [[$Qp1]]-mediationPoints [[$Mp1]]}

範例: 修改目的地別名，以移除所使用佇列點的任何限制:

  • 使用 Jython：
    AdminTask.modifySIBDestination([-bus , bus1 , -name , MyAlias2, 
 -queuePoints, [[]]])
  • 使用 Jacl：
    $AdminTask modifySIBDestination {-bus bus1 -name MyAlias2 
-useAllQueuePoints=true -useAllMediationPoints=true}

範例: 設定預設訊息正向遞送路徑:

  • 使用 Jython：
    
AdminTask.showSIBDestination(["-bus", "abus", "-name", "myqueue"])                                                            
"{receiveExclusive=false, defaultForwardRoutingPath=[], defaultPriority=0,                                            
exceptionDestination=_SYSTEM.Exception.Destination.node01.aserver-abus,                                                                     
uuid=97CC75AC71E5932CAB3417AC, overrideOfQOSByProducerAllowed=true,    
sendAllowed=true, maxFailedDeliveries=5,                                
maxReliability=ASSURED_PERSISTENT, reliability=ASSURED_PERSISTENT,      
receiveAllowed=true, identifier=myqueue}"                               

    
AdminTask.modifySIBDestination(["-bus", "abus", "-name", "myqueue", "-receiveAllowed", 
"FALSE", "-defaultForwardRoutingPath", "[[abus queue1] [abus Queue2]]"])        

    
AdminTask.showSIBDestination(["-bus", "abus", "-name", "myqueue"])                                                            
"{receiveExclusive=false, defaultForwardRoutingPath=[[abus, queue1] [abus, Queue2]],                                                       
defaultPriority=0, exceptionDestination=_SYSTEM.Exception.Destination.node01.aserver-abus,                                                                     
uuid=97CC75AC71E5932CAB3417AC, overrideOfQOSByProducerAllowed=true,     
sendAllowed=true, maxFailedDeliveries=5,                                
maxReliability=ASSURED_PERSISTENT, reliability=ASSURED_PERSISTENT,      
receiveAllowed=false, identifier=myqueue}"