+

Search Tips   |   Advanced Search

modifySIBMQLink command

Use the modifySIBMQLink command to modify the properties of an IBM MQ link.

To run the command, use the AdminTask object of the wsadmin scripting client.

(iSeries) (iSeries) The wsadmin scripting client is run from Qshell. (iSeries) See Configure Qshell to run WebSphere scripts .

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

After using the command, save the changes to the master configuration using the following command:

The modifySIBMQLink command modifies the properties of a IBM MQ link.


Target object

An IBM MQ link.


Required parameters

-bus

The name of the service integration bus for which we created the IBM MQ link. Use the listSIBuses command to list the names of existing buses.

-messagingEngine

The name of the messaging engine for which we created the IBM MQ link. Use the listSIBEngines command to list the names of existing messaging engines.

-name

The name of the IBM MQ link.


Conditional parameters

None.


Optional parameters

IBM MQ link configuration parameters:

-queueManagerName

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

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

-description

An optional description for the bus, for administrative purposes.

-exceptionDestination

The destination for an inbound message when the IBM 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 IBM 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 IBM 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 IBM 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 IBM 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 IBM MQ link. This is compared with the value for the corresponding partner IBM 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 IBM 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 IBM MQ link sender channel to the IBM MQ receiver channel when there are no messages on the transmission point being served by the IBM 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 IBM 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 we 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 IBM MQ information center.

Information Value
Default 999999999
Range 100 through 999999999

-nonPersistentMessageSpeed Fast | Normal

The class of service for nonpersistent messages on channels of this IBM 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 IBM MQ link, which shows whether a running instance of a IBM MQ link receiver channel (associated with this IBM MQ link) should be adopted. In the event of a communications failure, a running instance of a IBM MQ link receiver channel might be waiting for messages. When communication is reestablished, and the partner IBM MQ sender channel next attempts to establish a session with the IBM MQ link receiver channel, the request will fail as there is already a running instance of the IBM MQ link receiver channel that believes it is in session with the partner IBM MQ link sender channel. We can overcome this problem by selecting this option, which causes the already running instance of the IBM MQ link receiver channel to be stopped and a new instance to be started.

If we set this option to True, the IBM MQ sender channels might reestablish a connection to this IBM 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 IBM MQ link, which shows whether the link is started or stopped when the hosting messaging engine is first started. Until it is started, the IBM MQ link is unavailable.

Information Value
Default Started
Range

Stopped

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

Started

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

IBM MQ link sender channel parameters:

-senderChannelName

The sender channel that sends messages to the gateway queue manager. The sender channel communicates with an IBM 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 IBM MQ.

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

-hostName

The host name or TCP/IP address for the gateway queue manager used to connect into the IBM 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 IBM MQ link is defined.

-port

The TCP/IP port number on which the gateway queue manager is listening for the IBM 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 IBM 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 we 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 IBM MQ link is defined.

If we do specify the connection list parameter, we must have already specified a value for the sender channel name parameter, otherwise the value specified for the connection name list parameter is ignored.

If we 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 is a reasonable interval. Change this value only if we understand the implications for performance, and we 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 we want your channels to be active only when there are messages for them to transmit, we 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.

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 IBM MQ, see the Intercommunication section of the IBM 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 IBM MQ, see the Intercommunication section of the IBM 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 IBM MQ, see the Intercommunication section of the IBM MQ information center.

Information Value
Default 1200 seconds
Range 0 through 999999

-senderChannelInitialState Started | Stopped

The state of the IBM MQ link, which shows whether the sender channel is started or stopped when the associated IBM 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 IBM MQ link is in a stopped state and cannot communicate with the IBM MQ network.

Started

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

IBM MQ link receiver channel parameters:

-receiverChannelName

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

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

-inboundNonPersistentReliability Best effort | Reliable

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

This reliability delivery option is assigned to all IBM 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

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 IBM MQ through this IBM 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 IBM MQ link, which shows whether the receiver channel is started or stopped when the associated IBM 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 IBM MQ link is in a stopped state and cannot communicate with the IBM MQ network.

Started

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

-preferLocal TRUE | FALSE

This option indicates that the link prefers to send incoming messages to the queue point of the target destination 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 or later server.

This option is supported only when used by a JMS application running with a WASv7.0 or later server or client, and that is connected to a messaging engine running on WASv7.0 or later server. Use on previous versions of WAS 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 located on the same messaging engine as the link, if available.

FALSE

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


Examples

Show the properties of a IBM MQ link, modify the link to change the batch size, then show the properties of the link again.

Modify a IBM MQ link so that the link has no preference for which queue points to use.