Use this command to create a new WebSphere® MQ link in the cell.
To run the command, use the AdminTask
object of the wsadmin
scripting client.
This command is only valid when
used with WebSphere Application
Server Version 6.1 and later application servers. 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
This 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.
- Command name
- createSIBMQLink
- Target
- None.
- Result
- A WebSphere MQ link
object.
To save the changes made by the command, invoke the "save"
command on the AdminConfig object.
Required parameters
- -bus busname
- 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 name
- 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 MQlinkname
- The name by which you want the WebSphere MQ
link to be known.
- -foreignBusName busname
- 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 name
- 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 text
- An optional description for the bus, for administrative purposes.
- -batchSize integer
- 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 considerations
when choosing the number for batch size, see the description of the
Batch size (BATCHSZ) property in the WebSphere MQ Intercommunication book.
Default |
50 |
Range |
1 through 9999 |
- -maxMsgSize integer
- 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 partner and the actual maximum used is the lower of the two values.
For
considerations when choosing the number for message size, see the
description of the Maximum message length (MAXMSGL) property in the WebSphere MQ Intercommunication book.
Default |
4194304 bytes (4MB) |
Range |
0 through 104857600 Specify
0 to use the largest value that the target queue manager will honor.
|
- -heartBeat integer
- The time, in seconds, between heartbeat flows passed from the sender channel across the WebSphere MQ link when there are no messages on the transmission queue.
Heartbeats
give the receiving channel the opportunity to quiesce the channel
connection.
For considerations when choosing the number for
this property, see the WebSphere MQ
Intercommunication book.
Default |
300 seconds |
Range |
0 through 999999 |
- -sequenceWrap long
- The value at which message sequence numbers wrap to start again at 1.
This
is the highest number the message sequence number reaches before it
restarts at 1.
For considerations when choosing the number for
this property, see the WebSphere MQ
Intercommunication book.
Default |
999999999 |
Range |
1 through 999999999 For considerations when choosing the
number for this property, see the description of the Sequence Numberwrap
(SEQWRAP) property in the WebSphere MQ
Intercommunication book.
|
- -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
- Whether or not this WebSphere MQ link can be adopted by another messaging engine if the original hosting messaging engine is restarted or adopted on another machine.
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.
- -initialState Started | Stopped
- Whether the WebSphere MQ link is started or stopped when the hosting messaging engine is first started. Until 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 name
- 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 considerations
when choosing channel names, see the description of the Channel name
(CHANNEL) property in the WebSphere MQ
Intercommunication book.
- -hostName name
- The hostname or TCP/IP 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 integer
- The TCP/IP port number on which the gateway queue manager is listening for the WebSphere MQ link.
Default |
1414 |
Range |
0 through 2147483647 |
- -discInterval integer
- 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 excessive overhead in constantly
starting up the channel. A very large value (more than an hour) could
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.
Default |
900 seconds |
Range |
0 through 999999 A value of 0
(zero) means never disconnect; the channel waits indefinitely for
messages.
|
- -shortRetryCount long
- 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.
Default |
10 |
Range |
0 through 999999999 |
- -shortRetryInterval integer
- The number of seconds between attempts by the sender channel to restart after a communication or partner failure.
For
considerations when using retry mechanisms with WebSphere MQ, see the WebSphere MQ Intercommunication book.
Default |
60 seconds |
Range |
0 through 999999 |
- -longRetryCount long
- 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
considerations when using retry mechanisms with WebSphere MQ, see the WebSphere MQ Intercommunication book.
Default |
999999999 |
Range |
0 through 999999999 |
- -longRetryInterval long
- 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
considerations when using retry mechanisms with WebSphere MQ, see the WebSphere MQ Intercommunication book.
Default |
1200 seconds |
Range |
0 through 999999 |
- -senderChannelInitialState Started | Stopped
- Whether the sender channel is started or stopped when the associated WebSphere MQ link is first started. Until 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 name
- 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 may also be discarded if a connection used to send them becomes unavailable and as a result of constrained system resources.
- Express
- 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
- 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 may be discarded when a messaging engine fails.
- Assured
- Messages are not discarded.
|
- -receiverChannelInitialState Started | Stopped
- Whether the receiver channel is started or stopped when the associated WebSphere MQ link is first started. Until 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.
|
Example
wsadmin>$AdminTask createSIBMQLink {-bus SCA.SYSTEM.IBM-AA8DA602255Cell01.Bus -messagingEngine IBM-AA8DA602255Node01.server1-SCA.SYSTEM.IBM-AA8DA602255Cell01.Bus -name myMQLink2
-foreignBusName MQNetwork2 -queueManagerName MQMgrIPL -senderChannelTransportChain OutboundBasicMQLink}
myMQLink2(cells/IBM-AA8DA602255Cell01/nodes/IBM-AA8DA602255Node01/servers/server1|sib-engines.xml#SIBMQLink_1132607756126)
wsadmin>