createSIBMQLink command

Use the createSIBMQLink command to create a new WebSphere MQ link for a specified service integration bus. To run the command, use the AdminTask object of the wsadmin scripting client. Command-line help is provided for service integration bus commands:

After using the command, save the changes to the master configuration; for example, by using the following command:

AdminConfig.save()

 

Purpose

The createSIBMQLink command creates a new WebSphere MQ link for a specified service integration bus. The WebSphere MQ link connects a messaging engine as a queue manager to WebSphere MQ, thereby providing a bridge between a service integration bus and a WebSphere MQ network.

 

Target object

A bus.

 

Required parameters

-bus

The name of the service integration bus for which you want to create the WebSphere MQ link. You can use the listSIBuses command to list the names of existing buses.

-messagingEngine

The name of the messaging engine for which you want to create the WebSphere MQ link. The WebSphere MQ link connects a messaging engine as a queue manager to WebSphere MQ, thereby providing a bridge between a service integration bus and a WebSphere MQ network.

-name

The name by which you want the WebSphere MQ link to be known.

-foreignBusName

The name of the foreign bus that defines the WebSphere MQ network for the WebSphere MQ link. Use the listSIBForeignBuses command to list the names of existing foreign buses.

-queueManagerName

The name of the virtual queue manager associated with the messaging engine, and by which the messaging engine is known to a remote WebSphere MQ network.

The queue manager name must conform to the WebSphere MQ naming conventions; for example, the name must be a maximum of 48 characters.

-senderChannelTransportChain OutboundBasicMQLink | OutboundSecureMQLink

The name of the sender channel that sends messages to the gateway queue manager. The sender channel communicates with a WebSphere MQ receiver channel on the gateway queue manager, and converts service integration bus messages to MQ format messages.

 

Conditional parameters

None.

 

Optional parameters

WebSphere MQ link configuration parameters:

-description

An optional description for the bus, for admin purposes.

-exceptionDestination

The destination for an inbound message when the WebSphere MQ link cannot deliver the message to its target bus destination, or to the exception destination configured for that target destination, or when the target destination does not exist.

System

The WebSphere MQ link uses the default exception destination. All messages that cannot be delivered to the bus destination are rerouted automatically to the system default exception destination for the messaging engine that this link is assigned to: _SYSTEM.Exception.Destinationmessaging_engine_name.

None

The WebSphere MQ link has no exception destination. Undeliverable messages are not rerouted to an exception destination and can block the processing of other messages waiting for delivery through the link to the same bus. This option can be used to preserve message ordering.

Specify

The WebSphere MQ link uses the exception destination specified here. If this is not possible, it uses the system exception destination.

-batchSize

The maximum number of messages that can be sent through a channel before taking a checkpoint.

The batch size does not affect the way the sender and receiver channels for this link transfer messages. Messages are always transferred individually, but are committed or backed out as a batch.

See about choosing the batch size, see the description of the batch size (BATCHSZ) property in the Intercommunication section of the WebSphere MQ information center.

Default

50

Range

1 through 9999

-maxMsgSize

The maximum message length, in bytes, that can be transmitted on any channel for the WebSphere MQ link. This is compared with the value for the corresponding partner WebSphere MQ channel and the actual maximum used is the lower of the two values.

For information about how to choose an appropriate number, see the description of the Maximum message length (MAXMSGL) property in the Intercommunication section of the WebSphere MQ information center.

Default

4194304 bytes (4MB)

Range

0 through 104857600

Specify 0 to use the largest value that the target queue manager will honor.

-heartBeat

The negotiated time, in seconds, between heartbeat flows passed from the WebSphere MQ link sender channel to the WebSphere MQ receiver channel when there are no messages on the transmission point being served by the WebSphere MQ link sender channel.

Heartbeats give the receiving channel the opportunity to quiesce the channel connection.

See about choosing the value for this property, see the Intercommunication section of the WebSphere MQ information center.

Default

300 seconds

Range

0 through 999999

-sequenceWrap

The value at which message sequence numbers wrap to start again at 1. For example, if you specify a value of 1000, when the message sequence number reaches 1001 it will restart at 1.

See about choosing the value for this property, see the description of the Sequence Number wrap (SEQWRAP) property in the Intercommunication section of the WebSphere MQ information center.

