Creating new bus destinations using the wsadmin tool

Use the createSIBDestinations command to create new bus destinations for a service integration bus.

This command provides only a subset of the properties available. If you want to set other properties, you need to use the administrative console or wsadmin and JACL

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 the topic "Configure Qshell to run WebSphere® Application Server scripts".

This command is valid only when it is used with WebSphere Application Server Version 6.1.0 Fix Pack 15 or later. Do not use it with earlier versions.

Command-line help is provided for service integration bus commands:

For additional details of the command properties, see the related reference topic.

Purpose

The createSIBDestinations command creates new bus destinations for a service integration bus. With this command, a messaging destination can also be localized to a WebSphere MQ server bus member.

Command name
createSIBDestinations
Target
None.
Result
Bus destination objects.

To save the changes made by the command, invoke the "save" command on the AdminConfig object.

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 destinationnames
The identifiers by which these destinations are known for administrative purposes.
-type Alias | Foreign | Queue | TopicSpace | WebService | Port
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.
Queue
A queue, for point-to-point messaging.
TopicSpace
A topic space, for publish/subscribe messaging.
WebService
Represents an externally-hosted target Web service.
Port
Represents a particular message and transport binding for an outbound service that communicates with an externally-hosted target Web service.
-wmqServer Servername -wmqQueueName Queuename
[Queue destination] To assign the bus destinations to a WebSphere MQ queue, specify both the name of the WebSphere MQ server bus member where the destinations are assigned, and the name of the WebSphere MQ queue used to store messages sent to the destinations. Servername is the name of the WebSphere MQ server as specified in the -name parameter when creating the WebSphere MQ server. Queuename is the name allocated to the WebSphere MQ queue by WebSphere MQ administration.

Conditional parameters

None.

Optional parameters

-useRFH2 TRUE | FALSE
Determines whether or not messages sent to the destinations have an RFH2 header. This parameter is only valid if assigning queue-type destinations to a WebSphere MQ server bus member.

When service integration converts a message from the service integration format to WebSphere MQ format, by default it includes a WebSphere MQ RHF2 in the WebSphere MQ message. This header contains message attributes, such as JMS message attributes, which are not WebSphere MQ message attributes and therefore do not appear in the MQMD WebSphere MQ message descriptor. Some WebSphere MQ applications cannot process messages which include an RFH2. If messages sent to these destinations will be processed by WebSphere MQ applications which cannot tolerate an RFH2, specify FALSE.

Possible values are:
TRUE
Messages sent to these destinations have an RFH2 header.
FALSE
Messages sent to these destinations do not have an RFH2 header.
The default is TRUE.
-persistentReliability RELIABLE_PERSISTENT | ASSURED

Determines the service integration quality of service level property for WebSphere MQ messages that are received by service integration from a WebSphere MQ network. The messages in a WebSphere MQ network have their own quality of service level that is determined by WebSphere MQ. However when these messages are received by a service integration application, they are assigned a service integration quality of service level property that depends on their WebSphere MQ quality of service level.

For example, if a WebSphere MQ message is persistent, using this attribute, you can specify that a service integration application which examines the quality of service level will observe best effort nonpersistent, express nonpersistent, reliable nonpersistent, reliable persistent or assured persistent (the default is assured persistent).

Possible values are:

BEST_EFFORT_NONPERSISTENT
Messages are discarded when a messaging engine stops or fails. Messages may also be discarded if a connection used to send them becomes unavailable and as a result of constrained system resources.

For non-transactional JMS message-driven beans and MessageListeners that use a JMS destination configured on the default messaging provider, best-effort nonpersistent messages are not recoverable. In this case, if a message is unlocked because the message-driven bean or MessageListener threw an exception, then the message is not redelivered or sent to the exception destination because it was deleted from the message store when it was passed to the listener. If you require higher message reliability for non-transactional JMS message-driven beans and MessageListeners, configure a different option for the Maximum reliability property of the bus destination.

EXPRESS_NONPERSISTENT
Messages are discarded when a messaging engine stops or fails. Messages may 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 may be discarded when a messaging engine fails.
ASSURED_PERSISTENT
Messages are not discarded.
The default is ASSURED_PERSISTENT.
-nonPersistentReliability BEST_EFFORT | EXPRESS | RELIABLE_NON_PERSISTENT

Determines the service integration quality of service level property for WebSphere MQ messages that are received by service integration from a WebSphere MQ network. The messages in a WebSphere MQ network have their own quality of service level that is determined by WebSphere MQ. However when these messages are received by a service integration application, they are accorded a service integration quality of service level property that depends on their WebSphere MQ quality of service level.

For example, if a WebSphere MQ message is nonpersistent, using this attribute, you can specify that a service integration application which examines the quality of service level will observe best effort nonpersistent, express nonpersistent, reliable nonpersistent, reliable persistent or assured persistent (the default is reliable nonpersistent).

