Use the createSIBMQLink command to create
a new WebSphere® MQ link for a specified service
integration bus.
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.
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. You can 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 administrative 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
that is 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.
For more information
about choosing the batch size, see the description of the batch size
(BATCHSZ) property in the Intercommunication section
of the WebSphere MQ information center.
Information |
Value |
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.
Information |
Value |
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.
For more information about choosing the value for
this property, see the Intercommunication section of
the WebSphere MQ information center.
Information |
Value |
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.
For more information 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.
Information |
Value |
Default |
999999999 |
Range |
1 through 999999999 |
- -nonPersistentMessageSpeed Fast | Normal
- The class of service for nonpersistent messages on channels of this WebSphere MQ link.
Information |
Value |
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. You 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.
Information |
Value |
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.
Information |
Value |
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.
For more information
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.
Information |
Value |
Default |
1414 |
Range |
0 through 65535 |
- -connameList
- The connection name list for the gateway queue manager which is
used to connect to the WebSphere MQ network.
The connections are tried in the order in which they are specified
in the connection name list until a connection is successfully established.
If no connection is successful, the channel starts retry processing.
The
connection names must be given as a comma separated list in the following
format:
Dnsname1(portnumber1) , Dnsname2(portnumber2)
Type the DNS name or the IP address of the host on
which the gateway queue manager is running. Type the port number in
the range 0 through 65535.
If you do not specify the connection
name list parameter, 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.
If
you do specify the connection name list parameter, you must have already
specified a value for the sender channel name parameter, otherwise
the value that you specify for the connection name list parameter
is ignored.
If you specify the host name and port parameter
as well as the connection name list parameter, then at runtime the
connection name list takes precedence and host name and port values
are ignored.
- -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 you need a different
value for the requirements of the traffic flowing down your 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 your 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.
Information |
Value |
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 connection name list is provided, during each retry the connections are tried in the order in which they are specified in the connection list until a connection is successfully established. 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.
Information |
Value |
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.
Information |
Value |
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 connection name list is provided, during each retry the connections are tried in the order in which they are specified in the connection list until a connection is successfully established. 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.
Information |
Value |
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.
Information |
Value |
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.
Information |
Value |
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.
Information |
Value |
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.
Information |
Value |
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.
Information |
Value |
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 WebSphere Application Server Version 7.0 or later server.
This option
is supported only when used by a JMS application that is running with
a WebSphere Application Server Version 7.0 or later server or client, and
that is connected to a messaging engine running on WebSphere Application Server Version 7.0 or later server. Use on previous
versions of WebSphere Application Server will result
in an exception to the application.
Information |
Value |
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.
|
Examples
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]')