Default

999999999

Range

1 through 999999999

-nonPersistentMessageSpeed Fast | Normal

The class of service for nonpersistent messages on channels of this WebSphere MQ link.

Default

Fast

Range

Fast

Nonpersistent messages can be lost if there is a transmission failure or if the channel stops when the messages are in transit.

Normal

Nonpersistent messages are not lost if there is a transmission failure or if the channel stops when the messages are in transit.

-adoptable True | False

A property of the WebSphere MQ link, which shows whether a running instance of a WebSphere MQ link receiver channel (associated with this WebSphere MQ link) should be adopted. In the event of a communications failure, a running instance of a WebSphere MQ link receiver channel might be left waiting for messages. When communication is reestablished, and the partner WebSphere MQ sender channel next attempts to establish a session with the WebSphere MQ link receiver channel, the request will fail as there is already a running instance of the WebSphere MQ link receiver channel that believes it is in session with the partner WebSphere MQ sender channel. We can overcome this problem by selecting this option, which causes the already running instance of the WebSphere MQ link receiver channel to be stopped and a new instance to be started.

If you set this option to True, the WebSphere MQ sender channels might reestablish a connection to this WebSphere MQ link in the event that a communications failure has occurred and the link has not yet detected the failure condition.

Default

True

-initialState Started | Stopped

The state of the WebSphere MQ link, which shows whether the link is started or stopped when the hosting messaging engine is first started. Until it is started, the WebSphere MQ link is unavailable.

Default

Started

Range

Stopped

When the associated messaging engine is started, the WebSphere MQ link is in a stopped state and cannot communicate with the WebSphere MQ network.

Started

When the associated messaging engine is started, the WebSphere MQ link is started automatically and is enabled for communication with the WebSphere MQ network.

WebSphere MQ link sender channel parameters:

-senderChannelName

The sender channel that sends messages to the gateway queue manager. The sender channel communicates with a WebSphere MQ receiver channel on the gateway queue manager, and converts service integration bus messages to MQ format messages.

This name must be the same as the name of the receiver channel on WebSphere MQ.

See about choosing channel names, see the description of the channel name (CHANNEL) property in the Intercommunication section of the WebSphere MQ information center.

-hostName

The host name or TCP/IP address for the gateway queue manager that is used to connect into the WebSphere MQ network.

Type the host name or IP address of the host on which the gateway queue manager runs.

If this field is blank, the gateway queue manager is assumed to be running on the same host as the messaging engine on which the WebSphere MQ link is defined.

-port

The TCP/IP port number on which the gateway queue manager is listening for the WebSphere MQ link.

Default

1414

Range

0 through 65535

-discInterval

The time in seconds for which the sender channel waits for new messages to arrive on the transmission queue after sending a batch of messages. The channel disconnects after this interval, and must be restarted manually or by triggering.

The default value is a reasonable interval. Change this value only if you understand the implications for performance, and we need a different value for the requirements of the traffic flowing down the channels.

Performance is affected by the value specified for the disconnect interval. A very low value (a few seconds) can cause an unacceptable amount of processing in constantly starting up the channel. A very large value (more than an hour) might mean that system resources are unnecessarily held up.

If you want the channels to be active only when there are messages for them to transmit, you should set the disconnect interval to a fairly low value. Note that the default setting is quite high and so is not recommended for channels where this level of control is required. Because it is difficult to interrupt the receiving channel, the most economical option is to have the channel automatically disconnect and reconnect as the workload demands. For most channels, the appropriate setting of the disconnect interval can be established heuristically.

Default

900 seconds

Range

0 through 999999

A value of 0 (zero) means never disconnect; the channel waits indefinitely for messages.

-shortRetryCount

The maximum number of times that the sender channel tries to restart after a communication or partner failure. If the count of remaining retries reaches zero, and the channel has not restarted, then the long retry mechanism is invoked.

For more information about using retry mechanisms with WebSphere MQ, see the Intercommunication section of the WebSphere MQ information center.

Default

10

Range

0 through 999999999

-shortRetryInterval

The number of seconds between attempts by the sender channel to restart after a communication or partner failure.

For more information about using retry mechanisms with WebSphere MQ, see the Intercommunication section of the WebSphere MQ information center.

