createSIBDestinations command
Use the createSIBDestinations command to create new bus destinations for a service integration bus.
To run the command, use the AdminTask object of the wsadmin scripting client.
The wsadmin scripting client is run from Qshell.
For more information, see Configuring Qshell to run WebSphere scripts using wsadmin scripting.
- For a list of the available service integration bus commands in Jython and a brief
description of each command, enter the following command at the wsadmin prompt:
print AdminTask.help('SIBAdminCommands')
- For overview help on a given command, enter the following command at the wsadmin
prompt:
print AdminTask.help('command_name')
AdminConfig.save()
Purpose
The createSIBDestinations command creates multiple new bus destinations for a service integration bus, all with the same properties. If the destinations created are alias destinations, they all target the same destination. With this command, the new bus destinations can also be localized to a WebSphere® MQ server bus member.
Target object
A service integration bus.
Required parameters
- -bus
- The name of the service integration bus on which to create the bus destinations. To list the names of existing buses, use the listSIBuses command.
- -nameList
- The list of identifiers by which these destinations are known for administrative purposes.
- -type
- Indicates the type of bus destination that you want to create:
- Alias
- An alias destination, that provides a level of abstraction between applications and the underlying target bus destinations that hold messages. Applications interact with the alias destination, so the target bus destination can be changed without changing the application.
- Foreign
- A foreign destination, which identifies a destination on another bus, and enables applications on one bus to access the destination on another bus directly.
- Port
- Represents a particular message and transport binding for an outbound service that communicates with an externally-hosted target web service.
- Queue
- A queue, for point-to-point messaging.
- TopicSpace
- A topic space, for publish/subscribe messaging.
- WebService
- Represents an externally-hosted target web service.
Conditional parameters
None.
Optional parameters
- -cluster
- To assign the bus destinations to a cluster bus member, specify the name of the cluster. Do not specify the -node, -server or -wmqServer parameters.
- -node
- To assign the bus destinations to a server bus member, specify both the name of the node on which the server runs and the name of the server. Do not specify the -cluster or -wmqServer parameters.
- -server
- To assign the bus destinations to a server bus member, specify both the name of the node on which the server runs and the name of the server. Do not specify the -cluster or -wmqServer parameters.
- -wmqServer
- To assign the bus destinations to a IBM MQ queue, specify both the name of the WebSphere MQ server bus member where the destination is assigned (this parameter), and the name of the IBM MQ queue used to store messages sent to the destinations (the -wmqQueueName parameter). Set the-wmqServer parameter to the name you gave when you created the WebSphere MQ server. Set the -wmqQueueName parameter to the name allocated to the IBM MQ queue by IBM MQ administration. Do not specify the -cluster, -node or -server parameters.
- -aliasBus
- If you are creating alias destinations, specify the source bus name of the alias mapping.
- -targetBus
- If you are creating alias destinations, specify the name of the bus to which the alias destinations are mapped.
- -targetName
- If you are creating alias destinations, specify the name of the destination to which the alias destinations are mapped.
- -foreignBus
- If you are creating foreign destinations specify the name of the foreign bus.
- -description
- Specify a description for the bus destinations for administrative purposes.
- -reliability
- Specify the default reliability level to assign to messages produced to these destinations when
an explicit reliability has not been set by the producer application. Service integration supports five reliability levels (also known as delivery options or qualities of service):
- BEST_EFFORT_NONPERSISTENT
- Messages are discarded when a messaging engine stops or fails. Messages might also be discarded if a connection used to send them becomes unavailable or as a result of constrained system resources.
- EXPRESS_NONPERSISTENT
- Messages are discarded when a messaging engine stops or fails. Messages might also be discarded if a connection used to send them becomes unavailable.
- RELIABLE_NONPERSISTENT
- Messages are discarded when a messaging engine stops or fails.
- RELIABLE_PERSISTENT
- Messages might be discarded when a messaging engine fails.
- ASSURED_PERSISTENT
- Messages are not discarded.
Note: Higher levels of reliability have higher impacts on performance.For more information about service integration reliability levels, see Message reliability levels - JMS delivery mode and service integration quality of service.
- -maxReliability
- Specify the maximum reliability level that is accepted for values specified by producer
applications. Service integration supports five reliability levels (also known as delivery options or qualities of service):
- BEST_EFFORT_NONPERSISTENT
- EXPRESS_NONPERSISTENT
- RELIABLE_NONPERSISTENT
- RELIABLE_PERSISTENT
- ASSURED_PERSISTENT
For more information about service integration reliability levels, see Message reliability levels - JMS delivery mode and service integration quality of service.
- -nonPersistentReliability
Specify the service integration quality of service to use with nonpersistent IBM MQ messages that are received by service integration from a IBM MQ network. The messages in a IBM MQ network have their own quality of service level. This is either persistent or non-persistent. When these messages are received by a service integration application, they are assigned a service integration quality of service level that depends on their IBM MQ quality of service level.
For nonpersistent IBM MQ messages received, the default service integration quality of service is RELIABLE_NONPERSISTENT. If you choose to override this default, you will probably choose one of the other nonpersistent service integration qualities of service BEST_EFFORT_NONPERSISTENT or EXPRESS_NONPERSISTENT. However, you can choose any of the five possible service integration qualities of service:- BEST_EFFORT_NONPERSISTENT
- EXPRESS_NONPERSISTENT
- RELIABLE_NONPERSISTENT
- RELIABLE_PERSISTENT
- ASSURED_PERSISTENT
For more information, see Mapping the JMS delivery option and message reliability to and from the IBM MQ persistence value.
- -persistentReliability
Specify the service integration quality of service to use with persistent IBM MQ messages that are received by service integration from a IBM MQ network. The messages in a IBM MQ network have their own quality of service level. This is either persistent or non-persistent. When these messages are received by a service integration application, they are assigned a service integration quality of service level that depends on their IBM MQ quality of service level.
For persistent IBM MQ messages received, the default service integration quality of service is ASSURED_PERSISTENT. If you choose to override this default, you will probably choose the other persistent service integration quality of service RELIABLE_PERSISTENT. However, you can choose any of the five possible service integration qualities of service:- BEST_EFFORT_NONPERSISTENT
- EXPRESS_NONPERSISTENT
- RELIABLE_NONPERSISTENT
- RELIABLE_PERSISTENT
- ASSURED_PERSISTENT
For more information, see Mapping the JMS delivery option and message reliability to and from the IBM MQ persistence value.
- -overrideOfQOSByProducerAllowed TRUE | FALSE
- Controls the quality of service for message flows between producers and the destination. Select this option to use the quality of service specified by producers instead of the quality defined for the destination.
- -defaultPriority number
- The default priority assigned to messages sent to this destination when a priority has not been set by the producer.
- -maxFailedDeliveries number
- The maximum number of failed attempts to process a message. After this number of failed attempts, the message is forwarded from the intended destination to its exception destination. Specify a value in the range 0 through 2147483647. A value of 0 (zero) means that if a message cannot be delivered on the first attempt, it is either forwarded to the exception destination or discarded, as defined by the -exceptionDestination parameter.
- -exceptionDestination value
- Use these properties to define what happens to any messages that cannot be delivered to this destination.
- By default, all messages that cannot be delivered to this destination are rerouted to the system default exception destination for the messaging engine to which this destination is assigned (_SYSTEM.Exception.Destination.messaging_engine_name). Use this parameter to override the default value. You can set a specific exception destination for this destination, or you can specify that undeliverable messages are not rerouted to an exception destination by entering an empty string (""), in which case the maximum failed deliveries count has no effect.
Note: An undeliverable message can block the processing of other messages waiting for delivery to the same destination.
- You can use this option and specify no exception destination to preserve message ordering.
- -sendAllowed TRUE | FALSE
- Clear this option (setting it to FALSE) to stop producers from being able to
send messages to these destinations.
- For a queue point of a non-mediated destination, or a mediation point of a mediated destination, if you clear this option then new messages (from attached producers or forwarded from another destination) are redirected to any available message point. If no message points are available, then messages that have already been accepted onto the bus, and new messages from attached producers, are preserved by the bus until a message point becomes available. The only exception to this is the case of a destination with only one message point (queue point or mediation point depending on whether the destination is mediated or non-mediated), where the producer is attached to the same messaging engine. In this case, an exception message is generated on each send call. The exception message indicates that the only extant localization has been disabled for send. The producer remains open as usual, and any more send calls succeed if the Send allowed property of the localization is reselected (reset to TRUE).
- For a queue point of a mediated destination, if you clear this option then messages from mediation instances are redirected to any available message point. If no message points are available, then the messages are preserved by the bus until a message point becomes available. For any mediation instance (that is, on any server that has a mediation point), if the same server hosts a queue point, and that queue point is the only queue point for the destination, then the mediation changes to the stopped on error state.
- -receiveAllowed TRUE | FALSE
- Clear this option (setting it to false) to prevent consumers from being able to receive messages from this destination. For the message point, if you clear this option then any open consumers change state and an exception is generated if the consumer requests a message. Messages can continue to be sent, and accumulate on the message point.
- -receiveExclusive TRUE | FALSE
- Select this option (setting it to true) to allow only one consumer to attach to a destination. If you select this option, only a single consumer can be attached to each queue point of a queue destination at any one time. Subsequent consumers attempting to attach to a queue point with a consumer already attached are rejected.
- -maintainStrictMessageOrder TRUE | FALSE
- Select this option (setting it to TRUE) to maintain the order in which a producer sends messages to a destination.
- At run time, this property has priority over other configuration property values. For information about the configuration properties that are overridden at run time, see Strict message ordering for bus destinations.
- -topicAccessCheckRequired
- Include this option if authorization checks are required for access to topics.
- -replyDestination
- The name of a destination to be appended to any non-empty reverse routing path of messages sent to this destination. This property is intended for use with mediations on reply messages. For more information about the use of this property, see Configuring a destination reverse routing path.
- -replyDestinationBus
- The name of the bus on which the reply destination is configured. This property is intended for use with mediations on reply messages. For more information about the use of this property, see Configuring a destination reverse routing path.
- -delegateAuthorizationCheckToTarget
- Indicates whether the authorization check is performed on the alias or the target destination. Include this option if you want the authorization check to be performed on the target destination.
- -wmqQueueName
- To assign these bus destinations to a IBM MQ queue, specify both the name of the WebSphere MQ server bus member where the destinations are assigned (the -wmqServer parameter), and the name of the IBM MQ queue used to store messages sent to these destinations (this parameter). Set the-wmqServer parameter to the name you gave when you created the WebSphere MQ server. Set the -wmqQueueName parameter to the name allocated to the IBM MQ queue by IBM MQ administration. Do not specify the -cluster, -node or -server parameters.
- -useRFH2 or -mqRfh2Allowed TRUE | FALSE
- Determines whether messages sent to these destinations have an MQRFH2 header.
- When service integration converts a message from the service integration format to IBM MQ format, by default it includes an MQRHF2 header in the IBM MQ message. This header contains message attributes, such as JMS message attributes, which are not IBM MQ message attributes and therefore do not appear in the IBM MQ message descriptor (MQMD). Some IBM MQ applications cannot process messages that include an MQRFH2 header. If messages sent to this destination will be processed by IBM MQ applications that cannot tolerate an MQRFH2, clear this option (setting it to FALSE).
- If you are assigning queue-type destinations to a WebSphere MQ server bus member, use the -useRFH2 parameter. If you are creating alias destinations or foreign destinations, use the -mqRfh2Allowed parameter.
- -auditAllowed TRUE | FALSE
- Clear this option (setting it to FALSE) to prevent the bus from auditing topic level authorization checks when the bus and application server have auditing enabled. The default value is TRUE. You must have Audit Administrator privileges to use this parameter. The parameter is ignored if it is used in the creation of other types of destination.
- -defaultForwardRoutingPath
- The value to which a message forward routing path is set if the message contains no forward routing path. This identifies a sequential list of intermediary bus destinations that messages must pass through to reach a target bus destination. The format of the field is a list of bus destinations specified as bus_name:destination_name.
- -queuePoints
- A list of the queue points used by users of the alias destination. If no specific queue points
are supplied, all queue points can be used. The target destination must be a queue destination in
the same bus as the alias destination definition. The target destination must also be a queue
destination with multiple queue points.
A queue point is specified in the form destination_name@messaging_engine_name.
- -mediationPoints
- A list of the mediation points used by users of the alias destination. If no specific mediation
points are supplied, all mediation points can be used. The target destination must be a mediated
queue destination in the same bus as the alias destination definition. The target destination must
also be a queue destination with multiple mediation points.
A mediation point is specified in the form destination_name@messaging_engine_name.
- -persistRedeliveryCount TRUE | FALSE
- Select this option (setting it to TRUE) to persist the failed delivery counts
of JMS messages in the message store. The value for the option is set to FALSE by
default.Important: Although the property is selected, the property will not be effective until the database tables are upgraded using the sibDBUpgrade command for WebSphere Application Server Version 9.0 and later.
Example 1
- Using
Jython:
wsadmin>AdminTask.createSIBDestinations("[-bus bus1 -type QUEUE -cluster cluster1 -nameList [[-identifier myqueue1][-identifier myqueue2]]]") "(cells/9994GKCCell01/buses/bus1|sib-destinations.xml#SIBQueue_1098215169998)"
- Using
Jacl:
wsadmin>$AdminTask createSIBDestinations {-bus bus1 -type QUEUE -cluster cluster1 -nameList {{myqueue1} {myqueue2}}} (cells/9994GKCCell01/buses/bus1|sib-destinations.xml#SIBQueue_1098215169998)
Example 2:
- Using
Jython:
wsadmin>AdminTask.createSIBDestinations("[-bus bus1 -type ALIAS -nameList [[MyAlias1][MyAlias2]] -aliasBus bus1 -targetName MyDestination1 -reliability INHERIT -maxReliability INHERIT -overrideOfOQSByProducerAllowed INHERIT -sendAllowed INHERIT -receiveAllowed INHERIT -queuePoints [[MyDestination1@cluster1.001-bus1] [MyDestination1@cluster1.002-bus1]]]")
- Using
Jacl:
wsadmin>set cluster [ lindex [ $AdminConfig list ServerCluster ] 1 ] wsadmin>$AdminTask createSIBDestinations {-bus bus1 -type ALIAS -nameList {{MyAlias1} {MyAlias2}} -aliasBus bus1 -targetName MyDestination1 -reliability INHERIT -maxReliability INHERIT -overrideOfOQSByProducerAllowed INHERIT -sendAllowed INHERIT -receiveAllowed INHERIT -queuePoints {{"MyDestination1@cluster1.001-bus1"} {"MyDestination1@cluster1.002-bus1}}}