Possible values (as previously described) are:

BEST_EFFORT_NONPERSISTENT
EXPRESS_NONPERSISTENT
RELIABLE_NONPERSISTENT
RELIABLE_PERSISTENT
ASSURED_PERSISTENT
The default is RELIABLE_NONPERSISTENT.
-description
An optional description for these bus destinations, for administrative purposes.
-node nodename -server servername
[Not topic space] To assign these 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.
-cluster
[Not topic space] To assign these bus destinations to a cluster bus member, specify the name of the cluster.

Use this option only in WebSphere Application Server environments that support server clusters.

-aliasBus
[Alias destination] To create an alias destination, type the source bus name of the alias mapping.
-targetBus
[Alias destination] To create an alias destination, type the name of the bus to which the alias destination is mapped.
-targetName
[Alias destination] To create an alias destination, type the name of the destination to which the alias maps.
-foreignBus
[Foreign destination] To create a foreign destination, type the name of the foreign bus.
-reliability BEST_EFFORT_NONPERSISTENT | EXPRESS_NONPERSISTENT | RELIABLE_NONPERSISTENT | RELIABLE_PERSISTENT | ASSURED_PERSISTENT
The reliability assigned to a message produced to this destination when an explicit reliability has not been set by the producer. Possible values (as previously described) are:
BEST_EFFORT_NONPERSISTENT
EXPRESS_NONPERSISTENT
RELIABLE_NONPERSISTENT
RELIABLE_PERSISTENT
ASSURED_PERSISTENT
-overrideOfQOSByProducerAllowed TRUE | FALSE
Select this option to enable producers to override the default reliability that is set on the destination.
-defaultPriority
The default priority assigned to messages sent to this destination when a priority has not been set by the producer. Specify a value in the range 0 (lowest) through 9 (high).
-maxFailedDeliveries
The maximum number of failed attempts to process a message before the message is forwarded to the exception destination for the 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 property.
-exceptionDestination
The destination to which a message is forwarded by the system when it 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.engine_name). Use this parameter to override the default value. You can either specify the name of another destination to use as the exception destination, or you can specify an empty String (""), in which case the maximum failed deliveries count has no effect and undeliverable messages are not rerouted to an exception destination.
Note: An undeliverable message can block the processing of other messages waiting for delivery to the same destination.
This option can be used to preserve message ordering.
-sendAllowed TRUE | FALSE
Send allowed
Selected
Producers can send messages to this destination.
Cleared
Producers cannot send messages to this destination.
  • For a queue point of a non-mediated destination, or a mediation point of a mediated destination, 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 is generated on each send call. The exception message indicates that the reason for the exception is that the only extant localization has been disabled for send. The producer remains open as normal, 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, clearing this Send allowed property alters the behavior of the mediation instances that are sending to the destination in the same way as setting it to false on a non-mediated destination affects producing applications: Messages are sent instead to any alternative message point. If no localizations are available, 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.
TRUE
Consumers can get messages from this destination.
FALSE
Consumers cannot get messages from this destination.

For the message point, 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.

-maintainStrictMessageOrder TRUE | FALSE
Maintain strict message order
Selected
Maintains the order in which a producer sends messages to the destination.

At runtime, this property has priority over other configuration property values. For information on the configuration properties that are overridden at runtime, see Strict message ordering for bus destinations.

Cleared
Message order is not preserved for this destination.
-quiesceMode TRUE | FALSE
Quiesce mode
-receiveExclusive TRUE | FALSE
Receive exclusive
-topicAccessCheckRequired
[Topic space] Whether or not 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 bus on which the reply destination exists. 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
[Alias destination] Indicates whether the authorization check is performed on the alias or the target destination.
-defaultForwardRoutingPath
The value to which a message's forward routing path will be set if the message contains no forward routing path, in the format, bus:name or :name.

Example

wsadmin>$AdminTask createSIBDestinations {-bus myBus -type QUEUE -cluster cluster1 -nameList {{myqueue1} {myqueue2}} }
(cells/9994GKCCell01/buses/abus|sib-destinations.xml#SIBQueue_1098215169998)



Related concepts
WebSphere MQ queue points and mediation points
WebSphere MQ server and mediated exchange scenarios
Mediations
Related tasks
Creating the queue-type destination and assigning it to a WebSphere MQ queue
Mediating a destination using a WebSphere MQ queue as the mediation point
Related reference
Destinations administrative commands
Reference topic Reference topic    

Terms and conditions for information centers | Feedback

Last updatedLast updated: Aug 30, 2013 8:21:57 PM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=pix&product=was-express-iseries&topic=rjo_cli_dests_create
File name: rjo_cli_dests_create.html