Default

60 seconds

Range

0 through 999999

-longRetryCount

The maximum number of times that the sender channel tries to restart after the short retry mechanism did not recover from a communication or partner failure. If the count of remaining retries reaches zero, and the channel has not restarted, then an error is logged and the channel is stopped.

For more information about using retry mechanisms with WebSphere MQ, see the Intercommunication section of the WebSphere MQ information center.

Default

999999999

Range

0 through 999999999

-longRetryInterval

The number of seconds between attempts by the sender channel to restart after the short retry mechanism did not recover from a communication or partner failure.

For more information about using retry mechanisms with WebSphere MQ, see the Intercommunication section of the WebSphere MQ information center.

Default

1200 seconds

Range

0 through 999999

-senderChannelInitialState Started | Stopped

The state of the WebSphere MQ link, which shows whether the sender channel is started or stopped when the associated WebSphere MQ link is first started. Until it is started, the channel is unavailable.

Default

Started

Range

Stopped

When the associated messaging engine is started, the WebSphere MQ link is in a stopped state and cannot communicate with the WebSphere MQ network.

Started

When the associated messaging engine is started, the WebSphere MQ link is started automatically and is enabled for communication with the WebSphere MQ network.

WebSphere MQ link receiver channel parameters:

-receiverChannelName

The name of the receiver channel for the WebSphere MQ link, used to receive messages from WebSphere MQ onto the bus.

This name must be the same as the name of the sender channel on WebSphere MQ.

-inboundNonPersistentReliability Best effort | Express | Reliable

The acceptable reliability of message delivery for nonpersistent message flows from WebSphere MQ through this WebSphere MQ link, from Best effort to Reliable, in order of increasing reliability.

This reliability delivery option is assigned to all WebSphere MQ nonpersistent messages flowing over this receiver channel.

Default

Reliable

Range

Best effort

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™

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

Messages are discarded when a messaging engine stops or fails.

-inboundPersistentReliability Reliable | Assured

The acceptable reliability of message delivery for inbound persistent message flows from WebSphere MQ through this WebSphere MQ link, from Reliable to Assured, in order of increasing reliability.

Default

Assured

Range

Reliable

Messages might be discarded when a messaging engine fails.

Assured

Messages are not discarded.

-receiverChannelInitialState Started | Stopped

The state of the WebSphere MQ link, which shows whether the receiver channel is started or stopped when the associated WebSphere MQ link is first started. Until it is started, the channel is unavailable.

Default

Started

Range

Stopped

When the associated messaging engine is started, the WebSphere MQ link is in a stopped state and cannot communicate with the WebSphere MQ network.

Started

When the associated messaging engine is started, the WebSphere MQ link is started automatically and is enabled for communication with the WebSphere MQ network.

-preferLocal TRUE | FALSE

This option indicates that the link prefers to send incoming messages to the queue point of the target destination that is located on the same messaging engine as the link, if available. The link must be owned by a messaging engine running on a WAS V7.0 server.

This option is supported only when used by a JMS application that is running with a WAS V7.0 server or client, and that is connected to a messaging engine running on WAS V7.0 server. Use on previous versions of WAS will result in an exception to the application.

Default

TRUE

Range

TRUE

Send each incoming message to the queue point of the target destination that is located on the same messaging engine as the link, if available.

FALSE

Send incoming messages to any queue points of the target destinations.

 

Example

AdminTask.createSIBMQLink('[-bus bus1 -messagingEngine cluster1.000-bus1 -name myMQLink2 -foreignBusName MQNetwork2 -queueManagerName MQMgrIPL -senderChannelTransportChain OutboundBasicMQLink]') 'myMQLink2(cells/cell01/nodes/node01/servers/server1|sib-engines.xml# SIBMQLink_1132607756126)'

Create a SIBMQLink that uses queue points on the same messaging engine as the target destination, whenever possible.

AdminTask.createSIBMQLink('[-bus bus1 -messagingEngine cluster1.000-bus1 -name MyMQLink -foreignBusName -MQQMgr1 -queueManagerName bus1 -senderChannelTransportChain OutboundBasicMQLink -preferLocal TRUE]')
   


Last updated Nov 10, 2010 8:23:07 PM CST